Swiftpack.co - Package - apple/swift-argument-parser

Swift Argument Parser

Usage

Begin by declaring a type that defines the information that you need to collect from the command line. Decorate each stored property with one of ArgumentParser's property wrappers, declare conformance to ParsableCommand, and implement your command's logic in the run() method.

import ArgumentParser

struct Repeat: ParsableCommand {
    @Flag(help: "Include a counter with each repetition.")
    var includeCounter = false

    @Option(name: .shortAndLong, help: "The number of times to repeat 'phrase'.")
    var count: Int?

    @Argument(help: "The phrase to repeat.")
    var phrase: String

    mutating func run() throws {
        let repeatCount = count ?? .max

        for i in 1...repeatCount {
            if includeCounter {
                print("\(i): \(phrase)")
            } else {
                print(phrase)
            }
        }
    }
}

Repeat.main()

You kick off execution by calling your type's static main() method. The ArgumentParser library parses the command-line arguments, instantiates your command type, and then either executes your run() method or exits with a useful message.

ArgumentParser uses your properties' names and type information, along with the details you provide using property wrappers, to supply useful error messages and detailed help:

$ repeat hello --count 3
hello
hello
hello
$ repeat --count 3
Error: Missing expected argument 'phrase'.
Usage: repeat [--count <count>] [--include-counter] <phrase>
  See 'repeat --help' for more information.
$ repeat --help
USAGE: repeat [--count <count>] [--include-counter] <phrase>

ARGUMENTS:
  <phrase>                The phrase to repeat.

OPTIONS:
  --include-counter       Include a counter with each repetition.
  -c, --count <count>     The number of times to repeat 'phrase'.
  -h, --help              Show help for this command.

For more information and documentation about all supported options, see the Documentation folder at the root of the repository.

Examples

This repository includes a few examples of using the library:

  • repeat is the example shown above.
  • roll is a simple utility implemented as a straight-line script.
  • math is an annotated example of using nested commands and subcommands.

You can also see examples of ArgumentParser adoption among Swift project tools:

  • indexstore-db is a simple utility with two commands.
  • swift-format uses some advanced features, like custom option values and hidden flags.

Adding ArgumentParser as a Dependency

To use the ArgumentParser library in a SwiftPM project, add the following line to the dependencies in your Package.swift file:

.package(url: "https://github.com/apple/swift-argument-parser", from: "0.3.0"),

Because ArgumentParser is under active development, source-stability is only guaranteed within minor versions (e.g. between 0.0.3 and 0.0.4). If you don't want potentially source-breaking package updates, use this dependency specification instead:

.package(url: "https://github.com/apple/swift-argument-parser", .upToNextMinor(from: "0.3.0")),

Finally, include "ArgumentParser" as a dependency for your executable target:

let package = Package(
    // name, platforms, products, etc.
    dependencies: [
        .package(url: "https://github.com/apple/swift-argument-parser", from: "0.3.0"),
        // other dependencies
    ],
    targets: [
        .target(name: "<command-line-tool>", dependencies: [
            .product(name: "ArgumentParser", package: "swift-argument-parser"),
        ]),
        // other targets
    ]
)

Github

link
Stars: 1851

Dependencies

Used By

Total: 0

Releases

ArgumentParser 0.3.1 -

Fixes

  • An option or flag can now declare a name with both single- and double- dash prefixes, such as -my-flag and --my-flag. Specify both names in the name parameter when declaring your property:

    @Flag(name: [.long, .customLong("my-flag", withSingleDash: true)])
    var myFlag = false
    
  • Parsing performance improvements.

ArgumentParser 0.3.0 -

Additions

  • Shell completions scripts are now available for Fish.

Changes

  • Array properties without a default value are now treated as required for the user of a command-line tool. In previous versions of the library, these properties defaulted to an empty array; a deprecation was introduced for this behavior in version 0.2.0.

    Migration: Specify an empty array as the default value for properties that should not require user input:

    // old
    @Option var names: [String]
    // new
    @Option var names: [String] = []
    

ArgumentParser 0.2.2 -

Fixes

  • Zsh completion scripts have improved documentation and better support multi-word completion strings, escaped characters, non-standard executable locations, and empty help strings.

ArgumentParser 0.2.1 -

Additions

  • You can now generate Bash and Zsh shell completion scripts for commands, either by using the --generate-completion-script flag when running a command, or by calling the static completionScript(for:) method on a root ParsableCommand type. See the guide to completion scripts for information on customizing and installing the completion script for your command.

Fixes

  • Property wrappers without parameters can now be written without parentheses — e.g. @Flag var verbose = false.
  • When displaying default values for array properties, the help screen now correctly uses the element type's ExpressibleByArgument conformance to generate the description.
  • Running a project that defines a command as its own subcommand now fails with a useful error message.

ArgumentParser 0.2.0 -

Additions

  • You can now specify default values for array properties of parsable types. The default values are overridden if the user provides at least one value as part of the command-line arguments.

Changes

  • This release of swift-argument-parser requires Swift 5.2.

  • Default values for all properties are now written using default initialization syntax, including some values that were previously implicit, such as empty arrays and false for Boolean flags.

    Migration: Specify default values using typical Swift default value syntax to remove the deprecation warnings:

    // old
    @Flag() var verbose: Bool
    // new
    @Flag() var verbose = false
    

    Important: There is a semantic change for flags with inversions that do not have a default value. In previous releases, these flags had a default value of false; starting in 0.2.0, these flags will have no default, and will therefore be required by the user. Specify a default value of false to retain the old behavior.

Fixes

  • Options with multiple names now consistently show the first-declared name in usage and help screens.
  • Default subcommands are indicated in the help screen.
  • User errors with options are now shown before positional argument errors, eliminating some false negative reports.
  • CMake compatibility fixes.

ArgumentParser 0.1.0 -

Additions

  • Error messages and help screens now include information about how to request more help.
  • CMake builds now support installation.

Changes

  • The static func main() method on ParsableCommand no longer returns Never. This allows ParsableCommand types to be designated as the entry point for a Swift executable by using the @main attribute.

    Migration: For most uses, this change is source compatible. If you have used main() where a () -> Never function is explicitly required, you'll need to change your usage or capture the method in another function.

  • Optional no longer conforms to ExpressibleByArgument, to avoid some property declarations that don't make sense.

    Migration: This is source-compatible for all property declarations, with deprecations for optional properties that define an explicit default. If you're using optional values where an ExpressibleByArgument type is expected, such as a generic function, you will need to change your usage or provide an explicit override.

  • ParsableCommand's run() method requirement is now a mutating method, allowing mutations to a command's properties, such as sorting an array of arguments, without additional copying.

    Migration: No changes are required for commands that are executed through the main() method. If you manually parse a command and then call its run() method, you may need to change the command from a constant to a variable.

Removals

  • The @Flag initializers that were deprecated in version 0.0.6 are now marked as unavailable.

Fixes

  • @Option properties of an optional type that use a transform closure now correctly indicate their optionality in the usage string.
  • Correct wrapping and indentation are maintained for abstracts and discussions with short lines.
  • Empty abstracts no longer add extra blank lines to the help screen.
  • Help requests are still honored even when a parsed command fails validation.
  • The -- terminator isn't consumed when parsing a command, so that it can be parsed as a value when a subcommand includes an .unconditionalRemaining argument array.
  • CMake builds work correctly again.

ArgumentParser 0.0.6 -

Additions

  • Command definition validation now checks for name collisions between options and flags.
  • ValidationError.message is now publicly accessible.
  • Added an EnumerableFlag protocol for CaseIterable types that are used to provide the names for flags. When declaring conformance to EnumerableFlag, you can override the name specification and help text for individual flags. See #65 for more detail.
  • When a command that requires arguments is called with no arguments at all, the error message includes the full help text instead of the short usage string. This is intended to provide a better experience for first-time users.
  • Added a helpMessage() method for generating the help text for a command or subcommand.

Deprecations

  • @Flag properties that use CaseIterable/String types as their values are deprecated, and the related @Flag initializers will be removed in a future version.

    Migration: Add EnumerableFlag conformance to the type of these kinds of @Flag properties.

Fixes

  • Errors thrown while parsing in a transform closure are printed correclty instead of a general Invalid state error.
  • Improvements to the guides and in the error message when attempting to access a value from an argument/option/flag definition.
  • Fixed issues in the CMake and Windows build configurations.
  • You can now use an = to join a value with an option's short name when calling a command. This previously only worked for long names.

ArgumentParser 0.0.5 -

Additions

  • You can now specify a version string in a ParsableCommand's configuration. The generated tool will then automatically respond to a --version flag.
  • Command definitions are now validated at runtime in debug mode, to check issues that can't be detected during compilation.

Fixes

  • Deprecation warnings during compilation on Linux have been removed.
  • The validate() method is now called on each command in the matched command stack, instead of only the last command in the stack.

ArgumentParser 0.0.4 -

Fixes

  • Removed usage of 5.2-only syntax.

ArgumentParser 0.0.3 -

Additions

  • You can specify the .unconditionalRemaining parsing strategy for arrays of positional arguments to accept dash-prefixed input, like example --one two -three.
  • You can now provide a default value for a positional argument.
  • You can now customize the display of default values in the extended help for an ExpressibleByArgument type.
  • You can call the static exitCode(for:) method on any command to retrieve the exit code for a given error.

Fixes

  • Supporting targets are now prefixed to prevent conflicts with other libraries.
  • The extension providing init?(argument:) to RawRepresentable types is now properly constrained.
  • The parser no longer treats passing the same exclusive flag more than once as an error.
  • ParsableArguments types that are declared as @OptionGroup() properties on commands can now also be declared on subcommands. Previosuly, the parent command's declaration would prevent subcommands from seeing the user-supplied arguments.
  • Default values are rendered correctly for properties with Optional types.
  • The output of help requests is now printed during the "exit" phase of execution, instead of during the "run" phase.
  • Usage strings now correctly show that optional positional arguments aren't required.
  • Extended help now omits extra line breaks when displaying arguments or commands with long names that don't provide help text.

ArgumentParser 0.0.2 -

Additions

  • The EX_USAGE exit code is now used for validation errors.
  • The parser provides near-miss suggestions when a user provides an unknown option.
  • ArgumentParser now builds on Windows.
  • You can throw an ExitCode error to exit without printing any output.
  • You can now create optional Boolean flags with inversions that default to nil:
    @Flag(inversion: .prefixedNo) var takeMyShot: Bool?
    
  • You can now specify exclusivity for case-iterable flags and for Boolean flags with inversions.

Fixes

  • Cleaned up a wide variety of documentation typos and shortcomings.
  • Improved different kinds of error messages:
    • Duplicate exclusive flags now show the duplicated arguments.
    • Subcommand validation errors print the correct usage string.
  • In the help screen:
    • Removed the extra space before the default value for arguments without descriptions.
    • Removed the default value note when the default value is an empty string.
    • Default values are now shown for Boolean options.
    • Case-iterable flags are now grouped correctly.
    • Case-iterable flags with default values now show the default value.
    • Arguments from parent commands that are included via @OptionGroup in subcommands are no longer duplicated.
  • Case-iterable flags created with the .chooseFirst exclusivity parameter now correctly ignore additional flags.

ArgumentParser 0.0.1 -

Initial release.