GNU Info
(zsh.info)Initialization
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.
Use of compinit
---------------
This section describes the use of compinit to initialize completion for
the current session when run directly by the user; 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 which will be read in on future invocations; this is the
default, although it 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'. On the next call to
compinit, it 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.
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...
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
for the _complete function.
Each NAME may also be of the form `CMD=SERVICE'. This is used by
functions that offer multiple services, i.e. different completion
behaviour for multiple commands. Such a string makes the
completion system call the function when completing arguments for
the command `cmd', setting the parameter $service to the string
`service'. The function can then use that parameter to decide
what to complete.
#compdef -p PATTERN
The file will be made autoloadable and the function defined in it
will be called when completing for a command whose name matches
the given PATTERN (a standard globbing pattern). Note that only
one PATTERN may be given.
#compdef -P PATTERN
Like the previous one, but the function will be called only if no
completion function for the command on the line could be found.
#compdef -k STYLE KEY-SEQUENCES...
This can be used to bind special completion functions to the
KEY-SEQUENCES specified. It creates a widget behaving like the
builtin widget STYLE, which must be one of those 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 Note: The zsh/complist
Module), the same happens to the menu-select widget.
The widget is then bound to all the KEY-SEQUENCES given, if any:
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 WIDGET-NAME STYLE KEY-SEQUENCES ...
This is similar to -k, with the same STYLE and KEY-SEQUENCES
arguments, preceded by a string giving the name of a widget. In
this case only one KEY-SEQUENCES argument may be given, but the
entire set of three arguments may be repeated with a different set
of arguments. In particular, the WIDGET-NAME must be distinct in
each set. It should begin with `_', else one will be added, and
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 ]
This is used for files defining utility functions that are not to
be called directly as completion functions but should be loaded
automatically when invoked. Typically they are to be called from
within one of the completion functions.
The OPTIONS will be given to the autoload builtin command when
making the function autoloaded. Most often, this will be +X to
force the function to be loaded immediately. Note that the -U
flag is always implicitly added.
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 and cannot be loaded when it is set. To
avoid having to unset KSH_AUTOLOAD, you can instead use one or more zwc
file(s) which have been created with the command zcompile -z to load
the functions for the completion system; see Note: Shell Builtin
Commands. This forces the functions to be autoloaded the way zsh
normally loads functions.
Functions
---------
The compinit file defines the following function, which may also be
called directly by the user.
compdef [ -an ] FUNCTION NAMES...
compdef -d NAMES...
compdef -p [ -a ] FUNCTION PATTERN
compdef -P [ -a ] FUNCTION PATTERN
compdef -k [ -an ] FUNCTION STYLE KEY-SEQUENCES...
compdef -K [ -an ] FUNCTION NAME STYLE KEY-SEQUENCES ...
The first form tells the completion system to call the given
FUNCTION when completing for the contexts or commands whose NAMES
are given: this is like the #compdef tag unless the first word
contains an equal sign. In this case all words have to be of the
form `CMD=SERVICE' where SERVICE is the name of a command or of a
service defined by an autoloaded function with the #compdef tag
and an argument of the form `CMD=SERVICE'. This kind of use makes
the arguments of the CMDs be completed as those for the SERVICES.
If the -n option is given, any existing completion behaviour for
particular contexts or commands will not be altered. These
definitions can be deleted by giving the -d option as in the
second form.
The form with -p is similar to the first, but FUNCTION will be
called for all commands whose name matches the PATTERN; this is
like the #compdef -p function tag.
The form with -P is like the third, but the FUNCTION will be
called only if no function for the command itself was found or if
one was found and it set the _compskip parameter to a value _not_
containing the substring patterns.
The form with -k defines a widget with the same name as the
FUNCTION which 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.
In each of the forms supporting it the -a option makes the
FUNCTION autoloadable (exactly equivalent to autoload -U FUNCTION).
The compdef function is the place to turn to when one wants to define
what the completion system should complete for a certain command. The
function named can of course be one of the functions supplied or one
written by the user. For example, if one has a command foo that gets
process identifiers as arguments, one could do:
compdef _pids foo
using the _pids function from the distribution to generate the process
identifiers. Not also the _gnu_generic function described below, which
can be used to complete options for commands that understand the
`--help' option.
automatically generated by info2www version 1.2.2.9