Support async custom completion functions for AsyncParsableCommand via async/await (#855)

* Support async custom completion functions for AsyncParsableCommand via async/await.
* Improve ParsableArguments#_errorLabel DocC.
* Fix preexisting typo.

Signed-off-by: Ross Goldberg <484615+rgoldberg@users.noreply.github.com>

Author: rgoldberg

Sources/ArgumentParser/CMakeLists.txt

@@ -49,7 +49,8 @@ add_library(ArgumentParser
   Utilities/StringExtensions.swift
   Utilities/SwiftExtensions.swift
   Utilities/Tree.swift
-  
+
+  Validators/AsyncCompletionsValidator.swift
   Validators/CodingKeyValidator.swift
   Validators/NonsenseFlagsValidator.swift
   Validators/ParsableArgumentsValidation.swift

Sources/ArgumentParser/Parsable Properties/CompletionKind.swift

@@ -41,12 +41,7 @@ public struct CompletionKind {
     case directory
     case shellCommand(String)
     case custom(@Sendable ([String], Int, String) -> [String])
-    #if !canImport(Dispatch)
-    @available(*, unavailable, message: "DispatchSemaphore is unavailable")
     case customAsync(@Sendable ([String], Int, String) async -> [String])
-    #else
-    case customAsync(@Sendable ([String], Int, String) async -> [String])
-    #endif
     case customDeprecated(@Sendable ([String]) -> [String])
   }
 
@@ -186,22 +181,12 @@ public struct CompletionKind {
   ///
   /// The same as `custom(@Sendable @escaping ([String], Int, String) -> [String])`,
   /// except that the closure is asynchronous.
-  #if !canImport(Dispatch)
-  @available(*, unavailable, message: "DispatchSemaphore is unavailable")
-  @available(macOS 10.15, macCatalyst 13, iOS 13, tvOS 13, watchOS 6, *)
-  public static func custom(
-    _ completion: @Sendable @escaping ([String], Int, String) async -> [String]
-  ) -> CompletionKind {
-    fatalError("DispatchSemaphore is unavailable")
-  }
-  #else
   @available(macOS 10.15, macCatalyst 13, iOS 13, tvOS 13, watchOS 6, *)
   public static func custom(
     _ completion: @Sendable @escaping ([String], Int, String) async -> [String]
   ) -> CompletionKind {
     CompletionKind(kind: .customAsync(completion))
   }
-  #endif
 
   /// Deprecated; only kept for backwards compatibility.
   ///

Sources/ArgumentParser/Parsable Types/AsyncParsableCommand.swift

@@ -25,6 +25,34 @@ public protocol AsyncParsableCommand: ParsableCommand {
 
 @available(macOS 10.15, macCatalyst 13, iOS 13, tvOS 13, watchOS 6, *)
 extension AsyncParsableCommand {
+  /// Parses a new instance of this type 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.
+  /// - Throws: If parsing failed or arguments contains a help request.
+  public static func parse(
+    _ arguments: [String]? = nil
+  ) async throws -> Self {
+    try parse(try await parseAsRoot(arguments))
+  }
+
+  /// 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.
+  /// - Throws: If parsing fails.
+  public static func parseAsRoot(
+    _ arguments: [String]? = nil
+  ) async throws -> ParsableCommand {
+    var parser = CommandParser(self)
+    let arguments = arguments ?? Array(CommandLine._staticArguments.dropFirst())
+    return try await parser.parse(arguments: arguments)
+  }
+
   /// Executes this command, or one of its subcommands, with the given arguments.
   ///
   /// This method parses an instance of this type, one of its subcommands, or
@@ -36,7 +64,7 @@ extension AsyncParsableCommand {
   ///   `arguments` is `nil`, this uses the program's command-line arguments.
   public static func main(_ arguments: [String]?) async {
     do {
-      var command = try parseAsRoot(arguments)
+      var command = try await parseAsRoot(arguments)
       if var asyncCommand = command as? AsyncParsableCommand {
         try await asyncCommand.run()
       } else {

Sources/ArgumentParser/Parsable Types/ParsableArguments.swift

@@ -26,7 +26,7 @@ public protocol ParsableArguments: Decodable, _SendableMetatype {
 
   /// The label to use for "Error: ..." messages from this type (experimental).
   ///
-  /// Can be ignored if `_errorPrefix`'s is changed.
+  /// `_errorLabel` will be ignored if `_errorPrefix` is changed to ignore `_errorLabel`.
   @available(*, deprecated, message: "Use _errorPrefix instead.")
   static var _errorLabel: String { get }
 
@@ -88,9 +88,15 @@ extension ParsableArguments {
   /// - Throws: If parsing failed or arguments contains a help request.
   public static func parse(
     _ arguments: [String]? = nil
+  ) throws -> Self {
+    try parse(try self.asCommand.parseAsRoot(arguments))
+  }
+
+  internal static func parse(
+    _ command: ParsableCommand
   ) throws -> Self {
     // Parse the command and unwrap the result if necessary.
-    switch try self.asCommand.parseAsRoot(arguments) {
+    switch command {
     case let helpCommand as HelpCommand:
       throw ParserError.helpRequested(visibility: helpCommand.visibility)
     case let result as _WrappedParsableCommand<Self>: