GNU Info
(zsh.info)Completion System Configuration
Completion System Configuration
===============================
This section gives a short overview of how the completion system works,
and then more detail on how users can configure how and when matches are
generated.
Overview
--------
When completion is attempted somewhere on a command line the completion
system first tries to find out the context where completion was tried.
The context depends on such things as the name of the command when
completing an argument, and possibly also the name of an option when
completing an argument to that option.
The `context' of a completion is a string consisting of multiple
fields. This is used to look up styles that can be used to configure the
completion system. Since it is not possible to build the whole context
string in advance, completion functions may modify some of the fields
and hence the context used for lookup may vary during the same call to
the completion system.
The context string always consists of the following fields, separated
by colons and with a leading colon before the first:
* The literal string completion, saying that this style is used by
the completion system.
* The FUNCTION; in many cases this field will be blank, but when the
completion system is called from other functions, like predict-on
or one of the functions in the Command directory of the
distribution, this field contains the name of that function, often
in an abbreviated form.
* The COMPLETER currently active, which is the name of the function
without the leading underscore. A `completer' is in overall
control of how completion is to be performed; `complete' is the
basic one for ordinary completion, but completers may perform
various related tasks such as correction, or modify the behaviour
of a later completer (see Note: Control Functions for more
information).
* The CONTEXT or COMMAND. This is either one of the special context
names such as -condition- as explained for the _complete completer
below, or the name of the command we are completing arguments for.
Completion functions for commands that have sub-commands usually
modify this field to contain the name of the command followed by a
minus sign and the sub-command (e.g. the completion function for
the cvs command sets this field to strings such as cvs-add when
completing for the add sub-command).
* The ARGUMENT, describing which argument we are completing.
Normally this is either a string of the form argument-N, where N
is the number of the argument or it is a string of the form
option-OPT-N when completing the N'th argument of the option OPT.
* The TAG. Tags are used to discriminate between the types of
matches a completion function can generate in a certain context.
As an example, the context name
:completion::complete:dvips:option-o-1:files
says that normal completion was attempted on an argument of the dvips
command (more precisely: completion was attempted on the first argument
after the -o option) and the completion function will generate
filenames for this context.
In many of the possible contexts the completion system can generate
matches, often multiple types of matches. These types are represented
as simple names called `tags'. The completion system will decide
internally what sort of tags are allowed; a list of the standard
possibilities is given below. To determine in which order the tags are
to be used by the completion function, the `tag-order' style for the
appropriate context may be set, as described in the list of standard
styles below. Only those types of matches whose tags were selected by
this style will be produced, and in the order given, although the
default is to try all relevant tags in an order determined by the
particular completion in use.
The _complete_help bindable command described in Note: Bindable
Commands can be invoked to find out the context and tag names and
styles used at a particular point in completion. It shows the list of
contexts and tags that would be used in if completion were tried at the
current cursor position. Hence one can easily find out all the
information needed to change the behaviour of the tag-order style for a
particular context.
Completion behaviour can be modified by various other styles defined
with the zstyle builtin command (Note: The zsh/zutil Module). When
looking up styles the completion system uses full context names,
including the tag.
Styles determine such things as how the matches are generated; some of
them correspond to shell options (for example, the use of menu
completion), but styles provide more specific control. They can have
any number of strings as their value. Looking up the value of a style
therefore consists of two things: the context, which may be matched as
a pattern, and the name of the style itself, which must be given
exactly.
For example, many completion functions can generate matches in a simple
and a verbose form and use the verbose style to decide which form
should be used. To make all such functions use the verbose form, put
zstyle ':completion:*' verbose yes
in one of the startup files like .zshrc; this sort of style can also be
configured with the compinstall function. This definition simply means
that the verbose style has yes as its value in every context inside the
completion system. If the context pattern were `*', the verbose style
would have this value anywhere the style mechanism is used, not just in
completion.
As a more specific example, the completion function for the kill
builtin command uses the verbose style to decide if jobs and processes
are listed only as job numbers and process identifiers or if they are
listed with the full job texts and the command lines of the processes
(the latter is achieved by calling the ps command). To make this
builtin list the matches only as numbers one could call:
zstyle ':completion:*:*:kill:*' verbose no
Furthermore, if one wanted to see the command lines for processes but
not the job texts one could use the fact that the context name contains
the tag name when styles are looked up. As the function for the kill
builtin command uses the tags jobs and processes, we can use:
zstyle ':completion:*:*:kill:*:jobs' verbose no
To have more control over when certain values for styles are used one
can use the special parameters available in completion widgets (see
Note: Completion Widgets)) and the -e option to zstyle that makes the
value be evaluated when looked up. For example, to make the completer
style have a different value when completing for the cvs command, one
could use the words special array:
zstyle -e ':completion:*' completer '
if [[ $words[1] = cvs ]]; then
reply=(_complete)
else
reply=(_complete _approximate)
fi'
One should be careful not to use too complicated code with this option,
at least for the styles that are looked up quite often. These are
basically those that define some global completion behaviour but allow
that to be different for all matches or groups of matches (such as the
menu and list-rows-first styles). Alternatively one can always use a
less general pattern for the context than in the example above and use
a second call to zstyle with a generic pattern and without using the -e
option to define the default behaviour.
Note that the order in which styles are _defined_ does not matter; the
style mechanism uses the most specific possible match for a particular
style to determine the set of values. More precisely, strings are
preferred over patterns (for example, `:completion::complete:foo' is
more specific than `:completion::complete:*'), and longer patterns are
preferred over shorter patterns.
As with tags, completion functions can use any style they choose, so
there can't be a complete list. However, the following two sections
list those tags and styles that are used in many places of the
completion system.
Standard Tags
-------------
Here are the tags currently used by the completion system. Some of them
are only used when looking up styles and do not refer to a particular
type of match.
accounts
used to look up the users-hosts style
all-expansions
used by the _expand completer when adding the single string
containing all possible expansions
all-files
for the names of all files (as distinct from a particular subset,
see the globbed-files tag).
arguments
when an argument of a command may be completed
arrays
for names of array parameters
association-keys
for keys of associative arrays; used when completing inside a
subscript of a parameter of this type
bookmarks
when completing bookmarks (e.g. for URLs and the zftp function
suite)
builtins
for names of builtin commands
characters
used for commands like stty when completing characters; also used
when completing character classes after an opening bracket
colormapids
for X colormap ids
colors
for color names
commands
for names of external commands and names of sub-commands (used by
some commands like cvs)
contexts
for contexts used by the zstyle builtin command
corrections
used by the _approximate and _correct completers for the possible
corrections
cursors
for cursor names used by X programs
default
used to look up default values for various styles that may also be
set for tags that are used when generating matches; note that this
tag is used when only the FUNCTION field of the context name is
set up
descriptions
used when looking up the value of the format style for descriptions
devices
for names of device special files
directories
for names of directories
directory-stack
for entries in the directory stack
displays
for X display names
domains
for network domains
expansions
used by the _expand completer for individual possibilities
resulting from expansion of a word
extensions
for X server extensions
file-descriptors
for the numbers of open file descriptors
files
the generic file-matching tag used by completion functions that can
complete the names of some kind of file
fonts
used for X font names
functions
names of functions, normally shell functions although certain
commands may understand other kinds of function
globbed-files
for names of files matching the glob pattern used by completion
functions that expect a certain type of file
groups
used when completing names of user groups
history-words
for words from the history
hosts
for hostnames
indexes
used for array indexes
jobs
used for jobs
keymaps
for names of zsh keymaps
keysyms
for names of X keysyms
libraries
for names of system libraries
limits
for system limits
local-directories
for names of directories which are subdirectories of the current
working directory when completing for the cd and related builtin
commands
manuals
for names of manual pages
maps
for map names (e.g. NIS maps)
messages
used to look up the format style for messages
modifiers
for names of X modifiers
modules
for modules (e.g. zsh modules)
my-accounts
used to look up the users-hosts style
named-directories
for named directories (you wouldn't have guessed that, would you?)
names
for all kinds of names
nicknames
for nicknames of NIS maps
options
for command options
original
used by the _approximate, _correct and _expand completers when
adding the original string
other-accounts
used to look up the users-hosts style
packages
for packages (e.g. rpm or installed Debian packages)
parameters
for names of parameters
path-directories
for names of directories found by searching the cdpath array when
completing for the cd and related builtin commands
paths
used to look up the values of the expand, ambiguous and
special-dirs styles
pods
for perl pods (documentation files)
ports
for communication ports
prefixes
for prefixes (like those of a URL)
printers
for printer names
processes
for process identifiers
processes-names
used to look up the command style when generating the names of
processes for killall
sequences
for sequences (e.g. mh sequences)
sessions
for sessions in the zftp function suite
signals
for signal names
strings
for strings (e.g. the replacement strings for the cd builtin
command)
styles
for styles used by the zstyle builtin command
tags
for tags (e.g. rpm tags)
targets
for makefile targets
types
for types of whatever (e.g. address types for the xhost command)
urls
used to look up the urls and local styles when completing URLs
users
for usernames
values
when completing a value out of a set of values (or a list of such
values)
version
used by _call_program to look up the command to run to determine
the installed version of various other commands (such as diff and
make).
warnings
used to look up the format style for warnings
widgets
for zsh widget names
windows
for IDs of X windows
zsh-options
for shell options
Standard Styles
---------------
Here are the names of the styles used by the completion system. Note
that the values of several of these styles represent boolean values;
here, any of the strings `true', `on', `yes', and `1' can be used for
the truth value `true' and the strings `false', `off', `no', and `0' are
interpreted as `false'. The behavior for any other value is undefined
unless the description for the particular style mentions other possible
values; in particular, the default value may be either on or off if the
style is not set.
Some of these styles are tested for every tag used to add possible
matches and for the default tag (most notably menu, list-colors and the
styles controlling the completion listing like list-packed and
last-prompt). When tested for the default tag, only the FUNCTION field
of the context will be set up, so the default value will normally be
set like:
zstyle ':completion:*:default' menu ...
accept-exact
This is tested for the default tag and the tags used when
generating matches. If it is set to `true' for at least one match
which is the same as the string on the line, this match will
immediately be accepted.
When completing pathnames (where it is looked up for the paths
tag), this style also accepts any number of patterns as the value.
If this is used, pathnames matching one of these patterns will be
accepted immediately even if the command line contains some more
partially typed pathname components and these match no file under
the directory accepted.
Note that this is also used by the _expand completer to decide if
words beginning with a tilde or parameter expansion should be
expanded. This means that if, for example, there are parameters
foo and foobar, the string `$foo' will only be expanded if
accept-exact is set to `true'.
add-space
This style is used by the _expand completer. If it is `true' (the
default), a space will be inserted after all words resulting from
the expansion (except for directory names which get a slash). The
value may also be the string `file' to make the completer add a
space only to names of existing files. Finally, the `true' values
and `file' may be combined with `subst' to keep the completer from
adding a space when the resulting words were generated by
expanding a substitution of the form `$(...)' or `${...}'.
It is also used by the _prefix completer as a simple boolean value
to decide if a space should be inserted before the suffix.
ambiguous
This applies when completing non-final components of filename
paths. If it is set, the cursor is left after the first ambiguous
component, even if menu completion is in use. It is tested with
the paths tag.
assign-list
When completing after an equals sign, the completion system
normally completes only one filename. In some cases, particularly
for certain parameters such as PATH, a list of filenames separated
by colons is required. This style can be set to a list of
patterns matching the names of such parameters.
The default is to complete lists when the word on the line already
contains a colon.
auto-description
If set, this style's value will be used as the description for
options which are not described by the completion functions, but
that have exactly one argument. The sequence `%d' in the value
will be replaced by the description for this argument. Depending
on personal preferences, it may be useful to set this style to
something like `specify: %d'. Note that this may not work for
some commands.
avoid-completer
This is used by the _all_matches completer to decide if the string
consisting of all matches should be added to the list currently
being generated. Its value is a list of names of completers. If
any of these is the name of the completer that generated the
matches in this completion, the string will not be added.
The default value for this style is `_expand _old_list _correct
_approximate', i.e. it contains the completers for which a string
with all matches will almost never be wanted.
cache-path
This style defines the path where any cache files containing dumped
completion data are stored. Defaults to `$ZDOTDIR/.zcompcache', or
`$HOME/.zcompcache' if $ZDOTDIR is not defined. The completion
layer will not be used unless the use-cache style is set.
call-command
Currently this is only used by the function completing make
targets. If it is set to `true' and the installed version of the
make command allows it, make is called in a way to generate all
possible targets. The default value of this style is `false'
because calling make can potentially take a very long time and in
some cases may even cause actions from the makefile be executed
despite the options given to make.
command
In many places, completion functions need to call external
commands to generate the list of completions. This style can be
used to override the command which is called in some such cases.
The elements of the value are joined with spaces to form a command
line to execute. The value can also start with a hyphen, in which
case the usual command will be added to the end; this is most
useful for putting `builtin' or `command' in front to make sure
the appropriate version of a command is called, for example to
avoid calling a shell function with the same name as an external
command.
As an example, the function generating process IDs as matches uses
this style with the processes tag to generate the IDs to complete
and the list of processes to display (if the verbose style is
`true'). The list produced by the command should look like the
output of the ps command. The first line is not displayed, but is
searched for the string `PID' (or `pid') to find the position of
the process IDs in the following lines. If the line does not
contain `PID', the first numbers in each of the other lines are
taken as the process IDs to complete.
Note that the completion function generally has to call the command
every time it is called. Because of that care should be taken to
specify only commands that take a short time to run (and that will
eventually stop at all).
commands
This is used by the function completing sub-commands for the system
initialisation scripts (residing in /etc/init.d or somewhere not
too far away from that). It's values give the default commands to
complete for those commands for which the completion function isn't
able to find them out automatically. The default for this style
are the two strings `start' and `stop'.
complete
This is used by the _expand_alias function when invoked as a
bindable command. If it set to `true' and the word on the command
line is not the name of an alias, matching alias names will be
completed.
completer
The strings given as the value of this style provide the names of
the completer functions to use. The available completer functions
are described in Note: Control Functions.
Each string may be the name of a completer function or a string of
the form `FUNCTION:NAME'. In the first case the COMPLETER field of
the context will contain the name of the completer without the
leading underscore and with all other underscores replaced by
hyphens. In the second case the FUNCTION is the name of the
completer to call, but the context will contain the NAME in the
COMPLETER field of the context. If the NAME starts with a hyphen,
the string for the context will be build from the name of the
completer function as in the first case with the NAME appended to
it. For example:
zstyle ':completion:*' completer _complete _complete:-foo
Here, completion will call the _complete completer twice, once
using `complete' and once using `complete-foo' in the COMPLETER
field of the context. Normally, using the same completer more
than once makes only sense when used with the `FUNCTIONS:NAME'
form, because otherwise the context name will be the same in all
calls to the completer; possible exceptions to this rule are the
_ignored and _prefix completers.
The default value for this style is _complete _ignored, i.e.
normally only completion will be done, first using the
ignored-patterns style and the $fignore array and then without
ignoring matches.
condition
This style is used by the _list completer function to decide if
insertion of matches should be delayed unconditionally. The
default is `true'.
disabled
If this is set to `true', the _expand_alias completer and bindable
command will try to expand disabled aliases, too. The default is
`false'.
disable-stat
This is used with an empty tag by the function completing for the
cvs command to decide if the zsh/stat module should be used to
generate names of modified files in the appropriate places (this
is its only use). If set, completion will use the ls command.
domains
If set, gives the names of network domains that should be
completed. If this is not set by the user domain names will be
taken from the file /etc/resolv.conf.
expand
This style is used when completing strings consisting of multiple
parts, such as path names. If one of its values is the string
`prefix', the partially typed word from the line will be expanded
as far as possible even if trailing parts cannot be completed. If
one of its values is the string `suffix', matching names for
components after the first ambiguous one will also be added. This
means that the resulting string is the longest unambiguous string
possible, but if menu completion is started on the list of matches
generated this way, this will also cycle through the names of the
files in pathname components after the first ambiguous one.
fake-files
This style is used when completing files and looked up without a
tag. Its values are of the form `DIR:NAMES...'. This will add
the NAMES (strings separated by spaces) as possible matches when
completing in the directory DIR, even if no such files really
exist.
This can be useful on systems that support special filesystems
whose top-level pathnames can not be listed or generated with glob
patterns. It can also be used for directories for which one does
not have read permission.
fake-parameters
This is used by the completion function generating parameter names
as matches. Its values are names of parameters which might not
yet be set, but which should be completed nonetheless. Each name
may also be followed by a colon and a string specifying the type
of the parameter (like `scalar', `array' or `integer'). If such a
type is given, the name will only be completed if parameters of
that type are requested in the particular context. Names for
which no type is specified will always be completed.
file-patterns
In most places where filenames are completed, the function _files
is used which can be configured with this style. If the style is
unset, _files offers, one after another, up to three tags:
`globbed-files', `directories' and `all-files', depending on the
types of files expected by the caller of _files.
If the file-patterns style is set, the default tags are not used.
Instead, the value of the style says which tags and which patterns
are to be offered. The strings in the value contain
specifications of the form `PATTERN:TAG'; each string may contain
any number of such specifications. The PATTERN gives a glob
pattern that is to be used to generate filenames. If it contains
the sequence `%p', that is replaced by the pattern(s) given by the
calling function. Colons in the pattern must be preceded by a
backslash to make them distinguishable from the colon before the
TAG. If more than one pattern is needed, the patterns can be
given inside braces, separated by commas. The TAGs of all strings
in the value will be offered by _files (again, one after another)
and used when looking up other styles. For strings containing
more than one specification, the filenames for all specifications
will be generated at the same try. If no `:TAG' is given the
`files' tag will be used. The TAG may also be followed by an
optional second colon and a description. If that is given, this
description will be used for the `%d' in the value of the format
style (if that is set) instead of the default description supplied
by the completion function. If the description given here
contains itself a `%d', that is replaced with the description
supplied by the completion function.
For example, to make the rm command first complete only names of
object files and the names of all files if no object file matches
the string on the line, one would do:
zstyle ':completion:*:*:rm:*' file-patterns \
'*.o:object-files' '%p:all-files'
Another interesting example is to change the default behaviour that
makes completion first offer files matching the patterns given by
the calling function, then directories and then all files. Many
people prefer to get both the files matching the given patterns
and the directories in the first try and all files at the second
try. To achieve this, one could do:
zstyle ':completion:*' file-patterns \
'%p:globbed-files *(-/):directories' '*:all-files'
This works even for contexts in which all files would be completed,
because _files will not try a pattern more than once and it stops
when the pattern `*' was tried.
Note also that during the execution of completion functions, the
EXTENDED_GLOB option is in effect, so the characters `#', `~' and
`^' have special meanings in the patterns.
file-sort
The completion function that generates filenames as possible
matches uses this style without a tag to determine in which order
the names should be listed and completed when using menu
completion. The value may be one of `size' to sort them by the
size of the file, `links' to sort them by the number of links to
the file, `modification' (or `time' or `date') to sort them by the
last modification time, `access' to sort them by the last access
time, or `inode' (or `change') to sort them by the last inode
change time. If the style is set to any other value, or is unset,
files will be sorted alphabetically by name. If the value
contains the string `reverse', sorting is done in decreasing order.
force-list
This forces a list of completions to be shown at any point where
listing is done, even in cases where the list would usually be
suppressed. For example, normally the list is only shown if there
are at least two different matches. By setting this style to
`always', the list will always be shown, even if there is only a
single match which is immediately accepted. The style may also be
set to a number. In this case the list will be shown if there are
at least that many matches, even if they would all insert the same
string.
This style is tested for the default tag and all tags used when
generating matches. This allows one to turn unconditional listing
on for certain types of matches.
format
If this is set for the descriptions tag, its value is used as a
string to display above matches in completion lists. The sequence
`%d' in this string will be replaced with a short description of
what these matches are. This string may also contain the
sequences to specify output attributes, such as `%B', `%S' and
`%{...%}'.
For the same purpose, this style is also tested with the tags used
when matches are generated before it is tested for the descriptions
tag. This provides the possibility of defining different format
strings for different types of matches.
Note also that some completer functions define additional
`%'-sequences. These are described for the completer functions
that make use of them.
For the messages tag, this style defines a string used by some
completion functions to display messages. Here, the `%d' is
replaced with a message given by the completion function.
Finally, when set with the warnings tag, the format string is
printed when no matches could be generated at all. In this case
the `%d' is replaced with the descriptions for the matches that
were expected separated by spaces and the sequence `%D' is
replaced with those descriptions separated by newlines.
The `%' for the sequences that are replaced by strings provided by
the completion functions like the `%d' may be followed by field
width specifications as described for the zformat builtin command
from the zsh/zutil module, see Note: The zsh/zutil Module.
glob
This is used by the _expand completer. If it is set to `true'
(the default), globbing will be attempted on the words resulting
from substitution (see the substitute style) or the original
string from the line.
global
If this is set to `true' (the default), the _expand_alias
completer and bindable command will try to expand global aliases.
group-name
The completion system can put different types of matches in
different groups which are then displayed separately in the list
of possible completions. This style can be used to give the names
for these groups for particular tags. For example, in command
position the completion system generates names of builtin and
external commands, names of aliases, shell functions and
parameters and reserved words as possible completions. To have
the external commands and shell functions listed separately, one
can set:
zstyle ':completion:*:*:-command-:*:commands' group-name commands
zstyle ':completion:*:*:-command-:*:functions' group-name functions
This also means that if the same name is used for different types
of matches, then those matches will be displayed together in the
same group.
If the name given is the empty string, then the name of the tag for
the matches will be used as the name of the group. So, to have all
different types of matches displayed separately, one can just set:
zstyle ':completion:*' group-name ''
All matches for which no group name is defined will be put in a
group named -default-.
group-order
This style is to be used together with the group-name style. Once
different types of matches are put into different groups, this
style can be used to define in which order these groups should
appear when listing (compare tag-order, which determines which
completions appear at all). The strings in the value are taken as
group names and the named groups will be shown in the order in
which their names appear in the value. All groups whose names are
not given in the value of this style will appear in the order
defined by the function generating the matches.
For example, to have names of builtin commands, shell functions and
external commands appear in this order when completing in command
position one would set:
zstyle ':completion:*:*:-command-:*' group-order \
builtins functions commands
groups
A style holding the names of the groups that should be completed.
If this is not set by the user, the group names from the YP
database or the file `/etc/group' will be used.
hidden
If this is set to one of the `true' values, the matches for the
tags for which this is set will not appear in the list; only the
description for the matches as set with the format style will be
shown. If this is set to `all', not even the description will be
displayed.
Note that the matches will still be completed; they are just not
shown in the list. To avoid having matches considered as possible
completions at all, the tag-order style can be modified as
described below.
hosts
A style holding the names of hosts that should be completed. If
this is not set by the user the hostnames in `/etc/hosts' will be
used.
hosts-ports
This style is used by commands that need or accept hostnames and
ports. The strings in the value should be of the form
`HOST:PORT'. These hostnames and ports are completed depending on
the information already on the line, so that if, for example, the
hostname is already typed, only those ports specified for that
host will be completed. Multiple ports for the same host may
appear.
ignore-line
This style is tested for the tags used when generating matches.
If it is set to `true', then none of the words that are already on
the line will be considered possible completions. If it is set to
`current', the word the cursor is on will not be considered a
possible completion. The same happens if the value is
`current-shown', but only if the list of completions is currently
shown on the screen. Finally, if it is set to `other' all words
except the current one will not be considered to be a possible
completion.
The values `current' and `current-shown' are a bit like the
opposite of accept-exact. They mean that only strings with missing
characters will be completed.
Note that you almost certainly don't want to set this to `true' or
`other' for a general context such as `:completion:*'. This is
because it would disallow completion of, for example, options
multiple times even if the command in question accepts the option
more than once.
ignore-parents
The style is tested by the function completing pathnames without a
tag to determine whether to ignore the names of directories
already mentioned in the current word, or the name of the current
working directory. The value must include one or both of the
following strings:
parent
The name of any directory whose path is already contained in
the word on the line is ignored. For example, when
completing after foo/../, the directory foo will not be
considered a valid completion.
pwd
The name of the current working directory will not be
completed, so that, for example, completion after ../ will
not use the name of the current directory.
In addition, the value may include one or both of:
..
Ignore the specified directories only when the word on the
line contains the substring `../'.
directory
Ignore only when names of directories are completed, not when
completing names of files.
Note that names of directories ignored because of one of the tests
will be ignored in the same way as the matches ignored because of
the ignored-patterns style. I.e., by using the _ignored completer
it is possible to complete these directories nonetheless.
ignored-patterns
This style can be used to specify a list of patterns which are
tested against against the trial completions in a given context;
any matching completions will be removed from the list of
possibilities. The _ignored completer can appear in the list of
completers to produce a list which includes these matches once
more. This is a more configurable version of the shell parameter
$fignore.
Note that during the execution of completion functions, the
EXTENDED_GLOB option is in effect, so the characters `#', `~' and
`^' have special meanings in the patterns.
insert-ids
When completing process IDs, for example as arguments to the kill
and wait builtins, completion allows the user to type the name of a
command, which will be converted to the appropriate process ID. A
problem arises when the process name typed is not unique. By
default (or if this style is set explicitly to `menu') the name
will be converted immediately to a set of possible IDs, and menu
completion will be started to cycle through them. If the value of
the style is `single', however, the shell will wait until the user
has typed enough to make the command unique before converting the
name to an ID; the user must type any additional characters
required. If the value is any other string, menu completion will
be started when the string typed by the user is longer than the
common prefix of the corresponding IDs.
insert-tab
If this has one of the `true' values, the completion system will
insert a TAB character (assuming it was used to start completion)
instead of performing completion when there is no non-blank
character to the left of the cursor. If set to `false',
completion will be done even there.
The value may also contain the substrings `pending' or
`pending=VAL' to make the character typed to start completion be
inserted instead of completion being tried when there is input
pending which has not yet been processed by the shell. If a VAL is
given, completion will not be done if there are at least that many
characters of unprocessed input. This is often useful to have set
when pasting characters into a terminal. Note however, that it
relies on the $PENDING special parameter from the zsh/zle module
being set properly which is not guaranteed on all platforms.
The default value of this style is `true' unless when completing
inside the vared builtin command, where it defaults to `false'.
insert-unambiguous
This is used by the _match and _approximate completer functions,
where the possible completions may not have a common prefix so
that menu completion is often the most useful may of choosing
completions. If the style is set to `true', the completer will
start menu completion only if no unambiguous string could be
generated that is at least as long as the original string typed by
the user. Note that the _approximate completer uses it after
setting the completer field in the context name to one of
correct-NUM or approximate-NUM, where NUM is the number of errors
that were accepted.
When used for the _match completer, the style may also be set to
the string `pattern'. This makes the pattern on the line be left
unchanged if it didn't match unambiguously.
keep-prefix
This style is used by the _expand completer. If it is `true', the
completer will try to keep a prefix containing a tilde or parameter
expansion. I.e., the string `~/f*' would be expanded to `~/foo'
instead of `/home/user/foo'. If the style is set to `changed'
(the default), the prefix will only be left unchanged if there
were other changes between the expanded words and the original
word from the command line. Any other value makes the prefix be
expanded unconditionally.
Note that with one of the `true' values, the _expand completer
returns if there is only one expansion and that is, after restoring
the original prefix, the same as the original word. This means
that other completers will be called immediately after _expand.
last-prompt
This is used to determine if the completion code should try to put
the cursor back onto the previous command line after showing a
completion listing (as for the ALWAYS_LAST_PROMPT option). As
with several other styles, it is tested for the default tag as
well as all the possible tags when generating matches. The cursor
will be moved back to the previous line if this style is `true'
for all types of matches added. Note also that this is
independent of the numeric argument, unlike the ALWAYS_LAST_PROMPT
option.
list
This style is used by the _history_complete_word bindable command.
If it is set to `true' it has no effect, but if it is set to
`false' the matches will not be listed, overriding the setting of
the options that control listing behaviour, especially AUTO_LIST.
Use the context prefix `:completion:history-words'.
list-colors
If the zsh/complist module is used, this style can be used to set
color specifications as with the ZLS_COLORS and ZLS_COLOURS
parameters, which will not be honored under this completion system
(see Note: The zsh/complist Module).
If this style is set for the default tag, the strings in the value
are taken as specifications that are to be used everywhere. If it
is set for other tags, the specifications are used only for
matches of the type described by the tag. For this to work best,
the group-name style must be set to an empty string. If the
group-name tag specifies other names for the groups the matches in
these groups can be colored by using these names together with the
`(group)...' syntax described for the ZLS_COLORS and ZLS_COLOURS
parameters and adding the specifications to the value for this
style with the default tag (although in most cases it should work
by setting this style for the appropriate tags).
It is possible to use the same specifications set up for the GNU
version of the ls command:
zstyle ':completion:*:default' list-colors ${(s.:.)LS_COLORS}
The default colors are the same as for the GNU ls command and can
be obtained by setting the style to an empty string (i.e. '').
list-packed
Like the list-colors style, this is tested with the default tag
and all tags used when generating matches. If it is set to `true'
for a tag, the matches added for it will be listed as if the
LIST_PACKED option were set. If it is set to `false', they are
listed normally.
list-prompt
If this style is set for the default tag, completion lists that
don't fit on the screen can be scrolled (see Note: The
zsh/complist Module). The value, if not the empty string, will
be displayed after every screenful and the shell will prompt for a
key press; if the style is set to the empty string, a default
prompt will be used. The value may contain the escape sequences
`%l' or `%L', which will be replaced by the number of the last line
displayed and the total number of lines; `%m' or `%M', which will
be replaced by the number of the last match shown and the total
number of matches; and `%p' and `%P', which will be replaced by
`Top' when at the beginning of the list, `Bottom' when at the end
and the position shown in percent of the total length otherwise.
In each of these cases the form with the uppercase letter is
replaced by a string of fixed width, padded to the right with
spaces. As in other prompt strings, the escape sequences `%S',
`%s', `%B', `%b', `%U', `%u', and `%{...%}' for entering and
leaving the display modes standout, bold and underline are also
available.
list-rows-first
This style is tested in the same way as the list-packed style and
determines if matches are to be listed in a rows-first fashion, as
for the LIST_ROWS_FIRST option.
list-suffixes
This style is used by the function used to complete filenames. If
completion is attempted on a string containing multiple partially
typed pathname components and this style is set to `true', all
components starting with the first one for which more than one
match could be generated will be shown.
local
This style is used by completion functions which generate URLs as
possible matches to add suitable matches when a URL points to a
local web server, that is, one whose files are available directly
on the local file system. Its value should consist of three
strings: a hostname, the path to the default web pages for the
server and the directory name used by a user placing web pages
within their home area. For example, completion after
`http://toast/~yousir/' will attempt to match the name `toast'
against the first argument to the style, and if successful will
look in the directory under ~yousir given by the third argument to
the style for possible completions.
match-original
This is used by the _match completer. If it is set to only,
_match will try to generate matches without inserting a `*' at the
cursor position. If set to any other non-empty value, it will
first try to generate matches without inserting the `*' and if
that yields no matches, it will try again with the `*' inserted.
If it is unset or set to the empty string, matching will only be
done with the `*' inserted.
matcher
This style is tested for tags used when generating matches. Its
value is used as an match specification additional to any given by
the matcher-list style which should be in the form described in
Note: Matching Control.
matcher-list
This style is used by the main completion function to retrieve
match specifications that are to be used everywhere. Its value
should be a list of such specifications. The completion system
will try them one after another for each completer selected. For
example, to first try simple completion and, if that generates no
matches, case-insensitive completion one would do:
zstyle ':completion:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}'
By default every specification replaces previous ones. If
specification is prefixed with +, it is added to the existing
list. This allows testing more general patterns without repeating
the whole list every time, as in:
zstyle ':completion:*' matcher-list '' '+m{a-Z}={A-Z}' '+m{A-Z}={a-z}'
The style allows even finer control by specifying a particular
completer, without the leading underscore, in the third field of
the completion context. For example, if one uses the completers
_complete and _prefix but wants to try case-insensitive completion
only when using the _complete completer, one would do:
zstyle ':completion:*' completer _complete _prefix
zstyle ':completion:*:complete:*' matcher-list \
'' 'm:{a-zA-Z}={A-Za-z}'
Note that the completer style allows user-defined names to be used
in the context instead of the name of the completer. This is
useful if, for example, one wants to try normal completion without
a match specification and with case-insensitive matching first,
correction if that doesn't generate any matches and partial-word
completion if that doesn't yield any matches either. In this case
one can give the _complete completer more than once in the
completer style and define different match specifications for each
occurrence, as in:
zstyle ':completion:*' completer _complete _correct _complete:foo
zstyle ':completion:*:complete:*' matcher-list \
'' 'm:{a-zA-Z}={A-Za-z}'
zstyle ':completion:*:foo:*' matcher-list \
'm:{a-zA-Z}={A-Za-z} r:|[-_./]=* r:|=*'
If the style is unset in any context no match specification is
applied; further, some completers such as _correct and
_approximate do not use the match specifications at all. However,
it is always safe to use the simple form for this style (as in the
first example above), since any completers which do not use match
specifications will only ever be called once, rather than once per
specification.
Since the specification-strings in this style have to be tried one
after another, it is a good idea to keep their number low. In
most cases one to three strings (each of which may, without to
large a performance hit, consist of more than one single match
specification) will give acceptable performance.
max-errors
This is used by the _approximate and _correct completer functions
to determine the maximum number of errors to allow. The completer
will try to generate completions by first allowing one error, then
two errors, and so on, until either a match or matches were found
or the maximum number of errors given by this style has been
reached.
If the value for this style contains the string `numeric', the
completer function will take any numeric argument as the maximum
number of errors allowed. For example, with
zstyle ':completion:*:approximate:::' max-errors 2 numeric
two errors are allowed if no numeric argument is given, but with a
numeric argument of six (as in `ESC-6 TAB'), up to six errors are
accepted. Hence with a value of `0 numeric', no correcting
completion will be attempted unless a numeric argument is given.
If the value contains the string `not-numeric', the completer will
_not_ try to generate corrected completions when given a numeric
argument, so in this case the number given should be greater than
zero. For example, `2 not-numeric' specifies that correcting
completion with two errors will usually be performed, but if a
numeric argument is given, correcting completion will not be
performed.
The default value for this style is `2 numeric'.
menu
If this is set to true in a given context, using any of the tags
defined for a given completion, menu completion will be used. The
tag `default' can be used to set the default value, but a specific
tag will take precedence. If none of the values found in this way
is true but at least one is set to `auto' the behaviour will be as
for the AUTO_MENU option. Finally, if one of the values is
explicitly set to false, menu completion will be turned off even
if it would otherwise be active (for example, with the
MENU_COMPLETE option).
Using the form `yes=NUM', where `yes' may be any of the true
values (`yes', `true', `on' and `1') turns on menu completion if
there at least NUM matches. Using this for one of the `false'
values (as in `no=10') makes menu completion _not_ be used if
there are NUM or more matches. Of course, this is only useful
when menu completion is normally used, e.g. by setting the
MENU_COMPLETE option. The `true' values may also be used in the
form `yes=long' to turn on menu completion if the list does not
fit onto the screen. This will start menu completion only if
normal completion was attempted, not when only the list of
possible completions was requested. To start menu completion even
then, the value `yes=long-list' can be used.
In addition to (or instead of) the above possibilities, the value
may contain the string `select', optionally followed by an equals
sign and a number. In this case menu selection (as defined by the
zsh/complist module) will be started. Without the optional
number, it will be started unconditionally and with a number it
will be started only if at least that many matches are generated;
if the values for more than one tag provide a number, the smallest
number is taken. Menu selection can be turned off explicitly by
defining a value containing the string `no-select'.
It is also possible to start menu selection only if the list of
matches does not fit on the screen by using the value
`select=long'. This will only start menu selection if the widget
invoked does completion, not simply listing as done by
delete-char-or-list; to start menu selection even here, use the
value `select=long-list'.
To turn on menu completion or menu selection when a certain number
of matches is generated _or_ the list of matches does not fit onto
the screen, both of `yes=' and `select=' can be given twice, once
with a number and once with `long' or `long-list'.
numbers
This is used with the jobs tag. If it is `true', the shell will
complete the job numbers instead of the shortest unambiguous
strings of the jobs' command lines. If the value is a number, job
numbers will only be used if that many words from the job
descriptions are required to resolve ambiguities. For example, if
the value is `1', strings will only be used if all jobs differ in
the first word on their command lines.
old-list
This is used by the _oldlist completer. If it is set to `always',
then standard widgets which perform listing will retain the
current list of matches, however they were generated; this can be
turned off explicitly with the value `never', giving the behaviour
without the _oldlist completer. If the style is unset, or any
other value, then the existing list of completions is displayed if
it is not already; otherwise, the standard completion list is
generated; this is the default behaviour of _oldlist. However, if
there is an old list and this style contains the name of the
completer function that generated the list, then the old list will
be used even if it was generated by a widget which does not do
listing.
For example, suppose you type ^Xc to use the _correct_word widget,
which generates a list of corrections for the word under the
cursor. Usually, typing ^D would generate a standard list of
completions for the word on the command line, and show that. With
_oldlist, it will instead show the list of corrections already
generated.
As another example consider the _match completer: with the
insert-unambiguous style set to `true' it inserts only a common
prefix string, if there is any. However, this may remove parts of
the original pattern, so that further completion could produce
more matches than on the first attempt. By using the _oldlist
completer and setting this style to _match, the list of matches
generated on the first attempt will be used again.
old-matches
This is used by the _all_matches completer to decide if an old
list of matches should be used if one exists. It may be set to
one of the `true' values or to the string `only' to use such a
list. If it is set to `only', _all_matches will only use an old
list and won't have any effect on the list of matches currently
being generated.
old-menu
This is used by the _oldlist completer. It controls how menu
completion behaves when a completion has already been inserted and
the user types a standard completion key type such as TAB. The
default behaviour of _oldlist is that menu completion always
continues with the existing list of completions. If this style is
set to `false', however, a new completion is started if the old
list was generated by a different completion command; this is the
behaviour without the _oldlist completer.
For example, suppose you type ^Xc to generate a list of
corrections, and menu completion is started in one of the usual
ways. Usually, or with this style set to false, typing TAB at
this point would start trying to complete the line as it now
appears. With _oldlist, it instead continues to cycle through the
list of corrections.
original
This is used by the _approximate and _correct completers to decide
if the original string should be added as one possible completion.
Normally, this is done only if there are at least two possible
corrections, but if this style is set to `true', it is always
added. Note that these completers use this style after setting
the completer field in the context name to correct-NUM or
approximate-NUM, where NUM is the number of errors that were
accepted.
packageset
This style is used when completing arguments of the Debian `dpkg'
program. It contains an override for the default package set for
a given context. For example,
zstyle ':completion:*:complete:dpkg:option--status-1:*' \
packageset avail
causes available packages, rather than only installed packages, to
be completed for `dpkg -status'.
path
The function that completes color names uses this style with the
colors tag. The value should be the pathname of a file containing
color names in the format of an X11 rgb.txt file. If the style is
not set but this file is found in one of various standard
locations it will be used as the default.
ports
A style holding the service names of ports to complete. If this is
not set by the user, the service names from `/etc/services' will
be used.
prefix-hidden
This is used when matches with a common prefix are added (e.g.
option names). If it is `true', this prefix will not be shown in
the list of matches.
The default value for this style is `false'.
prefix-needed
This, too, is used for matches with a common prefix. If it is set
to `true' this common prefix has to be typed by the user to
generate the matches. E.g. for options this means that the `-',
`+', or `--' has to be on the line to make option names be
completed at all.
The default value for this style is `true'.
preserve-prefix
This style is used when completing path names. Its value should
be a pattern matching an initial prefix of the word to complete
that should be left unchanged under all circumstances. For
example, on some Unices an initial `//' (double slash) has a
special meaning and hence should be kept. For that one could set
this style to the string `//'. As another example, setting this
style to `?:/' under Cygwin would allow completion after `a:/...'
and the like.
range
This is used by the _history completer and the
_history_complete_word bindable command to decide which words
should be completed. It may be set to a number, N, to say that
only the last N words from the history should be completed. The
value may also be of the form `MAX:SLICE'. This means that first
the last SLICE words will be completed. If that yields no
matches, the SLICE words before those will be tried and so on,
until either at least one match is generated or MAX words have
been tried. The default is to complete all words from the history
at once.
regular
This style is used by the _expand_alias completer and bindable
command. If set to `true' (the default), regular aliases will be
expanded but only in command position. If it is set to `false',
regular aliases will never be expanded and if it is set to the
string `always', regular aliases will be expanded even if not in
command position.
remove-all-dups
The _history_complete_word bindable command and the _history
completer use this to decide if all duplicate matches should be
removed, rather than just consecutive duplicates.
select-prompt
If this is set for the default tag, its value will be displayed
during menu selection (see the menu style above) when the
completion list does not fit on the screen as a whole. The same
escapes as for the list-prompt style are understood, but give the
number of the match or line the mark is on. A default prompt is
used when the value is the empty string.
select-scroll
This style is tested for the default tag and determines how a
completion list is scrolled during a menu selection (see the menu
style above) when the completion list does not fit on the screen
as a whole. Its value should be `0' (zero) to scroll by
half-screenfuls, a positive integer to scroll by that many lines
and a negative number to scroll by the number of lines of the
screen minus that number (or plus the number, since it is
negative). The default is to scroll by single lines.
separate-sections
This style is used with the manuals tag when completing names of
manual pages. If it is `true', entries for different sections are
added separately using tag names of the form `manual.X', where X
is the section number. This means that it is possible to make
pages from different sections be listed separately by setting the
group-name style. The default for this style is `false'.
single-ignored
This is used by the _ignored completer. It specifies what should
be done if it can generate only one match, which is often a
special case. If its value is `show', the single match will be
displayed but not inserted. If the value is `menu', then the
single match and the original string are both added as matches and
menu completion is started so that one can easily select either of
them.
sort
If set to `true', completion functions that generate words from the
history as possible matches sort these words alphabetically
instead of keeping them in the order in which they appear in the
history (from youngest to oldest).
This is also used by the _expand completer. Here, if it is set to
`true', the expansions generated will always be sorted. If it is
set to `menu', then the expansions are only sorted when they are
offered as single strings (not in the string containing all
possible expansions).
special-dirs
Normally, the completion code will not produce the directory names
`.' and `..' as possible completions. If this style is set to
`true', it will add both `.' and `..' as possible completions; if
it is set to `..', only `..' will be added.
squeeze-slashes
If set to `true', sequences of slashes (as in `foo//bar') will be
treated as if they were only one slash when completing pathnames.
This is the usual behaviour of UNIX paths. However, by default
the file completion function behaves as if there were a `*' between
the slashes.
stop
If set to `true', the _history_complete_word bindable command will
stop once when reaching the beginning or end of the history.
Invoking _history_complete_word will then wrap around to the
opposite end of the history. If this style is set to `false' (the
default), _history_complete_word will loop immediately as in a
menu completion.
subst-globs-only
This is used by the _expand completer. If it is set to `true',
the expansion will only be used if it resulted from globbing;
hence, if expansions resulted from the use of the substitute style
described below, but these were not further changed by globbing,
the expansions will be rejected.
The default for this style is `false'.
substitute
This boolean style controls whether the _expand completer will
first try to expand all substitutions in the string (such as
`$(...)' and `${...}').
The default is `true'.
suffix
This is used by the _expand completer if the word starts with a
tilde or contains a parameter expansion. If it is set to `true',
the word will only be expanded if it doesn't have a suffix, i.e.
if it is something like `~foo' or `$foo', but not if it is `~foo/'
or `$foo/bar', unless that suffix itself contains characters
eligible for expansion. The default for this style is `true'.
tag-order
This provides a mechanism for sorting how the tags available in a
particular context will be used.
The values for the style are sets of space-separated lists of tags.
The tags in each value will be tried at the same time; if no match
is found, the next value is used. (See the file-patterns style for
an exception to this behavior.)
For example:
zstyle ':completion:*:complete:-command-:*' tag-order \
'commands functions'
specifies that completion in command position should offer only
completions for external commands and shell functions immediately.
In addition to tag names, each string in the value may take one of
the following forms:
-
If any string in the value consists of only a hyphen, then
_only_ the tags specified by the other strings in the value
are generated. Normally all tags not explicitly selected are
tried last if the specified tags fail to generate any
matches. This means that a value consisting only of a single
hyphen turns off completion.
! TAGS...
A string starting with an exclamation mark specifies names of
tags that are _not_ to be used. The effect is the same as if
all other possible tags for the context had been listed.
TAG:LABEL ...
In strings not starting with an exclamation mark, it is also
possible to specify tag labels instead of only tags, where
TAG is one of the tags offered by the completion function for
the current context and LABEL is a name. For this, the
completion function will generate matches in the same way as
for the TAG but it will use the LABEL in place of the tag in
the context names used to look up styles. If the LABEL
starts with a hyphen, the TAG is prepended to the LABEL to
form the name used for lookup. This can be used to make the
completion system try a certain tag more than once, supplying
different style settings for each attempt, see below for an
example.
The LABEL may optionally be followed by a second colon and a
description. This description will then be used for the `%d'
in the value of the format style instead of the default
description supplied by the completion function. Spaces in
the description have to be quoted by preceding them with a
backslash and a `%d' appearing in the description is replaced
with the description given by the completion function.
In each of the cases above, the tag may also be a pattern or more
than one pattern inside braces and separated by commas. In this
case all of the offered tags matching the pattern(s) will be used
except for those that are given explicitly in the same string.
There are probably two main uses of this. One is the case where
one wants to try one of the tags more than once, setting other
styles differently for each try, but still wants to use all the
other tags without having to repeat them all. For example, to
make completion of function names in command position ignore all
the completion functions starting with an underscore the first
time completion is tried, one could do:
zstyle ':completion:*:*:-command-:*' tag-order \
'functions:-non-comp *' functions
zstyle ':completion:*:functions-non-comp' ignored-patterns '_*'
Here, the completion system will first try all tags offered, but
will use the tag label functions-non-comp when looking up styles
for the function names completed. For this, the ignored-patterns
style is set to exclude functions starting with an underscore from
the set of possible matches. If none of the generated matches
match the string on the line, the completion system will use the
second value of the tag-order style and complete functions names
again, but this time using the name functions to look up styles,
so that the ignored-patterns style is not used and all function
names are considered.
Of course, this can also be used to split the matches for one tag
into different groups. For example:
zstyle ':completion:*' tag-order \
'options:-long:long\ options
options:-short:short\ options
options:-single-letter:single\ letter\ options'
zstyle ':completion:*:options-long' ignored-patterns '[-+](|-|[^-]*)'
zstyle ':completion:*:options-short' ignored-patterns '--*' '[-+]?'
zstyle ':completion:*:options-single-letter' ignored-patterns '???*'
With the group-names style set, this makes options beginning with
`--', options beginning with a single `-' or `+' but containing
multiple characters, and single-letter options be displayed in
separate groups with different descriptions.
The second interesting use of patterns is the case where one wants
to try multiple match specifications one after another. The
matcher-list style offers something similar, but it is tested very
early in the completion system and hence can't be set for single
commands nor for more specific contexts. Here is how to try
normal completion without any match specification and, if that
generates no matches, try again with case-insensitive matching,
restricting the effect to arguments of the command foo:
zstyle ':completion:*:*:foo:*' tag-order '*' '*:-case'
zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}'
First, all the tags offered when completing after foo are tried
using the normal tag name. If that generates no matches, the
second value of tag-order is used, which tries all tags again
except that this time each has -case appended to its name for
lookup of styles. Hence this time the value for the matcher style
from the second call to zstyle in the example is used to make
completion case-insensitive.
Using the -e option of the zstyle builtin command, it is possible
to specify conditions saying when certain tags are to be used. For
example:
zstyle -e '*:-command-:*' tag-order '
if [[ -n $PREFIX ]]; then
reply=( )
else
reply=( - )
fi'
Makes completion in command position happen only if the string on
the line is not empty. This is tested using the PREFIX parameter
which is special in completion widgets; see Note: Completion
Widgets for a description of these special parameters. Setting
reply to an empty array ensures that only the default behaviour of
trying all tags at once is used and setting it to an array
containing only a hyphen disables that default behaviour - thus
keeping all tags from being tried.
If no style has been defined for a context, the strings
`(|*-)argument-* (|*-)option-* values' and `options' plus all tags
offered by the completion function will be used to provide a
sensible default behavior that causes arguments (whether normal
command arguments or arguments of options) to be completed before
option names for most commands.
urls
This is used together with the the urls tag by completion
functions that generate URLs as possible matches. If the value
consists of more than one string or if the only string does not
name a file or directory, the strings are used as the URLs to
complete.
If the value contains only one string and that is the name of a
normal file, the URLs are taken from that file (where the URLs may
be separated by white space or newlines).
Finally, if the only string in the value names a directory, that
should contain sub-directories named after the retrieval methods
which occur as the first part of a URL, i.e. `http', `ftp',
`bookmark', and so on. These sub-directories should contain files
and other sub-directories whose pathnames are possible completions
after the initial `http://', `ftp://', etc. See the description in
the file _urls in the User sub-directory of the completion system
for more information.
use-cache
If this is set, the completion caching layer is activated for any
completions which use it (via the _store_cache, _retrieve_cache,
and _cache_invalid functions). The directory containing the cache
files can be changed with the cache-path style.
use-compctl
If this style is set to a string _not_ equal to false, 0, no, and
off, the completion system may use any completion specifications
defined with the compctl builtin command. If the style is unset,
this is done only if the zsh/compctl module is loaded. The string
may also contain the substring `first' to make the definition for
`compctl -T' be used, and the substring `default' to make the one
for `compctl -D' be used.
Note that this is only intended to smooth the transition from
compctl to the new completion system and may disappear in the
future.
Note also that the definitions from compctl will only be used if
there is no specific completion function for the command in
question. For example, while completing arguments to the command
foo, if this was handled by a command function _foo, compctl would
never be tried, while if it was handled by _default, compctl would
be tried.
users
This may be set to a list of names that should be completed
whenever a username is needed. If it is not set or the string on
the line doesn't match any of the strings in this list, all
usernames will be completed.
users-hosts
The values of this style should be of the form `USER@HOST' or
`USER:HOST'. It is used for commands that need pairs of user- and
hostnames. For such commands, only the pairs from this style are
used and if, for example, the username is already typed, then only
the hostnames for which there is a pair with that username is
defined.
If set for the my-accounts tag, this is used for commands such as
rlogin and ssh; in this case the style should contain the names of
the user's own accounts on remote hosts. If set for the
other-accounts tag, it is used for commands such as talk and
finger and should contain other people's accounts. Finally, it
may also be used by some commands with the accounts tag.
users-hosts-ports
Like users-hosts but used for commands like telnet and containing
strings of the form `USER@HOST:PORT'.
verbose
This is used in several contexts to decide if only a simple or a
verbose list of matches should be generated. For example some
commands show descriptions for option names if this style is
`true'.
The default value for this style is `true'.
word
This is used by the _list completer, which prevents the insertion
of completions until a second completion attempt when the line has
not changed. The normal way of finding out if the line has
changed is to compare its entire contents between the two
occasions. If this style is true, the comparison is instead
performed only on the current word. Hence if completion is
performed on another word with the same contents, completion will
not be delayed.
automatically generated by info2www version 1.2.2.9