A minimal, pure Swift library for making command-line tools / interfaces.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Sources
Tests
.codecov.yml
.gitignore
.travis.yml
License.md
Package.swift
README.md
TODO.md

README.md

SwiftArgs

A minimal, pure Swift library for making command-line tools / interfaces.

Travis build status codebeat codecov SPM Swift version Swift version

SwiftArgs uses a very basic and limited parser for parsing commands, but it should suffice for basic usage requirements. You can use SwiftArgs when making a command-line app in Swift and let it do the parsing work for you.

SwiftArgs is largely model-based -- you define models for the command-line arguments that your program expects. These models are used for validation at runtime. When parsed successfully, instantiated objects of your models are returned to your Command Parser Delegate. The values of your command model properties will be set when returned to your Command Parser Delegate.

Contributions welcome.


Installation

Requires Swift 3.x or 4.x

Using Swift Package Manager:

dependencies: [
    .Package(url: "https://github.com/frazer-rbsn/SwiftArgs", majorVersion: 1),
]

Use

Registering commands with the parser

If you only need to define commands by keywords, i.e. without required arguments, option switches or usage documentation, you can use SwiftArgs as follows:

let parser = CommandParser()

try! parser.register("run", "new", "old")

Otherwise, you can define Command models that conform to a Command protocol, as follows:

struct RunCommand : Command {
    let name = "run"
}

let parser = CommandParser()

try! parser.register(RunCommand())

Command Models

You can decorate your command with more functionality by conforming to other protocols.

For example, if you want to add usage information to a command, conform to the HasHelpText protocol. If the user runs the command with invalid arguments, the helpText will be printed.

struct RunCommand : Command, HasHelpText {
    let name = "run"
    let helpText = "Helpful usage information goes here."
}
Commands with arguments

You can specify a command to have required ordered arguments, in the form of command x y z, where x, y and y are arguments and will be parsed as Argument models.

struct MoveCommand : CommandWithArguments {
    let name = "move"
    let arguments : [Argument] = [BasicArgument("x"), BasicArgument("y")]
}

Parsing the command line

In order to act upon runtime commands, create a CommandParserDelegate and pass it to the parser.

struct ParserDelegate : CommandParserDelegate {

    func receivedCommand(command: Command) {
        print("received command: \(command)")
    }

    func commandNotSupplied() {
        print("no command supplied")
    }
}

try! parser.parseCommandLine(delegate: ParserDelegate())

Build

  • Install Swift 3.x or Swift 4.x toolchain.
  • Run swift build in the root of the repo. Unit tests can be run with swift test.

Limitations

  • Hasn't been tested on Linux.
  • Doesn't support short-form option switches yet, e.g. mycommand -o