CommandCougar

1.0.0

Simple & Elegant Command Line Interfaces in Swift
hypertalk/CommandCougar

What's New

The Cougar

2017-05-15T00:03:42Z

Command Cougar

An elegant pure Swift library for building command line applications.

Build Status

Features

  • Light weight, simple, composed with pure value types.
  • Auto generated help menus for main command and sub-commands.
  • Help menu format is based on swift package manager
  • Supports multi command callbacks.
  • Swift 3 compatibility
  • Zero dependency
  • Supports Linux and swift build

Requirements

  • Mac OS X 10.10+ / Ubuntu 14.10
  • Xcode 8
  • Swift 3

Usage

CommandCougar supports a main command as well as subcommands. This is much like the swift package manager interface.

Consider this command

swift package -v update --repin

swift is the main command.

package is a subcommand of the swift command with -v as an option.

update is a subcommand of the package command with --repin as an option.

Simple Example

This example parses swift package -v update --repin and performs an echo callback each command

func echo(evaluation: Command.Evaluation) throws {
  print(
    "\(evaluation.name) evaluated with " +
    "options: \(evaluation.options) " +
    "and parameters \(evaluation.parameters)"
    )
}

let swiftCommand =
Command.Description(
    name: "swift",
    overview: "Swift Program",
    callback: echo,
    options: [],
    subCommands: [
        Command.Description(
            name: "package",
            overview: "Perform operations on Swift packages",
            callback: echo,
            options: [
                Option.Description(
                    flag: .both(short: "v", long: "verbose"),
                    overview: "Increase verbosity of informational output"),
                Option.Description(
                    flag: .long("enable-prefetching"),
                    overview: "Increase verbosity of informational output")
            ],
            subCommands: [
                Command.Description(
                    name: "update",
                    overview: "Update package dependencies",
                    callback: echo,
                    options: [
                        Option.Description(
                            flag: .long("repin"),
                            overview: "Update without applying pins and repin the updated versions.")
                    ],
                    subCommands: [])
            ])
    ])


do {
  // args normally is CommandLine.arguments
    let args = ["swift", "package", "-v", "update", "--repin"]
    let evaluation: Command.Evaluation = try swiftCommand.evaluate(arguments: args)
    try evaluation.performCallbacks()
} catch {
    print(error)
}

// Output
// swift evaluated with  options: []  and parameters []
// package evaluated with  options: [-v]  and parameters []
// update evaluated with  options: [--repin]  and parameters []

Accessing the values of the Command.Evaluation

To directly access the values of the returned Command.Evaluation

evaluation["package"]?.name  // results in "package"

evaluation["package"]?.options["v"] // results in Option.Evaluation

evaluation["package"]?.options["v"]?.flag.shortName // results in "v"

evaluation["package"]?.options["enable-prefetching"] // results in nil

evaluation["package update"]?.options["repin"]?.flag.longName // results in "repin"

Help menu automatically generated

The help menu for each subcommand is auto generated and the option is added to the command.

$ swift --help
OVERVIEW: Swift Program

USAGE: swift [option] <command>

COMMANDS:
   package                       Perform operations on Swift packages

OPTIONS:
   -h, --help                    The help menu

Help is also generated for subcommands

$ swift package --help
OVERVIEW: Perform operations on Swift packages

USAGE: swift package [option] <command>

COMMANDS:
   update                        Update package dependencies

OPTIONS:
   -v, --verbose                 Increase verbosity of informational output
   --enable-prefetching          Enable prefetching in resolver
   -h, --help                    The help menu

Creating a Command.Description

The Command.Description struct is used to represent how this command should be parsed.

Here is a Command.Description that will evaluate the above command.

let swiftCommand =
Command.Description(
    name: "swift",
    overview: "Swift Program",
    callback: swiftCallback,
    options: [],
    subCommands: [
      Command.Description(
        name: "package",
        overview: "Perform operations on Swift packages",
        callback: packageCallback,
        options: [
          Option.Description(
            flag: .both(short: "v", long: "verbose"),
            overview: "Increase verbosity of informational output"),
            Option.Description(
              flag: .both(long: "enable-prefetching"),
              overview: "Increase verbosity of informational output")
        ],
        subCommands: [
          Command.Description(
            name: "update",
            overview: "Update package dependencies",
            callback: updateCallback,
            options: [
              Option.Description(
                flag: .long("repin"),
                overview: "Update without applying pins and repin the updated versions.")
            ],
            subCommands: [])
        ])
    ])

Evaluating the Command.Description to create a Command.Evaluation

let args = CommandLine.arguments
let evaluation: Command.Evaluation = try swiftCommand.evaluate(arguments: args)

Performing callbacks on a Command.Evaluation

try evaluation.performCallbacks()

This will perform three callbacks:

swiftCallback: No options and no commands passed

packageCallback: -v as an option

updateCallback: --repin as an option

Communication

  • If you found a bug, open an issue.
  • If you have a feature request, open an issue.
  • If you want to contribute, open an issue or submit a pull request.

Installation

Swift Package Manager

dependencies: [
    .Package(url: "https://github.com/surfandneptune/CommandCougar.git", majorVersion: 1)
]

License

CommandCougar is released under the MIT license. See LICENSE for details.

Description

  • Swift Tools 3.1.0
View More Packages from this Author

Dependencies

  • None
Last updated: Tue Jan 31 2023 07:47:25 GMT-0500 (GMT-05:00)