With backtrace support built into command-line Swift, calling `fatalError`
for configuration/validation errors isn't very effective, since the error
messages get hidden by the backtrace. This switches to simply printing
the validation message to stderr and exiting with a failing error code,
which possibly should have always been the behavior.
This also revamps the file structure for validators.
* Restrict access to symbols in BashCompletionsGenerator.swift.
* Use key path instead of closure in BashCompletionsGenerator.swift.
* Remove extraneous bash spacing.
* Do not indent bash cases.
Standardize bash indents.
* Do not prefix bash cases with an open parenthesis.
* Brace & quote bash variable uses.
* Remove extraneous bash blank line.
* Improve bash escaping.
* Improve bash $cur, $prev, & $COMPREPLY.
Use positional arguments passed by bash to the main completion function instead of reading from COMP_WORDS, as that can return the wrong info if completing an empty word before a non-empty word.
Make $cur & $prev local & readonly.
Remove unnecessary COMPREPLY=().
* Improve bash $SAP_SHELL & $SAP_SHELL_VERSION.
Make them local & readonly.
* Overhaul BashCompletionsGenerator.swift as [ParsableCommand.Type] extension.
Inline some single-use functions.
* Move bashValueCompletion(…) in BashCompletionsGenerator.swift.
Move from ArgumentDefinition extension to [ParsableCommand.Type] extension.
* Overhaul bash completion script generation:
Attempt to emulate the much more complete & correct zsh completion script.
Offer candidates for only the current positional / option value, not for all.
Generate completions for positionals the same as for option values.
Offer flags & options only if no prior option-terminator marker (a standalone --).
Offer flags & options only if current word starts with a -, or if there are no remaining positional parameters.
Parse options prior to subcommands later in the command line.
Offer flags & options only once.
Do not offer flags or options if the current word is an option value.
* Add default help to bash completions iff no existing help subcommand.
* Improve bash file & directory completions.
Do not split paths with spaces into separate completions.
Escape spaces in paths.
Append / to directory paths.
Do not use _filedir from bash-completions; use builtin bash constructs instead.
Fix broken existing escaping of single quotes in file extension filters.
More succinct & performant.
* Disable history ! in bash completion scripts.
* Do not include uppercased extensions in bash file(extensions:) completions.
That behavior was a bug, not a feature.
Released Swift Argument Parser documentation says:
"Complete file names with the specified extensions."
It does not mention including uppercase versions of the extensions.
None of the other shells include uppercase versions of extensions.
Why should uppercase versions be special? Why not case-insensitive matching? Why not lowercase versions? Etc.
Any config depending on this behavior won't match uppercase extensions without manually being reconfigured, but there are a ton of other bug fixes that can also break compatibility.
* Use single quoted string for bash list completions.
bash scripts now escape single quotes in list values.
Any existing list values with escapes that worked in double quotes will not work in the single quotes. But now:
- list values needn't be escaped
- unescaped double quotes in list values won't break the script
- $ & other characters won't interact with the shell, so, e.g., command substitutions cannot cause problems
* Allow bash list completions to contain spaces.
* Allow bash custom completions to contain spaces.
Properly refuses to complete when there are no completion candidates.
Still cannot complete to an empty string.
* bash custom completion of empty word followed by other words.
* Prevent bash shellCommand completion scripting from breaking scripts.
Eval the given command from a single-quoted string instead of running it directly in the shell.
* Allow bash shellCommand completions to contain spaces.
If existing shellCommand completions depend on spaces as completion delimiters, they will not work anymore. Newlines are now the only supported delimiters.
Resolve#734
* Use zip(…) to generate bash positional argument numbers.
* Rework bash positional case generation.
* Reverse the polarity of the neutron flow of the completions help subcommand detector.
* Rename flags & options vars to flagCompletions & optionCompletions, respectively, in BashCompletionsGenerator.swift.
* Remove TODO comments from generated bash completion scripts.
---------
Signed-off-by: Ross Goldberg <484615+rgoldberg@users.noreply.github.com>
* Do not indent zsh cases.
Simplify zsh indent generation.
* Do not prefix zsh cases with an open parenthesis.
* Prevent zsh parameter word splitting.
Brace & quote parameter uses.
Use [@] for quoted array output.
* Improve comment in ZshCompletionsGenerator.swift.
* Fix incorrect zsh shellCommand single quotes:
4 consecutive single quotes were obviously intended to be 2 escaped single quotes,
but that isn't zsh syntax.
Use 2 double quotes instead.
* Remove extraneous zsh newline.
* Improve zsh variable declarations: scoping, typing & readonly.
Remove trailing spaces from InstallingCompletionScripts.md.
* Include zsh words before current subcommand in custom completion arg.
* Make subcommandHandler in ZshCompletionsGenerator.swift immutable.
* Escape zsh single quotes via '\'' instead of via '"'"'.
* Escape single quotes in zsh shellCommand String.
If someone already escapes single quotes from the String, this will cause an issue,
but no one should be required to go to the trouble to manually escape single quotes
in their script, especially since the requirement isn't documented or normal.
* Fix zsh custom completions for empty [String] & String elements.
If a Swift custom completion function returns an empty [String], if the user tries to
complete it, refuse to complete instead of inserting a blank space into the command line.
If a Swift custom completion function returns a [String] including a Swift empty String
or including a String with a description but with a blank completion
(e.g., ":description"), if that completion is selected, complete to a zsh empty string
'' instead of inserting a blank space into the command line.
Disambiguating between an empty [String] & a [String] with one empty String element
requires that an extra value be appended to the output of the Swift custom function,
which is then removed by the completion script.
* Simplify zsh subcommand completion function dispatch.
* Restrict access to symbols in ZshCompletionsGenerator.swift.
* Add default help to zsh completions iff no existing help subcommand.
* Use interpolated Strings in ZshCompletionsGenerator.swift.
* Create & use zsh __completion function.
* Improve zsh escaping.
* Set zsh settings to a known state.
Disable history ! in zsh completion scripts.
* Inline single-use functions & variables in ZshCompletionsGenerator.swift.
* Overhaul ZshCompletionsGenerator.swift as [ParsableCommand.Type] extension.
* Move functions in ZshCompletionsGenerator.swift.
Move from ArgumentDefinition extension to [ParsableCommand.Type] extension.
* Move zsh helper functions before command functions to mirror other shells.
* Prefix zsh helper functions with command name to prevent naming clashes.
Function names are globally scoped.
Without namespacing, if 2 programs use different versions of Swift Argument Parser,
one could overwrite the other's different version of the same helper function.
Renamed functions from *_completion to *_complete, as they complete, not return a
completion.
* Separate zsh _arguments flags from specs using :.
* Rename zsh args variable as arg_specs.
* Simplify zshCompletionString(…).
* Allow generating zsh setup scripts for arguments.
* Use zsh array for list completions instead of nested strings.
Allows list completions to contain spaces.
Resolve#726
* Make CompletionShell.format(…) internal instead of public.
* Reword uses of "iff" in completions code.
Redid a comment as a DocC.
* Replace zsh END_MARKER pseudo-completion with a space to ease migration.
Document why & how this pseudo-completion is used.
Do not trim whitespace in testing, as that breaks with the space pseudo-completion.
Testing should be as exact as possible; trimming whitespace makes it less exact.
* Throw error if attempting to generate a zsh completion script for no commands.
Force unwrap first in ZshCompletionsGenerator.swift.
---------
Signed-off-by: Ross Goldberg <484615+rgoldberg@users.noreply.github.com>
When a required option has a short name, longer single-dash arguments
can end up incorrectly colliding and causing confusing error messages.
This changes the error handling when a short-name option is missing
a value to show both the missing-value error _and_ a message about
the unrecognized longer/composite option.
Fixes#709.
Enables and fixes issues with additional platform tests
and the formatter with these additional rules:
- UseLetInEveryBoundCaseVariable
- NeverForceUnwrap
- BeginDocumentationCommentWithOneLineSummary
- ValidateDocumentationComments
- AlwaysUseCamelCase
The dump help tests previously included the json text in the Swift
source files as multiline strings. This made updating them very tedious
and made diffs hard to follow. This commit moves each of the json dumps
into their own files and adds an easy way of recording new ones as
needed.
Cleans up some lingering odds and ends from #647. Specifically switches
CommandInfoV0 to use the old style description and updates
ArgumentInfoV0 to emit value descriptions as a separate dictionary.
Create a `String?` singleton named `CompletionShell.requestingVersion` that
indicates which shell version is requesting completion candidates.
It will be set to the correct value while a Swift custom completion function is
executing to offer completions for a word from a command line (e.g., while
`customCompletion` from `@Option(completion: .custom(customCompletion))`
executes). Otherwise, it will be set to `nil`.
The requesting shell version is communicated to the Swift app via an environment
variable named `SAP_SHELL_VERSION`, which is exported by each of the generated
completion scripts.
Improve some nearby DocC.
Resolve#689
Signed-off-by: Ross Goldberg <484615+rgoldberg@users.noreply.github.com>
A CompletionShell singleton named CompletionShell.requesting has been created
that indicates which shell is requesting completion candidates.
The singleton is populated when a completion script is generated, so functions
used to generate arguments for CompletionKind creation functions can return
completion candidate syntax / shell commands tailored for that shell.
For the custom(:) CompletionKind creation function, the singleton is populated
at runtime (when a completion script requests completions from the Swift app
after a user types tab while composing a command line to call the app).
The requesting shell is communicated to the Swift app via an environment variable
named SAP_SHELL, which is exported by each of the generated completion scripts.
Resolve#672
Signed-off-by: Ross Goldberg <484615+rgoldberg@users.noreply.github.com>
Insert missing comma in targets array in Package.swift to fix Swift 5.7 build
break from commit 83c5134a24.
Replace 2 if expressions (which are not supported by Swift 5.7) that were added
to ToolInfo.swift by commit 83c5134a24.
Replace switch expression (which is not supported by Swift 5.7) that was added
to GenerateManual.swift by commit 44dd206a85.
Replace switch expression (which is not supported by Swift 5.7) that was added
to DumpHelpGenerationTests.swift by commit 83c5134a24.
Fixes#675
Signed-off-by: Ross Goldberg <484615+rgoldberg@users.noreply.github.com>
- resolves https://github.com/apple/swift-argument-parser/issues/668
by extending the ToolInfoV0 (help dump) struct to include visibility
information for commands (already exists for arguments).
- updates test output to verify existing examples extend with the
additional key.
Since `ExpressibleByArgument` already maintains a list of
enumerable values for an argument, we can extend this to serve
as an ordered list for a new dictionary property that maps the
value name to its description, if applicable. The new property
is a static variable on `ExpressibleByArgument` labelled
`allValueDescriptions`.
If the description string for a value is the same as the value
string, it's assumed that the description is not implemented.
The new value strings are used in the help screen, in the
dump-help JSON output, and in the generated manual.
* Added conversion for InputKey to/from fullPathString.
* Updated custom completions to use the IndexKey.fullPathString.
This resolves an issue where custom completion for arguments in an OptionGroup would fail to match the argument. It was caused by:
- the completion script only using the name of the argument (instead of the full path)
- the CommandParser looking for the matching argument by comparing a name only IndexKey with the “full” IndexKeys
* Updated BashCompletionsGenerator to use customCompletionCall.
The zsh completions already uses this function. The function’s implementation is the same as what the BashCompletionsGenerator is doing. This removes the duplicated logic.
* Updated completion tests to include nested arguments with custom completions.
* Switched to using the split method from the stdlib.
Prevously was using .components(seperatedBy:) from Foundation.
* Updated the fish completions to include arguments
* Introduce subcommand grouping into the command configuration to improve help
Add optional support for grouping subcommands into named groups, to
help bring order to commands with many subcommands without requiring
additional structure. For example, here's the help for a
"subgroupings" command that has an ungrouped subcommand (m), and two
groups of subcommands ("broken" and "complicated").
USAGE: subgroupings <subcommand>
OPTIONS:
-h, --help Show help information.
SUBCOMMANDS:
m
BROKEN SUBCOMMANDS:
foo Perform some foo
bar Perform bar operations
COMPLICATED SUBCOMMANDS:
n
See 'subgroupings help <subcommand>' for detailed help.
To be able freely mix subcommands and subcommand groups, CommandConfiguration
has a new initializer that takes a result builder. The help output
above is created like this:
struct WithSubgroups: ParsableCommand {
static let configuration = CommandConfiguration(
commandName: "subgroupings"
) {
CommandGroup(name: "Broken") {
Foo.self
Bar.self
}
M.self
CommandGroup(name: "Complicated") {
N.self
}
}
}
Each `CommandGroup` names a new group and is given commands (there are
no groups within groups). The other entries are arbitrary
ParsableCommands.
This structure is only cosmetic, and only affects help generation by
providing more structure for the reader. It doesn't impact existing
clients, who can still reason about the flattened list of subcommands
if they prefer.
* Add an optional abstract to command groups
* Expand subcommand group result builders to handle all result-builder syntax
Adds support for if, if-else, if #available, and for..in loops.
* Revert "Add an optional abstract to command groups"
This reverts commit ab563a22c0.
* Eliminate result builders in favor of a second "groupedSubcommands" array
Introduce subcommand groups with a more modest extension to the API that
adds another array of subcommand groups alongside the (ungrouped)
subcommands array. We can consider introducing result builders as a
separate step later, if there's more to be gained from it.
* Drop the (ungrouped) "subcommands" heading when there are none.
Adds a new API to ParsableArguments and ParsableCommand for getting the
usage string. This allows clients to use argument-parser in a more
piecemeal way to construct their own error screens.
This adds support for aliases for subcommands via a new parameter to
CommandConfigurations constructors. The aliases are passed as an array
of strings, where the default is just an empty array that signifies there
are no aliases. The aliases are supported regardless of if a different
commandName is chosen or not. This also updates how subcommands show up
in the help text. Any aliases are now displayed to the right of the original
command.
In addition to the functionality itself, this change:
1. Updates some of the EndToEnd parsing tests to make sure they function
while using aliases.
2. Sprinkles mentions where I saw fit in the documentation.
3. Updates the Math example to have aliases for `math stats average`
(`math stats avg`), and `math multiply` (`math mul`).
`math`'s help text now looks like the below:
```
~ math --help
OVERVIEW: A utility for performing maths.
USAGE: math <subcommand>
OPTIONS:
--version Show the version.
-h, --help Show help information.
SUBCOMMANDS:
add (default) Print the sum of the values.
multiply, mul Print the product of the values.
stats Calculate descriptive statistics.
See 'math help <subcommand>' for detailed help.
~ math stats --help
OVERVIEW: Calculate descriptive statistics.
USAGE: math stats <subcommand>
OPTIONS:
--version Show the version.
-h, --help Show help information.
SUBCOMMANDS:
average, avg Print the average of the values.
stdev Print the standard deviation of the values.
quantiles Print the quantiles of the values (TBD).
See 'math help stats <subcommand>' for detailed help.
```
and use of the aliases:
```
~ math mul 10 10
100
~ math stats avg 10 20
15.0
```
This change does NOT add any updates to the shell completion logic for
this feature.
Fixes#248
Some commands allow an option to be repeated to provide multiple values.
For example, ssh allows the -L flag to be repeated to establish multiple
port forwardings.
ArgumentParser supports this style when the Option value is an Array
and the parsingStrategy is ArrayParsingStrategy.singleValue or
.unconditionalSingleValue.
Without this patch, ArgumentParser generates a zsh completion script
that does not handle repeatable options correctly. The generated script
suppresses completion of any option after that option's first use, even
if the option is repeatable.
With this patch, ArgumentParser generates a zsh completion script that
allows a repeatable option to be completed each time it is used.
The relevant zsh _arguments syntax is documented here:
https://zsh.sourceforge.io/Doc/Release/Completion-System.html#Completion-Functions
Specifically, a repeatable option's optspec needs to start with '*'.
Furthermore, a repeatable argument must not list itself or its synonyms
in its own parenthesized suppression list. (This is not clearly
documented.)
fixes#564
* Add test for repeated flag completions
These warnings are showing up in tests about types and protocols
that are defined within this package, so they don't pose a problem
for future library evolution. Instead of using the `@retroactive`
attribute, which isn't supported by older compilers, this change
fully qualifies the type and protocol in the relevant conformance
declarations, which suppresses the issue.
Re: https://github.com/apple/swift-evolution/blob/main/proposals/0364-retroactive-conformance-warning.md
This change adds conditional `Sendable` conformance to all
property wrapper types when their `Value` is `Sendable`, enabling
commands to be used in concurrent contexts. Some notes on
the implementation:
* Fix flag exclusivity issues
This derives the `hasUpdated` check from the parsed values data type,
rather than storing it in the closure (which breaks sendability) or
passing it through the closure invocation (which wasn't finished
enough to actually work).
* Mark all `transform` methods as `@Sendable`
This allows for a stronger, compiler-supported guarantee of
sendability when a compound `ParsableArguments` or `ParsableCommand`
type is marked `Sendable`. Most transformations shouldn't be a
problem, since the general case is that these are pure string ->
value transformations.
In cases where making such a transformation sendable is impossible,
an author can always change the property to be just a string and
perform the transformation within the context of the command's
execution, in either the `run()` or `validate()` methods.
* Add `@preconcurrency` to Sendable closure APIs
This adds the `@preconcurrency` attribute to all public APIs that
have changed to take a `@Sendable` closure. This will ease the
migration path for sendable adoption for ArgumentParser users, since
a warning will only appear for using these APIs (like the `transform`
parameter in an @Option or @Argument) once they've turned on strict
concurrency checking.
I'm also backing out changes that avoided those warnings in the tests
and examples, since in most cases those warnings are spurious;
unapplied functions don't capture state. See
https://forums.swift.org/t/pitch-inferring-sendable-for-methods-and-key-path-literals/68011
for more on this and hopefully an upcoming fix for these issues.
* Raise minimum Swift version to 5.7
In order to provide `@preconcurrency` support, the package needs to
have a minimum Swift requirement of 5.7. This makes that change and
updates the README to indicate this for the next version.
* Respect the `COLUMNS` and `LINES` environment variables, if set, when determining screen size.
* Add test for COLUMNS environment override
* Make columns test idempotent against there being a COLUMNS value already set in the environment
* Make help tests be more explicit about screen widths.
Updates HelpGenerator to print possible value options as a suffix to the
user defined help string. In practice this looks like:
> Set diagnostic level to report public declarations without an
> availability attribute. (values: error, warn, ignore; default: warn)
When option groups are nested, any titles of the nested groups are
removed, even when the containing group doesn't have a title. This
change preserves the nested groups' titles when grouped in an
untitled option group. Nesting within a titled option group continues
to override any nested option groups.
Fixes#585.
When a property wrapper is applied to a property, the property's
storage is given a name with a prefixed underscore. That is,
for a property named `x`, the actual storage is named `_x`.
That prefixed storage is what is visible through reflection, so
when building an ArgumentSet from a command type's Mirror, we
need to remove the leading underscore. This is done when creating
an InputKey for each property.
However, InputKeys are also created from CodingKeys during
decoding of a ParsableCommand. These CodingKeys _do not_ have
the leading underscore that is visible, so any underscores
that appear are actually from the declaration of the property
with an underscored name. Removing leading underscores from
CodingKey names results in a mismatch when trying to find
the decoded value.
This change simplifies the InputKey type to use an array
path instead of an indirect enum and removes the leading
underscore dropping when creating an InputKey from a CodingKey.
rdar://104928743
A generated fish script didn't complete an option after an argument.
The cause is the generated fish script doesn't accept an input text which already has arguments.
For example, when the input is `repeat -`, the script can complete `--count`, but when the text is `repeat foo -`, the script cannot complete `repeat foo --count`, because the input text already has the argument "foo".
To fix the issue, `FishCompletionsGenerator` got a capability that can accept a text which has arguments.
- Renames AssertEqualStringsIgnoringTrailingWhitespace to
AssertEqualStrings and updates the implementation to require matching
trailing whitespace.
- Updates AssertEqualStrings to include much easier to read diff output
when CollectionDifference is available. This should add developers
when tests fail by providing more clear errors.
This change lets you provide a title for option groups, which is used
when generating the help screen. Titled option groups, when they exist,
are placed between the ARGUMENTS and OPTIONS section of the help.
Multiple option groups with the same title are coalesced into a single
group.
For example, this command declaration:
struct Extras: ParsableArguments {
@Flag(help: "Print extra output while processing.")
var verbose: Bool = false
@Flag(help: "Include details no one asked for.")
var oversharing: Bool = false
}
@main
struct Example: ParsableCommand {
@OptionGroup(title: "Extras")
var extras: Extras
@Argument var name: String?
@Option var title: String?
}
yields this help screen:
USAGE: example [--verbose] [--oversharing] [<name>] [--title <title>]
ARGUMENTS:
<name>
EXTRAS:
--verbose Print extra output while processing.
--oversharing Include details no one asked for.
OPTIONS:
--title <title>
-h, --help Show help information.
RawRepresentable types that have a non-String raw value are having
values displayed in the help screen by converting the RawRep value
into a string. However, these values are by default parsed by their
raw value, so we should use that for display instead.
This is accomplished by adding a defaultValueDescription
implementation for all ExpressibleByArgument-conforming RawValue
types, and then basing the allValues implementation on that.
This generalizes the existing overloads for String-based RawRep types,
while also allowing users who customize their ExpressibleByArgument
implementation to provide the correct help value for clients.
In the help for flags like --prefix/--no-prefix, use the name of the
default flag instead of true/false. When EnumerableFlag types
have separate help strings, show the correct default flag name
on the default flag in the help.
- Fixes#466.
- Adds initializers to ArgumentDefinition generic over a Container type.
The Container type must conform to a new internal protocol
ArgumentDefinitionContainer which describes functionality like default
set of help options for the argument defined by the property wrapper,
etc.
- Adds overloads for Optional @Arguments and @Options with default
values which emit deprecation warning to guide users towards using the
non-Optional versions.
If a ParsableArguments type doesn't implement init(from:) correctly,
it isn't decodable by the parser. This improves the validation
failure message for such types.
defaultValueDescription is always the enum case name, but that's not a
valid argument when the enum value differs from the case name. Extend
ExpressibleByArgument to use rawValue for defaultValueDescription for
string enums.
- Fixes a bug where built-in flags such as --help and --version were not
properly marked with isOptional which resulted in them appearing in
generated content (such as completion scripts and manuals) as required
arguments.
When an array of argument values fails to parse, no custom error message is
provided, and a list of valid candidate values is available, include the
list as part of the error message.
Addresses #401.
Nate Cook
Ross Goldberg
Rauhul Varma
Joseph Heck
Bri Peticca
Craig Siemens
Doug Gregor
Danny Canter
Cœur
Rob Mayoff
Saleem Abdulrasool
Kenny YorkandKenny York
Lev Walkin
Gwynne Raskind
Rauhul Varma
Tiago Lopes
matsuji
Rob RussoandRob Russo
David Peterson
Ian
Luciano Almeida
konomae