macOS • Windows • Web • Ubuntu • tvOS • iOS • Android • Amazon Linux • watchOS

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.")
  }
}

Some platforms lack certain features. The compilation conditions which appear throughout the documentation are defined as follows:

.define("PLATFORM_LACKS_FOUNDATION_PROCESS", .when(platforms: [.wasi, .tvOS, .iOS, .watchOS])),
.define("PLATFORM_LACKS_FOUNDATION_PROCESS_INFO", .when(platforms: [.wasi])),

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(3, 0, 5)
    ),
  ],
  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