base on Straightforward, type-safe argument parsing for Swift # 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, and then declare conformance to `ParsableCommand` and add the `@main` attribute. (Note, for `async` renditions of `run`, conform to `AsyncParsableCommand` rather than `ParsableCommand`.) Finally, implement your command's logic in the `run()` method. ```swift import ArgumentParser @main 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? = nil @Argument(help: "The phrase to repeat.") var phrase: String mutating func run() throws { let repeatCount = count ?? 2 for i in 1...repeatCount { if includeCounter { print("\(i): \(phrase)") } else { print(phrase) } } } } ``` 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'. Help: <phrase> The phrase to repeat. 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. ``` ## Documentation For guides, articles, and API documentation see the [library's documentation on the Web][docs] or in Xcode. - [ArgumentParser documentation][docs] - [Getting Started with ArgumentParser](https://swiftpackageindex.com/apple/swift-argument-parser/documentation/argumentparser/gettingstarted) - [`ParsableCommand` documentation](https://swiftpackageindex.com/apple/swift-argument-parser/documentation/argumentparser/parsablecommand) - [`AsyncParsableCommand` documentation](https://swiftpackageindex.com/apple/swift-argument-parser/documentation/argumentparser/asyncparsablecommand) [docs]: https://swiftpackageindex.com/apple/swift-argument-parser/documentation/argumentparser #### Examples This repository includes a few examples of using the library: - [`repeat`](Examples/repeat/Repeat.swift) is the example shown above. - [`roll`](Examples/roll/main.swift) is a simple utility implemented as a straight-line script. - [`math`](Examples/math/Math.swift) is an annotated example of using nested commands and subcommands. - [`count-lines`](Examples/count-lines/CountLines.swift) uses `async`/`await` code in its implementation. You can also see examples of `ArgumentParser` adoption among Swift project tools: - [`swift-format`](https://github.com/apple/swift-format/) uses some advanced features, like custom option values and hidden flags. - [`swift-package-manager`](https://github.com/apple/swift-package-manager/) includes a deep command hierarchy and extensive use of option groups. ## Project Status The Swift Argument Parser package is source-stable; version numbers follow semantic versioning. Source-breaking changes to public API can only land in a new major version. The public API of version 1.0.0 of the `swift-argument-parser` package consists of non-underscored declarations that are marked public in the `ArgumentParser` module. Interfaces that aren't part of the public API may continue to change in any release, including the exact wording and formatting of the autogenerated help and error messages, as well as the package’s examples, tests, utilities, and documentation. Future minor versions of the package may introduce changes to these rules as needed. We want this package to quickly embrace Swift language and toolchain improvements that are relevant to its mandate. Accordingly, from time to time, we expect that new versions of this package will require clients to upgrade to a more recent Swift toolchain release. Requiring a new Swift release will only require a minor version bump. ## Adding `ArgumentParser` as a Dependency To use the `ArgumentParser` library in a SwiftPM project, add it to the dependencies for your package and your command-line executable target: ```swift let package = Package( // name, platforms, products, etc. dependencies: [ // other dependencies .package(url: "https://github.com/apple/swift-argument-parser", from: "1.3.0"), ], targets: [ .executableTarget(name: "<command-line-tool>", dependencies: [ // other dependencies .product(name: "ArgumentParser", package: "swift-argument-parser"), ]), // other targets ] ) ``` ### Supported Versions The minimum Swift version supported by swift-argument-parser releases are detailed below: swift-argument-parser | Minimum Swift Version ----------------------|---------------------- `0.0.1 ..< 0.2.0` | 5.1 `0.2.0 ..< 1.1.0` | 5.2 `1.1.0 ..< 1.3.0` | 5.5 `1.3.0 ...` | 5.7 ", Assign "at most 3 tags" to the expected json: {"id":"10811","tags":[]} "only from the tags list I provide: [{"id":77,"name":"3d"},{"id":89,"name":"agent"},{"id":17,"name":"ai"},{"id":54,"name":"algorithm"},{"id":24,"name":"api"},{"id":44,"name":"authentication"},{"id":3,"name":"aws"},{"id":27,"name":"backend"},{"id":60,"name":"benchmark"},{"id":72,"name":"best-practices"},{"id":39,"name":"bitcoin"},{"id":37,"name":"blockchain"},{"id":1,"name":"blog"},{"id":45,"name":"bundler"},{"id":58,"name":"cache"},{"id":21,"name":"chat"},{"id":49,"name":"cicd"},{"id":4,"name":"cli"},{"id":64,"name":"cloud-native"},{"id":48,"name":"cms"},{"id":61,"name":"compiler"},{"id":68,"name":"containerization"},{"id":92,"name":"crm"},{"id":34,"name":"data"},{"id":47,"name":"database"},{"id":8,"name":"declarative-gui "},{"id":9,"name":"deploy-tool"},{"id":53,"name":"desktop-app"},{"id":6,"name":"dev-exp-lib"},{"id":59,"name":"dev-tool"},{"id":13,"name":"ecommerce"},{"id":26,"name":"editor"},{"id":66,"name":"emulator"},{"id":62,"name":"filesystem"},{"id":80,"name":"finance"},{"id":15,"name":"firmware"},{"id":73,"name":"for-fun"},{"id":2,"name":"framework"},{"id":11,"name":"frontend"},{"id":22,"name":"game"},{"id":81,"name":"game-engine "},{"id":23,"name":"graphql"},{"id":84,"name":"gui"},{"id":91,"name":"http"},{"id":5,"name":"http-client"},{"id":51,"name":"iac"},{"id":30,"name":"ide"},{"id":78,"name":"iot"},{"id":40,"name":"json"},{"id":83,"name":"julian"},{"id":38,"name":"k8s"},{"id":31,"name":"language"},{"id":10,"name":"learning-resource"},{"id":33,"name":"lib"},{"id":41,"name":"linter"},{"id":28,"name":"lms"},{"id":16,"name":"logging"},{"id":76,"name":"low-code"},{"id":90,"name":"message-queue"},{"id":42,"name":"mobile-app"},{"id":18,"name":"monitoring"},{"id":36,"name":"networking"},{"id":7,"name":"node-version"},{"id":55,"name":"nosql"},{"id":57,"name":"observability"},{"id":46,"name":"orm"},{"id":52,"name":"os"},{"id":14,"name":"parser"},{"id":74,"name":"react"},{"id":82,"name":"real-time"},{"id":56,"name":"robot"},{"id":65,"name":"runtime"},{"id":32,"name":"sdk"},{"id":71,"name":"search"},{"id":63,"name":"secrets"},{"id":25,"name":"security"},{"id":85,"name":"server"},{"id":86,"name":"serverless"},{"id":70,"name":"storage"},{"id":75,"name":"system-design"},{"id":79,"name":"terminal"},{"id":29,"name":"testing"},{"id":12,"name":"ui"},{"id":50,"name":"ux"},{"id":88,"name":"video"},{"id":20,"name":"web-app"},{"id":35,"name":"web-server"},{"id":43,"name":"webassembly"},{"id":69,"name":"workflow"},{"id":87,"name":"yaml"}]" returns me the "expected json"