Mirrors/fish-shell
2
0
Fork 0
mirror of https://github.com/fish-shell/fish-shell synced 2025-01-27 12:15:08 +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 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:: 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: # If myprog can list the valid outputs with the list-outputs subcommand:
complete -c myprog -l output -a '(myprog list-outputs)' 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" 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. This offers the arguments "yes" and "no" for::
In the complete call above, the ``-a`` arguments apply when the option -o/--output has been given, so this offers them for::
> myprog -o<TAB> > myprog -o<TAB>
> myprog --output=<TAB> > myprog --output=<TAB>
@ -36,9 +40,7 @@ which offers yes/no in these cases::
> myprog -o <TAB> > myprog -o <TAB>
> myprog --output <TAB> > myprog --output <TAB>
In the latter two cases, files will also be offered because file completion is enabled by default. Fish will also offer files by default, in addition to the arguments you specified. You would either inhibit file completion for a single option::
You would either inhibit file completion for a single option::
complete -c myprog -s o -l output --no-files -ra "yes no" complete -c myprog -s o -l output --no-files -ra "yes no"