| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This describes the shell code for the new completion system. It consists of various shell functions; those beginning `comp' are to be called directly, while those beginning `_' are called by the completion code. The shell functions of the second set, which implement completion behaviour and may be bound to keystrokes, are referred to as `widgets'.
19.2 Initialization 19.3 Completion System Configuration 19.4 Control Functions 19.5 Bindable Commands 19.6 Utility Functions 19.7 Completion Directories
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
If the system was installed completely, it should be enough to call the shell function compinit from your initialization file; see the next section. However, the function compinstall can be run by a user to configure various aspects of the completion system.
Usually, compinstall will insert code into .zshrc, although if that is not writable it will save it in another file and tell you that file's location. Note that it is up to you to make sure that the lines added to .zshrc are actually run; you may, for example, need to move them to an earlier place in the file if .zshrc usually returns early. So long as you keep them all together (including the comment lines at the start and finish), you can rerun compinstall and it will correctly locate and modify these lines. Note, however, that any code you add to this section by hand is likely to be lost if you rerun compinstall, although lines using the command `zstyle' should be gracefully handled.
The new code will take effect next time you start the shell, or run .zshrc by hand; there is also an option to make them take effect immediately. However, if compinstall has removed definitions, you will need to restart the shell to see the changes.
To run compinstall you will need to make sure it is in a directory mentioned in your fpath parameter, which should already be the case if zsh was properly configured as long as your startup files do not remove the appropriate directories from fpath. Then it must be autoloaded (`autoload -U compinstall' is recommended). You can abort the installation any time you are being prompted for information, and your .zshrc will not be altered at all; changes only take place right at the end, where you are specifically asked for confirmation.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section describes the use of compinit to initialize completion for the current session when called directly; if you have run compinstall it will be called automatically from your .zshrc.
To initialize the system, the function compinit should be in a directory mentioned in the fpath parameter, and should be autoloaded (`autoload -U compinit' is recommended), and then run simply as `compinit'. This will define a few utility functions, arrange for all the necessary shell functions to be autoloaded, and will then re-define all widgets that do completion to use the new system. If you use the menu-select widget, which is part of the zsh/complist module, you should make sure that that module is loaded before the call to compinit so that that widget is also re-defined. If completion styles (see below) are set up to perform expansion as well as completion by default, and the TAB key is bound to expand-or-complete, compinit will rebind it to complete-word; this is necessary to use the correct form of expansion.
Should you need to use the original completion commands, you can still bind keys to the old widgets by putting a `.' in front of the widget name, e.g. `.expand-or-complete'.
To speed up the running of compinit, it can be made to produce a dumped configuration that will be read in on future invocations; this is the default, but can be turned off by calling compinit with the option -D. The dumped file is .zcompdump in the same directory as the startup files (i.e. $ZDOTDIR or $HOME); alternatively, an explicit file name can be given by `compinit -d dumpfile'. The next invocation of compinit will read the dumped file instead of performing a full initialization.
If the number of completion files changes, compinit will recognise this and produce a new dump file. However, if the name of a function or the arguments in the first line of a #compdef function (as described below) change, it is easiest to delete the dump file by hand so that compinit will re-create it the next time it is run. The check performed to see if there are new functions can be omitted by giving the option -C. In this case the dump file will only be created if there isn't one already.
The dumping is actually done by another function, compdump, but you will only need to run this yourself if you change the configuration (e.g. using compdef) and then want to dump the new one. The name of the old dumped file will be remembered for this purpose.
If the parameter _compdir is set, compinit uses it as a directory where completion functions can be found; this is only necessary if they are not already in the function search path.
For security reasons compinit also checks if the completion system would use files not owned by root or by the current user, or files in directories that are world- or group-writable or that are not owned by root or by the current user. If such files or directories are found, compinit will ask if the completion system should really be used. To avoid these tests and make all files found be used without asking, use the option -u, and to make compinit silently ignore all insecure files and directories use the option -i. This security check is skipped entirely when the -C option is given.
The security check can be retried at any time by running the function compaudit. This is the same check used by compinit, but when it is executed directly any changes to fpath are made local to the function so they do not persist. The directories to be checked may be passed as arguments; if none are given, compaudit uses fpath and _compdir to find completion system directories, adding missing ones to fpath as necessary. To force a check of exactly the directories currently named in fpath, set _compdir to an empty string before calling compaudit or compinit.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The convention for autoloaded functions used in completion is that they start with an underscore; as already mentioned, the fpath/FPATH parameter must contain the directory in which they are stored. If zsh was properly installed on your system, then fpath/FPATH automatically contains the required directories for the standard functions.
For incomplete installations, if compinit does not find enough files beginning with an underscore (fewer than twenty) in the search path, it will try to find more by adding the directory _compdir to the search path. If that directory has a subdirectory named Base, all subdirectories will be added to the path. Furthermore, if the subdirectory Base has a subdirectory named Core, compinit will add all subdirectories of the subdirectories is to the path: this allows the functions to be in the same format as in the zsh source distribution.
When compinit is run, it searches all such files accessible via fpath/FPATH and reads the first line of each of them. This line should contain one of the tags described below. Files whose first line does not start with one of these tags are not considered to be part of the completion system and will not be treated specially.
The tags are:
Each name may also be of the form `cmd=service'. When completing the command cmd, the function typically behaves as if the command (or special context) service was being completed instead. This provides a way of altering the behaviour of functions that can perform many different completions. It is implemented by setting the parameter $service when calling the function; the function may choose to interpret this how it wishes, and simpler functions will probably ignore it.
If the #compdef line contains one of the options -p or -P, the words following are taken to be patterns. The function will be called when completion is attempted for a command or context that matches one of the patterns. The options -p and -P are used to specify patterns to be tried before or after other completions respectively. Hence -P may be used to specify default actions.
The option -N is used after a list following -p or -P; it specifies that remaining words no longer define patterns. It is possible to toggle between the three options as many times as necessary.
When one of the key-sequences is typed, the function in the file will be invoked to generate the matches. Note that a key will not be re-bound if if it already was (that is, was bound to something other than undefined-key). The widget created has the same name as the file and can be bound to any other keys using bindkey as usual.
#compdef -K _foo_complete complete-word "^X^C" \ _foo_list list-choices "^X^D" |
(all on one line) defines a widget _foo_complete for completion, bound to `^X^C', and a widget _foo_list for listing, bound to `^X^D'.
The # is part of the tag name and no white space is allowed after it. The #compdef tags use the compdef function described below; the main difference is that the name of the function is supplied implicitly.
Note also that the functions for the completion system assume that the KSH_AUTOLOAD option is not set. They cannot be loaded if it is set. To avoid having to unset KSH_AUTOLOAD, you can instead use one or more zwc file(s) that have been created with the command zcompile -z to load the functions for the completion system; see 16. Shell Builtin Commands. This forces the functions to be autoloaded the way zsh normally loads functions.
The special contexts for which completion functions can be defined are:
Default implementations are supplied for each of these contexts. In most cases the context -context- is implemented by a corresponding function _context, for example the context `-tilde-' and the function `_tilde').
The contexts -redirect- and -value- allow extra context-specific information. (Internally, this is handled by the functions for each context calling the function _dispatch.) The extra information is added separated by commas.
For the -redirect- context, the extra information is in the form `-redirect-,op,command', where op is the redirection operator and command is the name of the command on the line. If there is no command on the line yet, the command field will be empty.
For the -value- context, the form is `-value-,name,command', where name is the name of the parameter. In the case of elements of an associative array, for example `assoc=(key <TAB>', name is expanded to `name-key'. In certain special contexts, such as completing after `make CFLAGS=', the command part gives the name of the command, here make; otherwise it is empty.
It is not necessary to define fully specific completions as the functions provided will try to generate completions by progressively replacing the elements with `-default-'. For example, when completing after `foo=<TAB>', _value will try the names `-value-,foo,' (note the empty command part), `-value-,foo,-default-' and`-value-,-default-,-default-', in that order, until it finds a function to handle the context.
As an example:
compdef '_files -g "*.log"' '-redirect-,2>,-default-' |
completes files matching `*.log' after `2> <TAB>' for any command with no more specific handler defined.
Also:
compdef _foo -value-,-default-,-default- |
specifies that _foo provides completions for the values of parameters for which no special function has been defined. This is usually handled by the function _value itself.
The same lookup rules are used when looking up styles (as described below); for example
zstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log' |
is another way to make completion after `2> <TAB>' complete files matching `*.log'.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following function is defined by compinit and may be called directly.
Alternatively, all the arguments may have the form `cmd=service'. Here service should already have been defined by `cmd1=service' lines in #compdef files, as described above. The argument for cmd will be completed in the same way as service.
The function argument may alternatively be a string containing any shell code. The string will be executed using the eval builtin command to generate completions. This provides a way of avoiding having to define a new completion function. For example, to complete files ending in `.h' as arguments to the command foo:
compdef '_files -g "*.h"' foo |
The option -n prevents any completions already defined for the command or context from being overwritten.
The option -d deletes any completion defined for the command or contexts listed.
The names may also contain -p, -P and -N options as described for the #compdef tag. The effect on the argument list is identical, switching between definitions of patterns tried initially, patterns tried finally, and normal commands and contexts.
The parameter $_compskip may be set by any function defined for a pattern context. If it is set to a value containing the substring `patterns' none of the pattern-functions will be called; if it is set to a value containing the substring `all', no other function will be called.
The form with -k defines a widget with the same name as the function that will be called for each of the key-sequences; this is like the #compdef -k tag. The function should generate the completions needed and will otherwise behave like the builtin widget whose name is given as the style argument. The widgets usable for this are: complete-word, delete-char-or-list, expand-or-complete, expand-or-complete-prefix, list-choices, menu-complete, menu-expand-or-complete, and reverse-menu-complete, as well as menu-select if the zsh/complist module is loaded. The option -n prevents the key being bound if it is already to bound to something other than undefined-key.
The form with -K is similar and defines multiple widgets based on the same function, each of which requires the set of three arguments name, style and key-sequences, where the latter two are as for -k and the first must be a unique widget name beginning with an underscore.
Wherever applicable, the -a option makes the function autoloadable, equivalent to autoload -U function.
The function compdef can be used to associate existing completion functions with new commands. For example,
compdef _pids foo |
uses the function _pids to complete process IDs for the command foo.
Note also the _gnu_generic function described below, which can be used to complete options for commands that understand the `--help' option.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When completion is attempted somewhere on the command line the completion system first works out the context. This takes account of a number of things including the command word (such as `grep' or `zsh') and options to which the current word may be an argument (such as the `-o' option to zsh which takes a shell option as an argument).
This context information is condensed into a string consisting of multiple fields separated by colons, referred to simply as `the context' in the remainder of the documentation. This is used to look up styles, context-sensitive options that can be used to configure the completion system. 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:
As an example, the context name
:completion::complete:dvips:option-o-1:files |
says that normal completion was attempted as the first argument to the option -o of the command dvips:
dvips -o ... |
and the completion function will generate filenames.
Each type of completion the system can perform in a given context is described by a `tag', a short descriptive string such as files in the example above. Any completion function may use any tag name it likes, but a list of the more common ones is given below.
Usually completion will be tried by all possible tags in an order given by the completion function. However, this can be altered by using the tag-order style. Completion is then restricted to the list of given tags in the given order.
The _complete_help bindable command shows all the contexts and tags available for completion at a particular point. This provides an easy way of finding information for tag-order and other styles. It is described in 19.5 Bindable Commands.
Styles determine such things as how the matches are generated, similarly to shell options but with much more control. They can have any number of strings as their value. They are defined with the zstyle builtin command (21.31 The zsh/zutil Module).
When looking up styles the completion system uses full context names, including the tag. 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 a startup file (probably .zshrc). This gives the verbose style the value yes in every context inside the completion system, unless that context has a more specific definition. It is best to avoid giving the context as `*' in case the style has some meaning outside the completion system.
Many such general purpose styles can be configured simply by using the compinstall function.
A more specific example of the use of the verbose style is by the completion for the kill builtin. If the style is set, the builtin lists full job texts and process command lines; otherwise it shows the bare job numbers and PIDs. To turn the style off for this use only:
zstyle ':completion:*:*:kill:*' verbose no |
For even more control, the style can use one of the tags `jobs' or `processes'. To turn off verbose display only for jobs:
zstyle ':completion:*:*:kill:*:jobs' verbose no |
The -e option to zstyle even allows completion function code to appear as the argument to a style; this requires some understanding of the internals of completion functions (see 18. Completion Widgets)). For example:
zstyle -e ':completion:*' completer '
if [[ $words[1] = cvs ]]; then
reply=(_complete)
else
reply=(_complete _approximate)
fi'
|
uses the value `_complete' for the completer style in most contexts, but the value `_complete _approximate' when the first word on the command line is `cvs'. This is probably more conveniently done by specifying the style for two different contexts. This form can be slow and should be avoided for commonly examined styles such as menu and list-rows-first.
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.
Style names like those of tags are arbitrary and depend on the completion function. However, the following two sections list some of the most common tags and styles.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Some of the following are only used when looking up particular styles and do not refer to a type of match.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Note that the values of several of these styles represent boolean values. Any of the strings `true', `on', `yes', and `1' can be used for the value `true' and any of the strings `false', `off', `no', and `0' for the value `false'. The behavior for any other value is undefined except where explicitly mentioned. The default value may be either true or false if the style is not set.
Some of these styles are tested first for every possible tag corresponding to a type of match, and if no style was found, for the default tag. The most notable styles of this type are menu, list-colors and styles controlling completion listing such as list-packed and last-prompt). When tested for the default tag, only the function field of the context will be set so that a style using the default tag will normally be defined along the lines of:
zstyle ':completion:*:default' menu ... |
When completing pathnames (where the tag used is `paths') this style accepts any number of patterns as the value in addition to the boolean values. 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.
This style is also used by the _expand completer to decide if words beginning with a tilde or parameter expansion should be expanded. For example, if there are parameters foo and foobar, the string `$foo' will only be expanded if accept-exact is set to `true'; otherwise the completion system will be allowed to complete $foo to $foobar. If the style is set to `continue', _expand will add the expansion as a match and the completion system will also be allowed to continue.
The _prefix completer uses this style as a simple boolean value to decide if a space should be inserted before the suffix.
The default is to complete lists when the word on the line already contains a colon.
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.
As an example, the completion function for process IDs 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 specified command for each attempt to generate the completion list. Hence care should be taken to specify only commands that take a short time to run, and in particular to avoid any that may never terminate.
Each string may be either 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 user-defined 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 only makes 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': only completion will be done, first using the ignored-patterns style and the $fignore array and then without ignoring matches.
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. However, menu completion can be used to cycle through all matches.
It is important to use a sufficiently restrictive context when specifying fake strings. Note that the styles fake-files and fake-parameters provide additional features when completing files or parameters.
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.
The file-patterns style provides alternatives to the default tags, which are not used. Its value consists of elements of the form `pattern:tag'; each string may contain any number of such specifications separated by spaces.
The pattern is a pattern that is to be used to generate filenames. Any occurrence of the sequence `%p' is replaced by any pattern(s) passed by the function calling _files. 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 and used when looking up other styles. Any tags in the same word will be offered at the same time and before later words. 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, which 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 then the names of all files if there is no matching object file:
zstyle ':completion:*:*:rm:*' file-patterns \
'*.o:object-files' '%p:all-files'
|
To alter the default behaviour of file completion -- offer files matching a pattern and directories on the first attempt, then all files --- to offer only matching files on the first attempt, then directories, and finally all files:
zstyle ':completion:*' file-patterns \
'%p:globbed-files' '*(-/):directories' '*:all-files'
|
This works even where there is no special pattern: _files matches all files using the pattern `*' at the first step and stops when it sees this pattern. Note also it will never try a pattern more than once for a single completion attempt.
During the execution of completion functions, the EXTENDED_GLOB option is in effect, so the characters `#', `~' and `^' have special meanings in the patterns.
This style is tested for the default tag as well as for each tag valid for the current completion. Hence the listing can be forced only for certain types of match.
The style is tested with each tag valid for the current completion before it is tested for the descriptions tag. Hence different format strings can be defined for different types of match.
Note also that some completer functions define additional `%'-sequences. These are described for the completer functions that make use of them.
Some completion functions display messages that may be customised by setting this style for the messages tag. Here, the `%d' is replaced with a message given by the completion function.
Finally, the format string is looked up with the warnings tag, for use 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. The sequence `%D' is replaced with the same descriptions separated by newlines.
It is possible to use printf-style field width specifiers with `%d' and similar escape sequences. This is handled by the zformat builtin command from the zsh/zutil module, see 21.31 The zsh/zutil Module.
zstyle ':completion:*:*:-command-:*:commands' group-name commands zstyle ':completion:*:*:-command-:*:functions' group-name functions |
As a consequence, any match with the same tag will be displayed in the same group.
If the name given is the empty string 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-.
For example, to have names of builtin commands, shell functions and external commands appear in that order when completing in command position:
zstyle ':completion:*:*:-command-:*' group-order \
builtins functions commands
|
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.
The values `current' and `current-shown' are a bit like the opposite of the accept-exact style: 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.
In addition, the value may include one or both of:
Excluded values act in a similar fashion to values of the ignored-patterns style, so they can be restored to consideration by the _ignored completer.
Note that the EXTENDED_GLOB option is set during the execution of completion functions, so the characters `#', `~' and `^' have special meanings in the patterns.
If the value of the style is `single', the shell will wait until the user has typed enough to make the command unique before converting the name to an ID; attempts at completion will be unsuccessful until that point. 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 to the corresponding IDs.
The value may also contain the substrings `pending' or `pending=val'. In this case, the typed character will be inserted instead of staring completion when there is unprocessed input pending. 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 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' except for completion within vared builtin command where it is `false'.
In the case of the _approximate completer, the completer field in the context will already have been set to one of correct-num or approximate-num, where num is the number of errors that were accepted.
In the case of the _match completer, the style may also be set to the string `pattern'. Then the pattern on the line is left unchanged if it does not match unambiguously.
The behaviour of expand when this style is true is to cause _expand to give up when a single expansion with the restored prefix is the same as the original; hence any remaining completers may be called.
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.
In addition to setting styles for specific tags, it is also possible to use group names specified explicitly by the group-name tag together with the `(group)' syntax allowed by the ZLS_COLORS and ZLS_COLOURS parameters and simply using the default tag.
It is possible to use any color specifications already 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. ").
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', the number of the last match shown and the total number of matches; and `%p' and `%P', `Top' when at the beginning of the list, `Bottom' when at the end and the position shown as a percentage of the total length otherwise. In each case the form with the uppercase letter will be replaced by a string of fixed width, padded to the right with spaces, while the lowercase form will be replaced by a variable width string. As in other prompt strings, the escape sequences `%S', `%s', `%B', `%b', `%U', `%u' for entering and leaving the display modes standout, bold and underline are also available, as is the form `%{...%}' for enclosing escape sequences which display with zero width.
For example:
zstyle ':completion:*' local toast \
/var/http/public/toast public_html
|
Completion after `http://toast/stuff/' will look for files in the directory /var/http/public/toast/stuff, while completion after `http://toast/~yousir/' will look for files in the directory ~yousir/public_html.
zstyle ':completion:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}'
|
By default each specification replaces the previous one; however, if a specification is prefixed with +, it is added to the existing list. Hence it is possible to create increasingly general specifications without repetition:
zstyle ':completion:*' matcher-list '' '+m{a-Z}={A-Z}' '+m{A-Z}={a-z}'
|
It is possible to create match specifications valid for particular completers by using the third field of the context. For example, to use the completers _complete and _prefix but only allow case-insensitive completion with _complete:
zstyle ':completion:*' completer _complete _prefix
zstyle ':completion:*:complete:*' matcher-list \
'' 'm:{a-zA-Z}={A-Za-z}'
|
User-defined names, as explained for the completer style, are available. This makes it possible to try the same completer more than once with different match specifications each time. For example, to try normal completion without a match specification, then normal completion with case-insensitive matching, then correction, and finally partial-word completion:
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. Note also that some completers such as _correct and _approximate do not use the match specifications at all, though these completers will only ever called once even if the matcher-list contains more than one element.
Where multiple specifications are useful, note that the entire completion is done for each element of matcher-list, which can quickly reduce the shell's performance. As a rough rule of thumb, one to three strings will give acceptable performance. On the other hand, putting multiple space-separated values into the same string does not have an appreciable impact on performance.
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'.
This has the most impact when several matches have the same description and so will be grouped together. Increasing the style will allow more matches to be grouped together; decreasing it will allow more of the description to be visible.
If none of the values found in this way is true but at least one is set to `auto', the shell behaves as if the AUTO_MENU option is set.
If one of the values is explicitly set to false, menu completion will be explicitly turned off, overriding the MENU_COMPLETE option and other settings.
In the form `yes=num', where `yes' may be any of the true values (`yes', `true', `on' and `1'), menu completion will be turned on if there are at least num matches. In the form `yes=long', menu completion will be turned on if the list does not fit on the screen. This does not activate menu completion if the widget normally only lists completions, but menu completion can be activated in that case with the value `yes=long-list' (Typically, the value `select=long-list' described later is more useful as it provides control over scrolling.)
Similarly, with any of the `false' values (as in `no=10'), menu completion will not be used if there are num or more matches.
The value of this widget also controls menu selection, as implemented by the zsh/complist module. The following values may appear either alongside or instead of the values above.
If the value contains the string `select', menu selection will be started unconditionally.
In the form `select=num', menu selection will only be started if there are at least num matches. 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'. To start menu selection even if the current widget only performs listing, use the value `select=long-list'.
To turn on menu completion or menu selection when a there are a certain number of matches or the list of matches does not fit on the screen, both of `yes=' and `select=' may be given twice, once with a number and once with `long' or `long-list'.
Finally, it is possible to activate two special modes of menu selection. The word `interactive' in the value causes interactive mode to be entered immediately when menu selection is started; see 21.6 The zsh/complist Module for a description of interactive mode. Including the string `search' does the same for incremental search mode. To select backward incremental search, include the string `search-backward'. )
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.
If this style is set it is generally unwise to call the _all_matches completer unconditionally. One possible use is for either this style or the completer style to be defined with the -e option to zstyle to make the style conditional.
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.
zstyle ':completion:*:complete:dpkg:option--status-1:*' \
packageset avail
|
causes available packages, rather than only installed packages, to be completed for `dpkg --status'.
The default value for this style is `false'.
The default value for this style is `true'.
If it is a singe number, only the last N words from the history will be completed.
If it is a range of the form `max:slice', the last slice words will be completed; then if that yields no matches, the slice words before those will be tried and so on. This process stops either when at least one match was been found, or max words have been tried.
The default is to complete all words from the history at once.
It is not always possible to know if connections are in fact to a remote site, so some may be prevented unnecessarily.
The style is tested first against the full context including the tag, and if that fails to produce a value against the context without the tag.
If the calling widget explicitly requests unsorted matches, this is usually honoured. However, the default (unsorted) behaviour of completion for the command history may be overridden by setting the style to true.
In the _expand completer, 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 but not in the string containing all possible expansions.
The following example sets special-dirs to `..' when the current prefix is empty, is a single `.', or consists only of a path beginning with `../'. Otherwise the value is `false'.
zstyle -e ':completion:*' special-dirs \ '[[ $PREFIX = (../)#(|.|..) ]] && reply=(..)' |
The default for this style is `false'.
The default is `true'.
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 first offers external commands and shell functions. Remaining tags will be tried if no completions are found.
In addition to tag names, each string in the value may take one of the following forms:
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.
In any of the forms above the tag may be a pattern or several patterns in the form `{pat1,pat2...}'. In this case all matching tags will be used except for any given explicitly in the same string.
One use of these features is to try one tag more than once, setting other styles differently on each attempt, but still 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:
zstyle ':completion:*:*:-command-:*' tag-order \
'functions:-non-comp *' functions
zstyle ':completion:*:functions-non-comp' ignored-patterns '_*'
|
On the first attempt, all tags will be offered but the functions tag will be replaced by functions-non-comp. The ignored-patterns style is set for this tag to exclude functions starting with an underscore. If there are no matches, the second value of the tag-order style is used which completes functions using the default tag, this time presumably including all function names.
The matches for one tag can be split 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, options beginning with `--', options beginning with a single `-' or `+' but containing multiple characters, and single-letter options will be displayed in separate groups with different descriptions.
Another use of patterns is 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.
It is possible to use the -e option of the zstyle builtin command to specify conditions for the use of particular tags. For example:
zstyle -e '*:-command-:*' tag-order '
if [[ -n $PREFIX$SUFFIX ]]; then
reply=( )
else
reply=( - )
fi'
|
Completion in command position will be attempted only if the string typed so far is not empty. This is tested using the PREFIX special parameter; see 18. Completion Widgets for a description of parameters which are special inside completion widgets. Setting reply to an empty array provides the default behaviour of trying all tags at once; setting it to an array containing only a hyphen disables the use of all tags and hence of all completions.
If no tag-order 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.
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 which 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, the directory hierarchy rooted at this directory gives the completions. The top level directory should be the file access method, such as `http', `ftp', `bookmark' and so on. In many cases the next level of directories will be a filename. The directory hierarchy can descend as deep as necessary.
For example,
zstyle ':completion:*' urls ~/.urls mkdir -p ~/.urls/ftp/ftp.zsh.org/pub/development |
allows completion of all the components of the URL ftp://ftp.zsh.org/pub/development after suitable commands such as `netscape' or `lynx'. Note, however, that access methods and files are completed separately, so if the hosts style is set hosts can be completed without reference to the urls style.
See the description in the function _urls itself for more information (e.g. `more $^fpath/_urls(N)').
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, if there is a function _foo to complete arguments to the command foo, compctl will never be invoked for foo. However, the compctl version will be tried if foo only uses default completion.
Currently this is only used in completions for `make', but it may be extended depending on authorial frustration.
It is possible to group values for sets of commands which allow a remote login, such as rlogin and ssh, by using the my-accounts tag. Similarly, values for sets of commands which usually refer to the accounts of other people, such as talk and finger, can be grouped by using the other-accounts tag. More ambivalent commands may use the accounts tag.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The initialization script compinit redefines all the widgets which perform completion to call the supplied widget function _main_complete. This function acts as a wrapper calling the so-called `completer' functions that generate matches. If _main_complete is called with arguments, these are taken as the names of completer functions to be called in the order given. If no arguments are given, the set of functions to try is taken from the completer style. For example, to use normal completion and correction if that doesn't generate any matches:
zstyle ':completion:*' completer _complete _correct |
after calling compinit. The default value for this style is `_complete _ignored', i.e. normally only ordinary completion is tried, first with the effect of the ignored-patterns style and then without it. The _main_complete function uses the return value of the completer functions to decide if other completers should be called. If the return value is zero, no other completers are tried and the _main_complete function returns.
If the first argument to _main_complete is a single hyphen, the arguments will not be taken as names of completers. Instead, the second argument gives a name to use in the completer field of the context and the other arguments give a command name and arguments to call to generate the matches.
The following completer functions are contained in the distribution, although users may write their own. Note that in contexts the leading underscore is stripped, for example basic completion is performed in the context `:completion::complete:...'.
It may be useful to use the _generic function described below to bind _all_matches to its own keystroke, for example:
zle -C all-matches complete-word _generic bindkey '^Xa' all-matches zstyle ':completion:all-matches:*' old-matches only zstyle ':completion:all-matches::::' completer _all_matches |