mirror of
https://github.com/fish-shell/fish-shell.git
synced 2026-05-18 00:31:15 -03:00
663430a925
Specifically, this now makes the -s/--short option to fish_opt optional when the -l/--long option is given. This commit does not modify argparse, as it already supports defining long flags without a corresponding short flag, however fish_opt would never take advantage of this feature. Note that due to a limitation in argparse, fish_opt will give an error if you try to define a one-character --long flag without also providing a --short option. For backwards compatibility, the --long-only flag is still included with fish_opt, and when used with -s/--short, will behave as before (the short flag is still defined, but argparse will fail if it is actually used by the parsed arguments, moreover the _flag_ option variables will not be defined). This can however be used to define a one character long flag.
81 lines
3.5 KiB
ReStructuredText
81 lines
3.5 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 or number that is used as the short flag in the option being defined. Either this option or the **--long** option must be provided.
|
|
|
|
**-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. If there is no **--short** flag, the long flag name must be more than one character (use **--short** together with **--long-only** to bypass this restriction).
|
|
|
|
**--long-only**
|
|
The option being defined will only allow the long flag name to be used, even if the short flag is defined (i.e., **--short** is specified).
|
|
|
|
**-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 a long flag name (``--token``) is defined:
|
|
|
|
|
|
|
|
::
|
|
|
|
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 --long=token --multiple-vals)
|
|
argparse $options -- $argv
|
|
|