mirror of
https://github.com/fish-shell/fish-shell
synced 2024-11-14 17:07:44 +00:00
d282bc4625
Rework for Doxygen >1.8. Moved large parts of the documentation to a simplified format, making use of Markdown enhancements and fixing bad long options.
95 lines
6 KiB
Text
95 lines
6 KiB
Text
\section complete complete - edit command specific tab-completions
|
|
|
|
\subsection complete-synopsis Synopsis
|
|
<tt>complete (-c|--command|-p|--path) COMMAND [(-s|--short-option) SHORT_OPTION] [(-l|--long-option|-o|--old-option) LONG_OPTION [(-a||--arguments) OPTION_ARGUMENTS] [(-w|--wraps) WRAPPED_COMMAND] [(-d|--description) DESCRIPTION] </tt>
|
|
|
|
\subsection complete-description Description
|
|
|
|
For an introduction to specifying completions, see <a
|
|
href='index.html#completion-own'>Writing your own completions</a> in
|
|
the fish manual.
|
|
|
|
- <tt>COMMAND</tt> is the name of the command for which to add a completion
|
|
- <tt>SHORT_OPTION</tt> is a one character option for the command
|
|
- <tt>LONG_OPTION</tt> is a multi character option for the command
|
|
- <tt>OPTION_ARGUMENTS</tt> is parameter containing a space-separated list of possible option-arguments, which may contain subshells
|
|
- <tt>DESCRIPTION</tt> is a description of what the option and/or option arguments do
|
|
- <tt>-C STRING</tt> or <tt>--do-complete=STRING</tt> makes complete try to find all possible completions for the specified string
|
|
- <tt>-e</tt> or <tt>--erase</tt> implies that the specified completion should be deleted
|
|
- <tt>-f</tt> or <tt>--no-files</tt> specifies that the option specified by this completion may not be followed by a filename
|
|
- <tt>-n</tt> or <tt>--condition</tt> specifies a shell command that must return 0 if the completion is to be used. This makes it possible to specify completions that should only be used in some cases.
|
|
- <tt>-o</tt> or <tt>--old-option</tt> implies that the command uses old long style options with only one dash
|
|
- <tt>-p</tt> or <tt>--path</tt> implies that the string COMMAND is the full path of the command
|
|
- <tt>-r</tt> or <tt>--require-parameter</tt> specifies that the option specified by this completion always must have an option argument, i.e. may not be followed by another option
|
|
- <tt>-u</tt> or <tt>--unauthoritative</tt> implies that there may be more options than the ones specified, and that fish should not assume that options not listed are spelling errors
|
|
- <tt>-A</tt> or <tt>--authoritative</tt> implies that there may be no more options than the ones specified, and that fish should assume that options not listed are spelling errors
|
|
- <tt>-x</tt> or <tt>--exclusive</tt> implies both <tt>-r</tt> and <tt>-f</tt>
|
|
- <tt>-w WRAPPED_COMMAND</tt> or <tt>--wraps=WRAPPED_COMMAND</tt> causes the specified command to inherit completions from the wrapped comamnd.
|
|
|
|
Command specific tab-completions in \c fish are based on the notion
|
|
of options and arguments. An option is a parameter which begins with a
|
|
hyphen, such as '`-h`', '`-help`' or '`--help`'. Arguments are parameters
|
|
that do not begin with a hyphen. Fish recognizes three styles of
|
|
options, the same styles as the GNU version of the getopt
|
|
library. These styles are:
|
|
|
|
- Short options, like '`-a`'. Short options are a single character long, are preceded by a single hyphen and may be grouped together (like '`-la`', which is equivalent to '`-l -a`'). Option arguments may be specified in the following parameter ('`-w 32`') or by appending the option with the value ('`-w32`').
|
|
- Old style long options, like '`-Wall`'. 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`').
|
|
- GNU style long options, like '`--colors`'. GNU style long options can be more than one character long, are preceded by two hyphens, and may not be grouped together. Option arguments may be specified in the following parameter ('`--quoting-style`') or by appending the option with a '`=`' and the value ('`--quoting-style=shell`'). GNU style long options may be abbreviated so long as the abbreviation is unique ('`--h`') is equivalent to '`--help`' if help is the only long option beginning with an 'h').
|
|
|
|
The options for specifying command name, command path, or command
|
|
switches may all be used multiple times to specify multiple commands
|
|
which have the same completion or multiple switches accepted by a
|
|
command.
|
|
|
|
The \c -w or \c --wraps options causes the specified command to inherit
|
|
completions from another command. The inheriting command is said to
|
|
"wrap" the inherited command. The wrapping command may have its own
|
|
completions in addition to inherited ones. A command may wrap multiple
|
|
commands, and wrapping is transitive: if A wraps B, and B wraps C,
|
|
then A automatically inherits all of C's completions. Wrapping can
|
|
be removed using the \c -e or \c --erase options.
|
|
|
|
When erasing completions, it is possible to either erase all
|
|
completions for a specific command by specifying `complete -e -c
|
|
COMMAND`, or by specifying a specific completion option to delete
|
|
by specifying either a long, short or old style option.
|
|
|
|
\subsection complete-example Example
|
|
|
|
The short style option `-o` for the `gcc` command requires
|
|
that a file follows it. This can be done using writing:
|
|
|
|
`complete -c gcc -s o -r`
|
|
|
|
The short style option `-d` for the `grep` command requires
|
|
that one of the strings '`read`', '`skip`' or '`recurse`' is used. This can
|
|
be specified writing:
|
|
|
|
`complete -c grep -s d -x -a "read skip recurse"`
|
|
|
|
The `su` command takes any username as an argument. Usernames are
|
|
given as the first colon-separated field in the file /etc/passwd. This
|
|
can be specified as:
|
|
|
|
`complete -x -c su -d "Username" `
|
|
`-a "(cat /etc/passwd | cut -d : -f 1)"`
|
|
|
|
The `rpm` command has several different modes. If the `-e` or `--erase` flag has been specified, `rpm` should delete one or more
|
|
packages, in which case several switches related to deleting packages are valid, like the `nodeps` switch.
|
|
|
|
This can be written as:
|
|
|
|
`complete -c rpm -n "__fish_contains_opt -s e erase"`
|
|
`-l nodeps -d "Don't check dependencies"`
|
|
|
|
where `__fish_contains_opt` is a function that checks the commandline
|
|
buffer for the presence of a specified set of options.
|
|
|
|
To implement an alias, use the \c -w or \c --wraps option:
|
|
|
|
<tt>complete -c hub -w git</tt>
|
|
|
|
Now hub inherits all of the completions from git. Note this can
|
|
also be specified in a function declaration.
|
|
|