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 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 com

pleting 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 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 command 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. Commands should not be combined with the -D, -C or -T

flags.

-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. -C controls completion when the command word

itself is being completed. If no compctl -C command has been is

sued, the names of any executable command (whether in the path

or specific to the shell, such as aliases or functions) are com

pleted.
-T supplies completion flags to be used before

any other processing is done, even those given to specific com

mands with other compctl definitions. This is only useful when

combined with extended completion (the -x flag, see the section

EXTENDED COMPLETION

fault 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 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 ex

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

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 it

self:

-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 combina

tion with -F, -B, -w, -a, -R and -G will complete names of func

tions, 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 (in

cluding 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 lead

er'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). Alterna

tively, the argument array itself may be a set of space- or com

ma-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)" lim

it

-g globstring

The globstring is expanded using filename

globbing; it should be quoted to protect it from immediate expan

sion. 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 `(ei

ther|or)' to match alternatives.)

-s subststring

The subststring is split into words and

these words are than expanded using all shell expansion mecha

nisms (see the zshexpn manual page). The resulting words are tak

en 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 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 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 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 complet

ed, 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 back

quoted expression from a completion array (-k) so that the ex

pression will not be evaluated until the complete line is execut

ed, 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 in

serted after the completed string. In the case of menu comple

tion 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 oth

er. It restricts the range of command line words that are con

sidered to be arguments. If combined with one of the extended

completion patterns `p[...]', `r[...]', or `R[...]' (see the

section 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 sup

plied 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. Comple

tion is tried with the options before the first `+'. If this pro

duces 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 the

section OPTION FLAGS above, are used to generate possible comple

tions. If no pattern matches, the options given before the -x

are used.

Note that each pattern should be supplied as a single ar

gument and should be quoted to prevent expansion of metacharac

ters 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-pat

terns 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 off

set 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 com

mand 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 com

plete 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 version 3.0 June 26, 1996

ZSHCOMPCTL(1)