diff --git a/CHANGELOG.md b/CHANGELOG.md index 745dff17e..194819339 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,18 +4,30 @@ Add new items at the end of the relevant section under **Unreleased**. --> -This project follows semantic versioning. While still in major version `0`, -source-stability is only guaranteed within minor versions (e.g. between -`0.0.3` and `0.0.4`). If you want to guard against potentially source-breaking -package updates, you can specify your package dependency using -`.upToNextMinor(from: "0.5.0")` as the requirement. - ## [Unreleased] *No changes yet.* --- +## [1.0.0] - 2021-09-10 + +The 1.0 release marks an important milestone — +`ArgumentParser` is now source stable! + +### Changes + +- `ArgumentParser` now provides a DocC documentation catalog, so you + can view rendered articles and symbol documentation directly within + Xcode. + +### Fixes + +- Parsing works as expected for options with single-dash names that + are declared using the `.upToNextOption` parsing strategy. + +--- + ## [0.5.0] - 2021-09-02 ### Additions @@ -515,7 +527,8 @@ This changelog's format is based on [Keep a Changelog](https://keepachangelog.co -[Unreleased]: https://github.com/apple/swift-argument-parser/compare/0.5.0...HEAD +[Unreleased]: https://github.com/apple/swift-argument-parser/compare/1.0.0...HEAD +[1.0.0]: https://github.com/apple/swift-argument-parser/compare/0.5.0...1.0.0 [0.5.0]: https://github.com/apple/swift-argument-parser/compare/0.4.4...0.5.0 [0.4.4]: https://github.com/apple/swift-argument-parser/compare/0.4.3...0.4.4 [0.4.3]: https://github.com/apple/swift-argument-parser/compare/0.4.2...0.4.3 diff --git a/Package@swift-5.5.swift b/Package@swift-5.5.swift index eb096c191..dd9926cb6 100644 --- a/Package@swift-5.5.swift +++ b/Package@swift-5.5.swift @@ -12,7 +12,7 @@ import PackageDescription -var package = Package( +let package = Package( name: "swift-argument-parser", products: [ .library( @@ -60,17 +60,12 @@ var package = Package( name: "ArgumentParserUnitTests", dependencies: ["ArgumentParser", "ArgumentParserTestHelpers"], exclude: ["CMakeLists.txt"]), + .testTarget( + name: "ArgumentParserPackageManagerTests", + dependencies: ["ArgumentParser", "ArgumentParserTestHelpers"], + exclude: ["CMakeLists.txt"]), .testTarget( name: "ArgumentParserExampleTests", dependencies: ["ArgumentParserTestHelpers"]), ] ) - -#if swift(>=5.2) -// Skip if < 5.2 to avoid issue with nested type synthesized 'CodingKeys' -package.targets.append( - .testTarget( - name: "ArgumentParserPackageManagerTests", - dependencies: ["ArgumentParser", "ArgumentParserTestHelpers"], - exclude: ["CMakeLists.txt"])) -#endif diff --git a/README.md b/README.md index 513478a1f..023d331de 100644 --- a/README.md +++ b/README.md @@ -5,12 +5,13 @@ 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. +and then declare conformance to `ParsableCommand` and add the `@main` attribute. +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 @@ -33,11 +34,8 @@ struct Repeat: ParsableCommand { } } } - -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. @@ -53,6 +51,7 @@ hello hello $ repeat --count 3 Error: Missing expected argument 'phrase'. +Help: The phrase to repeat. Usage: repeat [--count ] [--include-counter] See 'repeat --help' for more information. $ repeat --help @@ -67,7 +66,8 @@ OPTIONS: -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](https://github.com/apple/swift-argument-parser/tree/main/Documentation). +For more information and documentation about all supported options, +see the library's documentation in Xcode. ## Examples @@ -82,35 +82,40 @@ You can also see examples of `ArgumentParser` adoption among Swift project tools - [`indexstore-db`](https://github.com/apple/indexstore-db/pull/72) is a simple utility with two commands. - [`swift-format`](https://github.com/apple/swift-format/pull/154) uses some advanced features, like custom option values and hidden flags. -## Adding `ArgumentParser` as a Dependency +## Project Status -To use the `ArgumentParser` library in a SwiftPM project, -add the following line to the dependencies in your `Package.swift` file: +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. -```swift -.package(url: "https://github.com/apple/swift-argument-parser", from: "0.5.0"), -``` +The public API of version 1.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. -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: +Future minor versions of the package may introduce changes to these rules as needed. -```swift -.package(url: "https://github.com/apple/swift-argument-parser", .upToNextMinor(from: "0.5.0")), -``` +We'd like 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. -Finally, include `"ArgumentParser"` as a dependency for your executable target: +## 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: [ - .package(url: "https://github.com/apple/swift-argument-parser", from: "0.4.0"), // other dependencies + .package(url: "https://github.com/apple/swift-argument-parser", from: "1.0.0"), ], targets: [ - .target(name: "", dependencies: [ + .executableTarget(name: "", dependencies: [ + // other dependencies .product(name: "ArgumentParser", package: "swift-argument-parser"), ]), // other targets diff --git a/Sources/ArgumentParser/Documentation.docc/Extensions/Flag.md b/Sources/ArgumentParser/Documentation.docc/Extensions/Flag.md index d2be6d8cd..f72c7a3b5 100644 --- a/Sources/ArgumentParser/Documentation.docc/Extensions/Flag.md +++ b/Sources/ArgumentParser/Documentation.docc/Extensions/Flag.md @@ -15,7 +15,7 @@ ### Counted Flags -- ``init(name:help:)-87c7k`` +- ``init(name:help:)`` ### Custom Enumerable Flags @@ -37,7 +37,3 @@ ### Deprecated APIs - ``init()`` -- ``init(name:default:exclusivity:help:)`` -- ``init(name:help:)-5iirr`` -- ``init(name:exclusivity:help:)`` -- ``init(name:exclusivity:help:)``