swift-argument-parser

419 Commits 32 Branches 45 Tags

3 Commits

Include renames

Author	SHA1	Message	Date
Ross Goldberg	bdb3b27a68	Improve bash completion script generation (#735 ) * 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>	2025-02-16 13:06:01 -06:00
Ross Goldberg	f2eda39df5	Improve zsh completion script generation (#727 ) * 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>	2025-02-15 10:56:19 -08:00
Rauhul Varma	d3630e3190	Move additional tests to snapshots (#700 ) Moves some examples test to use snapshot files instead of inline multiline strings.	2025-02-06 10:28:22 -08:00

Author

SHA1

Message

Date

Ross Goldberg

bdb3b27a68

Improve bash completion script generation (#735 )

* 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>

2025-02-16 13:06:01 -06:00

Ross Goldberg

f2eda39df5

Improve zsh completion script generation (#727 )

* 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>

2025-02-15 10:56:19 -08:00

Rauhul Varma

d3630e3190

Move additional tests to snapshots (#700 )

Moves some examples test to use snapshot files instead of inline
multiline strings.

2025-02-06 10:28:22 -08:00