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 section Completion System, and the basic shell mechanisms which support it are described in section Completion Widgets. This chapter describes the older 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.
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 section Option Flags:
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.
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.
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, as described below in section Matching Control.
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.
These produce completion lists made up by the shell itself:
These have user supplied arguments to determine how the list of completions is to be made up:
compctl -k "(cputime filesize datasize stacksize coredumpsize resident descriptors)" limit
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.
compctl -D -f + -H 0 ''
which forces completion to look back in the history list for a word if no filename matches.
These do not directly specify types of name to be completed, but manipulate the options that do:
compctl -j -P "%" kill
inserts a `%' after the kill command and then completes job names.
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.
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.
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.
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.
(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'.
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.
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.
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 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 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:
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.
It is possible by use of the -M spec flag to specify how the characters in the string to be completed (referred to here as the command line) map onto the characters in the list of matches produced by the completion code (referred to here as the trial completions).
The spec consists of one or more matching descriptions separated by whitespace. Each description consists of a letter followed by a colon, then the patterns describing which character sequences on the line match which character sequences in the trial completion. Any sequence of characters not handled in this fashion must match exactly, as usual.
The forms of spec understood are as follows. In each case, the form with an uppercase initial character retains the string already typed on the command line as the final result of completion, while with a lowercase initial character the string on the command line is changed into the corresponding part of the trial completion.
Each lpat, tpat or anchor is either an empty string or consists of a sequence of literal characters (which may be quoted with a backslash), question marks, character classes, and correspondence classes; ordinary shell patterns are not used. Literal characters match only themselves, question marks match any character, and character classes are formed as for globbing and match any character in the given set.
Correspondence classes are defined like character classes, but with two differences: they are delimited by a pair of braces, and negated classes are not allowed, so the characters ! and ^ have no special meaning directly after the opening brace. They indicate that a range of characters on the line match a range of characters in the trial completion, but (unlike ordinary character classes) paired according to the corresponding position in the sequence. For example, to make any lowercase letter on the line match the corresponding uppercase letter in the trial completion, you can use `m:{a-z}={A-Z}'. More than one pair of classes can occur, in which case the first class before the = corresponds to the first after it, and so on. If one side has more such classes than the other side, the superfluous classes behave like normal character classes. In anchor patterns correspondence classes also behave like normal character classes.
The pattern tpat may also be a single star, `*'. This means that the pattern on the command line can match any number of characters in the trial completion. In this case the pattern must be anchored (on either side); the anchor then determines how much of the trial completion is to be included -- only the characters up to the next appearance of the anchor will be matched.
Examples:
The option -o produces option names in all-lowercase form, without underscores, and without the optional no at the beginning even though the builtins setopt and unsetopt understand option names with uppercase letters, underscores, and the optional no. The following alters the matching rules so that the prefix no and any underscore are ignored when trying to match the trial completions generated and uppercase letters on the line match the corresponding lowercase letters in the words:
compctl -M 'L:|[nN][oO]= M:_= M:{A-Z}={a-z}' \ -o setopt unsetopt
The first part says that the pattern `[nN][oO]' at the beginning (the empty anchor before the pipe symbol) of the string on the line matches the empty string in the list of words generated by completion, so it will be ignored if present. The second part does the same for an underscore anywhere in the command line string, and the third part uses correspondence classes so that any uppercase letter on the line matches the corresponding lowercase letter in the word. The use of the uppercase forms of the specification characters (L and M) guarantees that what has already been typed on the command line (in particular the prefix no) will not be deleted.
The second example makes completion case insensitive. By using compctl with the -M option alone this applies to every completion. This is just the same as in the setopt example, except here we wish to retain the characters in the list of completions:
compctl -M 'm:{a-z}={A-Z}'
This makes lowercase letters match their uppercase counterparts. To make uppercase letters match the lowercase forms as well:
compctl -M 'm:{a-zA-Z}={A-Za-z}'
A nice example for the use of * patterns is partial word completion. Sometimes you would like to make strings like c.s.u complete to strings like comp.source.unix, i.e. the word on the command line consists of multiple parts, separated by a dot in this example, where each part should be completed separately -- note, however, that the case where each part of the word, i.e. comp, source and unix in this example, is to be completed separately is a different problem to be solved by extended completion. The example can be handled by:
compctl -M 'r:|.=* r:|=*' \ -k '(comp.sources.unix comp.sources.misc ...)' ngroups
The first specification says that lpat is the empty string, while anchor is a dot; tpat is *, so this can match anything except for the `.' from the anchor in the trial completion word. So in c.s.u, the matcher sees c, followed by the empty string, followed by the anchor `.', and likewise for the second dot, and replaces the empty strings before the anchors, giving c[omp].s[ources].u[nix], where the last part of the completion is just as normal.
The second specification is needed to make this work when the cursor is in the middle of the string on the command line and the option COMPLETE_IN_WORD is set. In this case the completion code would normally try to match trial completions that end with the string as typed so far, i.e. it will only insert new characters at the cursor position rather then at the end. However in our example we would like the code to recognise matches which contain extra characters after the string on the line (the nix in the example). Hence we say that the empty string at the end of the string on the line matches any characters at the end of the trial completion.
More generally, the specification
compctl -M 'r:|[.,_-]=* r:|=*'
allows one to complete words with abbreviations before any of the characters in the square brackets in any completion. For example, to complete veryverylongfile.c rather than veryverylongheader.h with the above in effect, you can just type very.c before attempting completion.
The form compctl -M that defines global matching actually accepts any number of specification strings, unlike the case where the -M option applies only to a particular command. In this case, when completion is attempted for any command, the code will try the specifications in order until one matches. This allows one to define simple and fast matches to be used first, more powerful matchers as a second choice, and so on.
For example, one can make the code match trial completions that contain the string on the command line as a substring, not just at the beginning. Since this might produce more matches than we want, we arrange for it to be tried only if the matchers described above don't produce any matches:
compctl -M 'r:|[.,_-]=* r:|=*' 'l:|=* r:|=*'
Here, if the string on the command line is foo.bar, compctl first tries matching fooanything.baranything, as with the previous example. If that fails, the two descriptions in the second string after the -M say that the blanks at the beginning and end of the string on the command line can match any set of characters at the beginning or end of the trial completion, so it will look for anythingfoo.baranything.
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.