ZSHCOMPCTL(1)
NAME
zshcompctl - zsh programmable completion
DESCRIPTION
compctl [ -CDT ] options [ command ... ]
compctl [ -CDT ] options
[ -x pattern options - ... -- ]
[ + options [ -x ... -- ] ... [+] ]
[ command ... ]
compctl -L [ -CDT ] [ 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 exam-
ple 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 sepa-
rately specified. These correspond to the following flags
and arguments, all of which (except for -L) may be com-
bined with any combination of the options described subse-
quently in the section OPTION FLAGS:
command ...
controls completion for the named commands,
which must be listed last on the command
line. If completion is attempted for a com-
mand with a pathname containing slashes and
no completion definition is found, the
search is retried with the last pathname
component. Note that aliases are expanded
before the command name is determined unless
the COMPLETE_ALIASES option is set. Com-
mands should not be combined with the -D, -C
or -T flags.
-D controls default completion behavior for the
arguments of commands not assigned any spe-
cial behavior. If no compctl -D command has
been issued, filenames are completed.
-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.
-T supplies completion flags to be used before
any other processing is done, even those
given to specific commands with other com-
pctl definitions. This is only useful when
combined with extended completion (the -x
flag, see the section 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 -Tx 'C[0,*/*]' -f - 's[~]' -k friends -S/
to complete the strings in the array friends
after a ~. The first 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
may be specified, otherwise all defined com-
pletions are listed. Any other flags sup-
plied 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 com-
pletion) 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.
OPTION FLAGS
[ -fcFBdeaRGovNAIOPZEnbjrzu ]
[ -k array ] [ -g globstring ] [ -s subststring ]
[ -K function ] [ -H num pattern ]
[ -Q ] [ -P prefix ] [ -S suffix ]
[ -q ] [ -X explanation ]
[ -l cmd ] [ -U ]
The remaining options specify the type of command argu-
ments 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.
-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 the zshoptions
manual page).
-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 com-
mand 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 comple-
tions. 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 the zshexpn
manual page). 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 file-
names.
-K function
Call the given function to get the comple-
tions. The function is passed two argu-
ments: the prefix and the suffix of the word
on which completion is to be attempted, in
other words those characters before the cur-
sor position, and those from the cursor
position onwards. The function should set
the variable reply to an array containing
the completions (one completion per ele-
ment); 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 exam-
ple,
function whoson { reply=(`users`); }
compctl -K whoson talk
completes only logged-on users after `talk'.
Note that `whoson' must return an array so
that "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 nega-
tive 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 com-
pleted, 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 com-
pleted string; any initial part already
typed will be completed and the whole prefix
ignored for completion purposes. For exam-
ple,
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 possi-
ble 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. It restricts the range of command
line words that are considered to be argu-
ments. If combined with one of the extended
completion patterns `p[...]', `r[...]', or
`R[...]' (see the section EXTENDED COMPLE-
TION below) the range is restricted to the
range of arguments specified in the brack-
ets. 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 com-
mand 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. Comple-
tion 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 alterna-
tive completion using +. Each pattern is examined in
turn; when a match is found, the corresponding options, as
described in the section 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 com-
posed 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 inclu-
sive. The comma and to are optional; to
defaults to the same value as from. The num-
bers may be negative: -n refers to the n'th
last word on the line.
c[offset,string] ...
Matches if the string matches the word off-
set by offset from the current word posi-
tion. 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 con-
sidered 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. Any-
thing 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 previ-
ous 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.