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.
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.
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.5.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.5.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.4.0"),
// other dependencies
],
targets: [
.target(name: "<command-line-tool>", dependencies: [
.product(name: "ArgumentParser", package: "swift-argument-parser"),
]),
// other targets
]
)