Mirrors/fish-shell
2
0
Fork 0
mirror of https://github.com/fish-shell/fish-shell synced 2024-09-20 06:22:12 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs: Some rewording on completions

Browse source
This commit is contained in:
Fabian Boehm 2024-05-10 17:40:18 +02:00
parent f71623ec1b
commit e32efc0581
1 changed files with 10 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
doc_src/completions.rst
View file

@ -3,20 +3,24 @@
Writing your own completions
============================
To specify a completion, use the ``complete`` command. ``complete`` takes as a parameter the name of the command to specify a completion for. For example, to add a completion for the program ``myprog``, one would start the completion command with ``complete -c myprog ...``
To specify a completion, use the ``complete`` command. ``complete`` takes as a parameter the name of the command to specify a completion for. For example, to add a completion for the program ``myprog``, start the completion command with ``complete -c myprog ...``
For a complete description of the various switches accepted by the ``complete`` command, see the documentation for the :doc:`complete <cmds/complete>` builtin, or write ``complete --help`` inside the ``fish`` shell.
To provide a list of possible completions for myprog, use the ``-a`` switch. If ``myprog`` accepts the arguments start and stop, this can be specified as ``complete -c myprog -a 'start stop'``. The argument to the ``-a`` switch is always a single string. At completion time, it will be tokenized on spaces and tabs, and variable expansion, command substitution and other forms of parameter expansion will take place::
# If myprog can list the valid outputs with the list-outputs subcommand:
complete -c myprog -l output -a '(myprog list-outputs)'
``fish`` has a special syntax to support specifying switches accepted by a command. The switches ``-s``, ``-l`` and ``-o`` are used to specify a short switch (single character, such as ``-l``), a gnu style long switch (such as ``--color``) and an old-style long switch (like ``-shuffle``), respectively. If the command 'myprog' has an option '-o' which can also be written as ``--output``, and which can take an additional value of either 'yes' or 'no', this can be specified by writing::
``fish`` has a special syntax to support specifying switches accepted by a command. The switches ``-s``, ``-l`` and ``-o`` are used to specify a short switch (single character, such as ``-l``), a gnu style long switch (such as ``--color``) and an old-style long switch (with one ``-``, like ``-shuffle``), respectively. If the command 'myprog' has an option that can be written as ``-o`` or ``--output``, that is::
complete -c myprog -s o -l output
If this option takes an optional argument, you would also add ``--argument`` or ``-a``, and give that the possible arguments::
complete -c myprog -s o -l output -a "yes no"
For a complete description of the various switches accepted by the ``complete`` command, see the documentation for the :doc:`complete <cmds/complete>` builtin, or write ``complete --help`` inside the ``fish`` shell.
In the complete call above, the ``-a`` arguments apply when the option -o/--output has been given, so this offers them for::
This offers the arguments "yes" and "no" for::
> myprog -o<TAB>
> myprog --output=<TAB>
@ -36,9 +40,7 @@ which offers yes/no in these cases::
> myprog -o <TAB>
> myprog --output <TAB>
In the latter two cases, files will also be offered because file completion is enabled by default.
You would either inhibit file completion for a single option::
Fish will also offer files by default, in addition to the arguments you specified. You would either inhibit file completion for a single option::
complete -c myprog -s o -l output --no-files -ra "yes no"