Merge branch 'apple:main' into main

CHANGELOG.md

@@ -6,15 +6,46 @@ Add new items at the end of the relevant section under **Unreleased**.
 
 ## [Unreleased]
 
+*No new changes.*
+
+---
+
+## [1.3.0] - 2023-12-06
+
+### Changes
+
+- The `@Option`, `@Argument`, `@Flag`, and `@OptionGroup` property wrappers now 
+  conditionally conform to `Sendable` when the wrapper's `Value` type conforms. With this
+  change, you can mark `ParsableCommand` types as `Sendable` when you want to be able to
+  pass a parsed command across concurrent contexts. ([#582])
+
+  *Migration:* Users that aren't ready to resolve sendability warnings can add the
+  `@preconcurrency` attribute to `import ArgumentParser` statements.
+
+- To support migration to `Sendable` annotation, the minimum Swift version for
+  `swift-argument-parser` has been increased to Swift 5.7. Users of older Swift versions
+  will be able to continue using version 1.2.3 of the library. ([#582])
+
 ### Additions
 
 - Help screens now include possible options for `ExpressibleByArgument` types
   with non empty `allValueStrings`. Types also conforming to `CaseIterable` do
   not need to manually implement `allValueStrings`, instead it is derived from
   `allCases`. ([#594])
 
-<!-- Add: "Don't remove nested option group titles (#592)" -->
-<!-- Add: "Document ability to skip unknown parameters (#572)" -->
+### Fixes
+
+- The titles for nested option groups are preserved when embedded into commands without
+  specifying a new title. ([#592])
+- When wrapping help and error messages, the library now uses the `COLUMNS` environment
+  variable when set, instead of immediately falling back to 80 columns. ([#596])
+- Bash completion scripts now respect the extensions given in a `.file(...)` completion
+  kind. ([#590])
+- Bash completion scripts now properly escape command names that include hyphens. ([#573])
+- Documentation improvements. ([#572], [#565], [#602])
+
+The 1.3.0 release includes contributions from [Alkenso], [compnerd], [gwynne],
+[kennyyork], [natecook1000], [rauhul], [robertmryan], and [vlm]. Thank you!
 
 ---
 
@@ -803,7 +834,8 @@ This changelog's format is based on [Keep a Changelog](https://keepachangelog.co
 
 <!-- Link references for releases -->
 
-[Unreleased]: https://github.com/apple/swift-argument-parser/compare/1.2.3...HEAD
+[Unreleased]: https://github.com/apple/swift-argument-parser/compare/1.3.0...HEAD
+[1.3.0]: https://github.com/apple/swift-argument-parser/compare/1.2.3...1.3.0
 [1.2.3]: https://github.com/apple/swift-argument-parser/compare/1.2.2...1.2.3
 [1.2.2]: https://github.com/apple/swift-argument-parser/compare/1.2.1...1.2.2
 [1.2.1]: https://github.com/apple/swift-argument-parser/compare/1.2.0...1.2.1
@@ -897,16 +929,25 @@ This changelog's format is based on [Keep a Changelog](https://keepachangelog.co
 [#550]: https://github.com/apple/swift-argument-parser/pull/550
 [#552]: https://github.com/apple/swift-argument-parser/pull/552
 [#554]: https://github.com/apple/swift-argument-parser/pull/554
+[#565]: https://github.com/apple/swift-argument-parser/pull/565
+[#572]: https://github.com/apple/swift-argument-parser/pull/572
+[#573]: https://github.com/apple/swift-argument-parser/pull/573
 [#574]: https://github.com/apple/swift-argument-parser/pull/574
 [#579]: https://github.com/apple/swift-argument-parser/pull/579
-[#579]: https://github.com/apple/swift-argument-parser/pull/594
+[#582]: https://github.com/apple/swift-argument-parser/pull/582
+[#590]: https://github.com/apple/swift-argument-parser/pull/590
+[#592]: https://github.com/apple/swift-argument-parser/pull/592
+[#594]: https://github.com/apple/swift-argument-parser/pull/594
+[#596]: https://github.com/apple/swift-argument-parser/pull/596
+[#602]: https://github.com/apple/swift-argument-parser/pull/602
 
 <!-- Link references for contributors -->
 
 [3405691582]: https://github.com/apple/swift-argument-parser/commits?author=3405691582
 [adellibovi]: https://github.com/apple/swift-argument-parser/commits?author=adellibovi
 [aleksey-mashanov]: https://github.com/apple/swift-argument-parser/commits?author=aleksey-mashanov
 [AliSoftware]: https://github.com/apple/swift-argument-parser/commits?author=AliSoftware
+[Alkenso]: https://github.com/apple/swift-argument-parser/commits?author=Alkenso
 [allevato]: https://github.com/apple/swift-argument-parser/commits?author=allevato
 [artemnovichkov]: https://github.com/apple/swift-argument-parser/commits?author=artemnovichkov
 [atierian]: https://github.com/apple/swift-argument-parser/commits?author=atierian
@@ -968,6 +1009,7 @@ This changelog's format is based on [Keep a Changelog](https://keepachangelog.co
 [rauhul]: https://github.com/apple/swift-argument-parser/commits?author=rauhul
 [rickrizzo]: https://github.com/apple/swift-argument-parser/commits?author=rickrizzo
 [rjstelling]: https://github.com/apple/swift-argument-parser/commits?author=rjstelling
+[robertmryan]: https://github.com/apple/swift-argument-parser/commits?author=robertmryan
 [Sajjon]: https://github.com/apple/swift-argument-parser/commits?author=Sajjon
 [schlagelk]: https://github.com/apple/swift-argument-parser/commits?author=schlagelk
 [SergeyPetrachkov]: https://github.com/apple/swift-argument-parser/commits?author=SergeyPetrachkov
@@ -978,6 +1020,7 @@ This changelog's format is based on [Keep a Changelog](https://keepachangelog.co
 [thomasvl]: https://github.com/apple/swift-argument-parser/commits?author=thomasvl
 [TiagoMaiaL]: https://github.com/apple/swift-argument-parser/commits?author=TiagoMaiaL
 [toddthomas]: https://github.com/apple/swift-argument-parser/commits?author=toddthomas
+[vlm]: https://github.com/apple/swift-argument-parser/commits?author=vlm
 [werm098]: https://github.com/apple/swift-argument-parser/commits?author=werm098
 [Wevah]: https://github.com/apple/swift-argument-parser/commits?author=Wevah
 [Wildchild9]: https://github.com/apple/swift-argument-parser/commits?author=Wildchild9

CMakeLists.txt

@@ -1,27 +1,22 @@
-cmake_minimum_required(VERSION 3.15.1)
-
-list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules)
+cmake_minimum_required(VERSION 3.19)
 
 project(swift-argument-parser
   LANGUAGES Swift)
 
 option(BUILD_EXAMPLES "Build Example Programs" TRUE)
 option(BUILD_SHARED_LIBS "Build shared libraries by default" YES)
 
-include(CTest)
-include(SwiftSupport)
-
-if(CMAKE_VERSION VERSION_LESS 3.16 AND CMAKE_SYSTEM_NAME STREQUAL Windows)
-  set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
-  set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
-else()
-  set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
-  set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
-endif()
+list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules)
 
+set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
+
 set(CMAKE_Swift_MODULE_DIRECTORY ${CMAKE_BINARY_DIR}/swift)
 
+include(CTest)
+include(SwiftSupport)
+
 find_package(dispatch CONFIG)
 find_package(Foundation CONFIG)
 find_package(XCTest CONFIG)

README.md

@@ -123,7 +123,7 @@ let package = Package(
     // name, platforms, products, etc.
     dependencies: [
         // other dependencies
-        .package(url: "https://github.com/apple/swift-argument-parser", from: "1.2.0"),
+        .package(url: "https://github.com/apple/swift-argument-parser", from: "1.3.0"),
     ],
     targets: [
         .executableTarget(name: "<command-line-tool>", dependencies: [
@@ -144,4 +144,4 @@ 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 ...` (future)  | 5.7
+`1.3.0 ...`           | 5.7

Sources/ArgumentParser/Completions/BashCompletionsGenerator.swift

@@ -13,7 +13,7 @@ struct BashCompletionsGenerator {
   /// Generates a Bash completion script for the given command.
   static func generateCompletionScript(_ type: ParsableCommand.Type) -> String {
     // TODO: Add a check to see if the command is installed where we expect?
-    let initialFunctionName = [type].completionFunctionName()
+    let initialFunctionName = [type].completionFunctionName().makeSafeFunctionName
     return """
     #!/bin/bash
 
@@ -26,7 +26,7 @@ struct BashCompletionsGenerator {
   /// Generates a Bash completion function for the last command in the given list.
   fileprivate static func generateCompletionFunction(_ commands: [ParsableCommand.Type]) -> String {
     let type = commands.last!
-    let functionName = commands.completionFunctionName()
+    let functionName = commands.completionFunctionName().makeSafeFunctionName
 
     // The root command gets a different treatment for the parsing index.
     let isRootCommand = commands.count == 1
@@ -240,3 +240,9 @@ extension ArgumentDefinition {
     }
   }
 }
+
+extension String {
+    var makeSafeFunctionName: String {
+        self.replacingOccurrences(of: "-", with: "_")
+    }
+}

Sources/ArgumentParser/Documentation.docc/Articles/GettingStarted.md

@@ -21,7 +21,7 @@ import PackageDescription
 let package = Package(
     name: "Count",
     dependencies: [
-        .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.2.0"),
+        .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.3.0"),
     ],
     targets: [
         .executableTarget(

Sources/ArgumentParser/Documentation.docc/Extensions/Argument.md

@@ -4,7 +4,7 @@
 
 ### Single Arguments
 
-- ``init(help:completion:)-6mld0``
+- ``init(help:completion:)-6pqzn``
 - ``init(help:completion:)-4p94d``
 - ``init(help:completion:transform:)-3fjtc``
 - ``init(help:completion:transform:)-7yn32``
@@ -21,5 +21,4 @@
 
 ### Infrequently Used APIs
 
-- ``init(from:)``
 - ``wrappedValue``

Sources/ArgumentParser/Documentation.docc/Extensions/CommandConfiguration.md

@@ -24,7 +24,3 @@
 - ``version``
 - ``shouldDisplay``
 
-### Deprecated APIs
-
-- ``init(commandName:abstract:discussion:version:shouldDisplay:subcommands:defaultSubcommand:helpNames:)``
-

Sources/ArgumentParser/Documentation.docc/Extensions/Flag.md

@@ -27,7 +27,6 @@
 
 ### Infrequently Used APIs
 
-- ``init(from:)``
 - ``wrappedValue``
 
 ### Supporting Types

Sources/ArgumentParser/Documentation.docc/Extensions/Option.md

@@ -5,12 +5,12 @@
 ### Single Options
 
 - ``init(name:parsing:help:completion:)-7slrf``
-- ``init(name:parsing:help:completion:)-5k0ug``
+- ``init(name:parsing:help:completion:)-4yske``
 - ``init(name:parsing:help:completion:transform:)-2wf44``
 - ``init(name:parsing:help:completion:transform:)-25g7b``
 - ``init(wrappedValue:name:parsing:help:completion:transform:)-2llve``
 - ``SingleValueParsingStrategy``
-- ``init(wrappedValue:name:parsing:help:completion:)-7xcum``
+- ``init(wrappedValue:name:parsing:help:completion:)-7ilku``
 
 ### Array Options
 
@@ -22,11 +22,4 @@
 
 ### Infrequently Used APIs
 
-- ``init(from:)``
 - ``wrappedValue``
-
-### Deprecated APIs
-
-- ``init(wrappedValue:name:parsing:completion:help:)``
-- ``init(wrappedValue:name:parsing:help:completion:)-4pl7h``
-- ``init(wrappedValue:name:parsing:help:completion:transform:)-6rqji``

Sources/ArgumentParser/Documentation.docc/Extensions/OptionGroup.md

@@ -13,7 +13,6 @@
 ### Infrequently Used APIs
 
 - ``init()``
-- ``init(from:)``
 - ``wrappedValue``
 - ``description``
 

Sources/ArgumentParser/Documentation.docc/Extensions/ParsableArguments.md

@@ -22,7 +22,7 @@
 ### Handling Errors
 
 - ``message(for:)``
-- ``fullMessage(for:)``
+- ``fullMessage(for:columns:)``
 - ``exitCode(for:)``
 
 ### Generating Completion Scripts
@@ -33,4 +33,3 @@
 ### Infrequently Used APIs
 
 - ``init()``
-- ``helpMessage(columns:)``

Sources/ArgumentParser/Parsable Properties/Argument.swift

@@ -21,15 +21,17 @@
 /// argument is required, while `greeting` is optional because it has a default
 /// value.
 ///
-///     @main
-///     struct Greet: ParsableCommand {
-///         @Argument var name: String
-///         @Argument var greeting: String = "Hello"
+/// ```swift
+/// @main
+/// struct Greet: ParsableCommand {
+///     @Argument var name: String
+///     @Argument var greeting: String = "Hello"
 ///
-///         mutating func run() {
-///             print("\(greeting) \(name)!")
-///         }
+///     mutating func run() {
+///         print("\(greeting) \(name)!")
 ///     }
+/// }
+/// ```
 ///
 /// You can call this program with just a name or with a name and a
 /// greeting. When you supply both arguments, the first argument is always
@@ -49,8 +51,8 @@ public struct Argument<Value>:
     self._parsedValue = _parsedValue
   }
 
-  public init(from decoder: Decoder) throws {
-    try self.init(_decoder: decoder)
+  public init(from _decoder: Decoder) throws {
+    try self.init(_decoder: _decoder)
   }
 
   /// This initializer works around a quirk of property wrappers, where the

Sources/ArgumentParser/Parsable Properties/Flag.swift

@@ -18,18 +18,20 @@
 /// For example, the following program declares a flag that lets a user indicate
 /// that seconds should be included when printing the time.
 ///
-///     @main
-///     struct Time: ParsableCommand {
-///         @Flag var includeSeconds = false
+/// ```swift
+/// @main
+/// struct Time: ParsableCommand {
+///     @Flag var includeSeconds = false
 ///
-///         mutating func run() {
-///             if includeSeconds {
-///                 print(Date.now.formatted(.dateTime.hour().minute().second()))
-///             } else {
-///                 print(Date.now.formatted(.dateTime.hour().minute()))
-///             }
+///     mutating func run() {
+///         if includeSeconds {
+///             print(Date.now.formatted(.dateTime.hour().minute().second()))
+///         } else {
+///             print(Date.now.formatted(.dateTime.hour().minute()))
 ///         }
 ///     }
+/// }
+/// ```
 ///
 /// `includeSeconds` has a default value of `false`, but becomes `true` if
 /// `--include-seconds` is provided on the command line.
@@ -74,8 +76,8 @@ public struct Flag<Value>: Decodable, ParsedWrapper {
     self._parsedValue = _parsedValue
   }
 
-  public init(from decoder: Decoder) throws {
-    try self.init(_decoder: decoder)
+  public init(from _decoder: Decoder) throws {
+    try self.init(_decoder: _decoder)
   }
 
   /// This initializer works around a quirk of property wrappers, where the