Completion Directories
======================

In the source distribution, the files are contained in various
subdirectories of the Completion directory.  They may have been
installed in the same structure, or into one single function directory.
The following is a description of the files found in the original
directory structure.  If you wish to alter an installed file, you will
need to copy it to some directory which appears earlier in your fpath
than the standard directory where it appears.

Base
     The core functions and special completion widgets automatically
     bound to keys.  You will certainly need most of these, though will
     probably not need to alter them.  Many of these are documented
     above.

Zsh
     Functions for completing arguments of shell builtin commands and
     utility functions for this.  Some of these are also used by
     functions from the Unix directory.

Unix
     Functions for completing arguments of external commands and suites
     of commands.  They may need modifying for your system, although in
     many cases some attempt is made to decide which version of a
     command is present.  For example, completion for the mount command
     tries to determine the system it is running on, while completion
     for many other utilities try to decide whether the GNU version of
     the command is in use, and hence whether the -help option is
     supported..

X, AIX, BSD, ...
     Completion and utility function for commands available only on
     some systems.

Completion Using compctl
************************

Types of completion
===================

This version of zsh has two ways of performing completion of words on
the command line.  New users of the shell may prefer to use the newer
and more powerful system based on shell functions; this is described in
Completion System, and the basic shell mechanisms which support
it are described in Completion Widgets.  This chapter describes
the older compctl command.

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

compctl [ -CDT ] OPTIONS [ COMMAND ... ]

compctl [ -CDT ] OPTIONS [ -x PATTERN OPTIONS - ... - ] [ + OPTIONS [ -x ... - ] ... [+] ] [ COMMAND ... ]

compctl -M MATCH-SPECS ...

compctl -L [ -CDTM ] [ COMMAND ... ]

compctl + COMMAND ...

Control the editor's completion behavior according to the supplied set
of OPTIONS.  Various editing commands, notably expand-or-complete-word,
usually bound to tab, will attempt to complete a word typed by the
user, while others, notably delete-char-or-list, usually bound to ^D in
EMACS editing mode, list the possibilities; compctl controls what those
possibilities are.  They may for example be filenames (the most common
case, and hence the default), shell variables, or words from a
user-specified list.

Command Flags
=============

Completion of the arguments of a command may be different for each
command or may use the default.  The behavior when completing the
command word itself may also be separately specified.  These correspond
to the following flags and arguments, all of which (except for -L) may
be combined with any combination of the OPTIONS described subsequently
in Option Flags:

COMMAND ...
     controls completion for the named commands, which must be listed
     last on the command line.  If completion is attempted for a
     command with a pathname containing slashes and no completion
     definition is found, the search is retried with the last pathname
     component. If the command starts with a =, completion is tried
     with the pathname of the command.

     Any of the COMMAND strings may be patterns of the form normally
     used for filename generation.  These should be be quoted to
     protect them from immediate expansion; for example the command
     string 'foo*' arranges for completion of the words of any command
     beginning with foo.  When completion is attempted, all pattern
     completions are tried in the reverse order of their definition
     until one matches.  By default, completion then proceeds as
     normal, i.e. the shell will try to generate more matches for the
     specific command on the command line; this can be overridden by
     including -tn in the flags for the pattern completion.

     Note that aliases are expanded before the command name is
     determined unless the COMPLETE_ALIASES option is set.  Commands
     may not be combined with the -C, -D or -T flags.

-C
     controls completion when the command word itself is being
     completed.  If no compctl -C command has been issued,  the names
     of any executable command (whether in the path or specific to the
     shell, such as aliases or functions) are completed.

-D
     controls default completion behavior for the arguments of commands
     not assigned any special behavior.  If no compctl -D command has
     been issued, filenames are completed.

-T
     supplies completion flags to be used before any other processing is
     done, even before processing for compctls defined for specific
     commands.  This is especially useful when combined with extended
     completion (the -x flag, see Extended Completion below).
     Using this flag you can define default behavior which will apply
     to all commands without exception, or you can alter the standard
     behavior for all commands.  For example, if your access to the
     user database is too slow and/or it contains too many users (so
     that completion after `~' is too slow to be usable), you can use

          compctl -T -x 's[~] C[0,[^/]#]' -k friends -S/ -tn

     to complete the strings in the array friends after a `~'.  The
     C[...] argument is necessary so that this form of ~-completion is
     not tried after the directory name is finished.

-L
     lists the existing completion behavior in a manner suitable for
     putting into a start-up script; the existing behavior is not
     changed.  Any combination of the above forms, or the -M flag
     (which must follow the -L flag), may be specified, otherwise all
     defined completions are listed.  Any other flags supplied are
     ignored.

_no argument_
     If no argument is given, compctl lists all defined completions in
     an abbreviated form;  with a list of OPTIONS, all completions with
     those flags set (not counting extended completion) are listed.

If the + flag is alone and followed immediately by the COMMAND list,
the completion behavior for all the commands in the list is reset to
the default.  In other words, completion will subsequently use the
options specified by the -D flag.

The form with -M as the first and only option defines global matching
specifications (see Matching Control). The match specifications
given will be used for every completion attempt (only when using
compctl, not with the new completion system) and are tried in the order
in which they are defined until one generates at least one match. E.g.:

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

This will first try completion without any global match specifications
(the empty string) and, if that generates no matches, will try case
insensitive completion.

Option Flags
============

[ -fcFBdeaRGovNAIOPZEnbjrzu/12 ]

[ -k ARRAY ] [ -g GLOBSTRING ] [ -s SUBSTSTRING ]

[ -K FUNCTION ]

[ -Q ] [ -P PREFIX ] [ -S SUFFIX ]

[ -W FILE-PREFIX ] [ -H NUM PATTERN ]

[ -q ] [ -X EXPLANATION ] [ -Y EXPLANATION ]

[ -y FUNC-OR-VAR ] [ -l CMD ] [ -h CMD ] [ -U ]

[ -t CONTINUE ] [ -J NAME ] [ -V NAME ]

[ -M MATCH-SPEC ]

The remaining OPTIONS specify the type of command arguments to look for
during completion.  Any combination of these flags may be specified;
the result is a sorted list of all the possibilities.  The options are
as follows.

Simple Flags
------------

These produce completion lists made up by the shell itself:

-f
     Filenames and filesystem paths.

-/
     Just filesystem paths.

-c
     Command names, including aliases, shell functions, builtins and
     reserved words.

-F
     Function names.

-B
     Names of builtin commands.

-m
     Names of external commands.

-w
     Reserved words.

-a
     Alias names.

-R
     Names of regular (non-global) aliases.

-G
     Names of global aliases.

-d
     This can be combined with -F, -B, -w, -a, -R and -G to get names
     of disabled functions, builtins, reserved words or aliases.

-e
     This option (to show enabled commands) is in effect by default, but
     may be combined with -d; -de in combination with -F, -B, -w, -a,
     -R and -G will complete names of functions, builtins, reserved
     words or aliases whether or not they are disabled.

-o
     Names of shell options (see Options).

-v
     Names of any variable defined in the shell.

-N
     Names of scalar (non-array) parameters.

-A
     Array names.

-I
     Names of integer variables.

-O
     Names of read-only variables.

-p
     Names of parameters used by the shell (including special
     parameters).

-Z
     Names of shell special parameters.

-E
     Names of environment variables.

-n
     Named directories.

-b
     Key binding names.

-j
     Job names:  the first word of the job leader's command line.  This
     is useful with the kill builtin.

-r
     Names of running jobs.

-z
     Names of suspended jobs.

-u
     User names.

Flags with Arguments
--------------------

These have user supplied arguments to determine how the list of
completions is to be made up:

-k ARRAY
     Names taken from the elements of $ARRAY (note that the `$' does
     not appear on the command line).  Alternatively, the argument
     ARRAY itself may be a set of space- or comma-separated values in
     parentheses, in which any delimiter may be escaped with a
     backslash; in this case the argument should be quoted.  For
     example,

          compctl -k "(cputime filesize datasize stacksize
          	       coredumpsize resident descriptors)" limit

-g GLOBSTRING
     The GLOBSTRING is expanded using filename globbing; it should be
     quoted to protect it from immediate expansion. The resulting
     filenames are taken as the possible completions.  Use `*(/)'
     instead of `*/' for directories.  The fignore special parameter is
     not applied to the resulting files.  More than one pattern may be
     given separated by blanks. (Note that brace expansion is _not_
     part of globbing.  Use the syntax `(either|or)' to match
     alternatives.)

-s SUBSTSTRING
     The SUBSTSTRING is split into words and these words are than
     expanded using all shell expansion mechanisms (see
     Expansion).  The resulting words are taken as possible
     completions.  The fignore special parameter is not applied to the
     resulting files.  Note that -g is faster for filenames.

-K FUNCTION
     Call the given function to get the completions.  Unless the name
     starts with an underscore, the function is passed two arguments:
     the prefix and the suffix of the word on which completion is to be
     attempted, in other words those characters before the cursor
     position, and those from the cursor position onwards.  The whole
     command line can be accessed with the -c and -l flags of the read
     builtin. The function should set the variable reply to an array
     containing the completions (one completion per element); note that
     reply should not be made local to the function.  From such a
     function the command line can be accessed with the -c and -l flags
     to the read builtin.  For example,

          function whoson { reply=(`users`); }
          compctl -K whoson talk

     completes only logged-on users after `talk'.  Note that `whoson'
     must return an array, so `reply=`users`' would be incorrect.

-H NUM PATTERN
     The possible completions are taken from the last NUM history
     lines.  Only words matching PATTERN are taken.  If NUM is zero or
     negative the whole history is searched and if PATTERN is the empty
     string all words are taken (as with `*').  A typical use is

          compctl -D -f + -H 0 ''

     which forces completion to look back in the history list for a
     word if no filename matches.

Control Flags
-------------

These do not directly specify types of name to be completed, but
manipulate the options that do:

-Q
     This instructs the shell not to quote any metacharacters in the
     possible completions.  Normally the results of a completion are
     inserted into the command line with any metacharacters quoted so
     that they are interpreted as normal characters.  This is
     appropriate for filenames and ordinary strings.  However, for
     special effects, such as inserting a backquoted expression from a
     completion array (-k) so that the expression will not be evaluated
     until the complete line is executed, this option must be used.

-P PREFIX
     The PREFIX is inserted just before the completed string; any
     initial part already typed will be completed and the whole PREFIX
     ignored for completion purposes.  For example,

          compctl -j -P "%" kill

     inserts a `%' after the kill command and then completes job names.

-S SUFFIX
     When a completion is found the SUFFIX is inserted after the
     completed string.  In the case of menu completion the suffix is
     inserted immediately, but it is still possible to cycle through the
     list of completions by repeatedly hitting the same key.

-W FILE-PREFIX
     With directory FILE-PREFIX:  for command, file, directory and
     globbing completion (options -c, -f, -/, -g), the file prefix is
     implicitly added in front of the completion.  For example,

          compctl -/ -W ~/Mail maildirs

     completes any subdirectories to any depth beneath the directory
     ~/Mail, although that prefix does not appear on the command line.
     The FILE-PREFIX may also be of the form accepted by the -k flag,
     i.e. the name of an array or a literal list in parenthesis. In
     this case all the directories in the list will be searched for
     possible completions.

-q
     If used with a suffix as specified by the -S option, this causes
     the suffix to be removed if the next character typed is a blank or
     does not insert anything or if the suffix consists of only one
     character and the next character typed is the same character; this
     the same rule used for the AUTO_REMOVE_SLASH option.  The option
     is most useful for list separators (comma, colon, etc.).

-l CMD
     This option restricts the range of command line words that are
     considered to be arguments.  If combined with one of the extended
     completion patterns `p[...]', `r[...]', or `R[...]'  (see
     Extended Completion below) the range is restricted to the range
     of arguments specified in the brackets.  Completion is then
     performed as if these had been given as arguments to the CMD
     supplied with the option. If the CMD string is empty the first
     word in the range is instead taken as the command name, and
     command name completion performed on the first word in the range.
     For example,

          compctl -x 'r[-exec,;]' -l '' -- find

     completes arguments between `-exec' and the following `;' (or the
     end of the command line if there is no such string) as if they were
     a separate command line.

-h CMD
     Normally zsh completes quoted strings as a whole. With this option,
     completion can be done separately on different parts of such
     strings. It works like the -l option but makes the completion code
     work on the parts of the current word that are separated by
     spaces. These parts are completed as if they were arguments to the
     given CMD. If CMD is the empty string, the first part is completed
     as a command name, as with -l.

-U
     Use the whole list of possible completions, whether or not they
     actually match the word on the command line.  The word typed so far
     will be deleted.  This is most useful with a function (given by the
     -K option) which can examine the word components passed to it (or
     via the read builtin's -c and -l flags) and use its own criteria
     to decide what matches.  If there is no completion, the original
     word is retained.  Since the produced possible completions seldom
     have interesting common prefixes and suffixes, menu completion is
     started immediately if AUTO_MENU is set and this flag is used.

-y FUNC-OR-VAR
     The list provided by FUNC-OR-VAR is displayed instead of the list
     of completions whenever a listing is required; the actual
     completions to be inserted are not affected.  It can be provided
     in two ways. Firstly, if FUNC-OR-VAR begins with a $ it defines a
     variable, or if it begins with a left parenthesis a literal array,
     which contains the list.  A variable may have been set by a call
     to a function using the -K option.  Otherwise it contains the name
     of a function which will be executed to create the list.  The
     function will be passed as an argument list all matching
     completions, including prefixes and suffixes expanded in full, and
     should set the array reply to the result.  In both cases, the
     display list will only be retrieved after a complete list of
     matches has been created.

     Note that the returned list does not have to correspond, even in
     length, to the original set of matches, and may be passed as a
     scalar instead of an array.  No special formatting of characters is
     performed on the output in this case; in particular, newlines are
     printed literally and if they appear output in columns is
     suppressed.

-X EXPLANATION
     Print EXPLANATION when trying completion on the current set of
     options. A `%n' in this string is replaced by the number of
     matches that were added for this explanation string.  The
     explanation only appears if completion was tried and there was no
     unique match, or when listing completions. Explanation strings
     will be listed together with the matches of the group specified
     together with the -X option (using the -J or -V option). If the
     same explanation string is given to multiple -X options, the
     string appears only once (for each group) and the number of
     matches shown for the `%n' is the total number of all matches for
     each of these uses. In any case, the explanation string will only
     be shown if there was at least one match added for the explanation
     string.

     The sequences %B, %b, %S, %s, %U, and %u specify output attributes
     (bold, standout, and underline) and %{...%} can be used to include
     literal escape sequences as in prompts.

-Y EXPLANATION
     Identical to -X, except that the EXPLANATION first undergoes
     expansion following the usual rules for strings in double quotes.
     The expansion will be carried out after any functions are called
     for the -K or -y options, allowing them to set variables.

-t CONTINUE
     The CONTINUE-string contains a character that specifies which set
     of completion flags should be used next.  It is useful:

     (i) With -T, or when trying a list of pattern completions, when
     compctl would usually continue with ordinary processing after
     finding matches; this can be suppressed with `-tn'.

     (ii) With a list of alternatives separated by +, when compctl
     would normally stop when one of the alternatives generates
     matches.  It can be forced to consider the next set of completions
     by adding `-t+' to the flags of the alternative before the `+'.

     (iii) In an extended completion list (see below), when compctl
     would normally continue until a set of conditions succeeded, then
     use only the immediately following flags.  With `-t-', compctl will
     continue trying extended completions after the next `-'; with
     `-tx' it will attempt completion with the default flags, in other
     words those before the `-x'.

-J NAME
     This gives the name of the group the matches should be placed in.
     Groups are listed and sorted separately; likewise, menu completion
     will offer the matches in the groups in the order in which the
     groups were defined. If no group name is explicitly given, the
     matches are stored in a group named DEFAULT. The first time a
     group name is encountered, a group with that name is created.
     After that all matches with the same group name are stored in that
     group.

     This can be useful with non-exclusive alternative completions.  For
     example, in

          compctl -f -J files -t+ + -v -J variables foo

     both files and variables are possible completions, as the -t+
     forces both sets of alternatives before and after the + to be
     considered at once.  Because of the -J options, however, all files
     are listed before all variables.

-V NAME
     Like -J, but matches within the group will not be sorted in
     listings nor in menu completion. These unsorted groups are in a
     different name space from the sorted ones, so groups defined as -J
     files and -V files are distinct.

-1
     If given together with the -V option, makes only consecutive
     duplicates in the group be removed. Note that groups with and
     without this flag are in different name spaces.

-2
     If given together with the -J or -V option, makes all duplicates
     be kept. Again, groups with and without this flag are in different
     name spaces.

-M MATCH-SPEC
     This defines additional matching control specifications that
     should be used only when testing words for the list of flags this
     flag appears in. The format of the MATCH-SPEC string is described
     in Matching Control.

Alternative Completion
======================

compctl [ -CDT ] OPTIONS + OPTIONS [ + ... ] [ + ] COMMAND ...

The form with `+' specifies alternative options. Completion is tried
with the options before the first `+'. If this produces no matches
completion is tried with the flags after the `+' and so on. If there
are no flags after the last `+' and a match has not been found up to
that point, default completion is tried.  If the list of flags contains
a -t with a + character, the next list of flags is used even if the
current list produced matches.

Extended Completion
===================

compctl [ -CDT ] OPTIONS -x PATTERN OPTIONS - ... -
     [ COMMAND ... ]

compctl [ -CDT ] OPTIONS [ -x PATTERN OPTIONS - ... - ]
     [ + OPTIONS [ -x ... - ] ... [+] ] [ COMMAND ... ]

The form with `-x' specifies extended completion for the commands
given; as shown, it may be combined with alternative completion using
`+'.  Each PATTERN is examined in turn; when a match is found, the
corresponding OPTIONS, as described in Option Flags above, are
used to generate possible completions.  If no PATTERN matches, the
OPTIONS given before the -x are used.

Note that each pattern should be supplied as a single argument and
should be quoted to prevent expansion of metacharacters by the shell.

A PATTERN is built of sub-patterns separated by commas; it matches if
at least one of these sub-patterns matches (they are `or'ed). These
sub-patterns are in turn composed of other sub-patterns separated by
white spaces which match if all of the sub-patterns match (they are
`and'ed).  An element of the sub-patterns is of the form `C[...][...]',
where the pairs of brackets may be repeated as often as necessary, and
matches if any of the sets of brackets match (an `or').  The example
below makes this clearer.

The elements may be any of the following:

s[STRING]...
     Matches if the current word on the command line starts with one of
     the strings given in brackets.  The STRING is not removed and is
     not part of the completion.

S[STRING]...
     Like s[STRING] except that the STRING is part of the completion.

p[FROM,TO]...
     Matches if the number of the current word is between one of the
     FROM and TO pairs inclusive. The comma and TO are optional; TO
     defaults to the same value as FROM.  The numbers may be negative:
     -N refers to the N'th last word on the line.

c[OFFSET,STRING]...
     Matches if the STRING matches the word offset by OFFSET from the
     current word position.  Usually OFFSET will be negative.

C[OFFSET,PATTERN]...
     Like c but using pattern matching instead.

w[INDEX,STRING]...
     Matches if the word in position INDEX is equal to the
     corresponding STRING.  Note that the word count is made after any
     alias expansion.

W[INDEX,PATTERN]...
     Like w but using pattern matching instead.

n[INDEX,STRING]...
     Matches if the current word contains STRING.  Anything up to and
     including the INDEXth occurrence of this string will not be
     considered part of the completion, but the rest will.  INDEX may
     be negative to count from the end: in most cases, INDEX will be 1
     or -1.  For example,

          compctl -s '`users`' -x 'n[1,@]' -k hosts -- talk

     will usually complete usernames, but if you insert an @ after the
     name, names from the array HOSTS (assumed to contain hostnames,
     though you must make the array yourself) will be completed.  Other
     commands such as rcp can be handled similarly.

N[INDEX,STRING]...
     Like n except that the string will be taken as a character class.
     Anything up to and including the INDEXth occurrence of any of the
     characters in STRING will not be considered part of the completion.

m[MIN,MAX]...
     Matches if the total number of words lies between MIN and MAX
     inclusive.

r[STR1,STR2]...
     Matches if the cursor is after a word with prefix STR1.  If there
     is also a word with prefix STR2 on the command line after the one
     matched by STR1 it matches only if the cursor is before this word.
     If the comma and STR2 are omitted, it matches if the cursor is
     after a word with prefix STR1.

R[STR1,STR2]...
     Like r but using pattern matching instead.

q[STR]...
     Matches the word currently being completed is in single quotes and
     the STR begins with the letter `s', or if completion is done in
     double quotes and STR starts with the letter `d', or if completion
     is done in backticks and STR starts with a `b'.

Example
=======

     compctl -u -x 's[+] c[-1,-f],s[-f+]' \
       -g '~/Mail/*(:t)' - 's[-f],c[-1,-f]' -f -- mail

This is to be interpreted as follows:

If the current command is mail, then

     if ((the current word begins with + and the previous word is -f)
     or (the current word begins with -f+)), then complete the
     non-directory part (the `:t' glob modifier) of files in the
     directory ~/Mail; else

     if the current word begins with -f or the previous word was -f,
     then complete any file; else

     complete user names.

Zsh Modules
***********

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

Some optional parts of zsh are in modules, separate from the core of
the shell.  Each of these modules may be linked in to the shell at
build time, or can be dynamically linked while the shell is running if
the installation supports this feature.  The modules that are bundled
with the zsh distribution are:

zsh/cap
     Builtins for manipulating POSIX.1e (POSIX.6) capability
     (privilege) sets.

zsh/clone
     A builtin that can clone a running shell onto another terminal.

zsh/compctl
     The compctl builtin for controlling completion.

zsh/complete
     The basic completion code.

zsh/complist
     Completion listing extensions.

zsh/computil
     A module with utility builtins needed for the shell function based
     completion system.

zsh/deltochar
     A ZLE function duplicating EMACS' zap-to-char.

zsh/example
     An example of how to write a module.

zsh/files
     Some basic file manipulation commands as builtins.

zsh/mapfile
     Access to external files via a special associative array.

zsh/mathfunc
     Standard scientific functions for use in mathematical evaluations.

zsh/parameter
     Access to internal hash tables via special associative arrays.

zsh/sched
     A builtin that provides a timed execution facility within the
     shell.

zsh/stat
     A builtin command interface to the stat system call.

zsh/termcap
     Interface to the termcap database.

zsh/terminfo
     Interface to the terminfo database.

zsh/zftp
     A builtin FTP client.

zsh/zle
     The Zsh Line Editor, including the bindkey and vared builtins.

zsh/zleparameter
     Access to internals of the Zsh Line Editor via parameters.

zsh/zprof
     A module allowing profiling for shell functions.

zsh/zpty
     A builtin for starting a command in a pseudo-terminal.

zsh/zutil
     Some utility builtins, e.g. the one for supporting configuration
     via styles.

The zsh/cap Module
==================

The zsh/cap module is used for manipulating POSIX.1e (POSIX.6)
capability sets.  If the operating system does not support this
interface, the builtins defined by this module will do nothing.  The
builtins in this module are:

cap [ CAPABILITIES ]
     Change the shell's process capability sets to the specified
     CAPABILITIES, otherwise display the shell's current capabilities.

getcap FILENAME ...
     This is a built-in implementation of the POSIX standard utility.
     It displays the capability sets on each specified FILENAME.

setcap CAPABILITIES FILENAME ...
     This is a built-in implementation of the POSIX standard utility.
     It sets the capability sets on each specified FILENAME to the
     specified CAPABILITIES.

The zsh/clone Module
====================

The zsh/clone module makes available one builtin command:

clone TTY
     Creates a forked instance of the current shell, attached to the
     specified TTY.  In the new shell, the PID, PPID and TTY special
     parameters are changed appropriately.  $! is set to zero in the new
     shell, and to the new shell's PID in the original shell.

     The return value of the builtin is zero in both shells if
     successful, and non-zero on error.

The zsh/compctl Module
======================

The zsh/compctl module makes available two builtin commands. compctl,
is the old, deprecated way to control completions for ZLE.  See
Completion Using compctl.  The other builtin command, compcall can be
used in user-defined completion widgets, see Completion Widgets.

The zsh/complete Module
=======================

The zsh/complete module makes available several builtin commands which
can be used in user-defined completion widgets, see Completion Widgets.

The zsh/complist Module
=======================

The zsh/complist module offers three extensions to completion listings:
the ability to highlight matches in such a list, the ability to scroll
through long lists and a different style of menu completion.

Colored completion listings
---------------------------

Whenever one of the parameters ZLS_COLORS or ZLS_COLOURS is set and the
zsh/complist module is loaded or linked into the shell, completion
lists will be colored.  Note, however, that complist will not
automatically be loaded if it is not linked in:  on systems with
dynamic loading, `zmodload zsh/complist' is required.

The parameters ZLS_COLORS and ZLS_COLOURS describe how matches are
highlighted.  To turn on highlighting an empty value suffices, in which
case all the default values given below will be used.  The format of
the value of these parameters is the same as used by the GNU version of
the ls command: a colon-separated list of specifications of the form
`NAME=VALUE'.  The NAME may be one of the following strings, most of
which specify file types for which the VALUE will be used.  The strings
and their default values are:

no 0
     for normal text (i.e. when displaying something other than a
     matched file)

fi 0
     for regular files

di 32
     for directories

ln 36
     for symbolic links

pi 31
     for named pipes (FIFOs)

so 33
     for sockets

bd 44;37
     for block devices

cd 44;37
     for character devices

ex 35
     for executable files

mi NONE
     for a non-existent file (default is the value defined for fi)

lc \e[
     for the left code (see below)

rc m
     for the right code

tc 0
     for the character indicating the file type  printed after
     filenames if the LIST_TYPES option is set

sp 0
     for the spaces printed after matches to align the next column

ec NONE
     for the end code

Apart from these strings, the NAME may also be an asterisk (`*')
followed by any string. The VALUE given for such a string will be used
for all files whose name ends with the string.  The NAME may also be an
equals sign (`=') followed by a pattern.  The VALUE given for this
pattern will be used for all matches (not just filenames) whose display
string are matched by the pattern.  Definitions for both of these take
precedence over the values defined for file types and the form with the
leading asterisk takes precedence over the form with the leading equal
sign.

The last form also allows different parts of the displayed strings to
be colored differently.  For this, the pattern has to use the `(#b)'
globbing flag and pairs of parentheses surrounding the parts of the
strings that are to be colored differently.  In this case the VALUE may
consist of more than one color code separated by equal signs.  The
first code will be used for all parts for which no explicit code is
specified and the following codes will be used for the parts matched by
the sub-patterns in parentheses.  For example, the specification
`=(#b)(?)*(?)=0=3=7' will be used for all matches which are at least
two characters long and will use the code `3' for the first character,
`7' for the last character and `0' for the rest.

All three forms of NAME may be preceded by a pattern in parentheses.
If this is given, the VALUE will be used only for matches in groups
whose names are matched by the pattern given in the parentheses.  For
example, `(g*)m*=43' highlights all matches beginning with `m' in
groups whose names  begin with `g' using the color code `43'.  In case
of the `lc', `rc', and `ec' codes, the group pattern is ignored.

Note also that all patterns are tried in the order in which they appear
in the parameter value until the first one matches which is then used.

When printing a match, the code prints the value of lc, the value for
the file-type or the last matching specification with a `*', the value
of rc, the string to display for the match itself, and then the value
of ec if that is defined or the values of lc, no, and rc if ec is not
defined.

The default values are ISO 6429 (ANSI) compliant and can be used on
vt100 compatible terminals such as xterms.  On monochrome terminals the
default values will have no visible effect.  The colors function from
the contribution can be used to get associative arrays containing the
codes for ANSI terminals (see Other Functions).  For example,
after loading colors, one could use `$colors[red]' to get the code for
foreground color red and `$colors[bg-green]' for the code for
background color green.

If the completion system invoked by compinit is used, these parameters
should not be set directly because the system controls them itself.
Instead, the list-colors style should be used (see Completion System Configuration).

Scrolling in completion listings
--------------------------------

To enable scrolling through a completion list, the LISTPROMPT parameter
must be set.  Its value will be used as the prompt; if it is the empty
string, a default prompt will be used.  The value may contain escapes
of the form `%x'.  It supports the escapes `%B', `%b', `%S', `%s',
`%U', `%u' and `%{...%}' used also in shell prompts as well as three
pairs of additional sequences: a `%l' or `%L' is replaced by the number
of the last line shown and the total number of lines in the form
`NUMBER/TOTAL'; a `%m' or `%M' is replaced with the number of the last
match shown and the total number of matches; and `%p' or `%P' is
replaced with `Top', `Bottom' or the position of the first line shown
in percent of the total number of lines, respectively.  In each of
these cases the form with the uppercase letter will be replaced with a
string of fixed width, padded to the right with spaces, while the
lowercase form will not be padded.

If the parameter LISTPROMPT is set, the completion code will not ask if
the list should be shown.  Instead it immediately starts displaying the
list, stopping after the first screenful, showing the prompt at the
bottom, waiting for a keypress after temporarily switching to the
listscroll keymap.  Some of the zle functions have a special meaning
while scrolling lists:

send-break
     stops listing discarding the key pressed

accept-line, down-history, down-line-or-history
down-line-or-search, vi-down-line-or-history
     scrolls forward one line

complete-word, menu-complete, expand-or-complete
expand-or-complete-prefix, menu-complete-or-expand
     scrolls forward one screenful

Every other character stops listing and immediately processes the key
as usual.  Any key that is not bound in the listscroll keymap or that
is bound to undefined-key is looked up in the keymap currently selected.

As for the ZLS_COLORS and ZLS_COLOURS parameters, LISTPROMPT should not
be set directly when using the shell function based completion system.
Instead, the list-prompt style should be used.

Menu selection
--------------

The zsh/complist module also offers an alternative style of selecting
matches from a list, called menu selection, which can be used if the
shell is set up to return to the last prompt after showing a completion
list (see the ALWAYS_LAST_PROMPT option in Options).  It can be
invoked directly by the widget menu-select defined by the module.
Alternatively, the parameter MENUSELECT can be set to an integer, which
gives the minimum number of matches that must be present before menu
selection is automatically turned on.  This second method requires that
menu completion be started, either directly from a widget such as
menu-complete, or due to one of the options MENU_COMPLETE or AUTO_MENU
being set.  If MENUSELECT is set, but is 0, 1 or empty, menu selection
will always be started during an ambiguous menu completion.

When using the completion system based on shell functions, the
MENUSELECT parameter should not be used (like the ZLS_COLORS and
ZLS_COLOURS parameters described above).  Instead, the menu style
should be used with the select=... keyword.

After menu selection is started, the matches will be listed. If there
are more matches than fit on the screen, only the first screenful is
shown.  The matches to insert into the command line can be selected
from this list.  In the list one match is highlighted using the value
for ma from the ZLS_COLORS or ZLS_COLOURS parameter.  The default value
for this is `7' which forces the selected match to be highlighted using
standout mode on a vt100-compatible terminal.  If neither ZLS_COLORS
nor ZLS_COLOURS is set, the same terminal control sequence as for the
`%S' escape in prompts is used.

If there are more matches than fit on the screen and the parameter
MENUPROMPT is set, its value will be shown below the matches.  It
supports the same escape sequences as LISTPROMPT, but the number of the
match or line shown will be that of the one where the mark is placed.
If its value is the empty string, a default prompt will be used.

The MENUSCROLL parameter can be used to specify how the list is
scrolled.  If the parameter is unset, this is done line by line, if it
is set to `0' (zero), the list will scroll half the number of lines of
the screen.  If the value is positive, it gives the number of lines to
scroll and if it is negative, the list will be scrolled the number of
lines of the screen minus the (absolute) value.

As for the ZLS_COLORS, ZLS_COLOURS and LISTPROMPT parameters, neither
MENUPROMPT nor MENUSCROLL should be set directly when using the shell
function based completion system.  Instead, the select-prompt and
select-scroll styles should be used.

The completion code sometimes decides not to show all of the matches in
the list.  These hidden matches are either matches for which the
completion function which added them explicitly requested that they not
appear in the list (using the -n option of the compadd builtin command)
or they are matches which duplicate a string already in the list
(because they differ only in things like prefixes or suffixes that are
not displayed).  In the list used for menu selection, however, even
these matches are shown so that it is possible to select them.  To
highlight such matches the hi and du capabilities in the ZLS_COLORS and
ZLS_COLOURS parameters are supported for hidden matches of the first
and second kind, respectively.

Selecting matches is done by moving the mark around using the zle
movement functions.  When not all matches can be shown on the screen at
the same time, the list will scroll up and down when crossing the top or
bottom line.  The following zle functions have special meaning during
menu selection:

accept-line
     accepts the current match and leaves menu selection

send-break
     leaves menu selection and restores the previous contents of the
     command line

redisplay, clear-screen
     execute their normal function without leaving menu selection

accept-and-hold, accept-and-menu-complete
     accept the currently inserted match and continue selection
     allowing to select the next match to insert into the line

accept-and-infer-next-history
     accepts the current match and then tries completion with menu
     selection again;  in the case of files this allows one to select a
     directory and immediately attempt to complete files in it;  if
     there are no matches, a message is shown and one can use undo to
     go back to completion on the previous level, every other key
     leaves menu selection (including the other zle functions which are
     otherwise special during menu selection)

undo
     removes matches inserted during the menu selection by one of the
     three functions before

down-history, down-line-or-history
vi-down-line-or-history,  down-line-or-search
     moves the mark one line down

up-history, up-line-or-history
vi-up-line-or-history, up-line-or-search
     moves the mark one line up

forward-char, vi-forward-char
     moves the mark one column right

backward-char, vi-backward-char
     moves the mark one column left

forward-word, vi-forward-word
vi-forward-word-end, emacs-forward-word
     moves the mark one screenful down

backward-word, vi-backward-word, emacs-backward-word
     moves the mark one screenful up

vi-forward-blank-word, vi-forward-blank-word-end
     moves the mark to the first line of the next group of matches

vi-backward-blank-word
     moves the mark to the last line of the previous group of matches

beginning-of-history
     moves the mark to the first line

end-of-history
     moves the mark to the last line

beginning-of-buffer-or-history, beginning-of-line
beginning-of-line-hist, vi-beginning-of-line
     moves the mark to the leftmost column

end-of-buffer-or-history, end-of-line
end-of-line-hist, vi-end-of-line
     moves the mark to the rightmost column

complete-word, menu-complete, expand-or-complete
expand-or-complete-prefix, menu-expand-or-complete
     moves the mark to the next match

reverse-menu-complete
     moves the mark to the previous match

All movement functions wrap around at the edges; any other zle function
not listed leaves menu selection and executes that function.  It is
possible to make widgets in the above list do the same by using the
form of the widget with a `.' in front.  For example, the widget
`.accept-line' has the effect of leaving menu selection and accepting
the entire command line.

During this selection the widget uses the keymap menuselect.  Any key
that is not defined in this keymap or that is bound to undefined-key is
looked up in the keymap currently selected.  This is used to ensure
that the most important keys used during selection (namely the cursor
keys, return, and TAB) have sensible defaults.  However, keys in the
menuselect keymap can be modified directly using the bindkey builtin
command (see The zsh/zle Module). For example, to make the
return key leave menu selection without accepting the match currently
selected one could call

     bindkey -M menuselect '^M' send-break

after loading the zsh/complist module.