GNU Info
(zsh.info)Completion Functions
Utility Functions
=================
Descriptions follow for utility functions that may be useful when
writing completion functions. Most of these reside in the Base
subdirectory. Like the example functions for commands in the
distribution, the utility functions generating matches all follow the
convention of returning zero if they generated completions and non-zero
if no matching completions could be added.
When writing completion functions or other ZLE widgets that call
completion, it might be interesting to know about two more features
offered by the _main_complete function. The arrays compprefuncs and
comppostfuncs may be set to contain names of functions that are to be
called immediately before or after completion has been tried. The
functions will only be called once, unless they put themselves into the
arrays again.
_all_labels [ -12VJ ] TAG NAME DESCR [ COMMAND ARGS ... ]
This is a convenient interface to the _next_label function below,
implementing the loop shown in the _next_label example. The
COMMAND is the one that should be called to generate the matches.
The options stored in the parameter NAME will automatically be
inserted into the ARGS given to the COMMAND. Normally, they are
put directly after the COMMAND, but if one of the ARGS is a single
hyphen, they are inserted directly before that. If the hyphen is
the last argument, that will be removed from the argument list
before the COMMAND is called. This allows _all_labels to be used
in almost all cases where the matches can be generated by a single
call to the compadd builtin command or by a call to one of the
utility functions.
For example:
local expl
...
if _requested foo; then
...
_all_labels foo expl '...' compadd ... - $matches
fi
Will complete the strings from the matches parameter, using
compadd with additional options which will take precedence over
those generated by _all_labels.
_alternative [ -C NAME ] SPECS ...
This function is useful in simple cases where multiple tags are
available. Essentially, it implements a loop like the one
described for the _tags function above.
The tags to use and the action to perform if a tag is requested are
described using the SPECS which are of the form:
`TAG:DESCR:ACTION'. The TAGs are offered using _tags and if the
tag is requested, the ACTION is executed with the given
description DESCR. The ACTIONs supported are those used by the
_arguments function (described below), without the `->STATE' and
`=...' forms.
For example, the ACTION may be a simple function call. With that
one could do:
_alternative \
'users:user:_users' \
'hosts:host:_hosts'
to offer usernames and hostnames as possible matches (which are
generated by the _users and _hosts functions respectively).
Note that, like _arguments this will also use _all_labels to
execute the actions, so one doesn't need to call that explicitly
unless another tag is to be used, for example in a function called
from _alternative.
Like _tags this function supports the -C option to give a
different name for the argument context field.
_arguments [ -ACS ] [ -O NAME ] [ -M MATCHSPEC ] SPEC ...
This function can be used to complete words on the line by
describing the options and arguments which may be passed to the
command for which completion is being performed. The description
is given as arguments to this function, with each SPEC describing
one option or normal argument of the command. The forms of SPEC
understood are:
N:MESSAGE:ACTION
N::MESSAGE:ACTION
This describes the N'th normal argument. The MESSAGE will be
printed above the matches generated and the ACTION says what
can be completed in this position (see below). If there are
two colons before the MESSAGE, this describes an optional
argument. If the MESSAGE contains only white space, nothing
will be printed above the matches unless the action adds an
explanation string itself.
:MESSAGE:ACTION
::MESSAGE:ACTION
Like the previous one, but describing the _next_ argument.
I.e. if you want to describe all arguments a command can get,
you can leave out the numbers in the description and just use
this form to describe them one after another in the order
they have to appear on the line.
*:MESSAGE:ACTION
*::MESSAGE:ACTION
*:::MESSAGE:ACTION
This describes how arguments (usually non-option arguments,
those not beginning with - or +) are to be completed when no
description with one of the first two forms was given. This
also means that any number of arguments can be completed.
With two colons before the MESSAGE, the words special array
and the CURRENT special parameter are modified to refer only
to the normal arguments when the ACTION is executed or
evaluated. With three colons before the MESSAGE they are
modified to refer only to the normal arguments covered by
this description.
OPTSPEC[DESCRIPTION ...]
This describes an option and (if DESCRIPTION is given) the
arguments that have to come after the option. If no
DESCRIPTION is given, this means to offer only the option
name as a possible completion in the right places. (Note
that the brackets, above, around DESCRIPTION, indicate that
zero or more DESCRIPTIONs may appear; but the brackets are not
themselves part of this format. If brackets are used, they
are part of the OPTSPEC; see below.)
In the descriptions below, the option names represented by
OPTNAME are normally taken to be multi-character names, and a
word from the line is considered to contain only one option
(or none). By giving the -s option to _arguments before the
first SPEC, each OPTNAME is considered to be a single
character and each word from the line may contain more than
one such option letter. However, words beginning with two
hyphens (like `--prefix') are still considered to contain only
one option name. This allows the use of the `-s' option to
describe single-letter options together with such long option
names.
The -s option may be combined with the option -w to say that
more option characters are to be expected even after an
option that takes an argument. For example, if a command
takes the options `a' and `b', where `a' takes an argument in
the next word, _arguments would normally not complete the
other option directly after `-a', but it would allow that if
given the -w option.
Similarly, the option -W may be given together with -s to
force completion of single-letter options even after options
that get an argument in the same word. For example, if a
command takes the options `a' and `b', where `a' needs an
argument in the same word, directly after the option
character, _arguments would normally only execute the action
for that argument and not offer other single-letter options
as possible completions. If given the -W option, it will
offer other options as possible completions after executing
the action for the argument. Note that, depending on the
action, this may mean that the other options can't really be
completed, but at least they will be listed. For more
control, use an utility function like _guard in the
argument's action.
The forms of OPTSPEC are:
*OPTSPEC
If the option may be given more than once, a star (`*')
must be added in front of one of the following forms of
OPTSPEC. Otherwise, if the option is already on the
line and to the left of the cursor, it is not offered as
a possible completion again.
-OPTNAME
+OPTNAME
In the simplest form the OPTSPEC is just the option name
beginning with a minus or a plus sign, such as `-foo'.
The first argument for the option (if any) must follow
as a _separate_ word directly after the option.
If the command accepts the option with either a leading
minus or a leading plus sign, use either `-+OPTNAME' or
`+-OPTNAME' to define both variants at once.
In all the following forms, the leading `-' may be
replaced or paired with `+' in this way.
-OPTNAME-
The first argument of the option must come directly
after the option name _in the same word_, as in
`-foo-:...'.
-OPTNAME+
The first argument may appear immediately after OPTNAME
in the same word, or may instead appear as a separate
word after the option.
-OPTNAME=
The argument may appear as the next word, or in same
word as the option name provided that it is separated
from it by an equals sign.
-OPTNAME=-
The argument to the option must appear after an equals
sign in the same word, and may not be given in the next
argument.
OPTSPEC[EXPLANATION]
An explanation string may be appended to any of the
preceding forms of OPTSPEC by enclosing it in brackets,
as in `-q[query operation]'.
The verbose style is used to decide if these explanation
strings should be displayed with the option in a
completion listing.
If no bracketed explanation string is given but the
auto-description style is set and only one argument is
described for this OPTSPEC, the value of the style is
displayed, with any appearance of the sequence `%d' in
it replaced by the MESSAGE of the first DESCRIPTION that
follows the OPTSPEC; see below.
Note that the special meaning of a leading or trailing - or +
in OPTSPEC means that when the command to be completed
accepts options like `-+' or `-=', the second character has
to be quoted with a backslash, as in `-\+'.
Each DESCRIPTION following an OPTSPEC must take one of the
following forms:
:MESSAGE:ACTION
::MESSAGE:ACTION
Describes a mandatory argument with one colon, or an
optional argument with two colons. As in other forms of
SPEC, the MESSAGE will be printed above the matches
generated (unless it contains only white space, see
above) and the ACTION says what can be completed in this
position.
:*PATTERN:MESSAGE:ACTION
:*PATTERN::MESSAGE:ACTION
:*PATTERN:::MESSAGE:ACTION
This describes multiple arguments. Only the _last_
description may be given in this form. If the PATTERN
is empty (i.e., :*:), all following words on the line
are to be completed as described by the ACTION;
otherwise, all words up to a word matching the PATTERN
are to be completed using the ACTION.
When the MESSAGE is preceded by two colons, the words
special array and the CURRENT special parameter are
modified during the execution or evaluation of the
ACTION to refer only to the words after the option.
When preceded by three colons, they are modified to
refer only to the words covered by this description.
Note that only one such `:*'-specification is useful and
no other argument specification may be given after it.
To include a colon in any OPTNAME, MESSAGE, or ACTION anywhere
above, it has to be preceded by a backslash, as `\:'.
Each of the six forms of SPEC (yes, there are six, keep track of
the nestings) may be preceded by a list of option names and
argument numbers with which the option or argument described is
mutually exclusive. This list is given in parentheses, as in
`(-two -three 1)-one:...' or `(-foo):...'. In the first example,
the options `-two' and `-three' and the first argument will not be
offered as possible completions if the option `-one' is on the
line before the cursor, and in the second example the option
`-foo' will not be offered if the argument described by the
specification is on the line.
The list may also contain a single star (*) as one of its elements
to specify that the description for the rest arguments (i.e. a
specification of the form `*:...') should not be used, a colon (:)
to specify that the descriptions for all normal (non-option-)
arguments should not be used and a hyphen (-) to specify that the
descriptions for all options should not be used. This paragraph
desperately needs rewriting.
To simplify writing writing functions that call _arguments more
than once, the SPECS may also start with the character `!'
(exclamation mark) to make the spec _not_ be completed. However,
if this is used with one of the forms describing options, the
option (and its arguments, if it takes any) will be understood and
skipped if they appear on the command line. It's just that the
option itself will not be completed. This is intended to be used
with an array containing the options used in the first call to
arguments. The second call can then use `\!${^global_options}' to
ignore those options and complete only the ones understood in the
current context.
In every case above, the ACTION determines how the possible
completions should be generated. In places where no sensible
matches can be generated, the action should consist of only a
space. This will make the MESSAGE be displayed but no possible
completions listed. Note that even in this case the colon at the
end of the MESSAGE is needed. The only case where it can be left
is when neither a MESSAGE, nor a ACTION is given.
Except for the `->STRING' form below, the ACTION will be executed
by calling the _all_labels function to process all tag labels, so
one doesn't need to call that explicitly unless another tag is to
be used, for example in a function called in the ACTION.
When only one of a fixed set of strings can be completed, the
ACTION can consist of these strings as a list in parentheses, as
in:
:foo:(foo bar baz)
Such a list in doubled parentheses should contain strings
consisting of the string to complete followed by `\:' and a
description, as in:
:foo:((a\:bar b\:baz))
The matches will be listed together with their descriptions if the
description style for the values tag is set.
An ACTION of the form `->STRING' is used by functions that
implement a state machine. In this case, the `STRING's (with all
leading and trailing spaces and tabs removed) of all actions that
have to be used will be stored in the global array state. The
function returns with a non-zero return value if the cursor is not
in a position where options can be completed or if the current
word could not be completed to an option. But if the -R option is
given to _arguments, the function will instead return with a return
value of 300 (to make it distinguishable from other return values)
after setting the global `context', `line' and `opt_args'
parameters as described below, and without resetting any changes
made to the special parameters such as PREFIX and words. This
enables wrapper functions around _arguments to be able to find out
if they have to make sure that the special completion parameters
are not reset when they return.
Note that this means that a function calling _arguments with at
least one action containing such a `->STRING' has to declare
appropriate local parameters as in:
local context state line
typeset -A opt_args
This will ensure that _arguments does not create unused global
parameters.
A string in braces is evaluated to generate the matches and if the
ACTION does not begin with an opening parentheses or brace, it is
also split into separate words and executed. If the ACTION starts
with a space, this list of words will be invoked unchanged,
otherwise it will be invoked with some extra strings placed after
the first word which can be given as arguments to the compadd
builtin command and which make sure that the MESSAGE given in the
description will be shown above the matches. These arguments are
taken from the array parameter `expl' which will be set up before
executing the ACTION and hence may be used in it (normally in an
expansion like `$expl[@]').
If the ACTION starts with `= ' (an equals sign followed by a
space), _arguments will insert the contents of the ARGUMENT field
of the current context as the new first element in the words
special array and increments the value of the CURRENT special
parameter. In other words, it inserts a dummy element in the words
array and makes CURRENT still point to the word in that array
where the cursor is. This is only really useful when used with one
of the forms that make _arguments modify the words array to
contain only some of the words from the line, i.e. one of the
argument description forms where the MESSAGE is preceded by two or
three colons. For example, when the function called in the action
for such an argument itself uses _arguments, the dummy element is
needed to make that second call to _arguments use all words from
the restricted range for argument parsing. Without the inserted
dummy element, the first word in the range would be taken (by the
second _arguments) to be the command name and hence ignored.
During the evaluation or execution of the action the array `line'
will be set to the command name and normal arguments from the
command line, i.e. to the words from the command line excluding
all options and their arguments. These are stored in the
associative array `opt_args', using the option names as keys and
their arguments as the values. For options that have more than one
argument these are given as one string, separated by colons. All
colons in the original arguments are preceded with backslashes.
The parameter `context' (set only in the calling function when
using an action of the form `->STRING', not during the evaluation
of other ACTIONs) is set to the automatically created context
names. These are either strings of the form `option-OPT-N' for the
N'th argument of the option -OPT, or strings of the form
`argument-N' for the N'th argument (for rest arguments the N is
the string `rest'). For example, when completing the argument of
the -o option, the name is `option-o-1' and for the second normal
(non-option-) argument it is `argument-2'.
Also, during the evaluation of the ACTION, the context name in the
curcontext parameter is changed by appending the same string that
is stored in the context parameter.
It is also possible to specify multiple sets of options and
arguments with the sets separated by single hyphens. The
specifications before the first hyphen are shared by all sets
given after the first hyphen. The first word in every other set
gives the name of the set. This name may appear in exclusion lists
in the specifications, either alone or before one of the possible
values described above (with a `-' between the name and the rest).
For example:
_arguments \
-a \
- set1 \
-c \
- set2 \
-d \
':arg:(x2 y2)'
This defines two sets. When the command line contains the option
`-c', the `-d' option and the argument will not be considered
possible completions. When it contains `-d' or an argument, the
option `-c' will not be completed any more, but if `-a' is given,
both sets will still be considered valid, because it appears
before the first hyphen, so both sets contain this option.
If the name-string is of the form `(NAME)' then all specifications
in the set have an implicit exclusion list containing the name of
the set, i.e. all specifications are mutual exclusive with all
other specifications in the same set. This is useful for defining
multiple sets of options which are mutually exclusive and in which
the options are aliases for each other. E.g.:
_arguments \
-a -b \
- '(compress)' \
{-c,--compress}'[compress]' \
- '(uncompress)' \
{-d,--decompress}'[decompress]'
Note that using multiple sets will be slower than using only one
set because the completion code has to parse the command line once
for every set. So more than one set should only be used if the
command syntax is too complicated. Note also that an option
specification with rest-arguments (as in `-foo:*:...') often
allows the use of multiple sets to be avoided.
To simplify the specifications for commands with standard option
parsing, the options -S and -A may be given. With -S, no option
will be completed after a `--' on the line and this argument will
otherwise be ignored. With -A, no options will be completed after
the first non-option argument on the line. The -A has to be
followed by a pattern matching all strings which are not to be
taken as arguments. For example, to make _arguments stop
completing options after the first normal argument, but ignoring
all strings starting with a hyphen even if they are not described
by one of the OPTSPECs, one would use: `-A "-*"'.
Another option supported is `-O NAME'. The NAME will be taken as
the name of an array and its elements will be given to functions
called to generate matches when executing the ACTIONS. For
example, this allows one to give options for the compadd builtin
that should be used for all ACTIONs.
Also, the -M option followed by a string may be given before the
first description. The string will be used as the match
specification when completing option names and values instead of
the default `r:|[_-]=* r:|=*'.
Finally, the option -C can be given to make _arguments modify the
curcontext parameter when an action of the form `->STATE' is used.
This parameter is used to keep track of the current context and in
this case it (and not the parameter context as explained above)
has to be made local to make sure that calling functions don't use
the modified value. Also, the local version of curcontext has to
be initialised with the old value as in:
local curcontext="$curcontext"
The function can also be made to automatically complete long
options for commands that support the `--help' option as, for
example, most of the GNU commands do. For this, the string `--'
must be given as one argument and if it is, the command from the
line is invoked with the `--help' option and its output is parsed
to find possible option names. Note that this means that you
should be careful to make sure that this feature is not used for a
command that does not support this option.
For such automatically found options that get an argument after an
`=', the function also tries to automatically find out what should
be completed as the argument. The possible completions for
option-arguments can be described with the arguments after the
`--' (which are not used as described above). Each argument
contains one description of the form `PATTERN:MESSAGE:ACTION'. The
MESSAGE and the ACTION have the same format as for the normal
option descriptions described above. The ACTION will be executed to
complete arguments of options whose description in the output of
the command from the line with the `--help' option matches the
PATTERN. For example:
_arguments -- '*\*:toggle:(yes no)' \
'*=FILE*:file:_files' \
'*=DIR*:directory:_files -/'
Here, `yes' and `no' will be completed as the argument of options
whose description ends in a star, file names for options that
contain the substring `=FILE' in the description, and paths for
options whose description contains `=DIR'. In fact, the last two
patterns are not needed since this function always completes files
for option descriptions containing `=FILE' and paths for option
descriptions that contain `=DIR' or `=PATH'. These builtin
patterns can be overridden by patterns given as arguments, however.
Note also that _arguments tries to find out automatically if the
argument for an option is optional. If it fails to automatically
detect this, the colon before the MESSAGE can be doubled to tell
it about this as described for the normal option descriptions
above.
If the PATTERN ends in `(-)', this will removed from the pattern
and the ACTION will be used only directly after the `=', not in
the next word. I.e., this is like a normal specification as
described above using `=-'.
The option `-i PATTERNS' (which must be given after the `--') can
be used to give patterns for options which should not be
completed. The patterns can be given as the name of an array
parameter or as a literal list in parentheses. E.g. `-i
"(--(en|dis)able-FEATURE*)"' will make the options
`--enable-FEATURE' and `--disable-FEATURE' be ignored. The option
`-s PAIRS' (again, after the `--') can be used to describe option
aliases. Each PAIR consists of a pattern and a replacement. E.g.
some configure-scripts describe options only as `--enable-foo',
but also accept `--disable-foo'. To allow completion of the second
form, one would use `-s "(#--enable- --disable-)"'.
Example:
_arguments '-l+:left border:' \
'-format:paper size:(letter A4)' \
'*-copy:output file:_files::resolution:(300 600)' \
':postscript file:_files -g \*.\(ps\|eps\)' \
'*:page number:'
This describes three options: `-l', `-format', and `-copy'. The
first one gets one argument described as `LEFT BORDER' for which
no completion will be offered because of the empty action. The
argument may come directly after the `-l' or it may be given as
the next word on the line. The `-format' option gets one argument
(in the next word) described as `PAPER SIZE' for which only the
strings `letter' and `A4' will be completed. The `-copy' option
differs from the first two in that it may appear more than once on
the command line and in that it accepts two arguments. The first
one is mandatory and will be completed as a filename. The second
one is optional (because of the second colon before the
description `RESOLUTION') and will be completed from the strings
`300' and `600'.
The last two descriptions say what should be completed as
arguments. The first one describes the first argument as a
`POSTSCRIPT FILE' and makes files ending in `ps' or `eps' be
completed. The last description says that all other arguments are
`PAGE NUMBERS' but does not give possible completions.
_cache_invalid CACHE_IDENTIFIER
This function returns 0 if the completions cache corresponding to
the given cache identifier needs rebuilding. It determines this by
looking up the cache-policy style for the current context, and if
it exists, runs the function of the same name, supplying the full
path to the relevant cache file as the only argument.
Example:
_example_caching_policy () {
# rebuild if cache is more than a week old
oldp=( "$1"(Nmw+1) )
(( $#oldp ))
}
_call_function RETURN NAME [ ARGS ... ]
If a function NAME exists, it is called with the arguments ARGS.
Unless it is the empty string or a single hyphen, RETURN is taken
as the name of a parameter and the return status from the called
function is stored in it. The return value of _call_function
itself is zero if the function NAME exists and was called and
non-zero otherwise.
_call_program TAG STRING ...
This function is used in places where a command is called, making
it possible for the user to override the default command call. It
looks up the command style with the supplied TAG. If the style is
set, its value is used as the command to execute.
In any case, the STRINGs from the call to _call_program or from the
style are concatenated with spaces between them and the resulting
string is evaluated. The return value is the return value of the
command called.
_combination [ -s PATTERN ] TAG STYLE SPECS ... FIELD OPTS ...
This function is used to complete combinations of values such as
pairs of hostnames and usernames. The possible values will be
taken from the STYLE whose name is given as the second argument.
The first argument is the TAG to use to do the lookup.
The style name should consist of multiple parts separated by
hyphens which are then used as field names. Known values for such
fields can be given after the second argument in arguments of the
form `FIELD=PATTERN'. The first argument without an equals sign
is taken as the name of the field for which completions should be
generated.
The matches generated will be taken from the value of the style.
These values should contain the possible values for the
combinations where the values for the different fields are
separated by colons or characters matching the pattern given after
the -s option to _combination; normally this is used to define
character classes like the `-s "[:@]"' used for the users-hosts
style.
Only the values for the requested fields for which the patterns
given in the `FIELD=PATTERN' match the respective fields in the
strings from the style value are generated as possible matches.
If no style with the given name is defined for the given tag but a
function named with the name of the requested field preceded by an
underscore is defined, that function will be called to generate the
matches. This is also done if none of the strings in the value of
the style match all the patterns given as arguments.
If the same name is used for more than one field, in both the
`FIELD=PATTERN' and the argument that gives the field name to
complete for, the number of the field (starting with one) may be
given after the fieldname, separated from it by a colon.
All arguments after the requested field name are passed to compadd
when generating matches from the style value, or to the functions
for the fields if they are called.
_contexts NAMES ...
This function looks up the definitions for the context and command
names given as arguments and calls the handler functions for them
if there is a definition (given with the compdef function). For
example, the function completing inside subscripts might use
`_contexts -math-' to include the completions generated for
mathematical environments.
_describe [ -o ] DESCR NAME1 [ NAME2 ] OPTS ... -- ...
This function is useful for preparing a list of command options or
arguments, together with their descriptions DESCR, as matches.
Multiple groups separated by -- can be supplied, potentially with
different completion options OPTS.
The DESCR is taken as a string to display above the matches if the
format style for the descriptions tag is set. After this come one
or two names of arrays followed by options to pass to compadd. The
first array contains the possible completions with their
descriptions in the form `COMPLETION:DESCRIPTION'. If a second
array is given, it should have the same number of elements as the
first one and the corresponding elements are added as possible
completions instead of the COMPLETION strings from the first
array. The completion list will retain the descriptions from the
first array. Finally, a set of completion options can appear.
If the option `-o' appears before the first argument, the matches
added will be treated as option names (typically following a `-',
`--' or `+' on the command line). This makes _describe use the
prefix-hidden, prefix-needed and verbose styles to find out if the
strings should be added at all and if the descriptions should be
shown. Without the `-o' option, only the verbose style is used.
_describe uses the _all_labels function to generate the matches, so
it does not need to appear inside a loop over tag labels.
_description [ -12VJ ] TAG NAME DESCR [ SPECS ... ]
This function is called before completions are added (typically by
a call to compadd); it tests various styles and arranges for any
necessary options to be passed on to compadd. The styles are
tested in the current context using the given TAG; options are put
into the array called NAME for passing on to compadd; the
description for the current set of matches is passed in DESCR.
The styles tested are: format (which is first tested for the given
TAG and then for the descriptions tag if that isn't defined),
hidden, matcher, ignored-patterns and group-name (the last are
tested only for the tag given as the first argument). This
function also calls the _setup function which tests some more
styles.
The string returned by the format style (if any) will be modified
so that the sequence `%d' is replaced by the DESCR given as the
third argument without any leading or trailing white space. If,
after removing the white space, the DESCR is the empty string, the
format style will not be used and the options put into the NAME
array will not contain an explanation string to be displayed above
the matches. If _description is called with more than three
arguments, the additional SPECS should be of the form `CHAR:STR'
and every appearance of `%CHAR' in the format string will be
replaced by STRING.
The options placed in the array will also make sure that the
matches are placed in a separate group, depending on the value of
the group-name style. Normally a sorted group will be used for
this (with the `-J' option), but if an option starting with `-V',
`-J', `-1', or `-2' is given, that option will be included in the
array, so that it is possible to make the group unsorted by giving
the option `-V', `-1V', or `-2V'.
In most cases, the function will be used like this:
local expl
_description files expl file
compadd "$expl[@]" - "$files[@]"
Note the use of the parameter expl, the hyphen, and the list of
matches. Almost all calls to compadd within the completion system
use a similar format; this ensures that user-specified styles are
correctly passed down to the builtins which implement the
internals of completion.
_files
The function _files uses the file-patterns style and calls
_path_files with all the arguments it was passed except for -g and
-/. These two options are used depending on the setting of the
file-patterns style.
See _path_files below for a description of the full set of options
accepted by _files.
_gnu_generic
This function is a simple wrapper around the _arguments function
described above. It can be used to automatically complete long
options for commands that understand the `--help' option. It is
not intended to be used from completion functions but as a
top-level completion function in its own right. For example, to
enable option completion for the commands foo and bar, one would
call:
compdef _gnu_generic foo bar
in one of the initialization files after the call to compinit.
The default installation uses this function only to generate
completions for some GNU-commands because to complete the options,
the command has to be called and hence it shouldn't be used if one
can't be sure that the command understands the `--help' option.
_guard [ OPTIONS ] PATTERN [ DESCR ]
This function is intended to be used in an action of functions like
_arguments. It returns immediately with a non-zero return value if
the string to be completed does not match the PATTERN. If the
pattern matches, the DESCR is displayed and the function returns
zero if the word to complete is not empty and non-zero otherwise.
The PATTERN may be preceded by those options understood by compadd
that are passed down from _description, namely -M, -J, -V, -1, -2,
-n, -F and -X. All of these options, except -X, will be ignored.
If the -X option appears, the description following it will be
used as the string to display if the PATTERN matches, unless the
option DESCR is given to _guard itself, which will then take
precedence.
As an example, consider a command taking the options -n and -none,
where -n has to be followed by a numeric value in the same word.
By using either of:
_argument '-n-:numeric value:_guard "[0-9]#"' '-none'
or
_argument '-n-: :_guard "[0-9]#" "numeric value"' '-none'
_arguments can be made to both display the message `numeric value'
and complete options after `-n<TAB>'. If the `-n' is already
followed by one or more digits (matching the pattern given to
_guard), only the message will be displayed and if the `-n' is
followed by another character, only options are completed.
_message [ -r ] DESCR
The DESCR is used like the third argument to the _description
function. However, the resulting string will always be shown
whether or not matches were generated. This is useful to display
help texts in places where no completions can be generated
automatically.
This function also uses the format style for the messages tag in
preference to the format style for the descriptions tag. The
latter is used only if the former is unset.
If the -r option is given, no style is used and the DESCR is used
literally as the string to display. This is only used in cases
where that string is taken from some pre-processed argument list
containing an expanded description.
_multi_parts SEP ARRAY
This function receives two arguments: a separator character and an
array. As usual, the ARRAY may be either the name of an array
parameter or a literal array in the form `(foo bar)' (i.e. a list
of words separated by white space in parentheses). With these
arguments, this function will complete to strings from the array
where the parts separated by the separator character are completed
independently. For example, the _tar function from the
distribution caches the pathnames from the tar file in an array,
and then calls this function to complete these names in the way
normal filenames are completed by the _path_files function, by
using `_multi_parts / PATHARRAY'.
If the -i option is present, then any time there is a unique match
it will immediately be inserted even if that requires additional
separators to be inserted as well. When completing from a fixed
set of possible completions which are really words, this is often
the expected behaviour; however, if _multi_parts should behave
like completing pathnames, the -i option should not be used.
Like other utility functions, this function accepts the `-V',
`-J', `-1', `-2', `-n', `-f', `-X', `-M', `-P', `-S', `-r', `-R',
and `-q' options and passes them to the compadd builtin.
_next_label [ -12VJ ] TAG NAME DESCR [ OPTIONS ... ]
This function should be called repeatedly to generate the tag
labels. On each call it will check if another tag label is to be
used and, if there is at least one, zero is returned. If no more
tag labels are to be used, a non-zero status is returned.
The -12JV options and the first three arguments are given to the
_description function using the tag label instead of the first
argument as appropriate. The OPTIONS given after the DESCR should
be other options to be used for compadd or whatever function is to
be called to add the matches. _next_label will store these OPTIONS
in the parameter whose NAME is given as the second argument. This
is done in such a way that the description given by the user to
the tag-order style is preferred over the one given to _next_label.
Note that this function must not be called without a previous call
to _tags or _requested because it uses the tag label for the
current tag found by these functions.
A normal use of this function for the tag labels of the tag foo
looks like this:
local expl ret=1
...
if _requested foo; then
...
while _next_label foo expl '...'; do
compadd "$expl[@]" ... && ret=0
done
...
fi
return ret
_normal
This function is used for normal command completion. It has two
tasks: completing the first word on the command line as the name
of a command, and completing the arguments to this command. In
the second case, the name of the command is looked up to see if
special completions exists, including completions defined for
patterns which match the name. If none is found, completion is
performed for the context -default-.
The function can also be called by other completion functions
which need to treat a range of words as a command line. For
example, the function to complete after the pre-command specifiers
such as nohup removes the first word from the words array,
decrements the CURRENT parameter, then calls _normal again, with
the effect that `nohup CMD ...' is treated the same way was `CMD
...'.
If the command name matches a pattern, the parameter _compskip is
checked after the call to the corresponding completion function.
This has the same effect here as in the -first- context: if it is
set, no more completion functions are called even if there are no
matches so far.
_options
This can be used to complete option names. It uses a matching
specification that ignores a leading `no', ignores underscores and
allows the user to type upper-case letters which will match their
lower-case counterparts. All arguments passed to this function are
propagated unchanged to the compadd builtin.
_options_set and _options_unset
These functions complete only set or unset options, with the same
matching specification used in the _options function.
Note that you need to uncomment a few lines in the _main_complete
function for these functions to work properly. The lines in
question are used to store the option settings in effect before
the completion widget locally sets the options it needs. Hence
these options are not generally used by the completion system.
_parameters
This should be used to complete parameter names. _parameters can
take a -g PATTERN option which specifies that only parameters
whose type matches the PATTERN should be completed. Strings of
the same form as those returned by the t parameter expansion flag
are used here when matching the type. All other arguments are
passed unchanged to the compadd builtin.
_path_files
The function _path_files is used throughout the completion system
to complete filenames. It allows completion of partial paths. For
example, the string `/u/i/s/sig' may be completed to
`/usr/include/sys/signal.h'.
The options accepted by both _path_files and _files are:
-f
Complete all filenames. This is the default.
-/
Specifies that only directories should be completed.
-g PATTERN
Specifies that only files matching the PATTERN should be
completed.
-W PATHS
Specifies path prefixes that are to be prepended to the
string from the line to generate the filenames but that
should not be inserted in the line or shown in a completion
listing. Here, PATHS may be the name of an array parameter,
a literal list of paths enclosed in parentheses or an
absolute pathname.
-F
This option from the compadd builtin gives direct control
over which filenames should be ignored. If the option is not
present, the ignored-patterns style is used.
These functions also accept the `-J', `-V', `-1', `-2', `-n',
`-X', `-M', `-P', `-S', `-q', `-r', and `-R' options from the
compadd builtin.
Finally, the _path_files function uses the styles expand,
ambiguous, special-dirs, list-suffixes and file-sort.
_regex_arguments NAME SPECS ...
This function is a compiler to generate a completion function. The
first argument specifies the name of the generated function while
the remaining arguments specify a completion as a set of regular
expressions with actions. The generated function has the
structure of a finite-state machine whose states correspond to the
state (i.e. the context) of the completion. This state machine
uses a command line, which comes from the concatenation of the
words array up to the current cursor position using null
characters as separators with no extra quotation. This is
analysed and at the end the appropriate action is executed.
Specification arguments take one of following forms, in which
metacharacters such as `(', `)', `#' and `|' should be quoted.
/PATTERN/ [%LOOKAHEAD%] [-GUARD] [:TAG:DESCR:ACTION]
This is a primitive element, corresponding to one state of
the compiled state machine. The state is entered if
`(#b)((#B)PATTERN)(#B)LOOKAHEAD*' matches the command line
string. If it matches, `GUARD' is evaluated and its return
status is examined; if this is successful, the state is
entered, otherwise the test fails and other candidates are
tried. The PATTERN string `[]' is guaranteed never to match.
If the test succeeds and the state is entered, the left part
of the command line string matched as PATTERN is removed and
the next state is tried, proceeding from inside to outside
and from left to right.
If no test succeeds and the remaining command line string
contains no null character, the completion target is
restricted to the remainder of the command line string and
ACTIONs for the target are executed. In this case, nothing
is actually removed from the command line string so that any
previous or neighbouring state may also have ACTIONSs.
ACTIONSs evaluation are ordered by the tag-order style and
specified TAG by _alternative. So, the various formats
supported by _alternative can be used in ACTION. DESCR is
used for setting up the array parameter expl.
/PATTERN/+ [%LOOKAHEAD%] [-GUARD] [:TAG:DESCR:ACTION]
This is similar to `/PATTERN/ ...' but the left part of the
command line string is also considered as part of the
completion target.
/PATTERN/- [%LOOKAHEAD%] [-GUARD] [:TAG:DESCR:ACTION]
This is similar to `/PATTERN/ ...' but the ACTIONs of the
current and previous states are ignored even if the following
state's `PATTERN' matches the empty string.
( SPEC )
This groups SPECs.
SPEC #
This allows any number of repetitions of SPEC.
SPEC SPEC
This represents the concatenation of two SPECs.
SPEC | SPEC
Either of the two SPECs can be matched.
_requested [ -12VJ ] TAG [ NAME DESCR [ COMMAND ARGS ... ] ]
This function is called to decide whether a tag already registered
by a call to _tags (see below) is requested and hence completion
should be performed for it; it returns status zero if the tag is
requested and non-zero otherwise. This will usually be done in a
loop such as the following:
_tags foo bar baz
while _tags; do
if _requested foo; then
... # perform completion for foo
fi
... # test the tags bar and baz in the same way
... # exit loop if matches were generated
done
Note that the test for whether matches were generated is not
performed until the end of the _tags loop. This is so that the
user can specify a set of tags to be tested at the same time in
the tag-order parameter.
If the NAME and the DESCR are given, _requested calls the
_description function with these arguments, including the options.
If the COMMAND is given, the _all_labels function will be called
immediately with the same arguments. This is often useful to do
both the testing of the tag, getting the description for the
matches and adding the matches at once. For example:
local expl ret=1
_tags foo bar baz
while _tags; do
_requested foo expl 'description' \
compadd foobar foobaz && ret=0
...
(( ret )) || break
done
Note that this means that the COMMAND has to accept the options
that have to be passed down to compadd.
_retrieve_cache CACHE_IDENTIFIER
This function retrieves completion information from the file given
by CACHE_IDENTIFIER, stored in a directory specified by the
cache-path style (defaults to ~/.zsh/cache). The return value is
zero if retrieval was successful. It will only attempt retrieval
if the use-cache style is set, so you can call this function
without worrying about whether the user wanted to use the caching
layer.
See _store_cache below for more details.
_sep_parts
This function is passed alternating arrays and separators as
arguments. The arrays specify completions for parts of strings to
be separated by the separators. The arrays may be the names of
array parameters or a quoted list of words in parentheses. For
example, with the array `hosts=(ftp news)' the call `_sep_parts
'(foo bar)' @ hosts' will complete the string `f' to `foo' and
the string `b@n' to `bar@news'.
This function passes the `-V', `-J', `-1', `-2', `-n', `-X', `-M',
`-P', `-S', `-r', `-R', and `-q' options and their arguments to
the compadd builtin used to add the matches.
_setup TAG [ GROUP ]
This function expects a tag as its argument and sets up the special
parameters used by the completion system appropriately for the tag,
using styles such as list-colors and last-prompt.
The optional GROUP gives the name of the group in which the
matches will be placed. If it is not given, the TAG is used as the
group name.
Note that this function is called automatically from _description
so that one normally doesn't have to call it explicitly.
_store_cache CACHE_IDENTIFIER VARS ...
This function, when combined with _retrieve_cache and
_cache_invalid, makes it easy to implement a caching layer for
your completion functions. If a completion function needs to
perform a costly operation in order to generate data which is used
to calculate completions, you can store that data in variables,
and use this function to dump the values of those variables to a
file. Then, if they are needed in subsequent shell invocations,
they can be retrieved quickly from that file via _retrieve_cache,
avoiding the need for repeating the costly operation.
The CACHE_IDENTIFIER specifies the file which the data should be
dumped to, and is stored in a directory specified by the
cache-path style (defaults to ~/.zsh/cache). The remaining VARS
arguments are the variables to dump to the file.
The return value is zero if storage was successful. The function
will only attempt storage if the use-cache style is set, so you can
call this function without worrying about whether the user wanted
to use the caching layer.
If your completion function avoids calling _retrieve_cache when it
already has the completion data in the environment, it should
probably at least call _cache_invalid to check whether this data
and the data cached on disk is still valid.
See the _perl_modules completion function for a simple example of
usage of this caching layer.
_tags [ -C NAME [ TAGS ... ] ]
If called with arguments, these are taken as the names of the tags
for the types of matches the calling completion function can
generate in the current context. These tags are stored internally
and sorted by using the tag-order style. Following calls to this
function without arguments from the same function will then select
the first, second, etc. set of tags requested by the user. To
test if a certain tag should be tried, the _requested function has
to be called (see above).
The return value is zero if at least one of the tags is requested
and non-zero otherwise.
This function also accepts the -C option followed by a NAME. This
name is temporarily (i.e. not visible outside _tags) stored in the
argument field of the context name in the curcontext parameter.
This allows _tags to be made to use a more specific context name
without having to change and reset the curcontext parameter (which
would otherwise have the same effect).
_values SPECS ...
This is used to complete values (strings) and their arguments or
lists of such values. It can be used in two ways.
If the first argument is the option `-O NAME', this will be used
in the same way as by the _arguments function, in other words the
elements of the NAME array will be given to calls to compadd and
when executing an action.
Otherwise, if the first argument (or the first argument after the
`-O NAME' option if that is used) is the option `-s', the next
argument is used as the character that separates multiple values.
Thus the values completed appear in the same word on the command
line, unlike completion using _arguments.
The first argument (after the options and separator character if
they are given) is used as a string to print as a description
before listing the values.
All other arguments describe the possible values and their
arguments in the same format used for the description of options by
the _arguments function (see above). The only differences are that
no minus or plus sign is required at the beginning, that values
can have only one argument and that those forms of actions
beginning with an equal sign are not supported.
The character separating a value from its argument can be set
using the option -S (like -s, followed by the character to use as
the separator in the next argument). If this option is not used,
the equal sign will be used as the separator.
Example:
_values -s , 'description' \
'*foo[bar]' \
'(two)*one[number]:first count:' \
'two[another number]::second count:(1 2 3)'
This describes three possible values: `foo', `one', and `two'.
The first is described as `bar', takes no argument and may appear
more than once. The second is described as `number', may appear
more than once, and takes one mandatory argument described as
`first count' for which no action is specified so that it will not
be completed automatically. The `(two)' at the beginning says
that if the value `one' is on the line, the value `two' will not
be considered to be a possible completion anymore. Finally, the
last value (`two') is described as `another number' and takes an
optional argument described as `second count' which will be
completed from the strings `1', `2', and `3'. The _values function
will complete lists of these values separated by commas.
Like _arguments this function temporarily adds another context
name component to the current context name while executing the
ACTION. Here this name is just the name of the value for which
the argument is completed.
To decide if the descriptions for the values (not those for the
arguments) should be printed, the style verbose is used.
One last difference from _arguments is that this function uses the
associative array val_args to report values and their arguments,
although otherwise this is the same as the opt_args association
used by _arguments. This also means that the function calling
_values should declare the state, line, context and val_args
parameters as in:
local context state line
typeset -A val_args
when using an action of the form `->STRING'. With this function
the context parameter will be set to the name of the value whose
argument is to be completed.
Note also that _values normally adds the character used as the
separator between values as an auto-removable suffix so that users
don't have to type it themselves. But when using a `->STRING'
action _values can't do that because the matches for the argument
will be generated by the calling function. To get the usual
behaviour, the implementor of the calling function has to add the
suffix directly by passing the options `-qS X' (where X is the
separator character specified with the -s option of _values) to the
function generating the matches or to the compadd builtin.
Like _arguments, _values supports the -C option in which case you
have to make the parameter curcontext local instead of context (as
described above).
_wanted [ -C NAME ] [ -12VJ ] TAG NAME DESCR COMMAND ARGS ...
In many contexts, completion will generate one particular set of
matches (usually corresponding to a single tag); however, it is
still necessary to decide whether the user requires matches of
this type. This function is useful in such a case.
Like _requested, it should be passed arguments as for _description.
It calls _tags with the given TAG and if that returns zero (so
that the TAG is requested by the user) it calls _description.
Hence to offer only one tag and immediately use the description
generated:
_wanted tag expl 'description' \
compadd matches...
Unlike _requested, however, _wanted cannot be called without the
COMMAND. This is because _wanted also implements the loop over
the tags, not just the one for the labels; conversely, it should
not be called in the middle of a _tags loop.
Note that, as for _requested, the COMMAND has to accept the options
that have to be passed down to compadd.
Like _tags this function supports the -C option to give a
different name for the argument context field.
automatically generated by info2www version 1.2.2.9