Swift Argument Parser

You can configure a command's help display by providing an abstract, discussion, or custom usage string within the CommandConfiguration.

• abstract: A short summary of the command.
• discussion: Detailed information about the command's behavior.
• usage: A custom string defining how the command should be invoked.

struct Repeat: ParsableCommand {
    static let configuration = CommandConfiguration(
        abstract: "Repeats your input phrase.",
        usage: """
            repeat <phrase>
            repeat --count <count> <phrase>
            """,
        discussion: """
            Prints to stdout forever, or until you halt the program.
            """
    )

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

    @Option(help: "How many times to repeat.")
    var count: Int? = nil

    mutating func run() throws {
        for _ in 0..<(count ?? 2) {
            print(phrase) 
        }
    }
}

You can build complex command-line tools by nesting ParsableCommand types. A root command can specify its subcommands and an optional defaultSubcommand using the CommandConfiguration property.

To create a hierarchy:

1. Define a root ParsableCommand.
2. Use CommandConfiguration(subcommands: [...]) to list child commands.
3. For nested subcommands, define a child command that also provides a CommandConfiguration with its own subcommands list.

You can also use commandName in CommandConfiguration to override the default name derived from the type name, or aliases to provide alternative names for invoking a command.

struct Math: ParsableCommand {
    static let configuration = CommandConfiguration(
        abstract: "A utility for performing maths.",
        subcommands: [Add.self, Multiply.self, Statistics.self],
        defaultSubcommand: Add.self
    )
}

// A nested subcommand structure
extension Math {
    struct Statistics: ParsableCommand {
        static let configuration = CommandConfiguration(
            commandName: "stats",
            abstract: "Calculate descriptive statistics.",
            subcommands: [Average.self, StandardDeviation.self]
        )
    }
}

For simple scripts where you don't want to use @main, you can define a type conforming to ParsableArguments and parse command-line inputs manually.

Use parseOrExit(_:) to return an initialized instance or exit the process with an error message and code if parsing fails. Alternatively, use the throwing parse(_:) method if you want to handle errors manually.

To exit the script with a specific error and include usage information, use exit(withError:) passing a ValidationError.

struct SelectOptions: ParsableArguments {
    @Option var count: Int = 1
    @Argument var elements: [String] = []
}

// Parse and exit on failure
let options = SelectOptions.parseOrExit()

// Or parse and catch errors manually
do {
    let options = try SelectOptions.parse(CommandLine.arguments)
} catch {
    // Handle error
}

// Exit with a validation error and usage info
guard options.elements.count >= options.count else {
    let error = ValidationError("Please specify a 'count' less than the number of elements.")
    SelectOptions.exit(withError: error)
}

To use asynchronous code within your command-line tool's run() method, follow these steps:

1. Declare conformance to AsyncParsableCommand for your root command (even if the root command itself doesn't use async code).
2. Apply the @main attribute to the root command. (Note: If you have a main.swift file, you must rename it to the name of the command to avoid conflicts with @main).
3. For any specific command requiring asynchronous logic, declare conformance to AsyncParsableCommand and mark its run() method as async.

Subcommands that do not require asynchronous code do not need any changes and can continue using standard ParsableCommand conformance.

import Foundation
import ArgumentParser

@main
struct CountLines: AsyncParsableCommand {
    @Argument(transform: URL.init(fileURLWithPath:))
    var inputFile: URL

    mutating func run() async throws {
        let fileHandle = try FileHandle(forReadingFrom: inputFile)
        let lineCount = try await fileHandle.bytes.lines.reduce(into: 0) 
            { count, _ in count += 1 }
        print(lineCount)
    }
}