From 57175a80c048c5d0ca585d00403669c25a4441fe Mon Sep 17 00:00:00 2001 From: Mahmoud Al-Qudsi Date: Mon, 26 Sep 2022 14:05:54 -0500 Subject: [PATCH 1/2] `complete` docs: When to use old-style for short options There are many applications with "primitive" argument parsing capabalities that cannot handle munging two short options together (`-xf` for `-x -f`) or a short option and its required value (`-dall` for `-d all`). To prevent fish from suggesting munged arguments/payloads, the options (both long and short, not just long!) can be specified as `-o` or `--old-option` but none of this is documented. --- doc_src/cmds/complete.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc_src/cmds/complete.rst b/doc_src/cmds/complete.rst index e27f0db7b..1fb8eeeb8 100644 --- a/doc_src/cmds/complete.rst +++ b/doc_src/cmds/complete.rst @@ -36,8 +36,8 @@ The following options are available: **-l** or **--long-option** *LONG_OPTION* Adds a GNU-style long option to the completions list. -**-o** or **--old-option** *LONG_OPTION* - Adds an old-style long option to the completions list (see below for details). +**-o** or **--old-option** *OPTION* + Adds an old-style short or long option (see below for details). **-a** or **--arguments** *ARGUMENTS* Adds the specified option arguments to the completions list. @@ -76,7 +76,7 @@ Command specific tab-completions in ``fish`` are based on the notion of options - Short options, like ``-a``. Short options are a single character long, are preceded by a single hyphen and can be grouped together (like ``-la``, which is equivalent to ``-l -a``). Option arguments may be specified by appending the option with the value (``-w32``), or, if ``--require-parameter`` is given, in the following parameter (``-w 32``). -- Old-style long options, like ``-Wall`` or ``-name``. Old-style long options can be more than one character long, are preceded by a single hyphen and may not be grouped together. Option arguments are specified in the following parameter (``-ao null``) or after a ``=`` (``-ao=null``). +- Old-style options, long like ``-Wall`` or ``-name`` or even short like ``-a``. Old-style options can be more than one character long, are preceded by a single hyphen and may not be grouped together. Option arguments are specified by default following a space (``-ao null``) or after a ``=`` (``-ao=null``). Short options for commands that do not support concatenating multiple short options in one string (not supporting ``-xf`` as short for ``-x -f``) or a short option and its value in one string (not supporting ``-d9`` instead of ``-d 9``) should be specified as single-character old-style options; for example, ``complete -c foo -o s; complete -c foo -o v`` would never suggest ``foo -ov`` but rather ``foo -o -v``. - GNU-style long options, like ``--colors``. GNU-style long options can be more than one character long, are preceded by two hyphens, and can't be grouped together. Option arguments may be specified after a ``=`` (``--quoting-style=shell``), or, if ``--require-parameter`` is given, in the following parameter (``--quoting-style shell``). From e2d37152ad0e2827c585e9936370c8230b4ea4dd Mon Sep 17 00:00:00 2001 From: Mahmoud Al-Qudsi Date: Fri, 30 Sep 2022 19:17:07 -0500 Subject: [PATCH 2/2] Move short old-style example to end --- doc_src/cmds/complete.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc_src/cmds/complete.rst b/doc_src/cmds/complete.rst index 1fb8eeeb8..0a79ffd4e 100644 --- a/doc_src/cmds/complete.rst +++ b/doc_src/cmds/complete.rst @@ -76,7 +76,7 @@ Command specific tab-completions in ``fish`` are based on the notion of options - Short options, like ``-a``. Short options are a single character long, are preceded by a single hyphen and can be grouped together (like ``-la``, which is equivalent to ``-l -a``). Option arguments may be specified by appending the option with the value (``-w32``), or, if ``--require-parameter`` is given, in the following parameter (``-w 32``). -- Old-style options, long like ``-Wall`` or ``-name`` or even short like ``-a``. Old-style options can be more than one character long, are preceded by a single hyphen and may not be grouped together. Option arguments are specified by default following a space (``-ao null``) or after a ``=`` (``-ao=null``). Short options for commands that do not support concatenating multiple short options in one string (not supporting ``-xf`` as short for ``-x -f``) or a short option and its value in one string (not supporting ``-d9`` instead of ``-d 9``) should be specified as single-character old-style options; for example, ``complete -c foo -o s; complete -c foo -o v`` would never suggest ``foo -ov`` but rather ``foo -o -v``. +- Old-style options, long like ``-Wall`` or ``-name`` or even short like ``-a``. Old-style options can be more than one character long, are preceded by a single hyphen and may not be grouped together. Option arguments are specified by default following a space (``-foo null``) or after ``=`` (``-foo=null``). - GNU-style long options, like ``--colors``. GNU-style long options can be more than one character long, are preceded by two hyphens, and can't be grouped together. Option arguments may be specified after a ``=`` (``--quoting-style=shell``), or, if ``--require-parameter`` is given, in the following parameter (``--quoting-style shell``). @@ -148,4 +148,6 @@ Now hub inherits all of the completions from git. Note this can also be specifie complete -c git -Show all completions for ``git``. +Shows all completions for ``git``. + +Any command ``foo`` that doesn't support grouping multiple short options in one string (not supporting ``-xf`` as short for ``-x -f``) or a short option and its value in one string (not supporting ``-d9`` instead of ``-d 9``) should be specified as a single-character old-style option instead of as a short-style option; for example, ``complete -c foo -o s; complete -c foo -o v`` would never suggest ``foo -ov`` but rather ``foo -o -v``.