Swiftpack.co - Package - SDGGiesbrecht/SDGCommandLine

macOS • Windows • Web • CentOS • Ubuntu • Android • Amazon 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:

Parrot.main()

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

import SDGCommandLine

struct Parrot: Tool {
  static let applicationIdentifier: StrictString = "tld.Developper.Parrot"
  static let version: Version? = Version(1, 0, 0)
  static let packageURL: URL? = URL(string: "https://website.tld/Parrot")
  static let rootCommand: Command = parrot
}

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"
  static let cases: [MyLocalizations] = [.english]
  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(
      name: "SDGCommandLine",
      url: "https://github.com/SDGGiesbrecht/SDGCommandLine",
      from: Version(1, 6, 0)
    ),
  ],
  targets: [
    .target(
      name: "MyTarget",
      dependencies: [
        .product(name: "SDGCommandLine", package: "SDGCommandLine"),
        .product(name: "SDGCommandLineTestUtilities", package: "SDGCommandLine"),
        .product(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.6.0 -

New Features

  • A new Tool protocol can be used with @main.

Version 1.5.2 -

Bug Fixes

  • The API has been updated to use #filePath.

Version 1.5.1 -

Bug Fixes

  • Swift 5.3 (Older toolchains will not select this version.)

Version 1.5.0 -

New Features

  • CentOS and Amazon Linux are now supported.

Version 1.4.3 -

Bug Fixes

  • Dependencies have been updated.

Version 1.4.2 -

Bug Fixes

  • Dependencies have been updated.

Version 1.4.1 -

Bug Fixes

  • Dependencies have been updated.

Version 1.4.0 -

New Features

  • Web is now a supported platform. Actual runtime stability depends on the toolchain used to compile the package.

Version 1.3.2 -

Breaking Changes

  • Swift 5.2 (Older versions of Swift will ignore this release.)

Version 1.3.1 -

Bug Fixes

  • Minor internal optimizations.

Version 1.3.0 -

New Features

  • Windows and Android are supported. Actual runtime stability depends on the toolchain used to compile the package.

Version 1.2.5 -

Dependency updates.

Version 1.2.4 -

Dependency updates.

Version 1.2.3 -

Dependency updates.

Version 1.2.2 -

Dependency updates.

Version 1.2.1 -

Dependency updates.

Version 1.2.0 -

New Features

  • All platform restrictions have been removed.

Version 1.1.1 -

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 -

New Features

  • The provided interface elements are localized into German.

Version 1.0.2 -

Dependency updates.

Version 1.0.1 -

Bug Fixes

Dependency updates.

Version 1.0.0 -

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 -

Bug Fixes

Dependency updates.

Version 0.7.3 -

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 -

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 -

Bug Fixes

Dependency updates.

Version 0.7.0 -

Breaking Changes

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

Version 0.6.2 -

Bug Fixes

  • Dependency updates.

Version 0.6.1 -

Bug Fixes

  • Dependency updates.

Version 0.6.0 -

Breaking Changes

  • Swift 5
  • macOS 10.13