diff --git a/doc_src/completions.rst b/doc_src/completions.rst index 86501aa00..eb6ffef4e 100644 --- a/doc_src/completions.rst +++ b/doc_src/completions.rst @@ -5,14 +5,57 @@ 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 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: + 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:: 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 ` builtin, or write ``complete --help`` inside the ``fish`` shell. -There are also special switches for specifying that a switch requires an argument, to disable filename completion, to create completions that are only available in some combinations, etc.. For a complete description of the various switches accepted by the ``complete`` command, see the documentation for the :doc:`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:: + + > myprog -o + > myprog --output= + +By default, option arguments are *optional*, so the candidates are only offered directly attached like that, so they aren't given in this case:: + + > myprog -o + +Usually options *require* a parameter, so you would give ``--require-parameter`` / ``-r``:: + + complete -c myprog -s o -l output -ra "yes no" + +which offers yes/no in these cases:: + + > myprog -o + > myprog --output= + > myprog -o + > myprog --output + +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:: + + complete -c myprog -s o -l output --no-files -ra "yes no" + +or with a specific condition:: + + complete -c myprog -f --condition '__fish_seen_subcommand_from somesubcommand' + +or you can disable file completions globally for the command:: + + complete -c myprog -f + +If you have disabled them globally, you can enable them just for a specific condition or option with the ``--force-files`` / ``-F`` option:: + + # Disable files by default + complete -c myprog -f + # but reenable them for --config-file + complete -c myprog -l config-file --force-files -r As a more comprehensive example, here's a commented excerpt of the completions for systemd's ``timedatectl``:: @@ -98,8 +141,6 @@ Functions beginning with the string ``__fish_print_`` print a newline separated - ``__fish_print_interfaces`` prints a list of all known network interfaces. -- ``__fish_print_packages`` prints a list of all installed packages. This function currently handles Debian, rpm and Gentoo packages. - .. _completion-path: Where to put completions