mirror of
https://github.com/fish-shell/fish-shell.git
synced 2026-04-30 09:31:15 -03:00
4db61ee117
This commit fixes #8432 by adding put =* in an option spec to indicate that the option takes an optional value, where subsequent uses of the option accumulate the value (so the parsing behaviour is like =?, but the _flag_ variables are appended to like =+). If the option didn't have a value, it appends an empty string. As an example,. long=* -- --long=1 --long will execute set -l _flag_long 1 '' (i.e. count $_flag_long is 2), whereas with =? instead, you'd get set -l _flag_long (i.e. count $_flag_long is 0). As a use case, I'm aware of git clone which has a --recurse-submodules=[<pathspec>]: if you use it without a value, it operates on all submodules, with a value, it operates on the given submodule. The fish_opt function will generate an =* option spec when given both the --optional-val and --multiple-vals options (previously, doing so was an error). fish_opt now also accepts -m as an abbreviation for --multiple-vals, to go with the pre-existing -o and -r abbreviations for --optional-val and --required-val.
81 lines
3.4 KiB
ReStructuredText
81 lines
3.4 KiB
ReStructuredText
.. _cmd-fish_opt:
|
|
|
|
fish_opt - create an option specification for the argparse command
|
|
==================================================================
|
|
|
|
Synopsis
|
|
--------
|
|
|
|
.. synopsis::
|
|
|
|
fish_opt -s ALPHANUM [-l LONG-NAME] [-ormd] [--long-only]
|
|
fish_opt --help
|
|
|
|
Description
|
|
-----------
|
|
|
|
This command provides a way to produce option specifications suitable for use with the :doc:`argparse <argparse>` command. You can, of course, write the option specifications by hand without using this command. But you might prefer to use this for the clarity it provides.
|
|
|
|
The following ``argparse`` options are available:
|
|
|
|
**-s** or **--short** *ALPHANUM*
|
|
Takes a single letter that is used as the short flag in the option being defined. This option is mandatory.
|
|
|
|
**-l** or **--long** *LONG-NAME*
|
|
Takes a string that is used as the long flag in the option being defined. This option is optional and has no default. If no long flag is defined then only the short flag will be allowed when parsing arguments using the option specification.
|
|
|
|
**--long-only**
|
|
The option being defined will only allow the long flag name to be used. The short flag name must still be defined (i.e., **--short** must be specified) but it cannot be used when parsing arguments using this option specification.
|
|
|
|
**-o** or **--optional-val**
|
|
The option being defined can take a value, but it is optional rather than required. If the option is seen more than once when parsing arguments, only the last value seen is saved. This means the resulting flag variable created by ``argparse`` will zero elements if no value was given with the option else it will have exactly one element.
|
|
|
|
**-r** or **--required-val**
|
|
The option being defined requires a value. If the option is seen more than once when parsing arguments, only the last value seen is saved. This means the resulting flag variable created by ``argparse`` will have exactly one element.
|
|
|
|
**-m** or **--multiple-vals**
|
|
The value of each instance of the option is accumulated. If **--optional-val** is provided, the value is optional, and an empty string is stored if no value is provided. Otherwise, the **--requiured-val** option is implied and each instance of the option requires a value. This means the resulting flag variable created by ``argparse`` will have one element for each instance of this option in the arguments, even for instances that did not provide a value.
|
|
|
|
**-d** or **--delete**
|
|
The option and any values will be deleted from the ``$argv_opts`` variables set by ``argparse``
|
|
(as with other options, it will also be deleted from ``$argv``).
|
|
|
|
**-h** or **--help**
|
|
Displays help about using this command.
|
|
|
|
Examples
|
|
--------
|
|
|
|
Define a single option specification for the boolean help flag:
|
|
|
|
|
|
|
|
::
|
|
|
|
set -l options (fish_opt -s h -l help)
|
|
argparse $options -- $argv
|
|
|
|
|
|
Same as above but with a second flag that requires a value:
|
|
|
|
|
|
|
|
::
|
|
|
|
set -l options (fish_opt -s h -l help)
|
|
set options $options (fish_opt -s m -l max --required-val)
|
|
argparse $options -- $argv
|
|
|
|
|
|
Same as above but with a third flag that can be given multiple times saving the value of each instance seen and only the long flag name (``--token``) can be used:
|
|
|
|
|
|
|
|
::
|
|
|
|
set -l options (fish_opt --short=h --long=help)
|
|
set options $options (fish_opt --short=m --long=max --required-val)
|
|
set options $options (fish_opt --short=t --long=token --multiple-vals --long-only)
|
|
argparse $options -- $argv
|
|
|