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

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 aliases expanded can be controlled with the regular, global and
     disabled styles.

     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 isn't the name of an alias, _expand_alias
     tries to complete the word to a full alias name without expanding
     it (but leaving 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 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 easily defined. For example,
     to define a widget that does normal completion and starts menu
     selection, one could do:

          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.