This is zsh.info, produced by makeinfo version 4.0 from ./zsh.texi.

INFO-DIR-SECTION Utilities
START-INFO-DIR-ENTRY
* ZSH: (zsh).                     The Z Shell Manual.
END-INFO-DIR-ENTRY


File: zsh.info,  Node: Control Functions,  Next: Bindable Commands,  Prev: Completion System Configuration,  Up: Completion System

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,
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

_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 *Note 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 *Note 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 *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 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 *Note 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 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 later completers
     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.  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.

bashcompinit
     This function provides compatibility with bash's programmable
     completion system.  When run it will define the functions, compgen
     and complete which correspond to the bash builtins with the same
     names.  It will then be possible to use completion specifications
     and functions written for bash.


File: zsh.info,  Node: Bindable Commands,  Next: Completion Functions,  Prev: Control Functions,  Up: Completion System

Bindable Commands
=================

In addition to the context-dependent completions provided, which are
expected to work in an intuitively obvious way, there are a few widgets
implementing special behaviour which can be bound separately to keys.
The following is a list of these and their default bindings.

_bash_completions
     This function is used by two widgets, _bash_complete-word and
     _bash_list-choices.  It exists to provide compatibility with
     completion bindings in bash.  The last character of the binding
     determines what is completed: `!', command names; `$', environment
     variables; `@', host names; `/', file names; `~' user names.  In
     bash, the binding preceded by `\e' gives completion, and preceded
     by `^X' lists options.  As some of these bindings clash with
     standard zsh bindings, only `\e~' and `^X~' are bound by default.
     To add the rest, the following should be added to .zshrc after
     compinit has been run:

          for key in '!' '$' '@' '/' '~'; do
            bindkey "\e$key" _bash_complete-word
            bindkey "^X$key" _bash_list-choices
          done

     This includes the bindings for `~' in case they were already bound
     to something else; the completion code does not override user
     bindings.

_correct_filename (^XC)
     Correct the filename path at the cursor position.  Allows up to
     six errors in the name.  Can also be called with an argument to
     correct a filename path, independently of zle; the correction is
     printed on standard output.

_correct_word (^Xc)
     Performs correction of the current argument using the usual
     contextual completions as possible choices. This stores the string
     `correct-word' in the FUNCTION field of the context name and then
     calls the _correct completer.

_expand_alias (^Xa)
     This function can be used as a completer and as a bindable command.
     It expands the word the cursor is on if it is an alias.  The types
     of alias expanded can be controlled with the styles regular, global
     and disabled.

     When used as a bindable command there is one additional feature
     that can be selected by setting the complete style to `true'.  In
     this case, if the word is not the name of an alias, _expand_alias
     tries to complete the word to a full alias name without expanding
     it.  It leaves the cursor directly after the completed word so
     that invoking _expand_alias once more will expand the now-complete
     alias name.

_expand_word (^Xe)
     Performs expansion on the current word:  equivalent to the standard
     expand-word command, but using the _expand completer.  Before
     calling it, the FUNCTION field of the context is set to
     `expand-word'.

_generic
     This function is not defined as a widget and not bound by default.
     However, it can be used to define a widget and will then store
     the name of the widget in the FUNCTION field of the context and
     call the completion system.  This allows custom completion widgets
     with their own set of style settings to be defined easily.  For
     example, to define a widget that performs normal completion and
     starts menu selection:

          zle -C foo complete-word _generic
          bindkey '...' foo
          zstyle ':completion:foo:*' menu yes select=1

_history_complete_word (\e/)
     Complete words from the shell's command history. This uses the
     list, remove-all-dups, sort, and stop styles.

_most_recent_file (^Xm)
     Complete the name of the most recently modified file matching the
     pattern on the command line (which may be blank).  If given a
     numeric argument N, complete the Nth most recently modified file.
     Note the completion, if any, is always unique.

_next_tags (^Xn)
     This command alters the set of matches used to that for the next
     tag, or set of tags, either as given by the tag-order style or as
     set by default; these matches would otherwise not be available.
     Successive invocations of the command cycle through all possible
     sets of tags.

_read_comp (^X^R)
     Prompt the user for a string, and use that to perform completion
     on the current word.  There are two possibilities for the string.
     First, it can be a set of words beginning `_', for example `_files
     -/', in which case the function with any arguments will be called
     to generate the completions.  Unambiguous parts of the function
     name will be completed automatically (normal completion is not
     available at this point) until a space is typed.

     Second, any other string will be passed as a set of arguments to
     compadd and should hence be an expression specifying what should
     be completed.

     A very restricted set of editing commands is available when
     reading the string:  `DEL' and `^H' delete the last character;
     `^U' deletes the line, and `^C' and `^G' abort the function, while
     `RET' accepts the completion.  Note the string is used verbatim as
     a command line, so arguments must be quoted in accordance with
     standard shell rules.

     Once a string has been read, the next call to _read_comp will use
     the existing string instead of reading a new one.  To force a new
     string to be read, call _read_comp with a numeric argument.

_complete_debug (^X?)
     This widget performs ordinary completion, but captures in a
     temporary file a trace of the shell commands executed by the
     completion system.  Each completion attempt gets its own file.  A
     command to view each of these files is pushed onto the editor
     buffer stack.

_complete_help (^Xh)
     This widget displays information about the context names, the
     tags, and the completion functions used when completing at the
     current cursor position. If given a numeric argument other than 1
     (as in `ESC-2 ^Xh'), then the styles used and the contexts for
     which they are used will be shown, too.

     Note that the information about styles may be incomplete; it
     depends on the information available from the completion functions
     called, which in turn is determined by the user's own styles and
     other settings.

_complete_tag (^Xt)
     This widget completes symbol tags created by the etags or ctags
     programmes (note there is no connection with the completion
     system's tags) stored in a file TAGS, in the format used by etags,
     or tags, in the format created by ctags.  It will look back up the
     path hierarchy for the first occurrence of either file; if both
     exist, the file TAGS is preferred.  You can specify the full path
     to a TAGS or tags file by setting the parameter $TAGSFILE or
     $tagsfile respectively.  The corresponding completion tags used
     are etags and vtags, after emacs and vi respectively.

