Swiftpack.co - Package - SDGGiesbrecht/SDGCommandLine

macOS • Linux

Documentation

SDGCommandLine

SDGCommandLine provides tools for implementing a command line interface.

יְהַלְלוּ אֶת־שֵׁם יהוה כִּי הוּא צִוָּה וְנִבְרָאוּ׃

May they praise the name of the Lord, for He commanded and they came into being!

―a psalmist

Features

  • Automatic parsing of options and subcommands
  • Automatic help subcommand
  • Testable output
  • Colour formatting tools
    • Automatic •no‐colour option
  • Interface localization
    • Automatic set‐language subcommand to set language preferences.
    • Automatic •language option to run in a specific language only once.
  • Versioning tools
    • Automatic version subcommand
    • Automatic •use‐version option to attempt to download and temporarily use a specific version instead of the one which is installed (only for public Swift packages).

Example Usage

This example creates a tool with the following interface:

$ parrot speak
Squawk!

$ parrot speak •phrase "Hello, world!"
Hello, world!

main.swift must consist of the following lines:

ProcessInfo.applicationIdentifier = "tld.Developper.Parrot"
ProcessInfo.version = Version(1, 0, 0)
ProcessInfo.packageURL = URL(string: "https://website.tld/Parrot")

parrot.executeAsMain()

The rest can be anywhere in the project (but putting it in a separate, testable library module is recommended):

import SDGCommandLine

public let parrot = Command(
  name: UserFacing<StrictString, MyLocalizations>({ _ in "parrot" }),
  description: UserFacing<StrictString, MyLocalizations>({ _ in "behaves like a parrot." }),
  subcommands: [speak]
)

let speak = Command(
  name: UserFacing<StrictString, MyLocalizations>({ _ in "speak" }),
  description: UserFacing<StrictString, MyLocalizations>({ _ in "speaks." }),
  directArguments: [],
  options: [phrase],
  execution: { (_, options: Options, output: Command.Output) throws -> Void in

    if let specific = options.value(for: phrase) {
      output.print(specific)
    } else {
      output.print("Squawk!")
    }
  }
)

let phrase = Option<StrictString>(
  name: UserFacing<StrictString, MyLocalizations>({ _ in "phrase" }),
  description: UserFacing<StrictString, MyLocalizations>({ _ in "A custom phrase to speak." }),
  type: ArgumentType.string
)

enum MyLocalizations: String, InputLocalization {
  case english = "en"
  internal static let cases: [MyLocalizations] = [.english]
  internal static let fallbackLocalization: MyLocalizations = .english
}

Tests are easy to set up:

func testParrot() {
  switch parrot.execute(with: ["speak", "•phrase", "Hello, world!"]) {
  case .success(let output):
    XCTAssertEqual(output, "Hello, world!")
  case .failure:
    XCTFail("The parrot is not co‐operating.")
  }
}

Importing

SDGCommandLine provides libraries for use with the Swift Package Manager.

Simply add SDGCommandLine as a dependency in Package.swift and specify which of the libraries to use:

let package = Package(
    name: "MyPackage",
    dependencies: [
        .package(url: "https://github.com/SDGGiesbrecht/SDGCommandLine", from: Version(1, 2, 5)),
    ],
    targets: [
        .target(name: "MyTarget", dependencies: [
            .productItem(name: "SDGCommandLine", package: "SDGCommandLine"),
            .productItem(name: "SDGCommandLineTestUtilities", package: "SDGCommandLine"),
            .productItem(name: "SDGExportedCommandLineInterface", package: "SDGCommandLine"),
        ])
    ]
)

The modules can then be imported in source files:

import SDGCommandLine
import SDGCommandLineTestUtilities
import SDGExportedCommandLineInterface

About

The SDGCommandLine project is maintained by Jeremy David Giesbrecht.

If SDGCommandLine saves you money, consider giving some of it as a donation.

If SDGCommandLine saves you time, consider devoting some of it to contributing back to the project.

Ἄξιος γὰρ ὁ ἐργάτης τοῦ μισθοῦ αὐτοῦ ἐστι.

For the worker is worthy of his wages.

―‎ישוע/Yeshuʼa

Github

link
Stars: 3

Dependencies

Used By

Total: 0

Releases

Version 1.2.5 - 2020-01-14 23:37:31

Dependency updates.

Version 1.2.4 - 2019-12-04 06:37:50

Dependency updates.

Version 1.2.3 - 2019-11-15 22:46:39

Dependency updates.

Version 1.2.2 - 2019-10-27 21:04:22

Dependency updates.

Version 1.2.1 - 2019-10-24 21:04:42

Dependency updates.

Version 1.2.0 - 2019-10-09 20:22:57

New Features

  • All platform restrictions have been removed.

Version 1.1.1 - 2019-09-23 23:52:13

Swift 5.1 is required. Older versions of the package manager will not resolve to this release.

Bug Fixes

  • Dependency updates.

Version 1.1.0 - 2019-07-30 01:58:59

New Features

  • The provided interface elements are localized into German.

Version 1.0.2 - 2019-07-11 05:23:21

Dependency updates.

Version 1.0.1 - 2019-07-03 21:26:21

Bug Fixes

Dependency updates.

Version 1.0.0 - 2019-06-13 00:16:09

Breaking Changes

  • Modules do not export each other. Each must be imported separately.
    • The @_exported attribute was never officially supported by Swift anyway. As the last remaining thing blocking the 1.0.0 release, it was deemed not important enough to delay until official support. Since it is not strictly necessary for any functionality, it has been removed instead of waiting.

Version 0.7.4 - 2019-06-01 03:45:13

Bug Fixes

Dependency updates.

Version 0.7.3 - 2019-05-27 03:21:05

Bug Fixes

  • Fixed an issue where some options would appear duplicated in help and when exported.
  • Fixed some typos in the help output.

Version 0.7.2 - 2019-05-25 20:34:31

New Features

  • A separate, longer discussion section is available for information about a command beyond the simple summary description.
  • A new library can load the interface (i.e. the structured help information) of any tool built with SDGCommandLine in the debug configuration: SDGExportedCommandLineInterface.

Version 0.7.1 - 2019-05-16 05:04:31

Bug Fixes

Dependency updates.

Version 0.7.0 - 2019-05-09 20:33:21

Breaking Changes

  • Methods which throw specific errors types now do so using Result for stronger typing.

Version 0.6.2 - 2019-04-27 02:39:11

Bug Fixes

  • Dependency updates.

Version 0.6.1 - 2019-04-06 02:57:25

Bug Fixes

  • Dependency updates.

Version 0.6.0 - 2019-03-31 02:56:49

Breaking Changes

  • Swift 5
  • macOS 10.13

Version 0.5.2 - 2019-03-22 00:26:19

Bug Fixes

  • Dependency updates.

Version 0.5.1 - 2019-01-06 03:39:34

Bug Fixes

  • Dependency updates.

Version 0.5.0 - 2018-12-18 06:32:25

Breaking Changes

  • Swift 4.2.1

Version 0.4.2 - 2018-11-02 16:38:23

Bug Fixes

  • Dependency updates.

Version 0.4.1 - 2018-09-29 12:52:54

Bug Fixes

  • Linux no longer encounters linker errors when depending on SDGCommandLine. (See SR‐8803.)

Version 0.4.0 - 2018-09-25 17:08:20

Breaking Changes

  • Swift 4.2

Bug Fixes

  • help correctly filters out hidden options.

Version 0.3.3 - 2018-06-29 05:00:55

Bug Fixes

  • Fixed several corner cases where other error types escaped being wrapped in an Command.Error.

Version 0.3.2 - 2018-06-28 01:19:01

Bug Fixes

  • Dependencies have been updated.

Version 0.3.1 - 2018-05-31 05:12:20

Dependency updates only.

Version 0.3.0 - 2018-05-04 22:52:52

Breaking Changes

  • initialize() has been removed. Set ProcessInfo.applicationIdentifier, ProcessInfo.version and ProcessInfo.packageURL instead.
  • Command.Output is now a class. Instead of print(..., to: &output), use output.print(...).
  • Command.execute(...) now provides the output with thrown errors. In order to do so, other error types now get wrapped in a Command.Error.)
  • Low quality localizations have been dropped.

New Features

  • New argument types are provided:
    • integer(range:) (→ Int)
    • path (→ URL)
  • Commands and options can now be hidden from the “help” lists. (See their respective initializers.)
  • A new empty‐cache subcommand is available. It deletes anything saved to FileManager.url(in: .cache, [...]), including cached alternate versions.
  • New module to aid in writing tests: SDGCommandLineTestUtilities.
  • A new test mode (Command.Output.testMode) can be engaged to prevent command output from appearing amid test results.

Version 0.2.0 - 2018-04-10 20:42:29

Breaking Changes

  • Swift 4.1