zshcompctl
Hurricane Electric Internet Services
NAME
zshcompctl - zsh programmable completion
DESCRIPTION
compctl [ -cfqovbCDTAIFpEjBaRGuderzNOZn ] [ -k name ]
[ -X explanation ] [ -K function ]
[ -P prefix ] [ -S suffix ]
[ -g globstring ] [ -s subststring ]
[ -H num pattern ] [ -l cmd ] [ arg ... ]
compctl flags [ -x pattern flags - ... -- ]
[ + flags [ -x ... -- ] + ... [+] ] [ arg ... ]
compctl -L [-CDT] [ arg ... ]
compctl + arg ...
Control the editor's completion behavior when one
of arg is the current command. (Note that aliases
are expanded before this is determined, unless the
COMPLETE_ALIASES option is set.) With the -D flag,
control default completion behavior for commands
not assigned any special behavior; with -C, control
completion when there is no current command. The
-T flag gives the completion flags that are to used
first, prior to any other flags, even those given
to specific commands with other compctl defini-
tions. This is only useful when combined with
extended completion (the -x flag, see below).
Using this flag you can define default behaviour
you want to have everywhere and you can alter the
standard behaviour for all commands. For example,
if your access to the user database is too slow
and/or it contains too many users (so that comple-
tion 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
an ~ and files for words starting with a ~ and con-
taining a slash.
If the -L flag is given, the existing completion
behaviour for the command arguments is listed in a
manner suitable for putting into a start-up script.
The -C and -D options will list the behaviour for
command and default completion respectively. Any
other flags supplied are ignored. If no other argu-
ments are given, all defined completions are listed
in this form.
If the + flag is alone and followed immediately by
the arg list, the completion behaiour for all the
commands in the list is reset to its default by
deleting the command from the list of those handled
specially.
The remaining options specify the type of command
arguments to look for during completion. If comple-
tion 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.
-c Expect command names.
-f Expect filenames and filesystem paths.
-o Expect option names.
-v Expect variable names.
-b Expect key binding names.
-A Expect array names.
-I Expect integer variable names.
-F Expect function names.
-p Expect parameter names.
-E Expect environment variable names.
-j Expect job names (the first word of the job
leader's command line, useful with the kill
builtin).
-r Expect names of running jobs.
-z Expect names of suspended jobs.
-B Expect names of builtin commands.
-a Expect alias names.
-R Expect names of regular aliases.
-G Expect names of global aliases.
-u Expect user names.
-d Expect names of disabled commands.
-e Expect names of executable (and enabled)
commands.
-N Expect names of scalar parameters.
-O Expect names of readonly variables.
-Z Expect names of shell special parameters.
-n Expect named directories.
-q If given together with a suffix (see the -S
flag below) it makes this suffix be removed
if the next character typed is a blank or
does not insert anything (this is the same
rule as used for the AUTO_REMOVE_SLASH
option).
-k name
Expect names taken from the elements of
$name (which should be an array). Alterna-
tively, the argument name itself may be a
set of space- or comma-separated values in
parentheses, in which any delimiter may be
escaped with a backslash. (Example: `com-
pctl -k "(cputime filesize datasize stack-
size coredumpsize resident descriptors)"
limit'.)
-K function
Call the given function to get the comple-
tions. The function gets two arguments: the
prefix and the suffix of the word on which
completion is tried. The function should
set the variable reply to an array contain-
ing the completions (one completion per ele-
ment); note that reply should not be made
local. From such a function the command
line can be accessed with the -c and -l
flags to the read builtin. (Example: `func-
tion 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.
-X explanation
Print the explanation string when trying
completion. A `%n' in this string is
replaced by the number of matches.
-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. (Example:
`compctl -j -P "%" kill').
-S suffix
After a unique completion is found the suf-
fix is inserted after the completed string.
-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 used. More than one pattern may be
given separated by blanks. (Note that brace
expansion is not part of globbing.)
-s subststring
The substring is split into words and these
words are than expanded using all shell
expansion mechanisms. The resulting words
are taken as possible completions. The fig-
nore special parameter is not used. Note
that -g is faster for filenames.
-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 (or '*', of
course) all words are taken.
-l cmd This option can not be combined with any
other option. If it is given it restricts
the range of command line words that are
considered to be arguments. By default this
range contains all arguments without the
command string. If combined with extended
completion (see below) and one of the pat-
terns `p[...]', `r[...]', or `R[...]' the
range is restricted to the arguments between
the ones that are specified in the brackets.
After the range of arguments is determined
completion is done in it as if they were
arguments to the cmd given with this option.
If this string is empty the first word in
the range is taken as the command name for
which to complete. In this case, if the cur-
sor is in the first word, command names are
completed. Example: `compctl -x
'r[-exec,;]' -l '' -- find' completes the
arguments between `-exec' and the following
`;' (or the end of the command line if there
is no such string) as if they were specify-
ing a command on there own.
-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 (-K option), which can examine the
word via the read builtin's -c and -l flags
and use its own criterion to decide what
matches.
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 com-
pletion is tried.
The form with `-x' specifies extended completion
for the commands given as arg. Each pattern is
examined in turn; when a match is found, the corre-
sponding flags, as described above for the ordinary
case, are used to generate possible completions.
If no pattern matches, the flags given before the
-x are used. Note that each pattern should be sup-
plied 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 com-
mas; it matches if at least one of these sub-pat-
terns matches (they are `or'ed'). These sub-pat-
terns 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'). These elements may be
any of the following:
s[string] ...
The pattern matches if the current
word on the command line starts with
one of the strings given in brack-
ets. The string is not removed and
is not part of the completion.
S[string] ...
Like s[string] but the string is
part of the completion.
p[from,to] ...
The pattern matches if the number of
the current word is between one of
the from and to pairs. 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] ...
The pattern matches if one of the
strings matches the word offset by
offset from the current word posi-
tion.
C[offset,pattern] ...
This is like c but uses pattern
matching instead.
w[index,string] ...
The pattern matches if the word in
position index is equal to the cor-
responding string. Note that the
word count is made after 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.
N[index,string] ...
Like n[index,string] but 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 (inclu-
sive).
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
Complete users by default. After a -f with an
optional space, complete file names; if a + follows
the -f, whether or not there is a space in between,
complete with the non-directory part of files in
the directory ~/Mail.
Hurricane Electric Internet Services
Copyright (C) 1998
Hurricane Electric.
All Rights Reserved.