Merge branch 'main' into async

Author: natecook1000

.gitignore

@@ -3,4 +3,5 @@
 /Packages
 /*.xcodeproj
 .swiftpm
+.vscode
 .*.sw?

README.md

@@ -66,10 +66,18 @@ OPTIONS:
   -h, --help              Show help for this command.
 ```
 
-For more information and documentation about all supported options, 
-see the library's documentation in Xcode.
+## Documentation
 
-## Examples
+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://apple.github.io/swift-argument-parser/documentation/argumentparser/gettingstarted)
+- [`ParsableCommand` documentation](https://apple.github.io/swift-argument-parser/documentation/argumentparser/parsablecommand)
+
+[docs]: https://apple.github.io/swift-argument-parser/documentation/argumentparser/
+
+#### Examples
 
 This repository includes a few examples of using the library:
 
@@ -79,8 +87,8 @@ This repository includes a few examples of using the library:
 
 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.
+- [`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
 

Sources/ArgumentParser/Completions/CompletionsGenerator.swift

@@ -15,6 +15,8 @@ import Glibc
 import Darwin
 #elseif canImport(CRT)
 import CRT
+#elseif canImport(WASILibc)
+import WASILibc
 #endif
 
 /// A shell for which the parser can generate a completion script.

Sources/ArgumentParser/Completions/FishCompletionsGenerator.swift

@@ -2,8 +2,8 @@ struct FishCompletionsGenerator {
   static func generateCompletionScript(_ type: ParsableCommand.Type) -> String {
     let programName = type._commandName
     let helper = """
-    function __fish_\(programName)_using_command
-        set cmd (commandline -opc)
+    function _swift_\(programName)_using_command
+        set -l cmd (commandline -opc)
         if [ (count $cmd) -eq (count $argv) ]
             for i in (seq (count $argv))
                 if [ $cmd[$i] != $argv[$i] ]
@@ -14,7 +14,7 @@ struct FishCompletionsGenerator {
         end
         return 1
     end
-
+    
     """
 
     let completions = generateCompletions(commandChain: [programName], [type])
@@ -37,11 +37,11 @@ struct FishCompletionsGenerator {
       }
     }
 
-    let prefix = "complete -c \(programName) -n '__fish_\(programName)_using_command"
+    let prefix = "complete -c \(programName) -n '_swift_\(programName)_using_command"
     /// We ask each suggestion to produce 2 pieces of information
     /// - Parameters
     ///   - ancestors: a list of "ancestor" which must be present in the current shell buffer for
-    ///                this suggetion to be considered. This could be a combination of (nested)
+    ///                this suggestion to be considered. This could be a combination of (nested)
     ///                subcommands and flags.
     ///   - suggestion: text for the actual suggestion
     /// - Returns: A completion expression

Sources/ArgumentParser/Completions/ZshCompletionsGenerator.swift

@@ -185,7 +185,7 @@ extension ArgumentDefinition {
 
     case .custom:
       // Generate a call back into the command to retrieve a completions list
-      let commandName = commands.first!._commandName
+      let commandName = commands.first!._commandName.zshEscapingCommandName()
       return "{_custom_completion $_\(commandName)_commandname \(customCompletionCall(commands)) $words}"
     }
   }

Sources/ArgumentParser/Documentation.docc/ArgumentParser.md

@@ -37,26 +37,12 @@ the `ArgumentParser` library parses the command-line arguments,
 instantiates your command type,
 and then either calls your `run()` method or exits with a useful message.
 
-```
-$ repeat hello --count 3
-hello
-hello
-hello
-$ repeat --help
-USAGE: repeat [--count <count>] <phrase>
-
-ARGUMENTS:
-  <phrase>                The phrase to repeat.
-
-OPTIONS:
-  --count <count>         The number of times to repeat 'phrase'.
-  -h, --help              Show help for this command.
-$ repeat --count 3
-Error: Missing expected argument 'phrase'.
-Help:  <phrase>  The phrase to repeat.
-Usage: repeat [--count <count>] <phrase>
-  See 'repeat --help' for more information.
-```
+![The output of the Repeat command, declared above.](repeat.png)
+
+#### Additional Resources
+
+- [`ArgumentParser` on GitHub](https://github.com/apple/swift-argument-parser/)
+- [`ArgumentParser` on the Swift Forums](https://forums.swift.org/c/related-projects/argumentparser/60)
 
 ## Topics
 
@@ -102,3 +88,4 @@ Usage: repeat [--count <count>] <phrase>
 ### Advanced Topics
 
 - <doc:ManualParsing>
+- <doc:ExperimentalFeatures>

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

@@ -76,7 +76,7 @@ OPTIONS:
 
 ## Customizing Help for Commands
 
-In addition to configuring the command name and subcommands, as described in [Command and Subcommands](03%20Commands%20and%20Subcommands.md), you can also configure a command's help text by providing an abstract and discussion.
+In addition to configuring the command name and subcommands, as described in <doc:CommandsAndSubcommands>, you can also configure a command's help text by providing an abstract and discussion.
 
 ```swift
 struct Repeat: ParsableCommand {
@@ -185,7 +185,7 @@ OPTIONS:
 
 ## Hiding Arguments and Commands
 
-You may want to suppress features under development or experimental flags from the generated help screen. You can hide an argument or a subcommand by passing `shouldDisplay: false` to the property wrapper or `CommandConfiguration` initializers, respectively.
+You may want to suppress features under development or experimental flags from the generated help screen. You can hide an argument or a subcommand by passing `visibility: .hidden` to the property wrapper or `CommandConfiguration` initializers, respectively.
 
 `ArgumentHelp` includes a `.hidden` static property that makes it even simpler to hide arguments:
 

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

@@ -199,7 +199,7 @@ struct Example: ParsableCommand {
 }
 ```
 
-Throw an error from the `transform` function to indicate that the user provided an invalid value for that type. See [Handling Transform Errors](./05%20Validation%20and%20Errors.md#handling-transform-errors) for more about customizing `transform` function errors.
+Throw an error from the `transform` function to indicate that the user provided an invalid value for that type. See <doc:Validation> for more about customizing `transform` function errors.
 
 ## Using flag inversions, enumerations, and counts
 
@@ -255,7 +255,7 @@ struct Example: ParsableCommand {
 }
 ```
 
-The flag names in this case are drawn from the raw values — for information about customizing the names and help text, see the  [`EnumerableFlag` documentation](../Sources/ArgumentParser/Parsable%20Types/EnumerableFlag.swift).
+The flag names in this case are drawn from the raw values — for information about customizing the names and help text, see the  ``EnumerableFlag`` documentation.
 
 ```
 % example --in-memory-cache --pink --silver

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

@@ -0,0 +1,19 @@
+# Experimental Features
+
+Learn about ArgumentParser's experimental features.
+
+## Overview
+
+Command-line programs built using `ArgumentParser` may include some built-in experimental features, available with the prefix `--experimental`. These features should not be considered stable while still prefixed, as future releases may change their behavior or remove them.
+
+If you have any feedback on experimental features, please [open a GitHub issue][issue].
+
+## List of Experimental Features
+
+| Name | Description | related PRs | Version |
+| ------------- | ------------- | ------------- | ------------- |
+| `--experimental-dump-help`  | Dumps command/argument/help information as JSON | [#310][] [#335][] | 0.5.0 or newer |
+
+[#310]: https://github.com/apple/swift-argument-parser/pull/310
+[#335]: https://github.com/apple/swift-argument-parser/pull/335
+[issue]: https://github.com/apple/swift-argument-parser/issues/new/choose 

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

@@ -1,16 +1,16 @@
 # Manual Parsing and Testing
 
-Provide your own array of command-line inputs and work with parsed results by calling alternatives to `main()`.
+Provide your own array of command-line inputs or work directly with parsed command-line arguments.
 
 ## Overview
 
-For most programs, calling the static `main()` method on the root command type is all that's necessary. That single call parses the command-line arguments to find the correct command from your tree of nested subcommands, instantiates and validates the result, and executes the chosen command. For more control, however, you can perform each of those steps manually.
+For most programs, denoting the root command type as `@main` is all that's necessary. As the program's entry point, that type parses the command-line arguments to find the correct command from your tree of nested subcommands, instantiates and validates the result, and executes the chosen command. For more control, however, you can perform each of those steps manually.
 
 ## Parsing Arguments
 
 For simple Swift scripts, and for those who prefer a straight-down-the-left-edge-of-the-screen scripting style, you can define a single `ParsableArguments` type to parse explicitly from the command-line arguments.
 
-Let's implement the `Select` command discussed in [Validation and Errors](05%20Validation%20and%20Errors.md), but using a scripty style instead of the typical command. First, we define the options as a `ParsableArguments` type:
+Let's implement the `Select` command discussed in <doc:Validation>, but using a scripty style instead of the typical command. First, we define the options as a `ParsableArguments` type:
 
 ```swift
 struct SelectOptions: ParsableArguments {
@@ -51,7 +51,7 @@ print(chosen.joined(separator: "\n"))
 
 Manually parsing commands is a little more complex than parsing a simple `ParsableArguments` type. The result of parsing from a tree of subcommands may be of a different type than the root of the tree, so the static `parseAsRoot()` method returns a type-erased `ParsableCommand`.
 
-Let's see how this works by using the `Math` command and subcommands defined in [Commands and Subcommands](03%20Commands%20and%20Subcommands.md). This time, instead of calling `Math.main()`, we'll call `Math.parseAsRoot()`, and switch over the result:
+Let's see how this works by using the `Math` command and subcommands defined in [Commands and Subcommands](./CommandsAndSubcommands.md). This time, instead of calling `Math.main()`, we'll call `Math.parseAsRoot()`, and switch over the result:
 
 ```swift
 do {

Sources/ArgumentParser/Documentation.docc/Images/repeat.png

@@ -120,7 +120,7 @@ extension Argument where Value: ExpressibleByArgument {
   /// ```
   ///
   /// - Parameters:
-  ///   - wrappedValue: A default value to use for this property, provided implicitly by the compiler during propery wrapper initialization.
+  ///   - wrappedValue: A default value to use for this property, provided implicitly by the compiler during property wrapper initialization.
   ///   - help: Information about how to use this argument.
   public init(
     wrappedValue: Value,
@@ -481,7 +481,7 @@ extension Argument {
   ///
   /// This method is called to initialize an array `Argument` with no default value such as:
   /// ```swift
-  /// @Argument(tranform: baz)
+  /// @Argument(transform: baz)
   /// var foo: [String]
   /// ```
   ///

Sources/ArgumentParser/Parsable Properties/Argument.swift

@@ -11,6 +11,18 @@
 
 /// Help information for a command-line argument.
 public struct ArgumentHelp {
+  /// Visibility level of an argument's help.
+  public enum Visibility {
+      /// Show help for this argument whenever appropriate.
+      case `default`
+
+      /// Only show help for this argument in the extended help screen.
+      case hidden
+
+      /// Never show help for this argument.
+      case `private`
+  }
+
   /// A short description of the argument.
   public var abstract: String = ""
 
@@ -24,26 +36,57 @@ public struct ArgumentHelp {
   ///   flags don't include a value.
   public var valueName: String?
 
+  /// A visibility level indicating whether this argument should be shown in
+  /// the extended help display.
+  public var visibility: Visibility = .default
+
   /// A Boolean value indicating whether this argument should be shown in
   /// the extended help display.
-  public var shouldDisplay: Bool = true
+  @available(*, deprecated, message: "Use visibility level instead.")
+  public var shouldDisplay: Bool {
+    get {
+      return visibility == .default
+    }
+    set {
+      visibility = newValue ? .default : .hidden
+    }
+  }
 
   /// Creates a new help instance.
+  @available(*, deprecated, message: "Use init(_:discussion:valueName:visibility:) instead.")
   public init(
     _ abstract: String = "",
     discussion: String = "",
     valueName: String? = nil,
-    shouldDisplay: Bool = true)
+    shouldDisplay: Bool)
   {
     self.abstract = abstract
     self.discussion = discussion
     self.valueName = valueName
     self.shouldDisplay = shouldDisplay
   }
-  
-  /// A `Help` instance that hides an argument from the extended help display.
+
+  /// Creates a new help instance.
+  public init(
+    _ abstract: String = "",
+    discussion: String = "",
+    valueName: String? = nil,
+    visibility: Visibility = .default)
+  {
+    self.abstract = abstract
+    self.discussion = discussion
+    self.valueName = valueName
+    self.visibility = visibility
+  }
+
+  /// A `Help` instance that shows an argument only in the extended help display.
   public static var hidden: ArgumentHelp {
-    ArgumentHelp(shouldDisplay: false)
+    ArgumentHelp(visibility: .hidden)
+  }
+
+  /// A `Help` instance that hides an argument from the extended help display.
+  public static var `private`: ArgumentHelp {
+    ArgumentHelp(visibility: .private)
   }
 }
 

Sources/ArgumentParser/Parsable Properties/ArgumentHelp.swift

@@ -15,6 +15,8 @@ import Glibc
 import Darwin
 #elseif canImport(CRT)
 import CRT
+#elseif canImport(WASILibc)
+import WASILibc
 #endif
 
 #if os(Windows)
@@ -66,6 +68,8 @@ public struct ExitCode: Error, RawRepresentable, Hashable {
   /// An exit code that indicates that the user provided invalid input.
 #if os(Windows)
   public static let validationFailure = ExitCode(ERROR_BAD_ARGUMENTS)
+#elseif os(WASI)
+  public static let validationFailure = ExitCode(EXIT_FAILURE)
 #else
   public static let validationFailure = ExitCode(EX_USAGE)
 #endif

Sources/ArgumentParser/Parsable Properties/Errors.swift

@@ -231,7 +231,7 @@ extension Flag where Value == Bool {
   /// Creates a Boolean property with default value provided by standard Swift default value syntax that reads its value from the presence of a flag.
   ///
   /// - Parameters:
-  ///   - wrappedValue: A default value to use for this property, provided implicitly by the compiler during propery wrapper initialization.
+  ///   - wrappedValue: A default value to use for this property, provided implicitly by the compiler during property wrapper initialization.
   ///   - name: A specification for what names are allowed for this flag.
   ///   - help: Information about how to use this flag.
   public init(
@@ -273,7 +273,7 @@ extension Flag where Value == Bool {
   ///
   /// - Parameters:
   ///   - name: A specification for what names are allowed for this flag.
-  ///   - wrappedValue: A default value to use for this property, provided implicitly by the compiler during propery wrapper initialization.
+  ///   - wrappedValue: A default value to use for this property, provided implicitly by the compiler during property wrapper initialization.
   ///   - inversion: The method for converting this flag's name into an on/off pair.
   ///   - exclusivity: The behavior to use when an on/off pair of flags is specified.
   ///   - help: Information about how to use this flag.
@@ -305,7 +305,7 @@ extension Flag where Value == Bool {
   ///
   /// - Parameters:
   ///   - name: A specification for what names are allowed for this flag.
-  ///   - wrappedValue: A default value to use for this property, provided implicitly by the compiler during propery wrapper initialization.
+  ///   - wrappedValue: A default value to use for this property, provided implicitly by the compiler during property wrapper initialization.
   ///   - inversion: The method for converting this flag's name into an on/off pair.
   ///   - exclusivity: The behavior to use when an on/off pair of flags is specified.
   ///   - help: Information about how to use this flag.
@@ -393,7 +393,7 @@ extension Flag where Value: EnumerableFlag {
   /// ```
   ///
   /// - Parameters:
-  ///   - wrappedValue: A default value to use for this property, provided implicitly by the compiler during propery wrapper initialization.
+  ///   - wrappedValue: A default value to use for this property, provided implicitly by the compiler during property wrapper initialization.
   ///   - exclusivity: The behavior to use when multiple flags are specified.
   ///   - help: Information about how to use this flag.
   public init(