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>
* 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
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
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)
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.
* Use existential CodingKey parameters consistently
Swift 5.7 supports implicit opening for existentials, so these
conversions from `CodingKey` parameters to pass to methods that
are generic over `CodingKey` work fine. Prior to Swift 5.7, however,
these don't compile, with the message that `CodingKey` doesn't conform
to itself.
* Bump the required Swift version for the count-lines test
The overload resolution for the `static func main()` in an `@main`
type still had issues in Swift 5.6, such that a package with a min.
platform below that which works for concurrency backdeployment doesn't
properly resolve the AsyncParsableCommand `main()` function. In
Swift 5.7, this is properly resolved, so just the availability on
the main type is sufficient.
This change just skips the test of `count-lines` prior to Swift 5.7,
so that we can maintain the open platform minimum for the package
as a whole.
- 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.
Adds a new `AsyncParsableCommand` protocol, which provides a
`static func main() async` entry point and can call through to the root
command's or a subcommand's asynchronous `run()` method. For this
asynchronous execution, the root command must conform to `AsyncParsableCommand`,
but its subcommands can be a mix of asynchronous and synchronous commands.
Due to an issue in Swift 5.5, you can only use `@main` on an
`AsyncParsableCommand` root command starting in Swift 5.6.
This change also includes a workaround for clients that are using Swift 5.5.
Declare a separate type that conforms to `AsyncMainProtocol` and add the `@main`
attribute to that type.
```
@main enum Main: AsyncMain {
typealias Command = <#command#>
}
```
* Improve support for multi-word completions in Z shell
I will not pretend to fully understand why this new "expand string into array" expression works when the other didn't, but it does. The new expression is based on this SO answer: https://unix.stackexchange.com/a/29748.
The motivation for this change was for the install command of xcodes (https://github.com/RobotsAndPencils/xcodes) to support Xcode version completion strings with multiple words, like "11.6 Beta". The previous version of this expression would split this string into two, so that "11.6" and "Beta" were independent options in the ZSH completion UI, which didn't make sense for this use case.
* `shellCommand` stores output in a local array that is passed
to `_describe` to handle spaces and other punctuation in
the shell command output
* elide the help abstract if it is empty, as it confuses
the zsh completion system
* set the `_<commandName>_commandname` to `$words[1]`, which
is the full name of the command used to invoke the completion.
This ensures invocations like `./build/debug/math` ...
as passed on to the `_custom_completion` command.
Support for generating shell completion scripts for `ParsableCommand`
types, with customization points for `ExpressibleByArgument` types and
individual arguments and options. Zsh and Bash are supported in this
initial release.
* Add 'see help' messages to usage messages and the help screen
* Update tests for new help messages.
* Update guide examples with additional help messages
If a command cannot successfully run with zero arguments, print the error and the full help message instead of the short usage message.
This closes#134.
* Add built-in support for --version flag
* Test that command-defined --version overrides the built-in.
* Document the `version:` parameter in CommandConfiguration
* Include --version in the generated help.
* Add an API for converting an error to an exit code
* Make ExitCode more useful as a value type
* Update tests to use ExitCode values
* Typo fix
* Add a test for ExitCode.isSuccess
* Switch to just using ExitCode for tests
Rauhul Varma
Ross Goldberg
Craig Siemens
Danny Canter
Lev Walkin
Gwynne Raskind
Rauhul Varma
matsuji
Nate Cook
KthandNate Cook
Aaron Gyes
Jake Petroules
Kotaro Suto
François Lamboley
Gonzalo RH
Alfredo Delli Bovi
Daniel Duan
Brandon Evans
Stuart Carnie
Artem Novichkov
John Mueller
Elliott Williams