This removes the `async` overloads to `parse` and `parseAsRoot`
that caused a source break in 1.8.0, and introduces new names
that disambiguate the methods with `async` behavior. Instead of
calling the existing methods with the `await` keyword, users can
call `await asyncParse` or `await asyncParseAsRoot`.
This change also adds a validation step to the synchronous parsing
path to check if an async completions function is called.
Users that have already updated their code to work around the
source break will revert to the old methods with this change,
which will yield a "No 'async' operations occur within 'await'
expression" warning. They can remove the `await` keyword or update
to call the async versions directly to fix the warning.
* add implementation of replacing(_:with:)
* remove use of range(of:)
* Consolidate foundation usage
* Consolidate error to string logic
* Clean up env a bit
Improve zsh quoting.
Many quoting issues remain.
To fix them, there should first be enforced & documented limits on the acceptable characters in various values throughout SAP to avoid unnecessary quoting.
Signed-off-by: Ross Goldberg <484615+rgoldberg@users.noreply.github.com>
They indicate to the Swift custom completion function:
1. the word for which completions are being requested.
2. the location of the cursor within that word.
* 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>
Enables and fixes issues with additional platform tests
and the formatter with these additional rules:
- UseLetInEveryBoundCaseVariable
- NeverForceUnwrap
- BeginDocumentationCommentWithOneLineSummary
- ValidateDocumentationComments
- AlwaysUseCamelCase
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
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
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.
* 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.
* Escape backslash and square brackets as well as single quotes (#218 and #221)
- Escape appropriate chars in subcommand abstracts as well.
* Add test for escaped zsh characters
* `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.
Nate Cook
Ross Goldberg
Rauhul Varma
Craig Siemens
Cœur
Rob Mayoff
Kenny YorkandKenny York
Gwynne Raskind
matsuji
Rauhul Varma
Aaron Gyes
Kotaro Suto
Alfredo Delli Bovi
Daniel Duan
Brandon Evans
Nate Weaver
Stuart Carnie