(zsh.info.gz) Initialization
Info Catalog
(zsh.info.gz) Completion System
(zsh.info.gz) Completion System Configuration
20.2 Initialization
===================
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.
20.2.1 Use of compinit
----------------------
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.
The function bashcompinit provides compatibility with bash's
programmable completion system. When run it will define the functions,
compgen and complete which correspond to the bash builtins with the same
names. It will then be possible to use completion specifications and
functions written for bash.
20.2.2 Autoloaded files
-----------------------
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:
#compdef NAMES... [ -[pP] PATTERNS... [ -N NAMES... ] ]
The file will be made autoloadable and the function defined in it
will be called when completing NAMES, each of which is either the
name of a command whose arguments are to be completed or one of a
number of special contexts in the form -CONTEXT- described below.
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.
#compdef -k STYLE KEY-SEQUENCES...
This option creates a widget behaving like the builtin widget STYLE
and binds it to the given KEY-SEQUENCES, if any. The STYLE must be
one of the builtin widgets that perform completion, namely
complete-word, delete-char-or-list, expand-or-complete,
expand-or-complete-prefix, list-choices, menu-complete,
menu-expand-or-complete, or reverse-menu-complete. If the
zsh/complist module is loaded (see The zsh/complist Module)
the widget menu-select is also available.
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 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 WIDGET-NAME STYLE KEY-SEQUENCES ...
This is similar to -k except that only one KEY-SEQUENCES argument
may be given for each WIDGET-NAME STYLE pair. However, the entire
set of three arguments may be repeated with a different set of
arguments. Note in particular that the WIDGET-NAME must be
distinct in each set. If it does not begin with '_' this will be
added. The WIDGET-NAME should not clash with the name of any
existing widget: names based on the name of the function are most
useful. For example,
#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'.
#autoload [ OPTIONS ]
Functions with the #autoload tag are marked for autoloading but are
not otherwise treated specially. Typically they are to be called
from within one of the completion functions. Any OPTIONS supplied
will be passed to the autoload builtin; a typical use is +X to
force the function to be loaded immediately. Note that the -U and
-z flags are always added implicitly.
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.
The special contexts for which completion functions can be defined are:
-array-value-
The right hand side of an array-assignment ('foo=(...)')
-brace-parameter-
The name of a parameter expansion within braces ('${...}')
-assign-parameter-
The name of a parameter in an assignment, i.e. on the left hand
side of an '='
-command-
A word in command position
-condition-
A word inside a condition ('[[...]]')
-default-
Any word for which no other completion is defined
-equal-
A word beginning with an equals sign
-first-
This is tried before any other completion function. The function
called may set the _compskip parameter to one of various values:
all: no further completion is attempted; a string containing the
substring patterns: no pattern completion functions will be called;
a string containing default: the function for the '-default-'
context will not be called, but functions defined for commands will
-math-
Inside mathematical contexts, such as '((...))'
-parameter-
The name of a parameter expansion ('$...')
-redirect-
The word after a redirection operator.
-subscript-
The contents of a parameter subscript.
-tilde-
After an initial tilde ('~'), but before the first slash in the
word.
-value-
On the right hand side of an assignment.
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'.
20.2.3 Functions
----------------
The following function is defined by compinit and may be called
directly.
compdef [ -ane ] FUNCTION NAMES... [ -[pP] PATTERNS... [ -N NAMES... ] ]
compdef -d NAMES...
compdef -k [ -an ] FUNCTION STYLE KEY-SEQUENCES...
compdef -K [ -an ] FUNCTION NAME STYLE KEY-SEQUENCES ...
The first form defines the FUNCTION to call for completion in the
given contexts as described for the #compdef tag above.
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
almost any shell code. If the string contains an equal sign, the
above will take precedence. The option -e may be used to specify
the first argument is to be evaluated as shell code even if it
contains an equal sign. 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.
Info Catalog
(zsh.info.gz) Completion System
(zsh.info.gz) Completion System Configuration
automatically generated by
info2html