| Converting documentation...
| warning: '--level' is deprecated. Use '--coverage-summary-level' instead.
| warning: '--index' is deprecated. Use '--emit-lmdb-index' indead.
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/CustomizingCommandHelp.md:5:1: Overview section starts here
| --> Articles/CustomizingCommandHelp.md:62:1-62:33
| 60 | ```
| 61 |
| 62 + ## Modifying the Help Flag Names
| | ╰─suggestion: Change the heading to a level-3 heading
| 63 |
| 64 | Users can see the help screen for a command by passing either the `-h` or the `--help` flag, by default. If you need to use one of those flags for another purpose, you can provide alternative names when configuring a root command.
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/CustomizingCommandHelp.md:5:1: Overview section starts here
| --> Articles/CustomizingCommandHelp.md:126:1-126:19
| 124 | ```
| 125 |
| 126 + ## Hiding Commands
| | ╰─suggestion: Change the heading to a level-3 heading
| 127 |
| 128 | You may not want to show every one of your command as part of your command-line interface. To render a command invisible (but still usable), pass `shouldDisplay: false` to the ``CommandConfiguration`` initializer.
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/CustomizingCommandHelp.md:5:1: Overview section starts here
| --> Articles/CustomizingCommandHelp.md:130:1-130:41
| 128 | You may not want to show every one of your command as part of your command-line interface. To render a command invisible (but still usable), pass `shouldDisplay: false` to the ``CommandConfiguration`` initializer.
| 129 |
| 130 + ## Generating Help Text Programmatically
| | ╰─suggestion: Change the heading to a level-3 heading
| 131 |
| 132 | The help screen is automatically shown to users when they call your command with the help flag. You can generate the same text from within your program by calling the `helpMessage()` method.
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/CustomizingHelp.md:5:1: Overview section starts here
| --> Articles/CustomizingHelp.md:38:1-38:34
| 36 | ```
| 37 |
| 38 + ## Customizing Help for Arguments
| | ╰─suggestion: Change the heading to a level-3 heading
| 39 |
| 40 | For more control over the help text, pass an ``ArgumentHelp`` instance instead of a string literal. The `ArgumentHelp` type can include an abstract (which is what the string literal becomes), a discussion, a value name to use in the usage string, and a visibility level for that argument.
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/CustomizingHelp.md:5:1: Overview section starts here
| --> Articles/CustomizingHelp.md:77:1-77:31
| 75 | ```
| 76 |
| 77 + ## Enumerating Possible Values
| | ╰─suggestion: Change the heading to a level-3 heading
| 78 |
| 79 | When an argument or option has a fixed set of possible values, listing these values in the help screen can simplify use of your tool. You can customize the displayed set of values for custom ``ExpressibleByArgument`` types by implementing ``ExpressibleByArgument/allValueStrings``. Despite the name, ``ExpressibleByArgument/allValueStrings`` does _not_ need to be an exhaustive list of possible values.
|
| error: 'CaseIterable' doesn't exist at '/ArgumentParser/CustomizingHelp'
| --> Articles/CustomizingHelp.md:118:47-118:59
| 116 | ### Deriving Possible Values
| 117 |
| 118 + ExpressibleByArgument types that conform to ``CaseIterable`` do not need to manually specify ``ExpressibleByArgument/allValueStrings``. Instead, a list of possible values is derived from the type's cases, as in this updated example:
| 119 |
| 120 | ```swift
|
| error: 'CaseIterable' doesn't exist at '/ArgumentParser/CustomizingHelp'
| --> Articles/CustomizingHelp.md:151:40-151:52
| 149 | ```
| 150 |
| 151 + For an ``ExpressibleByArgument`` and ``CaseIterable`` type with many cases, you may still want to implement ``ExpressibleByArgument/allValueStrings`` to avoid an overly long list of values appearing in the help screen. For these types it is recommended to include the most common possible values.
| 152 |
| 153 | ## Controlling Argument Visibility
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/CustomizingHelp.md:5:1: Overview section starts here
| --> Articles/CustomizingHelp.md:153:1-153:35
| 151 | For an ``ExpressibleByArgument`` and ``CaseIterable`` type with many cases, you may still want to implement ``ExpressibleByArgument/allValueStrings`` to avoid an overly long list of values appearing in the help screen. For these types it is recommended to include the most common possible values.
| 152 |
| 153 + ## Controlling Argument Visibility
| | ╰─suggestion: Change the heading to a level-3 heading
| 154 |
| 155 | You can specify the visibility of any argument, option, or flag.
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/CustomizingHelp.md:5:1: Overview section starts here
| --> Articles/CustomizingHelp.md:221:1-221:41
| 219 | ```
| 220 |
| 221 + ## Grouping Arguments in the Help Screen
| | ╰─suggestion: Change the heading to a level-3 heading
| 222 |
| 223 | When you provide a title in an `@OptionGroup` declaration, that type's properties are grouped together under your title in the help screen. For example, this command bundles similar arguments together under a "Build Options" title:
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/DeclaringArguments.md:5:1: Overview section starts here
| --> Articles/DeclaringArguments.md:92:1-92:37
| 90 | ```
| 91 |
| 92 + ## Customizing option and flag names
| | ╰─suggestion: Change the heading to a level-3 heading
| 93 |
| 94 | By default, options and flags derive the name that you use on the command line from the name of the property, such as `--count` and `--index`. Camel-case names are converted to lowercase with hyphen-separated words, like `--strip-whitespace`.
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/DeclaringArguments.md:5:1: Overview section starts here
| --> Articles/DeclaringArguments.md:135:1-135:24
| 133 |
| 134 |
| 135 + ## Parsing custom types
| | ╰─suggestion: Change the heading to a level-3 heading
| 136 |
| 137 | Arguments and options can be parsed from any type that conforms to the ``ExpressibleByArgument`` protocol. Standard library integer and floating-point types, strings, and Booleans all conform to `ExpressibleByArgument`.
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/DeclaringArguments.md:5:1: Overview section starts here
| --> Articles/DeclaringArguments.md:204:1-204:51
| 202 | 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.
| 203 |
| 204 + ## Using flag inversions, enumerations, and counts
| | ╰─suggestion: Change the heading to a level-3 heading
| 205 |
| 206 | Flags are most frequently used for `Bool` properties. You can generate a `true`/`false` pair of flags by specifying a flag inversion:
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/DeclaringArguments.md:5:1: Overview section starts here
| --> Articles/DeclaringArguments.md:291:1-291:29
| 289 |
| 290 |
| 291 + ## Specifying default values
| | ╰─suggestion: Change the heading to a level-3 heading
| 292 |
| 293 | You can specify default values for almost all supported argument, option, and flag types using normal property initialization syntax:
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/DeclaringArguments.md:5:1: Overview section starts here
| --> Articles/DeclaringArguments.md:330:1-330:33
| 328 |
| 329 |
| 330 + ## Specifying a parsing strategy
| | ╰─suggestion: Change the heading to a level-3 heading
| 331 |
| 332 | When parsing a list of command-line inputs, `ArgumentParser` distinguishes between dash-prefixed keys and un-prefixed values. When looking for the value for a key, only an un-prefixed value will be selected by default.
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/ExperimentalFeatures.md:5:1: Overview section starts here
| --> Articles/ExperimentalFeatures.md:11:1-11:33
| 9 | If you have any feedback on experimental features, please [open a GitHub issue][issue].
| 10 |
| 11 + ## List of Experimental Features
| | ╰─suggestion: Change the heading to a level-3 heading
| 12 |
| 13 | | Name | Description | related PRs | Version |
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/GettingStarted.md:5:1: Overview section starts here
| --> Articles/GettingStarted.md:9:1-9:41
| 7 | This guide walks through building an example command. You'll learn about the different tools that `ArgumentParser` provides for defining a command's options, customizing the interface, and providing help text for your user.
| 8 |
| 9 + ## Adding ArgumentParser as a Dependency
| | ╰─suggestion: Change the heading to a level-3 heading
| 10 |
| 11 | Let's write a tool called `count` that reads an input file, counts the words, and writes the result to an output file.
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/GettingStarted.md:5:1: Overview section starts here
| --> Articles/GettingStarted.md:34:1-34:30
| 32 | ```
| 33 |
| 34 + ## Building Our First Command
| | ╰─suggestion: Change the heading to a level-3 heading
| 35 |
| 36 | Once we've built the `count` tool, we'll be able to run it like this:
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/GettingStarted.md:5:1: Overview section starts here
| --> Articles/GettingStarted.md:72:1-72:30
| 70 | > Note: The Swift compiler uses either the type marked with `@main` or a `main.swift` file as the entry point for an executable program. You can use either one, but not both — rename your `main.swift` file to the name of the command when you add `@main`. In this case, rename the file to `Count.swift`.
| 71 |
| 72 + ## Working with Named Options
| | ╰─suggestion: Change the heading to a level-3 heading
| 73 |
| 74 | Our `count` tool may have a usability problem — it's not immediately clear whether a user should provide the input file first, or the output file. Instead of using positional arguments for our two inputs, let's specify that they should be labeled options:
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/GettingStarted.md:5:1: Overview section starts here
| --> Articles/GettingStarted.md:109:1-109:17
| 107 | ```
| 108 |
| 109 + ## Adding a Flag
| | ╰─suggestion: Change the heading to a level-3 heading
| 110 |
| 111 | Next, we want to add a `--verbose` flag to our tool, and only print the message if the user specifies that option:
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/GettingStarted.md:5:1: Overview section starts here
| --> Articles/GettingStarted.md:145:1-145:22
| 143 |
| 144 |
| 145 + ## Using Custom Names
| | ╰─suggestion: Change the heading to a level-3 heading
| 146 |
| 147 | We can customize the names of our options and add an alternative to the `verbose` flag so that users can specify `-v` instead of `--verbose`. The new interface will look like this:
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/GettingStarted.md:5:1: Overview section starts here
| --> Articles/GettingStarted.md:178:1-178:18
| 176 | The default name specification is `.long`, which uses a property's name with a two-dash prefix. `.short` uses only the first letter of a property's name with a single-dash prefix, and allows combining groups of short options. You can specify custom short and long names with the `.customShort(_:)` and `.customLong(_:)` methods, respectively, or use the combined `.shortAndLong` property to specify the common case of both the short and long derived names.
| 177 |
| 178 + ## Providing Help
| | ╰─suggestion: Change the heading to a level-3 heading
| 179 |
| 180 | `ArgumentParser` automatically generates help for any command when a user provides the `-h` or `--help` flags:
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/GettingStarted.md:5:1: Overview section starts here
| --> Articles/GettingStarted.md:225:1-225:24
| 223 | ```
| 224 |
| 225 + ## The Complete Utility
| | ╰─suggestion: Change the heading to a level-3 heading
| 226 |
| 227 | As promised, here's the complete `count` command, for your experimentation:
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/GettingStarted.md:5:1: Overview section starts here
| --> Articles/GettingStarted.md:292:1-292:36
| 290 |
| 291 |
| 292 + ## Next Steps … Swift concurrency
| | ╰─suggestion: Change the heading to a level-3 heading
| 293 |
| 294 | `ArgumentParser` supports Swift concurrency, notably `async` renditions of `run`. If you use `async` rendition of `run`, conform to `AsyncParsableCommand` instead of `ParsableCommand`.
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/ManualParsing.md:5:1: Overview section starts here
| --> Articles/ManualParsing.md:9:1-9:21
| 7 | 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.
| 8 |
| 9 + ## Parsing Arguments
| | ╰─suggestion: Change the heading to a level-3 heading
| 10 |
| 11 | 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.
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/ManualParsing.md:5:1: Overview section starts here
| --> Articles/ManualParsing.md:50:1-50:20
| 48 | ```
| 49 |
| 50 + ## Parsing Commands
| | ╰─suggestion: Change the heading to a level-3 heading
| 51 |
| 52 | 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 ``ParsableCommand/parseAsRoot(_:)`` method returns a type-erased ``ParsableCommand``.
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/ManualParsing.md:5:1: Overview section starts here
| --> Articles/ManualParsing.md:83:1-83:32
| 81 | ```
| 82 |
| 83 + ## Providing Command-Line Input
| | ╰─suggestion: Change the heading to a level-3 heading
| 84 |
| 85 | All of the parsing methods — `parse()`, `parseOrExit()`, and `parseAsRoot()` — can optionally take an array of command-line inputs as an argument. You can use this capability to test your commands, to perform pre-parse filtering of the command-line arguments, or to manually execute commands from within the same or another target.
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/Validation.md:5:1: Overview section starts here
| --> Articles/Validation.md:60:1-60:35
| 58 | ```
| 59 |
| 60 + ## Handling Post-Validation Errors
| | ╰─suggestion: Change the heading to a level-3 heading
| 61 |
| 62 | The ``ValidationError`` type is a special `ArgumentParser` error — a validation error's message is always accompanied by an appropriate usage string. You can throw other errors, from either the `validate()` or `run()` method to indicate that something has gone wrong that isn't validation-specific. Errors that conform to `CustomStringConvertible` or `LocalizedError` provide the best experience for users.
|
| note: The majority of content should be under level-3 headers under the "Overview" section
| Articles/Validation.md:5:1: Overview section starts here
| --> Articles/Validation.md:106:1-106:29
| 104 | ```
| 105 |
| 106 + ## Handling Transform Errors
| | ╰─suggestion: Change the heading to a level-3 heading
| 107 |
| 108 | During argument and option parsing, you can use a closure to transform the command line strings to custom types. If this transformation fails, you can throw a `ValidationError`; its `message` property will be displayed to the user.
|
| note: This document does not have a summary.
| An abstract provides a short description of the document. Write a paragraph below the title of the document to use it as an abstract.
| --> Extensions/Argument.md:1:1-1:30
| 1 + # ``ArgumentParser/Argument``
| 2 |
| 3 | ## Topics
|
| note: This document does not have a summary.
| An abstract provides a short description of the document. Write a paragraph below the title of the document to use it as an abstract.
| --> Extensions/ArgumentArrayParsingStrategy.md:1:1-1:50
| 1 + # ``ArgumentParser/ArgumentArrayParsingStrategy``
| 2 |
| 3 | ## Topics
|
| note: This document does not have a summary.
| An abstract provides a short description of the document. Write a paragraph below the title of the document to use it as an abstract.
| --> Extensions/CommandConfiguration.md:1:1-1:42
| 1 + # ``ArgumentParser/CommandConfiguration``
| 2 |
| 3 | ## Topics
|
| error: 'init(commandName:abstract:usage:discussion:version:shouldDisplay:subcommands:defaultSubcommand:helpNames:aliases:)' doesn't exist at '/ArgumentParser/CommandConfiguration'
| --> Extensions/CommandConfiguration.md:7:5-7:119
| 5 | ### Creating a Configuration
| 6 |
| 7 + - ``init(commandName:abstract:usage:discussion:version:shouldDisplay:subcommands:defaultSubcommand:helpNames:aliases:)``
| | ╰─suggestion: Replace 'init(commandName:abstract:usage:discussion:version:shouldDisplay:subcommands:defaultSubcommand:helpNames:aliases:)' with 'init(commandName:abstract:usage:discussion:version:shouldDisplay:subcommands:groupedSubcommands:defaultSubcommand:helpNames:aliases:)'
| 8 |
| 9 | ### Customizing the Help Screen
|
| note: This document does not have a summary.
| An abstract provides a short description of the document. Write a paragraph below the title of the document to use it as an abstract.
| --> Extensions/Flag.md:1:1-1:26
| 1 + # ``ArgumentParser/Flag``
| 2 |
| 3 | ## Topics
|
| note: This document does not have a summary.
| An abstract provides a short description of the document. Write a paragraph below the title of the document to use it as an abstract.
| --> Extensions/Option.md:1:1-1:28
| 1 + # ``ArgumentParser/Option``
| 2 |
| 3 | ## Topics
|
| note: This document does not have a summary.
| An abstract provides a short description of the document. Write a paragraph below the title of the document to use it as an abstract.
| --> Extensions/OptionGroup.md:1:1-1:33
| 1 + # ``ArgumentParser/OptionGroup``
| 2 |
| 3 | ## Topics
|
| note: This document does not have a summary.
| An abstract provides a short description of the document. Write a paragraph below the title of the document to use it as an abstract.
| --> Extensions/ParsableArguments.md:1:1-1:39
| 1 + # ``ArgumentParser/ParsableArguments``
| 2 |
| 3 | ## Topics
|
| error: Parameter 'initial' not found in initializer declaration
| --> ../Parsable Properties/Argument.swift:621:9-621:61
| 619 | ///
| 620 | /// - Parameters:
| 621 + /// - initial: A default value to use for this property.
| | ╰─suggestion: Remove 'initial' parameter documentation
| 622 | /// - parsingStrategy: The behavior to use when parsing multiple values from
| 623 | /// the command-line arguments.
|
| error: Parameter 'wrappedValue' is missing documentation
| --> ../Parsable Properties/Argument.swift:625:79-625:79
| 623 | /// the command-line arguments.
| 624 | /// - help: Information about how to use this argument.
| 625 + /// - completion: Kind of completion provided to the user for this option.
| 626 | public init<T>(
| 627 | wrappedValue: Array<T>,
|
| error: Parameter 'command' not found in type method declaration
| --> ../Parsable Properties/Errors.swift:83:7-84:31
| 81 | /// flags or subcommands.
| 82 | ///
| 83 + /// - Parameter command: The command type to offer help for, if different
| | ╰─suggestion: Remove 'command' parameter documentation
| 84 + /// from the root command.
| 85 | public static func helpRequest(_ type: ParsableCommand.Type? = nil) -> CleanExit {
| 86 | self.init(base: .helpRequest(type))
|
| error: Parameter 'type' is missing documentation
| --> ../Parsable Properties/Errors.swift:84:31-84:31
| 82 | ///
| 83 | /// - Parameter command: The command type to offer help for, if different
| 84 + /// from the root command.
| | ╰─suggestion: Document 'type' parameter
| 85 | public static func helpRequest(_ type: ParsableCommand.Type? = nil) -> CleanExit {
| 86 | self.init(base: .helpRequest(type))
|
| error: Parameter 'wrappedValue' not found in initializer declaration
| --> ../Parsable Properties/Flag.swift:348:9-348:142
| 346 | /// - Parameters:
| 347 | /// - name: A specification for what names are allowed for this flag.
| 348 + /// - wrappedValue: A default value to use for this property, provided implicitly by the compiler during property wrapper initialization.
| | ╰─suggestion: Remove 'wrappedValue' parameter documentation
| 349 | /// - inversion: The method for converting this flag's name into an on/off pair.
| 350 | /// - exclusivity: The behavior to use when an on/off pair of flags is specified.
|
| error: Parameter 'name' not found in initializer declaration
| --> ../Parsable Properties/Flag.swift:583:9-583:74
| 581 | ///
| 582 | /// - Parameters:
| 583 + /// - name: A specification for what names are allowed for this flag.
| | ╰─suggestion: Remove 'name' parameter documentation
| 584 | /// - help: Information about how to use this flag.
| 585 | public init<Element>(
|
| error: Parameter 'wrappedValue' is missing documentation
| --> ../Parsable Properties/Flag.swift:584:56-584:56
| 582 | /// - Parameters:
| 583 | /// - name: A specification for what names are allowed for this flag.
| 584 + /// - help: Information about how to use this flag.
| | ╰─suggestion: Document 'wrappedValue' parameter
| 585 | public init<Element>(
| 586 | wrappedValue: [Element],
|
| error: Parameter 'transform' not found in initializer declaration
| --> ../Parsable Properties/Option.swift:709:9-710:49
| 707 | /// - completion: The type of command-line completion provided for this
| 708 | /// option.
| 709 + /// - transform: A closure that converts a string into this property's
| | ╰─suggestion: Remove 'transform' parameter documentation
| 710 + /// element type, or else throws an error.
| 711 | public init<T>(
| 712 | wrappedValue: Array<T>,
|
| error: Parameter 'subcommand' is missing documentation
| --> ../Parsable Types/ParsableCommand.swift:120:19-120:19
| 118 | /// - Parameters:
| 119 | /// - includeHidden: Include hidden help information in the generated
| | ╰─suggestion: Document 'subcommand' parameter
| 120 + /// message.
| 121 | /// - Returns: The usage text for this type.
| 122 | public static func usageString(Error: An error was encountered while compiling documentation