Matching Control
================

It is possible by use of the -M option of the compadd builtin command
to specify how the characters in the string to be completed (referred
to here as the command line) map onto the characters in the list of
matches produced by the completion code (referred to here as the trial
completions). Note that this is not used if the command line contains a
glob pattern and the GLOB_COMPLETE option is set or the pattern_match
of the compstate special association is set to a non-empty string.

The MATCH-SPEC given as the argument to the -M option (see
Builtin Commands) consists of one or more matching descriptions
separated by whitespace.  Each description consists of a letter
followed by a colon and then the patterns describing which character
sequences on the line match which character sequences in the trial
completion.  Any sequence of characters not handled in this fashion
must match exactly, as usual.

The forms of MATCH-SPEC understood are as follows. In each case, the
form with an uppercase initial character retains the string already
typed on the command line as the final result of completion, while with
a lowercase initial character the string on the command line is changed
into the corresponding part of the trial completion.

m:LPAT=TPAT
M:LPAT=TPAT
     Here, LPAT is a pattern that matches on the command line,
     corresponding to TPAT which matches in the trial completion.

l:LANCHOR|LPAT=TPAT
L:LANCHOR|LPAT=TPAT
l:LANCHOR||RANCHOR=TPAT
L:LANCHOR||RANCHOR=TPAT
b:LPAT=TPAT
B:LPAT=TPAT
     These letters are for patterns that are anchored by another
     pattern on the left side. Matching for LPAT and TPAT is as for m
     and M, but the pattern LPAT matched on the command line must be
     preceded by the pattern LANCHOR.  The LANCHOR can be blank to
     anchor the match to the start of the command line string;
     otherwise the anchor can occur anywhere, but must match in both
     the command line and trial completion strings.

     If no LPAT is given but a RANCHOR is, this matches the gap between
     substrings matched by LANCHOR and RANCHOR. Unlike LANCHOR, the
     RANCHOR only needs to match the trial completion string.

     The b and B forms are similar to l and L with an empty anchor, but
     need to match only the beginning of the trial completion or the
     word on the command line, respectively.

r:LPAT|RANCHOR=TPAT
R:LPAT|RANCHOR=TPAT
r:LANCHOR||RANCHOR=TPAT
R:LANCHOR||RANCHOR=TPAT
e:LPAT=TPAT
E:LPAT=TPAT
     As l, L, b and B, with the difference that the command line and
     trial completion patterns are anchored on the right side.  Here an
     empty RANCHOR and the e and E forms force the match to the end of
     the trial completion or command line string.

Each LPAT, TPAT or ANCHOR is either an empty string or consists of a
sequence of literal characters (which may be quoted with a backslash),
question marks, character classes, and correspondence classes; ordinary
shell patterns are not used.  Literal characters match only themselves,
question marks match any character, and character classes are formed as
for globbing and match any character in the given set.

Correspondence classes are defined like character classes, but with two
differences: they are delimited by a pair of braces, and negated classes
are not allowed, so the characters ! and ^ have no special meaning
directly after the opening brace.  They indicate that a range of
characters on the line match a range of characters in the trial
completion, but (unlike ordinary character classes) paired according to
the corresponding position in the sequence. For example, to make any
lowercase letter on the line match the corresponding uppercase letter in
the trial completion, you can use `m:{a-z}={A-Z}'.  More than one pair
of classes can occur, in which case the first class before the =
corresponds to the first after it, and so on.  If one side has more
such classes than the other side, the superfluous classes behave like
normal character classes.  In anchor patterns correspondence classes
also behave like normal character classes.

The pattern TPAT may also be one or two stars, `*' or `**'. This means
that the pattern on the command line can match any number of characters
in the trial completion. In this case the pattern must be anchored (on
either side); in the case of a single star, the ANCHOR then determines
how much of the trial completion is to be included -- only the
characters up to the next appearance of the anchor will be matched.
With two stars, substrings matched by the anchor can be matched, too.

Examples:

The keys of the options association defined by the parameter module are
the option names in all-lowercase form, without underscores, and
without the optional no at the beginning even though the builtins
setopt and unsetopt understand option names with uppercase letters,
underscores, and the optional no.  The following alters the matching
rules so that the prefix no and any underscore are ignored when trying
to match the trial completions generated and uppercase letters on the
line match the corresponding lowercase letters in the words:

     compadd -M 'L:|[nN][oO]= M:_= M:{A-Z}={a-z}' - \
       ${(k)options}

The first part says that the pattern `[nN][oO]' at the beginning (the
empty anchor before the pipe symbol) of the string on the line matches
the empty string in the list of words generated by completion, so it
will be ignored if present. The second part does the same for an
underscore anywhere in the command line string, and the third part uses
correspondence classes so that any uppercase letter on the line matches
the corresponding lowercase letter in the word. The use of the
uppercase forms of the specification characters (L and M) guarantees
that what has already been typed on the command line (in particular the
prefix no) will not be deleted.

Note that the use of L in the first part means that it matches only
when at the beginning of both the command line string and the trial
completion. I.e., the string `_NO_f' would not be completed to
`_NO_foo', nor would `NONO_f' be completed to `NONO_foo' because of the
leading underscore or the second `NO' on the line which makes the
pattern fail even though they are otherwise ignored. To fix this, one
would use `B:[nN][oO]=' instead of the first part. As described above,
this matches at the beginning of the trial completion, independent of
other characters or substrings at the beginning of the command line
word which are ignored by the same or other MATCH-SPECs.

The second example makes completion case insensitive.  This is just the
same as in the option example, except here we wish to retain the
characters in the list of completions:

     compadd -M 'm:{a-z}={A-Z}' ...

This makes lowercase letters match their uppercase counterparts.  To
make uppercase letters match the lowercase forms as well:

     compadd -M 'm:{a-zA-Z}={A-Za-z}' ...

A nice example for the use of * patterns is partial word completion.
Sometimes you would like to make strings like `c.s.u' complete to
strings like `comp.source.unix', i.e. the word on the command line
consists of multiple parts, separated by a dot in this example, where
each part should be completed separately -- note, however, that the
case where each part of the word, i.e. `comp', `source' and `unix' in
this example, is to be completed from separate sets of matches is a
different problem to be solved by the implementation of the completion
widget.  The example can be handled by:

     compadd -M 'r:|.=* r:|=*' \
       - comp.sources.unix comp.sources.misc ...

The first specification says that LPAT is the empty string, while
ANCHOR is a dot; TPAT is *, so this can match anything except for the
`.' from the anchor in the trial completion word.  So in `c.s.u', the
matcher sees `c', followed by the empty string, followed by the anchor
`.', and likewise for the second dot, and replaces the empty strings
before the anchors, giving `c[omp].s[ources].u[nix]', where the last
part of the completion is just as normal.

With the pattern shown above, the string `c.u' could not be completed
to `comp.sources.unix' because the single star means that no dot
(matched by the anchor) can be skipped. By using two stars as in
`r:|.=**', however, `c.u' could be completed to `comp.sources.unix'.
This also shows that in some cases, especially if the anchor is a real
pattern, like a character class, the form with two stars may result in
more matches than one would like.

The second specification is needed to make this work when the cursor is
in the middle of the string on the command line and the option
COMPLETE_IN_WORD is set. In this case the completion code would
normally try to match trial completions that end with the string as
typed so far, i.e. it will only insert new characters at the cursor
position rather then at the end.  However in our example we would like
the code to recognise matches which contain extra characters after the
string on the line (the `nix' in the example).  Hence we say that the
empty string at the end of the string on the line matches any characters
at the end of the trial completion.

More generally, the specification

     compadd -M 'r:|[.,_-]=* r:|=*' ...

allows one to complete words with abbreviations before any of the
characters in the square brackets.  For example, to complete
veryverylongfile.c rather than veryverylongheader.h with the above in
effect, you can just type very.c before attempting completion.

The specifications with both a left and a right anchor are useful to
complete partial words whose parts are not separated by some special
character. For example, in some places strings have to be completed
that are formed `LikeThis' (i.e. the separate parts are determined by a
leading uppercase letter) or maybe one has to complete strings with
trailing numbers. Here one could use the simple form with only one
anchor as in:

     compadd -M 'r:|[A-Z0-9]=* r:|=*' LikeTHIS FooHoo 5foo123 5bar234

But with this, the string `H' would neither complete to `FooHoo' nor to
`LikeTHIS' because in each case there is an uppercase letter before the
`H' and that is matched by the anchor. Likewise, a `2' would not be
completed. In both cases this could be changed by using
`r:|[A-Z0-9]=**', but then `H' completes to both `LikeTHIS' and
`FooHoo' and a `2' matches the other strings because characters can be
inserted before every uppercase letter and digit. To avoid this one
would use:

     compadd -M 'r:[^A-Z0-9]||[A-Z0-9]=** r:|=*' \
         LikeTHIS FooHoo foo123 bar234

By using these two anchors, a `H' matches only uppercase `H's that are
immediately preceded by something matching the left anchor `[^A-Z0-9]'.
The effect is, of course, that `H' matches only the string `FooHoo', a
`2' matches only `bar234' and so on.

When using the completion system (see Completion System), users
can define match specifications that are to be used for specific
contexts by using the matcher and matcher-list styles. The values for
the latter will be used everywhere.

Completion Widget Example
=========================

The first step is to define the widget:

     zle -C complete complete-word complete-files

Then the widget can be bound to a key using the bindkey builtin command:

     bindkey '^X\t' complete

After that the shell function complete-files will be invoked after
typing control-X and TAB. The function should then generate the
matches, e.g.:

     complete-files () { compadd - * }

This function will complete files in the current directory matching the
current word.

Completion System
*****************

Description
===========

This describes the shell code for the new completion system.  It
consists of various shell functions; those beginning `comp' are to be
called directly by the user, while those beginning `_' are called by the
completion code.  The shell functions of the second set which implement
completion behaviour and which may be bound to keystrokes, are referred
to as `widgets'.

Initialization
==============

If the system was installed completely, it should be enough to call the
shell function compinit from your initialization file; see the next
section.  However, the function compinstall can be run by a user to
configure various aspects of the completion system.

Usually, compinstall will insert code into .zshrc, although if that is
not writable it will save it in another file and tell you that file's
location.  Note that it is up to you to make sure that the lines added
to .zshrc are actually run; you may, for example, need to move them to
an earlier place in the file if .zshrc usually returns early.  So long
as you keep them all together (including the comment lines at the start
and finish), you can rerun compinstall and it will correctly locate and
modify these lines.  Note, however, that any code you add to this
section by hand is likely to be lost if you rerun compinstall, although
lines using the command `zstyle' should be gracefully handled.

The new code will take effect next time you start the shell, or run
.zshrc by hand; there is also an option to make them take effect
immediately.  However, if compinstall has removed definitions, you will
need to restart the shell to see the changes.

To run compinstall you will need to make sure it is in a directory
mentioned in your fpath parameter, which should already be the case if
zsh was properly configured as long as your startup files do not remove
the appropriate directories from fpath.  Then it must be autoloaded
(`autoload -U compinstall' is recommended).  You can abort the
installation any time you are being prompted for information, and your
.zshrc will not be altered at all; changes only take place right at the
end, where you are specifically asked for confirmation.

Use of compinit
---------------

This section describes the use of compinit to initialize completion for
the current session when run directly by the user; if you have run
compinstall it will be called automatically from your .zshrc.

To initialize the system, the function compinit should be in a
directory mentioned in the fpath parameter, and should be autoloaded
(`autoload -U compinit' is recommended), and then run simply as
`compinit'.  This will define a few utility functions, arrange for all
the necessary shell functions to be autoloaded, and will then re-define
all widgets that do completion to use the new system.  If you use the
menu-select widget, which is part of the zsh/complist module, you
should make sure that that module is loaded before the call to compinit
so that that widget is also re-defined.  If completion styles (see
below) are set up to perform expansion as well as completion by
default, and the TAB key is bound to expand-or-complete, compinit will
rebind it to complete-word; this is necessary to use the correct form
of expansion.

Should you need to use the original completion commands, you can still
bind keys to the old widgets by putting a `.' in front of the widget
name, e.g. `.expand-or-complete'.

To speed up the running of compinit, it can be made to produce a dumped
configuration which will be read in on future invocations; this is the
default, although it can be turned off by calling compinit with the
option -D.  The dumped file is .zcompdump in the same directory as the
startup files (i.e. $ZDOTDIR or $HOME); alternatively, an explicit file
name can be given by `compinit -d DUMPFILE'.  On the next call to
compinit, it will read the dumped file instead of performing a full
initialization.

If the number of completion files changes, compinit will recognise this
and produce a new dump file.  However, if the name of a function or the
arguments in the first line of a #compdef function (as described below)
change, it is easiest to delete the dump file by hand so that compinit
will re-create it the next time it is run.  The check performed to see
if there are new functions can be omitted by giving the option -C.  In
this case the dump file will only be created if there isn't one already.

The dumping is actually done by another function, compdump, but you
will only need to run this yourself if you change the configuration
(e.g. using compdef) and then want to dump the new one.  The name of
the old dumped file will be remembered for this purpose.

If the parameter _compdir is set, compinit uses it as a directory where
completion functions can be found; this is only necessary if they are
not already in the function search path.

For security reasons compinit also checks if the completion system
would use files not owned by root or by the current user, or files in
directories that are world- or group-writable or that are not owned by
root or by the current user.  If such files or directories are found,
compinit will ask if the completion system should really be used.  To
avoid these tests and make all files found be used without asking, use
the option -u, and to make compinit silently ignore all insecure files
and directories use the option -i.  This security check is skipped
entirely when the -C option is given.

The security check can be retried at any time by running the function
compaudit.  This is the same check used by compinit, but when it is
executed directly any changes to fpath are made local to the function
so they do not persist.  The directories to be checked may be passed as
arguments; if none are given, compaudit uses fpath and _compdir to find
completion system directories, adding missing ones to fpath as
necessary.  To force a check of exactly the directories currently named
in fpath, set _compdir to an empty string before calling compaudit or
compinit.

Autoloaded files
----------------

The convention for autoloaded functions used in completion is that they
start with an underscore; as already mentioned, the fpath/FPATH
parameter must contain the directory in which they are stored.  If zsh
was properly installed on your system, then fpath/FPATH automatically
contains the required directories for the standard functions.

For incomplete installations, if compinit does not find enough files
beginning with an underscore (fewer than twenty) in the search path, it
will try to find more by adding the directory _compdir to the search
path.  If that directory has a subdirectory named Base, all
subdirectories will be added to the path.  Furthermore, if the
subdirectory Base has a subdirectory named Core, compinit will add all
subdirectories of the subdirectories is to the path: this allows the
functions to be in the same format as in the zsh source distribution.

When compinit is run, it searches all such files accessible via
fpath/FPATH and reads the first line of each of them.  This line should
contain one of the tags described below.  Files whose first line does
not start with one of these tags are not considered to be part of the
completion system and will not be treated specially.

The tags are:

#compdef NAMES...
     The file will be made autoloadable and the function defined in it
     will be called when completing NAMES, each of which is either the
     name of a command whose arguments are to be completed or one of a
     number of special contexts in the form -CONTEXT- described below
     for the _complete function.

     Each NAME may also be of the form `CMD=SERVICE'.  This is used by
     functions that offer multiple services, i.e. different completion
     behaviour for multiple commands.  Such a string makes the
     completion system call the function when completing arguments for
     the command `cmd', setting the parameter $service to the string
     `service'.  The function can then use that parameter to decide
     what to complete.

#compdef -p PATTERN
     The file will be made autoloadable and the function defined in it
     will be called when completing for a command whose name matches
     the given PATTERN (a standard globbing pattern).  Note that only
     one PATTERN may be given.

#compdef -P PATTERN
     Like the previous one, but the function will be called only if no
     completion function for the command on the line could be found.

#compdef -k STYLE KEY-SEQUENCES...
     This can be used to bind special completion functions to the
     KEY-SEQUENCES specified.  It creates a widget behaving like the
     builtin widget STYLE, which must be one of those that perform
     completion, namely complete-word, delete-char-or-list,
     expand-or-complete, expand-or-complete-prefix, list-choices,
     menu-complete, menu-expand-or-complete, or reverse-menu-complete.
     If the zsh/complist module is loaded (see The zsh/complist Module),
     the same happens to the menu-select widget.

     The widget is then bound to all the KEY-SEQUENCES given, if any:
     when one of the KEY-SEQUENCES is typed, the function in the file
     will be invoked to generate the matches.  Note that a key will not
     be re-bound if if it already was (that is, was bound to something
     other than undefined-key).  The widget created has the same name
     as the file and can be bound to any other keys using bindkey as
     usual.

#compdef -K WIDGET-NAME STYLE KEY-SEQUENCES ...
     This is similar to -k, with the same STYLE and KEY-SEQUENCES
     arguments, preceded by a string giving the name of a widget.  In
     this case only one KEY-SEQUENCES argument may be given, but the
     entire set of three arguments may be repeated with a different set
     of arguments.  In particular, the WIDGET-NAME must be distinct in
     each set.  It should begin with `_', else one will be added, and
     should not clash with the name of any existing widget: names based
     on the name of the function are most useful.  For example,

          #compdef -K _foo_complete complete-word "^X^C" \
            _foo_list list-choices "^X^D"

     (all on one line) defines a widget _foo_complete for completion,
     bound to `^X^C', and a widget _foo_list for listing, bound to
     `^X^D'.

#autoload [ OPTIONS ]
     This is used for files defining utility functions that are not to
     be called directly as completion functions but should be loaded
     automatically when invoked.  Typically they are to be called from
     within one of the completion functions.

     The OPTIONS will be given to the autoload builtin command when
     making the function autoloaded.  Most often, this will be +X to
     force the function to be loaded immediately.  Note that the -U
     flag is always implicitly added.

The # is part of the tag name and no white space is allowed after it.
The #compdef tags use the compdef function described below; the main
difference is that the name of the function is supplied implicitly.

Note also that the functions for the completion system assume that the
KSH_AUTOLOAD option is not set and cannot be loaded when it is set.  To
avoid having to unset KSH_AUTOLOAD, you can instead use one or more zwc
file(s) which have been created with the command zcompile -z to load
the functions for the completion system; see Shell Builtin Commands.
This forces the functions to be autoloaded the way zsh
normally loads functions.

Functions
---------

The compinit file defines the following function, which may also be
called directly by the user.

compdef [ -an ] FUNCTION NAMES...
compdef -d NAMES...
compdef -p [ -a ] FUNCTION PATTERN
compdef -P [ -a ] FUNCTION PATTERN
compdef -k [ -an ] FUNCTION STYLE KEY-SEQUENCES...
compdef -K [ -an ] FUNCTION NAME STYLE KEY-SEQUENCES ...
     The first form tells the completion system to call the given
     FUNCTION when completing for the contexts or commands whose NAMES
     are given:  this is like the #compdef tag unless the first word
     contains an equal sign.  In this case all words have to be of the
     form `CMD=SERVICE' where SERVICE is the name of a command or of a
     service defined by an autoloaded function with the #compdef tag
     and an argument of the form `CMD=SERVICE'.  This kind of use makes
     the arguments of the CMDs be completed as those for the SERVICES.

     If the -n option is given, any existing completion behaviour for
     particular contexts or commands will not be altered.  These
     definitions can be deleted by giving the -d option as in the
     second form.

     The form with -p is similar to the first, but FUNCTION will be
     called for all commands whose name matches the PATTERN; this is
     like the #compdef -p function tag.

     The form with -P is like the third, but the FUNCTION will be
     called only if no function for the command itself was found or if
     one was found and it set the _compskip parameter to a value _not_
     containing the substring patterns.

     The form with -k defines a widget with the same name as the
     FUNCTION which will be called for each of the KEY-SEQUENCES; this
     is like the #compdef -k tag.  The function should generate the
     completions needed and will otherwise behave like the builtin
     widget whose name is given as the STYLE argument. The widgets
     usable for this are: complete-word, delete-char-or-list,
     expand-or-complete, expand-or-complete-prefix, list-choices,
     menu-complete, menu-expand-or-complete, and reverse-menu-complete,
     as well as menu-select if the zsh/complist module is loaded.  The
     option -n prevents the key being bound if it is already to bound
     to something other than undefined-key.

     The form with -K is similar and defines multiple widgets based on
     the same FUNCTION, each of which requires the set of three
     arguments NAME, STYLE and KEY-SEQUENCES, where the latter two are
     as for -k and the first must be a unique widget name beginning
     with an underscore.

     In each of the forms supporting it the -a option makes the
     FUNCTION autoloadable (exactly equivalent to autoload -U FUNCTION).

The compdef function is the place to turn to when one wants to define
what the completion system should complete for a certain command.  The
function named can of course be one of the functions supplied or one
written by the user.  For example, if one has a command foo that gets
process identifiers as arguments, one could do:

     compdef _pids foo

using the _pids function from the distribution to generate the process
identifiers.  Not also the _gnu_generic function described below, which
can be used to complete options for commands that understand the
`--help' option.