GNU Info
(zsh.info)Control Flags
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.
-W FILE-PREFIX
With directory FILE-PREFIX: for command, file, directory and
globbing completion (options -c, -f, -/, -g), the file prefix is
implicitly added in front of the completion. For example,
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.
-q
If used with a suffix as specified by the -S option, this causes
the suffix to be removed if the next character typed is a blank or
does not insert anything or if the suffix consists of only one
character and the next character typed is the same character; this
the same rule used for the AUTO_REMOVE_SLASH option. The option
is most useful for list separators (comma, colon, etc.).
-l CMD
This option 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 Note:
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
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.
-h CMD
Normally zsh completes quoted strings as a whole. With this option,
completion can be done separately on different parts of such
strings. It works like the -l option but makes the completion code
work on the parts of the current word that are separated by
spaces. These parts are completed as if they were arguments to the
given CMD. If CMD is the empty string, the first part is completed
as a command name, as with -l.
-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. Since the produced possible completions seldom
have interesting common prefixes and suffixes, menu completion is
started immediately if AUTO_MENU is set and this flag is used.
-y FUNC-OR-VAR
The list provided by FUNC-OR-VAR is displayed instead of the list
of completions whenever a listing is required; the actual
completions to be inserted are not affected. It can be provided
in two ways. Firstly, if FUNC-OR-VAR begins with a $ it defines a
variable, or if it begins with a left parenthesis a literal array,
which contains the list. A variable may have been set by a call
to a function using the -K option. Otherwise it contains the name
of a function which will be executed to create the list. The
function will be passed as an argument list all matching
completions, including prefixes and suffixes expanded in full, and
should set the array reply to the result. In both cases, the
display list will only be retrieved after a complete list of
matches has been created.
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.
-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 that were added for this explanation string. The
explanation only appears if completion was tried and there was no
unique match, or when listing completions. Explanation strings
will be listed together with the matches of the group specified
together with the -X option (using the -J or -V option). If the
same explanation string is given to multiple -X options, the
string appears only once (for each group) and the number of
matches shown for the `%n' is the total number of all matches for
each of these uses. In any case, the explanation string will only
be shown if there was at least one match added for the explanation
string.
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.
-Y EXPLANATION
Identical to -X, except that the EXPLANATION first undergoes
expansion following the usual rules for strings in double quotes.
The expansion will be carried out after any functions are called
for the -K or -y options, allowing them to set variables.
-t CONTINUE
The CONTINUE-string contains a character that specifies which set
of completion flags should be used next. It is useful:
(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'.
-J NAME
This gives the name of the group the matches should be placed in.
Groups are listed and sorted separately; likewise, menu completion
will offer the matches in the groups in the order in which the
groups were defined. If no group name is explicitly given, the
matches are stored in a group named DEFAULT. The first time a
group name is encountered, a group with that name is created.
After that all matches with the same group name are stored in that
group.
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.
-V NAME
Like -J, but matches within the group will not be sorted in
listings nor in menu completion. These unsorted groups are in a
different name space from the sorted ones, so groups defined as -J
files and -V files are distinct.
-1
If given together with the -V option, makes only consecutive
duplicates in the group be removed. Note that groups with and
without this flag are in different name spaces.
-2
If given together with the -J or -V option, makes all duplicates
be kept. Again, groups with and without this flag are in different
name spaces.
-M MATCH-SPEC
This defines additional matching control specifications that
should be used only when testing words for the list of flags this
flag appears in. The format of the MATCH-SPEC string is described
in Note: Matching Control.
automatically generated by info2www version 1.2.2.9