Duplicative approach to async support

This duplicates ParsableCommand in an attempt to provide async command
support in a non-source-breaking way. It's only partially functional,
as it would need a solution for AsyncParsableCommands to provide
a subcommand tree with other async commands, while CommandConfig only
supports the extant, non-async ParsableCommand type.

Issues that I'm working around:

- Switching ParsableCommand to have async main() and run() methods is
  source-breaking for any code that calls either method manually.
  Calling main() manually, in particular, was the documented way to
  use ArgumentParser for a long time, so this breakage would be
  significant.

- Adding an AsyncParsableCommand protocol that extends ParsableCommand
  causes problems because overload resolution of `static func main`
  seems problematic. When a type conforms to `AsyncParsableCommand`
  and receives both an async and non-async `main` function (via
  protocol extension or any other means I can find), the compiler
  treats them as ambiguous and rejects the @main attribute.

Not currently supported:
- Command configuration in AsyncParsableCommand, including subcommands
  and help information.

Author: natecook1000

Examples/math/main.swift renamed to Examples/math/Math.swift

@@ -11,6 +11,7 @@
 
 import ArgumentParser
 
+@main
 struct Math: ParsableCommand {
     // Customize your command's help and subcommands by implementing the
     // `configuration` property.
@@ -242,5 +243,3 @@ func customCompletion(_ s: [String]) -> [String] {
     ? ["aardvark", "aaaaalbert"]
     : ["hello", "helicopter", "heliotrope"]
 }
-
-Math.main()

Examples/repeat/main.swift renamed to Examples/repeat/Repeat.swift

@@ -11,6 +11,7 @@
 
 import ArgumentParser
 
+@main
 struct Repeat: ParsableCommand {
     @Option(help: "The number of times to repeat 'phrase'.")
     var count: Int?
@@ -33,5 +34,3 @@ struct Repeat: ParsableCommand {
         }
     }
 }
-
-Repeat.main()

Package.swift

@@ -1,4 +1,4 @@
-// swift-tools-version:5.2
+// swift-tools-version:5.5
 //===----------------------------------------------------------*- swift -*-===//
 //
 // This source file is part of the Swift Argument Parser open source project
@@ -12,8 +12,9 @@
 
 import PackageDescription
 
-var package = Package(
+let package = Package(
     name: "swift-argument-parser",
+    platforms: [.macOS(.v12)],
     products: [
         .library(
             name: "ArgumentParser",
@@ -23,48 +24,49 @@ var package = Package(
     targets: [
         .target(
             name: "ArgumentParser",
-            dependencies: ["ArgumentParserToolInfo"]),
+            dependencies: ["ArgumentParserToolInfo"],
+            exclude: ["CMakeLists.txt"]),
         .target(
             name: "ArgumentParserTestHelpers",
-            dependencies: ["ArgumentParser", "ArgumentParserToolInfo"]),
+            dependencies: ["ArgumentParser", "ArgumentParserToolInfo"],
+            exclude: ["CMakeLists.txt"]),
         .target(
             name: "ArgumentParserToolInfo",
-            dependencies: []),
+            dependencies: [],
+            exclude: ["CMakeLists.txt"]),
 
-        .target(
+        .executableTarget(
             name: "roll",
             dependencies: ["ArgumentParser"],
             path: "Examples/roll"),
-        .target(
+        .executableTarget(
             name: "math",
             dependencies: ["ArgumentParser"],
             path: "Examples/math"),
-        .target(
+        .executableTarget(
             name: "repeat",
             dependencies: ["ArgumentParser"],
             path: "Examples/repeat"),
 
-        .target(
+        .executableTarget(
             name: "changelog-authors",
             dependencies: ["ArgumentParser"],
             path: "Tools/changelog-authors"),
 
         .testTarget(
             name: "ArgumentParserEndToEndTests",
-            dependencies: ["ArgumentParser", "ArgumentParserTestHelpers"]),
+            dependencies: ["ArgumentParser", "ArgumentParserTestHelpers"],
+            exclude: ["CMakeLists.txt"]),
         .testTarget(
             name: "ArgumentParserUnitTests",
-            dependencies: ["ArgumentParser", "ArgumentParserTestHelpers"]),
+            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"]))
-#endif

[email protected]

@@ -0,0 +1,87 @@
+//===----------------------------------------------------------*- swift -*-===//
+//
+// This source file is part of the Swift Argument Parser open source project
+//
+// Copyright (c) 2020 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+//
+//===----------------------------------------------------------------------===//
+
+/// A type that can be executed as part of a nested tree of commands.
+public protocol AsyncParsableCommand: ParsableArguments {
+  /// Runs this command.
+  ///
+  /// After implementing this method, you can run your command-line
+  /// application by calling the static `main()` method on the root type.
+  /// This method has a default implementation that prints help text
+  /// for this command.
+  mutating func run() async throws
+}
+
+extension AsyncParsableCommand {
+  public mutating func run() async throws {
+    throw CleanExit.helpRequest(Self.asCommand)
+  }
+}
+
+// MARK: - API
+
+extension AsyncParsableCommand {
+  /// Parses an instance of this type, or one of its subcommands, from
+  /// command-line arguments.
+  ///
+  /// - Parameter arguments: An array of arguments to use for parsing. If
+  ///   `arguments` is `nil`, this uses the program's command-line arguments.
+  /// - Returns: A new instance of this type, one of its subcommands, or a
+  ///   command type internal to the `ArgumentParser` library.
+  public static func parseAsRoot(
+    _ arguments: [String]? = nil
+  ) throws -> AsyncParsableCommand {
+    var parser = CommandParser(self.asCommand)
+    let arguments = arguments ?? Array(CommandLine.arguments.dropFirst())
+    return try parser.parse(arguments: arguments).get() as! AsyncParsableCommand
+  }
+  
+  /// Returns the text of the help screen for the given subcommand of this
+  /// command.
+  ///
+  /// - Parameters:
+  ///   - subcommand: The subcommand to generate the help screen for.
+  ///     `subcommand` must be declared in the subcommand tree of this
+  ///     command.
+  ///   - columns: The column width to use when wrapping long line in the
+  ///     help screen. If `columns` is `nil`, uses the current terminal
+  ///     width, or a default value of `80` if the terminal width is not
+  ///     available.
+  public static func helpMessage(
+    for subcommand: ParsableCommand.Type,
+    columns: Int? = nil
+  ) -> String { 
+    let stack = CommandParser(self.asCommand).commandStack(for: subcommand)
+    return HelpGenerator(commandStack: stack).rendered(screenWidth: columns)
+  }
+
+  /// Parses an instance of this type, or one of its subcommands, from
+  /// the given arguments and calls its `run()` method, exiting with a
+  /// relevant error message if necessary.
+  ///
+  /// - Parameter arguments: An array of arguments to use for parsing. If
+  ///   `arguments` is `nil`, this uses the program's command-line arguments.
+  public static func main(_ arguments: [String]?) async {
+    do {
+      var command = try parseAsRoot(arguments)
+      try await command.run()
+    } catch {
+      exit(withError: error)
+    }
+  }
+
+  /// Parses an instance of this type, or one of its subcommands, from
+  /// command-line arguments and calls its `run()` method, exiting with a
+  /// relevant error message if necessary.
+  public static func main() async {
+    await self.main(nil)
+  }
+}

Sources/ArgumentParser/Parsable Types/AsyncParsableCommand.swift

@@ -2,7 +2,7 @@
 //
 // This source file is part of the Swift Argument Parser open source project
 //
-// Copyright (c) 2020 Apple Inc. and the Swift project authors
+// Copyright (c) 2020-2021 Apple Inc. and the Swift project authors
 // Licensed under Apache License v2.0 with Runtime Library Exception
 //
 // See https://swift.org/LICENSE.txt for license information
@@ -12,50 +12,10 @@
 import ArgumentParser
 import Foundation
 
-// MARK: GitHub API response modeling
-
-struct Comparison: Codable {
-  var commits: [Commit]
-}
-
-struct Commit: Codable {
-  var sha: String
-  var author: Author
-}
-
-struct Author: Codable {
-  var login: String
-  var htmlURL: String
-  
-  enum CodingKeys: String, CodingKey {
-    case login
-    case htmlURL = "html_url"
-  }
-  
-  var inlineLink: String {
-    "[\(login)]"
-  }
-}
-
-// MARK: Helpers
-
-extension Sequence {
-  func uniqued<T: Hashable>(by transform: (Element) throws -> T) rethrows -> [Element] {
-    var seen: Set<T> = []
-    var result: [Element] = []
-    
-    for element in self {
-      if try seen.insert(transform(element)).inserted {
-        result.append(element)
-      }
-    }
-    return result
-  }
-}
-
 // MARK: Command
 
-struct ChangelogAuthors: ParsableCommand {
+@main
+struct ChangelogAuthors: AsyncParsableCommand {  
   static var configuration: CommandConfiguration {
     CommandConfiguration(
       abstract: "A helper tool for generating author info for the changelog.",
@@ -128,8 +88,8 @@ struct ChangelogAuthors: ParsableCommand {
     return url
   }
 
-  mutating func run() throws {
-    let data = try Data(contentsOf: try comparisonURL())
+  mutating func run() async throws {
+    let (data, _) = try await URLSession.shared.data(from: try comparisonURL())
     let comparison = try JSONDecoder().decode(Comparison.self, from: data)
     let authors = comparison.commits.map({ $0.author })
       .uniqued(by: { $0.login })
@@ -140,6 +100,3 @@ struct ChangelogAuthors: ParsableCommand {
     print(references(for: authors))
   }
 }
-
-ChangelogAuthors.main()
-

Tools/changelog-authors/main.swift renamed to Tools/changelog-authors/ChangelogAuthors.swift

@@ -0,0 +1,35 @@
+//===----------------------------------------------------------*- swift -*-===//
+//
+// This source file is part of the Swift Argument Parser open source project
+//
+// Copyright (c) 2021 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+//
+//===----------------------------------------------------------------------===//
+
+// MARK: GitHub API response modeling
+
+struct Comparison: Codable {
+  var commits: [Commit]
+}
+
+struct Commit: Codable {
+  var sha: String
+  var author: Author
+}
+
+struct Author: Codable {
+  var login: String
+  var htmlURL: String
+  
+  enum CodingKeys: String, CodingKey {
+    case login
+    case htmlURL = "html_url"
+  }
+  
+  var inlineLink: String {
+    "[\(login)]"
+  }
+}