This is a texinfo version of the man page for the Z Shell, originally by
Paul Falstad.  It was converted from the `zsh.1' file distributed with
zsh v2.5.0 by Jonathan Hardwick, `jch@cs.cmu.edu' and updated/modified
by Clive Messer, `clive@epos.demon.co.uk' to its present state.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

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

`-K FUNCTION'
     Call the given function to get the completions.  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 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 that just `reply=`users`' is 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 '' -X '(No file found; using history)''

     which forces completion to look back in the history list for a
     word if no filename matches.  The explanation string is useful as
     it tells the user that no file of that name exists, which is
     otherwise ambiguous.  (See the next section for `-X'.)

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.

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

`-l CMD'
     This option cannot be combined with any other option.  It
     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.)
     the range is restricted to the 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.

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

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

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.

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 Options Flags, 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 meta-characters 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 INDEX'th 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.

`N[INDEX,STRING] ...'
     Like N[INDEX,STRING] except that the STRING will be taken as a
     character class.  Anything up to and including the INDEX'th
     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 it matches
     only if the cursor is before this word.

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

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.