(zsh.info.gz) Control Functions
Info Catalog
(zsh.info.gz) Completion System Configuration
(zsh.info.gz) Completion System
(zsh.info.gz) Bindable Commands
20.4 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 status of the completer
functions to decide if other completers should be called. If the return
status 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,
although users may write their own. Note that in contexts the leading
underscore is stripped, for example basic completion is performed in the
context ':completion::complete:...'.
_all_matches
This completer can be used to add a string consisting of all other
matches. As it influences later completers it must appear as the
first completer in the list. The list of all matches is affected
by the avoid-completer and old-matches styles described above.
It may be useful to use the _generic function described below to
bind _all_matches to its own keystroke, 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
Note that this does not generate completions by itself: first use
any of the standard ways of generating a list of completions, then
use ^Xa to show all matches. It is possible instead to add a
standard completer to the list and request that the list of all
matches should be directly inserted:
zstyle ':completion:all-matches::::' completer _all_matches _complete
zstyle ':completion:all-matches:*' insert true
In this case the old-matches style should not be set.
_approximate
This is similar to the basic _complete completer but allows the
completions to undergo corrections. The maximum number of errors
can be specified by the max-errors style; see the description of
approximate matching in Filename Generation for how errors
are counted. Normally this completer will only be tried after the
normal _complete completer:
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.
The completer progressively increases the number of errors allowed
up to the limit by the max-errors style, hence if a completion is
found with one error, no completions with two errors will be shown,
and so on. It modifies the completer name in the context to
indicate the number of errors being tried: on the first try the
completer field 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 passed with the -a option. The argument is
in the same format as 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 -e ':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- are handled specifically. These are all
mentioned above as possible arguments to the #compdef tag.
Before trying to find a function for a specific context, _complete
checks if the parameter 'compcontext' is set. Setting
'compcontext' allows the usual completion dispatching to be
overridden which is useful in places such as a function that uses
vared for input. 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 indicates
what should be completed in one of the forms accepted by the
_arguments utility function described 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). This is not used by
the completion system itself but is nonetheless handled when
explicitly called.
_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. The effect
is similar to spell-checking. It is based on _approximate, but the
completer field in the context name is correct.
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 is in
the same form a values to 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 perform 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. For this to happen, the completion system needs
to be invoked with complete-word, not expand-or-complete (the
default binding for TAB), as otherwise the string will be expanded
by the shell's internal mechanism before the completion system is
started. Note 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. The order in which these
strings are generated, if at all, can be controlled by the
group-order and tag-order styles, 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.
The kind of expansion to be tried is controlled by the substitute,
glob and subst-globs-only styles.
It is also possible to call _expand as a function, in which case
the different modes may be selected with options: -s for
substitute, -g for glob and -o for 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 styles regular, global and
disabled.
This function is also a bindable command, see Bindable
Commands.
_history
Complete words from the shell's command history. This completer
can be controlled by the remove-all-dups, and sort styles as for
the _history_complete_word bindable command, see Bindable
Commands and 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 invoked is
determined in the same way as for the _prefix completer. The
single-ignored style is also available as described above.
_list
This completer allows the insertion of matches to be delayed 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
Completion System Configuration.
_match
This completer is intended to be used after the _complete
completer. It behaves similarly but the string on the command line
may be a pattern to match against trial completions. This gives
the effect of the GLOB_COMPLETE option.
Normally completion will be performed by taking the pattern from
the line, inserting a '*' at the cursor position and comparing the
resulting pattern with the possible completions generated. This
can be modified with the match-original style described above.
The generated matches will be offered in a menu completion unless
the insert-unambiguous style is set to 'true'; see the description
above for other options for this style.
Note that matcher specifications defined globally or used by the
completion functions (the styles matcher-list and matcher) will not
be used.
_menu
This completer was written as simple example function to show how
menu completion can be enabled in shell code. However, it has the
notable effect of disabling menu selection which can be useful with
_generic based widgets. It should be used as the first completer
in the list. 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
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. The
effect is similar to the expand-or-complete-prefix command.
The completer style is used to decide which other completers are to
be called 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. On the second invocation the completer part of the
context appears as 'foo'.
To use _prefix as the last resort and try only normal completion
when it is invoked:
zstyle ':completion:*' completer _complete ... _prefix
zstyle ':completion::prefix:*' completer _complete
The add-space style is also respected. 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.
_user_expand
This completer behaves similarly to the _expand completer but
instead performs expansions defined by users. The styles add-space
and sort styles specific to the _expand completer are usable with
_user_expand in addition to other styles handled more generally by
the completion system. The tag all-expansions is also available.
The expansion depends on the array style user-expand being defined
for the current context; remember that the context for completers
is less specific than that for contextual completion as the full
context has not yet been determined. Elements of the array may
have one of the following forms:
$HASH
HASH is the name of an associative array. Note this is not a
full parameter expression, merely a $, suitably quoted to
prevent immediate expansion, followed by the name of an
associative array. If the trial expansion word matches a key
in HASH, the resulting expansion is the corresponding value.
_FUNC
_FUNC is the name of a shell function whose name must begin
with _ but is not otherwise special to the completion system.
The function is called with the trial word as an argument. If
the word is to be expanded, the function should set the array
reply to a list of expansions. Optionally, it can set REPLY
to a word that will be used as a description for the set of
expansions. The return status of the function is irrelevant.
Info Catalog
(zsh.info.gz) Completion System Configuration
(zsh.info.gz) Completion System
(zsh.info.gz) Bindable Commands
automatically generated by
info2html