GNU Info
(zsh.info)Control Functions
Control Functions
=================
The initialization script compinit redefines all the widgets which
perform completion to call the supplied widget function _main_complete.
This function acts as a wrapper calling the so-called `completer'
functions that generate matches. If _main_complete is called with
arguments, these are taken as the names of completer functions to be
called in the order given. If no arguments are given, the set of
functions to try is taken from the completer style. For example, to
use normal completion and correction if that doesn't generate any
matches:
zstyle ':completion:*' completer _complete _correct
after calling compinit. The default value for this style is `_complete
_ignored', i.e. normally only ordinary completion is tried, first with
the effect of the ignored-patterns style and then without it. The
_main_complete function uses the return value of the completer
functions to decide if other completers should be called. If the return
value is zero, no other completers are tried and the _main_complete
function returns.
If the first argument to _main_complete is a single hyphen, the
arguments will not be taken as names of completers. Instead, the second
argument gives a name to use in the COMPLETER field of the context and
the other arguments give a command name and arguments to call to
generate the matches.
The following completer functions are contained in the distribution
(users may write their own):
_all_matches
This completer can be used to add a string consisting of all other
matches. To ensure, that this string is always added, this
completer has to be used as the first completer in the list. The
avoid-completer style is used to decide if the string should be
added. This will only be done if the matches were generated by a
completer not named by one of the values of the style.
This function also uses the style old-matches. If it is set to
`true' or to the string `only' and there is a list of matches from
a previous completion, those matches will be inserted in the
command line. If it is set to the the string `only', it will only
insert an old list and won't add the string for all matches of the
list currently being generated.
With the old-matches style set, this completer should probably not
be called unconditionally. Instead one could use the -e option of
the zstyle builtin command to add a condition to the completer or
to the old-matches style. Alternatively, one could use the
_generic function to bind _all_matches to a separate key binding,
for example:
zle -C all-matches complete-word _generic
bindkey '^Xa' all-matches
zstyle ':completion:all-matches::::' old-matches only
zstyle ':completion:all-matches:*' completer _all_matches
_approximate
This completer function uses the _complete completer to generate a
list of strings for the context the cursor is currently in,
allowing you to specify a maximum number of errors: see the
description of approximate matching in Note: Filename Generation
for how errors are counted. The resulting list of corrected and
completed strings is then presented to the user. The intended use
of this completer function is to try after the normal _complete
completer by setting:
zstyle ':completion:*' completer _complete _approximate
This will give correcting completion if and only if normal
completion yields no possible completions. When corrected
completions are found, the completer will normally start menu
completion allowing you to cycle through these strings.
This completer uses the tags corrections and original when
generating the possible corrections and the original string. The
format style for the former may contain the additional sequences
`%e' and `%o' which will be replaced by the number of errors
accepted to generate the corrections and the original string,
respectively.
As with all completers, _approximate uses its name without the
underscore in the COMPLETER field of the context name. Once it
has started trying to generate matches, it will append a minus sign
and the number of errors accepted to its name. _approximate will
first look for completions with one error, then two, and on so up
to the limit on the number of errors set by the max-errors style.
Hence on the first try the completer field of the context contains
`approximate-1', on the second try `approximate-2', and so on.
When _approximate is called from another function, the number of
errors to accept may be given with the -a option. Its argument
should be the same as the value of the max-errors style, all in one
string.
Note that this completer (and the _correct completer mentioned
below) can be quite expensive to call, especially when a large
number of errors are allowed. One way to avoid this is to set up
the completer style using the -e option to zstyle so that some
completers are only used when completion is attempted a second
time on the same string, e.g.:
zstyle ':completion:*' completer '
if [[ $_last_try != "$HISTNO$BUFFER$CURSOR" ]]; then
_last_try="$HISTNO$BUFFER$CURSOR"
reply=(_complete _match _prefix)
else
reply=(_ignored _correct _approximate)
fi'
This uses the HISTNO parameter and the BUFFER and CURSOR special
parameters that are available inside zle and completion widgets to
find out if the command line hasn't changed since the last time
completion was tried. Only then are the _ignored, _correct and
_approximate completers called.
_complete
This completer generates all possible completions in a
context-sensitive manner, i.e. using the settings defined with the
compdef function explained above and the current settings of all
special parameters. This gives the normal completion behaviour.
To complete arguments of commands, _complete uses the utility
function _normal, which is in turn responsible for finding the
particular function; it is described below. Various contexts of
the form -CONTEXT-, as mentioned above for the #compdef tag, are
handled specially. These are:
-array-value-
for completion on the right hand side of an array-assignment
(`foo=(...)').
-brace-parameter-
for completing the name of a parameter expansion within braces
(`${...}').
-command-
for completing in a command position.
-condition-
for completion inside conditions (`[[...]]').
-default-
for generating completions when no special completion
function is used.
-equal-
for completion of words beginning with an equals sign
-first-
for adding completions before any other completion functions
are tried; if this function sets the _compskip parameter to
all, no other completion functions will be called, if it is
set to a string containing the substring patterns, no pattern
completion functions will be called, and if it is set to a
string containing default the function for the `-default-'
context will not be called, but functions defined for
commands will.
-math-
for completion inside mathematical contexts, such as
`((...))'.
-parameter-
for completing the name of a parameter expansion (`$...').
-redirect-
for completion after a redirection operator.
-subscript-
for completion inside subscripts.
-tilde-
for completion after a tilde (`~') character, but before a
slash.
-value-
for completion on the right hand side of an assignment.
Default implementations are supplied for each of these contexts,
in most cases named after the context itself (e.g. completion for
the `-tilde-' context is done by the function named `_tilde').
Before trying to find a function for a specific context, _complete
checks if the parameter `compcontext' is set. If it is set to an
array, the elements are taken to be the possible matches which
will be completed using the tag `values' and the description
`value'. If it is set to an associative array, the keys are used
as the possible completions and the values (if non-empty) are used
as descriptions for the matches. If `compcontext' is set to a
string containing colons, it should be of the form
`TAG:DESCR:ACTION'. In this case the TAG and DESCR give the tag
and description to use and the ACTION says what should be
completed in one of the forms described for the _arguments utility
function below.
Finally, if `compcontext' is set to a string without colons, the
value is taken as the name of the context to use and the function
defined for that context will be called. For this purpose, there
is a special context named -command-line- that completes whole
command lines (commands and their arguments) and is not used by
the completion system itself, but has a function handling
completion for it.
_correct
Generate corrections, but not completions, for the current word;
this is similar to _approximate but will not allow any number of
extra characters at the cursor as that completer does, hence this
is similar to spell-checking. It calls _approximate but uses a
different COMPLETER field in the context name.
For example, with:
zstyle ':completion:::::' completer _complete _correct _approximate
zstyle ':completion:*:correct:::' max-errors 2 not-numeric
zstyle ':completion:*:approximate:::' max-errors 3 numeric
correction will accept up to two errors. If a numeric argument is
given, correction will not be performed, but correcting completion
will be, and will accept as many errors as given by the numeric
argument. Without a numeric argument, first correction and then
correcting completion will be tried, with the first one accepting
two errors and the second one accepting three errors.
When _correct is called as a function, the number of errors to
accept may be given following the -a option. The argument should
be the same as the value of the accept style, all in one string.
This completer function is intended to be used without the
_approximate completer or, as in the example, just before it.
Using it after the _approximate completer is useless since
_approximate will at least generate the corrected strings
generated by the _correct completer - and probably more.
_expand
This completer function does not really do completion, but instead
checks if the word on the command line is eligible for expansion
and, if it is, gives detailed control over how this expansion is
done. When using this, one should not use the expand-or-complete
widget, but instead use complete-word, as expand-or-complete will
expand the string on the line before the completion widget is
called. Also, this completer should be called before the _complete
completer function.
The tags used when generating expansions are all-expansions for
the string containing all possible expansions, expansions when
adding the possible expansions as single matches and original when
adding the original string from the line. In which order these
strings are generated and which of these strings are generated at
all can be controlled by using the group-order style and by
modifying the tag-order style, as usual.
The format string for all-expansions and for expansions may
contain the sequence `%o' which will be replaced by the original
string from the line.
Which kind of expansion is tried is controlled by the substitute,
glob and subst-globs-only styles.
When _expand is called as a function, the different modes may be
selected with options. The -s to substitute, -g to glob and -o to
subst-globs-only.
_expand_alias
If the word the cursor is on is an alias, it is expanded and no
other completers are called. The types of aliases which are to be
expanded can be controlled with the regular, global and disabled
styles.
This function is also a bindable command, see Note: Bindable
Commands.
_history
Complete words from the shell's command history. This completer
uses the remove-all-dups, and sort styles also used by the
_history_complete_word bindable command, see Note: Bindable
Commands and Note: Completion System Configuration.
_ignored
The ignored-patterns style can be set to a list of patterns which
are compared against possible completions; matching ones are
removed. With this completer those matches can be reinstated, as
if no ignored-patterns style were set. The completer actually
generates its own list of matches; which completers are used for
this is determined in the same way as for the _prefix completer.
The single-ignored style is used if only one match could be
generated. It can be set to show to prevent that match from being
displayed or inserted into the line, or it can be set to menu, in
which case the single match and the original string from the line
will be offered in a menu completion.
_list
This completer allows one to delay the insertion of matches until
completion is attempted a second time without the word on the line
being changed. On the first attempt, only the list of matches
will be shown. It is affected by the styles condition and word,
see Note: Completion System Configuration.
_match
This completer is intended to be used after the _complete
completer. It allows one to give patterns on the command line and
to complete all strings matching these patterns from the set of
possible completions for the context the cursor is in, without
having to set the GLOB_COMPLETE option.
Normally this will be done by taking the pattern from the line,
inserting a `*' at the cursor position and comparing the resulting
pattern with the possible completions generated. However, if the
match-original style has a value of only, no `*' will be inserted.
If match-original has any other non-empty string as its value,
this completer will first try to generate matches without, then
with a `*' inserted at the cursor position.
The generated matches will be offered in a menu completion unless
the insert-unambiguous style is set to `true'. In this case menu
completion will only be started if no unambiguous string could be
generated that is at least as long as the original string. The
style may also be set to the string `pattern'. This will keep the
pattern on the line intact as long as there isn't an unambiguous
completion with which it could be replaced.
Note that the matcher specifications defined globally or used by
the completion functions will not be used.
_menu
This completer is a simple example function implemented to show how
menu completion can be done in shell code. It should be used as
the first completer and has the effect of making the code perform
menu completion. Note that this is independent of the setting of
the MENU_COMPLETE option and does not work with the other menu
completion widgets such as reverse-menu-complete, or
accept-and-menu-complete.
_oldlist
This completer controls how the standard completion widgets behave
when there is an existing list of completions which may have been
generated by a special completion (i.e. a separately-bound
completion command). It allows the ordinary completion keys to
continue to use the list of completions thus generated, instead of
producing a new list of ordinary contextual completions. It
should appear in the list of completers before any of the widgets
which generate matches. It uses two styles: old-list and
old-menu, see Note: Completion System Configuration.
_prefix
This completer can be used to try completion with the suffix
(everything after the cursor) ignored. In other words, the suffix
will not be considered to be part of the word to complete and
hence does not need to be matched. It uses the completer style to
decide which other completers to call to try to generate matches.
If this style is unset, the list of completers set for the current
context is used - except, of course, the _prefix completer itself.
Furthermore, if this completer appears more than once in the list
of completers only those completers not already tried by the last
invocation of _prefix will be called.
For example, consider this global completer style:
zstyle ':completion:*' completer \
_complete _prefix _correct _prefix:foo
Here, the _prefix completer tries normal completion but ignoring
the suffix. If that doesn't generate any matches, and neither does
the call to the _correct completer after it, _prefix will be
called a second time and, now only trying correction with the
suffix ignored. If you want to use _prefix as the last resort and
try only normal completion, you can use:
zstyle ':completion:*' completer _complete ... _prefix
zstyle ':completion::prefix:*' completer _complete
The add-space style is also used. If it is set to `true' then
_prefix will insert a space between the matches generated (if any)
and the suffix.
Note that this completer is only useful if the COMPLETE_IN_WORD
option is set; otherwise, the cursor will be moved to the end of
the current word before the completion code is called and hence
there will be no suffix.
automatically generated by info2www version 1.2.2.9