diff options
Diffstat (limited to 'Doc/zshcompsys.1')
| -rw-r--r-- | Doc/zshcompsys.1 | 5788 |
1 files changed, 5788 insertions, 0 deletions
diff --git a/Doc/zshcompsys.1 b/Doc/zshcompsys.1 new file mode 100644 index 000000000..9402b51f1 --- /dev/null +++ b/Doc/zshcompsys.1 @@ -0,0 +1,5788 @@ +.TH "ZSHCOMPSYS" "1" "May 14, 2022" "zsh 5\&.9" +.SH "NAME" +zshcompsys \- zsh completion system +.\" Yodl file: Zsh/compsys.yo +.SH "DESCRIPTION" +.PP +This describes the shell code for the `new\&' completion system, referred +to as \fBcompsys\fP\&. It is written in shell functions based on the +features described in +\fIzshcompwid\fP(1)\&. +.PP +The features are contextual, sensitive to the point at which completion is +started\&. Many completions are already provided\&. +For this reason, a user can perform a great many tasks without +knowing any details beyond how to initialize the system, which is +described +below in INITIALIZATION\&. +.PP +The context that decides what completion is to be performed may be +.PD 0 +.TP +.PD +\(bu +an argument or option position: these describe the position on the +command line at which completion is requested\&. For example `first argument +to rmdir, the word being completed names a directory\&'; + +.TP +\(bu +a special context, denoting an element in the shell\&'s syntax\&. For example +`a word in command position\&' or `an array subscript'\&. + +.PP +A full context specification contains other elements, as we shall describe\&. +.PP +Besides commands names and contexts, the system employs two more +concepts, \fIstyles\fP and \fItags\fP\&. These provide ways for the user +to configure the system\&'s behaviour\&. +.PP +Tags play a dual role\&. They serve as a classification system for +the matches, typically indicating a class of object that the user +may need to distinguish\&. For example, when completing arguments of the +\fBls\fP command the user may prefer to try \fBfiles\fP before \fBdirectories\fP, +so both of these are tags\&. They also appear as the rightmost +element in a context specification\&. +.PP +Styles modify various operations of the completion system, such as +output formatting, but also what kinds of completers are used (and in +what order), or which tags are examined\&. Styles may accept arguments +and are manipulated using the \fBzstyle\fP command described in +\fIzshmodules\fP(1)\&. +.PP +In summary, tags describe \fIwhat\fP the completion objects are, and style +\fBhow\fP they are to be completed\&. At various points of execution, the +completion system checks what styles and/or tags are defined for the +current context, and uses that to modify its behavior\&. The full +description of context handling, which determines how tags and other +elements of the context influence the behaviour of styles, is described +below in COMPLETION SYSTEM CONFIGURATION\&. +.PP +When a completion is requested, a dispatcher function is called; +see the description of \fB_main_complete\fP in the list of control functions +below\&. This dispatcher decides which function should +be called to produce the completions, and calls it\&. The result is +passed to one or more \fIcompleters\fP, functions that implement +individual completion strategies: simple completion, error correction, +completion with error correction, menu selection, etc\&. +.PP +More generally, the shell functions contained in the completion system are +of two types: +.PD 0 +.TP +.PD +\(bu +those beginning `\fBcomp\fP\&' are to be called directly; there are only +a few of these; + +.TP +\(bu +those beginning `\fB_\fP\&' are called by the +completion code\&. The shell functions of this set, which implement +completion behaviour and may be bound to keystrokes, are referred to +as `widgets\&'\&. These proliferate as new completions are required\&. + +.PP +.PP +.SH "INITIALIZATION" +.PP +If the system was installed completely, it should be enough to +call the shell function \fBcompinit\fP from your initialization file; see the +next section\&. However, the function \fBcompinstall\fP can be run by a user +to configure various aspects of the completion system\&. +.PP +Usually, \fBcompinstall\fP will insert code into \fB\&.zshrc\fP, 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 \fB\&.zshrc\fP are actually run; you may, for example, need to move +them to an earlier place in the file if \fB\&.zshrc\fP usually returns early\&. +So long as you keep them all together (including the comment lines at the +start and finish), you can rerun \fBcompinstall\fP 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 \fBcompinstall\fP, +although lines using the command `\fBzstyle\fP\&' should be gracefully handled\&. +.PP +The new code will take effect next time you start the shell, or run +\fB\&.zshrc\fP by hand; there is also an option to make them take effect +immediately\&. However, if \fBcompinstall\fP has removed definitions, you will +need to restart the shell to see the changes\&. +.PP +To run \fBcompinstall\fP you will need to make sure it is in a directory +mentioned in your \fBfpath\fP 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 \fBfpath\fP\&. Then it must be autoloaded +(`\fBautoload \-U compinstall\fP\&' is recommended)\&. You can abort the +installation any time you are being prompted for information, and your +\fB\&.zshrc\fP will not be altered at all; changes only take place right at the +end, where you are specifically asked for confirmation\&. +.PP +.SS "Use of compinit" +.PP +This section describes the use of \fBcompinit\fP to initialize completion for +the current session when called directly; if you have run +\fBcompinstall\fP it will be called automatically from your \fB\&.zshrc\fP\&. +.PP +To initialize the system, the function \fBcompinit\fP should be in a +directory mentioned in the \fBfpath\fP parameter, and should be autoloaded +(`\fBautoload \-U compinit\fP\&' is recommended), and then run simply as +`\fBcompinit\fP\&'\&. 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 \fBmenu\-select\fP widget, which is part of the +\fBzsh/complist\fP module, you should make sure that that module is loaded +before the call to \fBcompinit\fP 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 +\fBexpand\-or\-complete\fP, \fBcompinit\fP will rebind it to \fBcomplete\-word\fP; +this is necessary to use the correct form of expansion\&. +.PP +Should you need to use the original completion commands, you can still +bind keys to the old widgets by putting a `\fB\&.\fP\&' in front of the +widget name, e\&.g\&. `\fB\&.expand\-or\-complete\fP\&'\&. +.PP +To speed up the running of \fBcompinit\fP, 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 \fBcompinit\fP with the +option \fB\-D\fP\&. The dumped file is \fB\&.zcompdump\fP in the same +directory as the startup files (i\&.e\&. \fB$ZDOTDIR\fP or \fB$HOME\fP); +alternatively, an explicit file name can be given by `\fBcompinit \-d\fP +\fIdumpfile\fP\&'\&. The next invocation of \fBcompinit\fP will read the dumped +file instead of performing a full initialization\&. +.PP +If the number of completion files changes, \fBcompinit\fP 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 \fB#compdef\fP function (as described below) +change, it is easiest to delete the dump file by hand so that +\fBcompinit\fP 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 \fB\-C\fP\&. In this case the dump file will only be created if +there isn\&'t one already\&. +.PP +The dumping is actually done by another function, \fBcompdump\fP, but you +will only need to run this yourself if you change the configuration +(e\&.g\&. using \fBcompdef\fP) and then want to dump the new one\&. The name of +the old dumped file will be remembered for this purpose\&. +.PP +If the parameter \fB_compdir\fP is set, \fBcompinit\fP 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\&. +.PP +For security reasons \fBcompinit\fP 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, +\fBcompinit\fP 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 \fB\-u\fP, and to make \fBcompinit\fP silently ignore all insecure files +and directories use the option \fB\-i\fP\&. This security check is skipped +entirely when the \fB\-C\fP option is given, provided the dumpfile exists\&. +.PP +The security check can be retried at any time by running the function +\fBcompaudit\fP\&. This is the same check used by \fBcompinit\fP, but when it +is executed directly any changes to \fBfpath\fP 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, \fBcompaudit\fP uses \fBfpath\fP and +\fB_compdir\fP to find completion system directories, adding missing ones +to \fBfpath\fP as necessary\&. To force a check of exactly the directories +currently named in \fBfpath\fP, set \fB_compdir\fP to an empty string before +calling \fBcompaudit\fP or \fBcompinit\fP\&. +.PP +The function \fBbashcompinit\fP provides compatibility with bash\&'s programmable +completion system\&. When run it will define the functions, \fBcompgen\fP and +\fBcomplete\fP which correspond to the bash builtins with the same names\&. +It will then be possible to use completion specifications and functions +written for bash\&. +.PP +.SS "Autoloaded files" +.PP +The convention for autoloaded functions used in completion is that they +start with an underscore; as already mentioned, the \fBfpath/FPATH\fP +parameter must contain the directory in which they are stored\&. If \fBzsh\fP +was properly installed on your system, then \fBfpath/FPATH\fP automatically +contains the required directories for the standard functions\&. +.PP +For incomplete installations, if \fBcompinit\fP 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 \fB_compdir\fP to the search +path\&. If that directory has a subdirectory named \fBBase\fP, all +subdirectories will be added to the path\&. Furthermore, if the subdirectory +\fBBase\fP has a subdirectory named \fBCore\fP, \fBcompinit\fP will add all +subdirectories of the subdirectories to the path: this allows +the functions to be in the same format as in the \fBzsh\fP source +distribution\&. +.PP +When \fBcompinit\fP is run, it searches all such files accessible via +\fBfpath/FPATH\fP 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\&. +.PP +The tags are: +.PP +.PD 0 +.TP +.PD +\fB#compdef\fP \fIname\fP \&.\&.\&. [ \fB\-\fP{\fBp\fP|\fBP\fP} \fIpattern\fP \&.\&.\&. [ \fB\-N\fP \fIname\fP \&.\&.\&. ] ] +The file will be made autoloadable and the function defined +in it will be called when completing \fIname\fPs, 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 \fB\-\fP\fIcontext\fP\fB\-\fP described +below\&. +.RS +.PP +Each \fIname\fP may also be of the form `\fIcmd\fP\fB=\fP\fIservice\fP\&'\&. +When completing the command \fIcmd\fP, the function typically behaves as +if the command (or special context) \fIservice\fP 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 \fB$service\fP when calling the function; +the function may choose to interpret this how it wishes, and simpler +functions will probably ignore it\&. +.PP +If the \fB#compdef\fP line contains one of the options \fB\-p\fP or \fB\-P\fP, +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 \fB\-p\fP and \fB\-P\fP are used to specify +patterns to be tried before or after other completions respectively\&. +Hence \fB\-P\fP may be used to specify default actions\&. +.PP +The option \fB\-N\fP is used after a list following \fB\-p\fP or \fB\-P\fP; it +specifies that remaining words no longer define patterns\&. It is +possible to toggle between the three options as many times as necessary\&. +.RE +.TP +\fB#compdef \-k\fP \fIstyle key\-sequence\fP \&.\&.\&. +This option creates a widget behaving like the +builtin widget \fIstyle\fP and binds it to the given \fIkey\-sequence\fPs, +if any\&. The \fIstyle\fP must be one of the builtin widgets that perform +completion, namely \fBcomplete\-word\fP, \fBdelete\-char\-or\-list\fP, +\fBexpand\-or\-complete\fP, \fBexpand\-or\-complete\-prefix\fP, \fBlist\-choices\fP, +\fBmenu\-complete\fP, \fBmenu\-expand\-or\-complete\fP, or +\fBreverse\-menu\-complete\fP\&. If the \fBzsh/complist\fP module is loaded (see +\fIzshmodules\fP(1)) the widget \fBmenu\-select\fP is also available\&. +.RS +.PP +When one of the \fIkey\-sequence\fPs 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 +\fBundefined\-key\fP)\&. The widget created has the same name as the file and +can be bound to any other keys using \fBbindkey\fP as usual\&. +.RE +.TP +\fB#compdef \-K\fP \fIwidget\-name\fP \fIstyle\fP \fIkey\-sequence\fP [ \fIname\fP \fIstyle\fP \fIseq\fP \&.\&.\&. ] +This is similar to \fB\-k\fP except that only one \fIkey\-sequence\fP +argument may be given for each \fIwidget\-name\fP \fIstyle\fP pair\&. +However, the entire set of three arguments may be repeated with a +different set of arguments\&. Note in particular that the +\fIwidget\-name\fP must be distinct in each set\&. If it does not begin with +`\fB_\fP\&' this will be added\&. The \fIwidget\-name\fP should not clash with +the name of any existing widget: names based on the name of the function +are most useful\&. For example, +.RS +.PP +.RS +.nf +\fB#compdef \-K _foo_complete complete\-word "^X^C" \e + _foo_list list\-choices "^X^D"\fP +.fi +.RE +.PP +(all on one line) defines a widget \fB_foo_complete\fP for completion, bound +to `\fB^X^C\fP\&', and a widget \fB_foo_list\fP for listing, bound to `\fB^X^D\fP'\&. +.RE +.TP +\fB#autoload\fP [ \fIoptions\fP ] +Functions with the \fB#autoload\fP 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 \fIoptions\fP supplied +will be passed to the \fBautoload\fP builtin; a typical use is \fB+X\fP to +force the function to be loaded immediately\&. Note that the \fB\-U\fP and +\fB\-z\fP flags are always added implicitly\&. +.PP +The \fB#\fP is part of the tag name and no white space is allowed after it\&. +The \fB#compdef\fP tags use the \fBcompdef\fP function described below; the +main difference is that the name of the function is supplied implicitly\&. +.PP +The special contexts for which completion functions can be defined are: +.PP +.PD 0 +.TP +.PD +\fB\-array\-value\-\fP +The right hand side of an array\-assignment +(`\fIname\fP\fB=(\fP\fI\&.\&.\&.\fP\fB)\fP\&') +.TP +\fB\-assign\-parameter\-\fP +The name of a parameter in an assignment, i\&.e\&. on the left hand side of +an `\fB=\fP\&' +.TP +\fB\-brace\-parameter\-\fP +The name of a parameter expansion within braces (`\fB${\fP\fI\&.\&.\&.\fP\fB}\fP\&') +.TP +\fB\-command\-\fP +A word in command position +.TP +\fB\-condition\-\fP +A word inside a condition (`\fB[[\fP\fI\&.\&.\&.\fP\fB]]\fP\&') +.TP +\fB\-default\-\fP +Any word for which no other completion is defined +.TP +\fB\-equal\-\fP +A word beginning with an equals sign +.TP +\fB\-first\-\fP +This is tried before any other completion function\&. The function called +may set the \fB_compskip\fP parameter to one of various values: +\fBall\fP: no further completion is attempted; a string +containing the substring \fBpatterns\fP: no pattern completion functions +will be called; a string containing \fBdefault\fP: the +function for the `\fB\-default\-\fP\&' context will not be called, but +functions defined for commands will be\&. +.TP +\fB\-math\-\fP +Inside mathematical contexts, such as +`\fB((\fP\fI\&.\&.\&.\fP\fB))\fP\&' +.TP +\fB\-parameter\-\fP +The name of a parameter expansion (`\fB$\fP\fI\&.\&.\&.\fP\&') +.TP +\fB\-redirect\-\fP +The word after a redirection operator\&. +.TP +\fB\-subscript\-\fP +The contents of a parameter subscript\&. +.TP +\fB\-tilde\-\fP +After an initial tilde (`\fB~\fP\&'), but before the first slash +in the word\&. +.TP +\fB\-value\-\fP +On the right hand side of an assignment\&. +.PP +Default implementations are supplied for each of these +contexts\&. In most cases the context \fB\-\fP\fIcontext\fP\fB\-\fP is +implemented by a corresponding function \fB_\fP\fIcontext\fP, for example +the context `\fB\-tilde\-\fP\&' and the function `\fB_tilde\fP')\&. +.PP +The contexts \fB\-redirect\-\fP and \fB\-value\-\fP allow extra context\-specific +information\&. (Internally, this is handled by the functions for each +context calling the function \fB_dispatch\fP\&.) The extra +information is added separated by commas\&. +.PP +For the \fB\-redirect\-\fP context, the extra information is in the form +`\fB\-redirect\-,\fP\fIop\fP\fB,\fP\fIcommand\fP\&', where \fIop\fP is the +redirection operator and \fIcommand\fP is the name of the command on +the line\&. If there is no command on the line yet, the \fIcommand\fP +field will be empty\&. +.PP +For the \fB\-value\-\fP context, the form is +`\fB\-value\-,\fP\fIname\fP\fB,\fP\fIcommand\fP\&', where \fIname\fP is the name of +the parameter on the left hand side of the assignment\&. +In the case of elements of an associative array, for +example `\fBassoc=(key <TAB>\fP\&', \fIname\fP is expanded to +`\fIname\fP\fB\-\fP\fIkey\fP\&'\&. In certain special contexts, such as +completing after `\fBmake CFLAGS=\fP\&', the \fIcommand\fP part gives the +name of the command, here \fBmake\fP; otherwise it is empty\&. +.PP +It is not necessary to define fully specific completions as the +functions provided will try to generate completions by progressively +replacing the elements with `\fB\-default\-\fP\&'\&. For example, when +completing after `\fBfoo=<TAB>\fP\&', \fB_value\fP will try the names +`\fB\-value\-,foo,\fP\&' (note the empty \fIcommand\fP part), +`\fB\-value\-,foo,\-default\-\fP\&' and`\fB\-value\-,\-default\-,\-default\-\fP', in +that order, until it finds a function to handle the context\&. +.PP +As an example: +.PP +.RS +.nf +\fBcompdef \&'_files \-g "*\&.log"' '\-redirect\-,2>,\-default\-'\fP +.fi +.RE +.PP +completes files matching `\fB*\&.log\fP\&' after `\fB2> <TAB>\fP' for any +command with no more specific handler defined\&. +.PP +Also: +.PP +.RS +.nf +\fBcompdef _foo \-value\-,\-default\-,\-default\-\fP +.fi +.RE +.PP +specifies that \fB_foo\fP provides completions for the values of +parameters for which no special function has been defined\&. This is +usually handled by the function \fB_value\fP itself\&. +.PP +The same lookup rules are used when looking up styles (as described +below); for example +.PP +.RS +.nf +\fBzstyle \&':completion:*:*:\-redirect\-,2>,*:*' file\-patterns '*\&.log'\fP +.fi +.RE +.PP +is another way to make completion after `\fB2> <TAB>\fP\&' complete files +matching `\fB*\&.log\fP\&'\&. +.PP +.SS "Functions" +.PP +The following function is defined by \fBcompinit\fP and may be called +directly\&. +.PP +.PD 0 + +.TP +.PD 0 +\fBcompdef\fP [ \fB\-ane\fP ] \fIfunction name\fP \&.\&.\&. [ \fB\-\fP{\fBp\fP|\fBP\fP} \fIpattern\fP \&.\&.\&. [ \fB\-N\fP \fIname\fP \&.\&.\&.]] +.TP +.PD 0 +\fBcompdef \-d\fP \fIname\fP \&.\&.\&. +.TP +.PD 0 +\fBcompdef \-k\fP [ \fB\-an\fP ] \fIfunction style key\-sequence\fP [ \fIkey\-sequence\fP \&.\&.\&. ] +.TP +.PD +\fBcompdef \-K\fP [ \fB\-an\fP ] \fIfunction name style key\-seq\fP [ \fIname style seq\fP \&.\&.\&. ] +The first form defines the \fIfunction\fP to call for completion in the +given contexts as described for the \fB#compdef\fP tag above\&. +.RS +.PP +Alternatively, all the arguments may have the form +`\fIcmd\fP\fB=\fP\fIservice\fP\&'\&. Here \fIservice\fP should already have been +defined by `\fIcmd1\fP\fB=\fP\fIservice\fP\&' lines in \fB#compdef\fP files, as +described above\&. The argument for \fIcmd\fP will be completed in the +same way as \fIservice\fP\&. +.PP +The \fIfunction\fP 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 \fB\-e\fP 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 \fBeval\fP 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 +`\fB\&.h\fP\&' as arguments to the command \fBfoo\fP: +.PP +.RS +.nf +\fBcompdef \&'_files \-g "*\&.h"' foo\fP +.fi +.RE +.PP +The option \fB\-n\fP prevents any completions already defined for the +command or context from being overwritten\&. +.PP +The option \fB\-d\fP deletes any completion defined for the command or +contexts listed\&. +.PP +The \fIname\fPs may also contain \fB\-p\fP, \fB\-P\fP and \fB\-N\fP options as +described for the \fB#compdef\fP tag\&. The effect on the argument list is +identical, switching between definitions of patterns tried initially, +patterns tried finally, and normal commands and contexts\&. +.PP +The parameter \fB$_compskip\fP may be set by any function defined for a +pattern context\&. If it is set to a value containing the substring +`\fBpatterns\fP\&' none of the pattern\-functions will be called; if it is +set to a value containing the substring `\fBall\fP\&', no other function +will be called\&. Setting \fB$_compskip\fP in this manner is of particular +utility when using the \fB\-p\fP option, as otherwise the dispatcher will +move on to additional functions (likely the default one) after calling +the pattern\-context one, which can mangle the display of completion +possibilities if not handled properly\&. +.PP +The form with \fB\-k\fP defines a widget with the same name as the \fIfunction\fP +that will be called for each of the \fIkey\-sequence\fPs; this is like the +\fB#compdef \-k\fP tag\&. The function should generate the completions needed +and will otherwise behave like the builtin widget whose name is given as +the \fIstyle\fP argument\&. The widgets usable for this are: +\fBcomplete\-word\fP, \fBdelete\-char\-or\-list\fP, \fBexpand\-or\-complete\fP, +\fBexpand\-or\-complete\-prefix\fP, \fBlist\-choices\fP, \fBmenu\-complete\fP, +\fBmenu\-expand\-or\-complete\fP, and \fBreverse\-menu\-complete\fP, as well as +\fBmenu\-select\fP if the \fBzsh/complist\fP module is loaded\&. The option \fB\-n\fP +prevents the key being bound if it is already to bound to something other +than \fBundefined\-key\fP\&. +.PP +The form with \fB\-K\fP is similar and defines multiple widgets based on the +same \fIfunction\fP, each of which requires the set of three arguments +\fIname\fP, \fIstyle\fP and \fIkey\-seq\fPuence, where the latter two are as +for \fB\-k\fP and the first must be a unique widget name beginning with an +underscore\&. +.PP +Wherever applicable, the \fB\-a\fP option makes the \fIfunction\fP +autoloadable, equivalent to \fBautoload \-U \fP\fIfunction\fP\&. +.RE +.PP +The function \fBcompdef\fP can be used to associate existing completion +functions with new commands\&. For example, +.PP +.RS +.nf +\fBcompdef _pids foo\fP +.fi +.RE +.PP +uses the function \fB_pids\fP to complete process IDs for the command \fBfoo\fP\&. +.PP +Note also the \fB_gnu_generic\fP function described below, which can be +used to complete options for commands that understand the +`\fB\-\fP\fB\-help\fP\&' option\&. +.PP +.SH "COMPLETION SYSTEM CONFIGURATION" +.PP +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\&. +.PP +.SS "Overview" +.PP +When completion is attempted somewhere on the command line the +completion system begins building the context\&. The context represents +everything that the shell knows about the meaning of the command line +and the significance of the cursor position\&. This takes account of a +number of things including the command word (such as `\fBgrep\fP\&' or +`\fBzsh\fP\&') and options to which the current word may be an argument +(such as the `\fB\-o\fP\&' option to \fBzsh\fP which takes a shell option as an +argument)\&. +.PP +The context starts out very generic ("we are beginning a completion") +and becomes more specific as more is learned ("the current word is in a +position that is usually a command name" or "the current word might be a +variable name" and so on)\&. Therefore the context will vary during the +same call to the completion system\&. +.PP +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\&. Note that a user of the completion system +rarely needs to compose a context string, unless for example a new +function is being written to perform completion for a new command\&. What a +user may need to do is compose a \fIstyle\fP pattern, which is matched +against a context when needed to look up context\-sensitive options that +configure the completion system\&. +.PP +The next few paragraphs explain how a context is composed within the +completion function suite\&. Following that is discussion of how \fIstyles\fP +are defined\&. Styles determine such things as how the matches are +generated, similarly to shell options but with much more control\&. They +are defined with the \fBzstyle\fP builtin command (see \fIzshmodules\fP(1))\&. +.PP +The context string always consists of a fixed set of fields, separated +by colons and with a leading colon before the first\&. Fields which are +not yet known are left empty, but the surrounding colons appear anyway\&. +The fields are always in the order +\fB:completion:\fP\fIfunction\fP\fB:\fP\fIcompleter\fP\fB:\fP\fIcommand\fP\fB:\fP\fIargument\fP\fB:\fP\fItag\fP\&. These have the following meaning: +.PP +.PD 0 +.TP +.PD +\(bu +The literal string \fBcompletion\fP, saying that this style is used by +the completion system\&. This distinguishes the context from those used +by, for example, zle widgets and ZFTP functions\&. + +.TP +\(bu +The \fIfunction\fP, if completion is called from a named widget rather +than through the normal completion system\&. Typically this is blank, but +it is set by special widgets such as \fBpredict\-on\fP and the various +functions in the \fBWidget\fP directory of the distribution to the name of +that function, often in an abbreviated form\&. + +.TP +\(bu +The \fIcompleter\fP currently active, the name of the function without the +leading underscore and with other underscores converted to hyphens\&. A +`completer\&' is in overall control of how completion is to be performed; +`\fBcomplete\fP\&' is the simplest, but other completers exist to perform +related tasks such as correction, or to modify the behaviour of a later +completer\&. See +the section `Control Functions\&' below +for more information\&. + +.TP +\(bu +The \fIcommand\fP or a special \fB\-\fP\fIcontext\fP\fB\-\fP, just at it appears +following the \fB#compdef\fP tag or the \fBcompdef\fP function\&. 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\&. For example, the completion function for the \fBcvs\fP +command sets this field to \fBcvs\-add\fP when completing arguments to +the \fBadd\fP subcommand\&. + +.TP +\(bu +The \fIargument\fP; this indicates which command line or option argument +we are completing\&. For command arguments this generally takes the form +\fBargument\-\fP\fIn\fP, where \fIn\fP is the number of the argument, +and for arguments to options the form \fBoption\-\fP\fIopt\fP\fB\-\fP\fIn\fP +where \fIn\fP is the number of the argument to option \fIopt\fP\&. However, +this is only the case if the command line is parsed with standard +UNIX\-style options and arguments, so many completions do not set this\&. + +.TP +\(bu +The \fItag\fP\&. As described previously, tags are used to discriminate between +the types of matches a completion function can generate in a certain context\&. +Any completion function may use any tag name it likes, but a list of the +more common ones is given below\&. + +.PP +The context is gradually put together as the functions are executed, starting +with the main entry point, which adds \fB:completion:\fP and the \fIfunction\fP +element if necessary\&. The completer then adds the \fIcompleter\fP element\&. +The contextual completion adds the \fIcommand\fP and \fIargument\fP options\&. +Finally, the \fItag\fP is added when the types of completion are known\&. +For example, the context name +.PP +.RS +.nf +\fB\fB:completion::complete:dvips:option\-o\-1:files\fP\fP +.fi +.RE +.PP +says that normal completion was attempted as the first argument to the +option \fB\-o\fP of the command \fBdvips\fP: +.PP +.RS +.nf +\fB\fBdvips \-o \&.\&.\&.\fP\fP +.fi +.RE +.PP +and the completion function will generate filenames\&. +.PP +Usually completion will be tried for all possible tags in an order given +by the completion function\&. However, this can be altered by using the +\fBtag\-order\fP style\&. Completion is then restricted to the list of given +tags in the given order\&. +.PP +The \fB_complete_help\fP bindable command shows all the contexts and tags +available for completion at a particular point\&. This provides an easy +way of finding information for \fBtag\-order\fP and other styles\&. It is +described in +the section `Bindable Commands\&' below\&. +.PP +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 is matched to the most specific (best +fitting) pattern, and the name of the style itself, which must be +matched exactly\&. The following examples demonstrate that patterns +may be loosely defined for styles that apply broadly, or as tightly +defined as desired for styles that apply in narrower circumstances\&. +.PP +For example, many completion functions can generate matches in a +simple and a verbose form and use the \fBverbose\fP style to decide +which form should be used\&. To make all such functions use the verbose form, +put +.PP +.RS +.nf +\fBzstyle \&':completion:*' verbose yes\fP +.fi +.RE +.PP +in a startup file (probably \fB\&.zshrc\fP)\&. +This gives the \fBverbose\fP style the value \fByes\fP in every +context inside the completion system, unless that context has a more +specific definition\&. It is best to avoid giving the pattern as `\fB*\fP\&' +in case the style has some meaning outside the completion system\&. +.PP +Many such general purpose styles can be configured simply by using the +\fBcompinstall\fP function\&. +.PP +A more specific example of the use of the \fBverbose\fP style is by the +completion for the \fBkill\fP 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: +.PP +.RS +.nf +\fBzstyle \&':completion:*:*:kill:*:*' verbose no\fP +.fi +.RE +.PP +For even more control, the style can use one of the tags `\fBjobs\fP\&' or +`\fBprocesses\fP\&'\&. To turn off verbose display only for jobs: +.PP +.RS +.nf +\fBzstyle \&':completion:*:*:kill:*:jobs' verbose no\fP +.fi +.RE +.PP +The \fB\-e\fP option to \fBzstyle\fP even allows completion function code to +appear as the argument to a style; this requires some understanding of +the internals of completion functions (see +see \fIzshcompwid\fP(1)))\&. For example, +.PP +.RS +.nf +\fB\fBzstyle \-e \&':completion:*' hosts 'reply=($myhosts)'\fP\fP +.fi +.RE +.PP +This forces the value of the \fBhosts\fP style to be read from the +variable \fBmyhosts\fP each time a host name is needed; this is useful +if the value of \fBmyhosts\fP can change dynamically\&. +For another useful example, see the example in the description of the +\fBfile\-list\fP style below\&. This form can be +slow and should be avoided for commonly examined styles such +as \fBmenu\fP and \fBlist\-rows\-first\fP\&. +.PP +Note that the order in which styles are \fIdefined\fP does not matter; the +style mechanism uses the most specific possible match for a particular +style to determine the set of values\&. Strings are +preferred over patterns (for example, `\fB:completion::complete:::foo\fP\&' is +more specific than `\fB:completion::complete:::*\&'\fP), and longer patterns are +preferred over the pattern `\fB*\fP\&'\&. See +\fIzmodules\fP(1) +for details\&. +.PP +Context patterns that use something other than a wildcard (\fB*\fP) to match the +middle parts of the context \-\- the \fIcompleter\fP, \fIcommand\fP, and +\fIargument\fP in +\fB:completion:\fP\fIfunction\fP\fB:\fP\fIcompleter\fP\fB:\fP\fIcommand\fP\fB:\fP\fIargument\fP\fB:\fP\fItag\fP +\-\- should include all six colons (\fB:\fP) explicitly\&. Without this, +a pattern such as \fB:completion:*:foo:*\fP could match \fBfoo\fP against a +component other than the intended one (for example, against \fIcompleter\fP when +a match against \fIcommand\fP was intended)\&. +.PP +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\&. +.PP +.SS "Standard Tags" +.PP +Some of the following are only used when looking up particular styles +and do not refer to a type of match\&. +.PP +.PD 0 +.TP +.PD +\fBaccounts\fP +used to look up the \fBusers\-hosts\fP style +.TP +\fBall\-expansions\fP +used by the \fB_expand\fP completer when adding the single string containing +all possible expansions +.TP +\fBall\-files\fP +for the names of all files (as distinct from a particular subset, see the +\fBglobbed\-files\fP tag)\&. +.TP +\fBarguments\fP +for arguments to a command +.TP +\fBarrays\fP +for names of array parameters +.TP +\fBassociation\-keys\fP +for keys of associative arrays; used when completing inside a +subscript to a parameter of this type +.TP +\fBbookmarks\fP +when completing bookmarks (e\&.g\&. for URLs and the \fBzftp\fP function suite) +.TP +\fBbuiltins\fP +for names of builtin commands +.TP +\fBcharacters\fP +for single characters in arguments of commands such as \fBstty\fP\&. Also used +when completing character classes after an opening bracket +.TP +\fBcolormapids\fP +for X colormap ids +.TP +\fBcolors\fP +for color names +.TP +\fBcommands\fP +for names of external commands\&. Also used by complex commands such as +\fBcvs\fP when completing names subcommands\&. +.TP +\fBcontexts\fP +for contexts in arguments to the \fBzstyle\fP builtin command +.TP +\fBcorrections\fP +used by the \fB_approximate\fP and \fB_correct\fP completers for possible +corrections +.TP +\fBcursors\fP +for cursor names used by X programs +.TP +\fBdefault\fP +used in some contexts to provide a way of supplying a default when more +specific tags are also valid\&. Note that this tag is +used when only the \fIfunction\fP field of the context name is set +.TP +\fBdescriptions\fP +used when looking up the value of the \fBformat\fP style to generate +descriptions for types of matches +.TP +\fBdevices\fP +for names of device special files +.TP +\fBdirectories\fP +for names of directories \-\- \fBlocal\-directories\fP is used instead +when completing arguments of \fBcd\fP and related builtin commands when +the \fBcdpath\fP array is set +.TP +\fBdirectory\-stack\fP +for entries in the directory stack +.TP +\fBdisplays\fP +for X display names +.TP +\fBdomains\fP +for network domains +.TP +\fBemail\-\fP\fIplugin\fP +for email addresses from the `\fB_email\-\fP\fIplugin\fP\&' backend of \fB_email_addresses\fP +.TP +\fBexpansions\fP +used by the \fB_expand\fP completer for individual words (as opposed to +the complete set of expansions) resulting from the expansion of a word +on the command line +.TP +\fBextensions\fP +for X server extensions +.TP +\fBfile\-descriptors\fP +for numbers of open file descriptors +.TP +\fBfiles\fP +the generic file\-matching tag used by functions completing filenames +.TP +\fBfonts\fP +for X font names +.TP +\fBfstypes\fP +for file system types (e\&.g\&. for the \fBmount\fP command) +.TP +\fBfunctions\fP +names of functions \-\- normally shell functions, although certain +commands may understand other kinds of function +.TP +\fBglobbed\-files\fP +for filenames when the name has been generated by pattern matching +.TP +\fBgroups\fP +for names of user groups +.TP +\fBhistory\-words\fP +for words from the history +.TP +\fBhosts\fP +for hostnames +.TP +\fBindexes\fP +for array indexes +.TP +\fBinterfaces\fP +for network interfaces +.TP +\fBjobs\fP +for jobs (as listed by the `\fBjobs\fP\&' builtin) +.TP +\fBkeymaps\fP +for names of zsh keymaps +.TP +\fBkeysyms\fP +for names of X keysyms +.TP +\fBlibraries\fP +for names of system libraries +.TP +\fBlimits\fP +for system limits +.TP +\fBlocal\-directories\fP +for names of directories that are subdirectories of the current working +directory when completing arguments of \fBcd\fP and related builtin +commands (compare \fBpath\-directories\fP) \-\- when the \fBcdpath\fP +array is unset, \fBdirectories\fP is used instead +.TP +\fBmailboxes\fP +for e\-mail folders +.TP +\fBmanuals\fP +for names of manual pages +.TP +\fBmaps\fP +for map names (e\&.g\&. NIS maps) +.TP +\fBmessages\fP +used to look up the \fBformat\fP style for messages +.TP +\fBmodifiers\fP +for names of X modifiers +.TP +\fBmodules\fP +for modules (e\&.g\&. \fBzsh\fP modules) +.TP +\fBmy\-accounts\fP +used to look up the \fBusers\-hosts\fP style +.TP +\fBnamed\-directories\fP +for named directories (you wouldn\&'t have guessed that, would you?) +.TP +\fBnames\fP +for all kinds of names +.TP +\fBnewsgroups\fP +for USENET groups +.TP +\fBnicknames\fP +for nicknames of NIS maps +.TP +\fBoptions\fP +for command options +.TP +\fBoriginal\fP +used by the \fB_approximate\fP, \fB_correct\fP and \fB_expand\fP completers when +offering the original string as a match +.TP +\fBother\-accounts\fP +used to look up the \fBusers\-hosts\fP style +.TP +\fBpackages\fP +for packages (e\&.g\&. \fBrpm\fP or installed \fBDebian\fP packages) +.TP +\fBparameters\fP +for names of parameters +.TP +\fBpath\-directories\fP +for names of directories found by searching the \fBcdpath\fP array when +completing arguments of \fBcd\fP and related builtin commands (compare +\fBlocal\-directories\fP) +.TP +\fBpaths\fP +used to look up the values of the \fBexpand\fP, \fBambiguous\fP and +\fBspecial\-dirs\fP styles +.TP +\fBpods\fP +for perl pods (documentation files) +.TP +\fBports\fP +for communication ports +.TP +\fBprefixes\fP +for prefixes (like those of a URL) +.TP +\fBprinters\fP +for print queue names +.TP +\fBprocesses\fP +for process identifiers +.TP +\fBprocesses\-names\fP +used to look up the \fBcommand\fP style when generating the names of +processes for \fBkillall\fP +.TP +\fBsequences\fP +for sequences (e\&.g\&. \fBmh\fP sequences) +.TP +\fBsessions\fP +for sessions in the \fBzftp\fP function suite +.TP +\fBsignals\fP +for signal names +.TP +\fBstrings\fP +for strings (e\&.g\&. the replacement strings for the \fBcd\fP builtin +command) +.TP +\fBstyles\fP +for styles used by the zstyle builtin command +.TP +\fBsuffixes\fP +for filename extensions +.TP +\fBtags\fP +for tags (e\&.g\&. \fBrpm\fP tags) +.TP +\fBtargets\fP +for makefile targets +.TP +\fBtime\-zones\fP +for time zones (e\&.g\&. when setting the \fBTZ\fP parameter) +.TP +\fBtypes\fP +for types of whatever (e\&.g\&. address types for the \fBxhost\fP command) +.TP +\fBurls\fP +used to look up the \fBurls\fP and \fBlocal\fP styles when completing URLs +.TP +\fBusers\fP +for usernames +.TP +\fBvalues\fP +for one of a set of values in certain lists +.TP +\fBvariant\fP +used by \fB_pick_variant\fP to look up the command to run when determining +what program is installed for a particular command name\&. +.TP +\fBvisuals\fP +for X visuals +.TP +\fBwarnings\fP +used to look up the \fBformat\fP style for warnings +.TP +\fBwidgets\fP +for zsh widget names +.TP +\fBwindows\fP +for IDs of X windows +.TP +\fBzsh\-options\fP +for shell options +.PP +.SS "Standard Styles" +.PP +Note that the values of several of these styles represent boolean +values\&. Any of the strings `\fBtrue\fP\&', `\fBon\fP', +`\fByes\fP\&', and `\fB1\fP' can be used for the value `true' and +any of the strings `\fBfalse\fP\&', `\fBoff\fP', `\fBno\fP', and `\fB0\fP' 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\&. +.PP +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 +\fBdefault\fP tag\&. The most notable styles of this type are \fBmenu\fP, +\fBlist\-colors\fP and styles controlling completion listing such as +\fBlist\-packed\fP and \fBlast\-prompt\fP\&. When tested for the \fBdefault\fP +tag, only the \fIfunction\fP field of the context will be set so that +a style using the \fBdefault\fP tag will normally be defined along the lines of: +.PP +.RS +.nf +\fBzstyle \&':completion:*:default' menu \&.\&.\&.\fP +.fi +.RE +.PP +.PD 0 +.TP +.PD +\fBaccept\-exact\fP +This is tested for the \fBdefault\fP tag in addition to the tags valid for +the current context\&. If it is set to `true\&' and any of the trial +matches is the same as the string on the command line, this match will +immediately be accepted (even if it would otherwise be considered +ambiguous)\&. +.RS +.PP +When completing pathnames (where the tag used is `\fBpaths\fP\&') +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\&. +.PP +This style is also used by the \fB_expand\fP completer to decide if +words beginning with a tilde or parameter expansion should be +expanded\&. For example, if there are parameters +\fBfoo\fP and \fBfoobar\fP, the string `\fB$foo\fP\&' will only be expanded if +\fBaccept\-exact\fP is set to `true\&'; otherwise the completion system will +be allowed to complete \fB$foo\fP to \fB$foobar\fP\&. If the style is set to +`\fBcontinue\fP\&', \fB_expand\fP will add the expansion as a match and the completion +system will also be allowed to continue\&. +.RE +.TP +\fBaccept\-exact\-dirs\fP +This is used by filename completion\&. Unlike \fBaccept\-exact\fP it is +a boolean\&. By default, filename completion examines all components +of a path to see if there are completions of that component, even if +the component matches an existing directory\&. For example, when +completion after \fB/usr/bin/\fP, the function examines possible +completions to \fB/usr\fP\&. +.RS +.PP +When this style is `true\&', any prefix of a path that matches an existing +directory is accepted without any attempt to complete it further\&. +Hence, in the given example, the path \fB/usr/bin/\fP is accepted +immediately and completion tried in that directory\&. +.PP +This style is also useful when completing after directories that +magically appear when referenced, such as ZFS \fB\&.zfs\fP directories +or NetApp \fB\&.snapshot\fP directories\&. When the style is set the +shell does not check for the existence of the directory within the +parent directory\&. +.PP +If you wish to inhibit this behaviour entirely, set the \fBpath\-completion\fP +style (see below) to `false\&'\&. +.RE +.TP +\fBadd\-space\fP +This style is used by the \fB_expand\fP completer\&. If it is `true\&' (the +default), a space will be inserted after all words resulting from the +expansion, or a slash in the case of directory names\&. If the value +is `\fBfile\fP\&', the completer will only add a space +to names of existing files\&. Either a boolean `true\&' or the value +`\fBfile\fP\&' may be combined with `\fBsubst\fP', in which case the completer +will not add a space to words generated from the expansion of a +substitution of the form `\fB$(\fP\fI\&.\&.\&.\fP\fB)\fP\&' or `\fB${\fP\fI\&.\&.\&.\fP\fB}\fP'\&. +.RS +.PP +The \fB_prefix\fP completer uses this style as a simple boolean value +to decide if a space should be inserted before the suffix\&. +.RE +.TP +\fBambiguous\fP +This applies when completing non\-final components of filename paths, in +other words those with a trailing slash\&. If it is set, the cursor is +left after the first ambiguous component, even if menu completion is in +use\&. The style is always tested with the \fBpaths\fP tag\&. +.TP +\fBassign\-list\fP +When completing after an equals sign that is being treated as an +assignment, the completion system normally completes only one filename\&. +In some cases the value may be a list of filenames separated by colons, +as with \fBPATH\fP and similar parameters\&. This style can be set to a +list of patterns matching the names of such parameters\&. +.RS +.PP +The default is to complete lists when the word on the line already +contains a colon\&. +.RE +.TP +\fBauto\-description\fP +If set, this style\&'s value will be used as the description for options that +are not described by the completion functions, but that have exactly +one argument\&. The sequence `\fB%d\fP\&' 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 `\fBspecify: %d\fP\&'\&. +Note that this may not work for some commands\&. +.TP +\fBavoid\-completer\fP +This is used by the \fB_all_matches\fP 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\&. +.RS +.PP +The default value for this style is `\fB_expand _old_list _correct +_approximate\fP\&', i\&.e\&. it contains the completers for which a string +with all matches will almost never be wanted\&. +.RE +.TP +\fBcache\-path\fP +This style defines the path where any cache files containing dumped +completion data are stored\&. It defaults to `\fB$ZDOTDIR/\&.zcompcache\fP\&', or +`\fB$HOME/\&.zcompcache\fP\&' if \fB$ZDOTDIR\fP is not defined\&. The completion +cache will not be used unless the \fBuse\-cache\fP style is set\&. +.TP +\fBcache\-policy\fP +This style defines the function that will be used to determine whether +a cache needs rebuilding\&. See the section on the \fB_cache_invalid\fP +function below\&. +.TP +\fBcall\-command\fP +This style is used in the function for commands such as \fBmake\fP and +\fBant\fP where calling the command directly to generate matches suffers +problems such as being slow or, as in the case of \fBmake\fP can +potentially cause actions in the makefile to be executed\&. If it is set +to `true\&' the command is called to generate matches\&. The default value +of this style is `false\&'\&. +.TP +\fBcommand\fP +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 that 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 `\fBbuiltin\fP\&' or `\fBcommand\fP' 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\&. +.RS +.PP +As an example, the completion function for process IDs uses this +style with the \fBprocesses\fP tag to generate the IDs to complete and +the list of processes to display (if the \fBverbose\fP style is `true\&')\&. +The list produced by the command should look like the output of the +\fBps\fP command\&. The first line is not displayed, but is searched for +the string `\fBPID\fP\&' (or `\fBpid\fP') to find the position of the +process IDs in the following lines\&. If the line does not contain +`\fBPID\fP\&', the first numbers in each of the other lines are taken as the +process IDs to complete\&. +.PP +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\&. +.RE +.TP +\fBcommand\-path\fP +This is a list of directories to search for commands to complete\&. The +default for this style is the value of the special parameter \fBpath\fP\&. +.TP +\fBcommands\fP +This is used by the function completing sub\-commands for the system +initialisation scripts (residing in \fB/etc/init\&.d\fP or somewhere not +too far away from that)\&. Its 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 `\fBstart\fP\&' and `\fBstop\fP'\&. +.TP +\fBcomplete\fP +This is used by the \fB_expand_alias\fP function when invoked as a +bindable command\&. If set to `true\&' and the word on the command +line is not the name of an alias, matching alias names will be +completed\&. +.TP +\fBcomplete\-options\fP +This is used by the completer for \fBcd\fP, \fBchdir\fP and \fBpushd\fP\&. +For these commands a \fB\-\fP is used to introduce a directory stack entry +and completion of these is far more common than completing options\&. +Hence unless the value of this style is `true\&' options will not be +completed, even after an initial \fB\-\fP\&. If it is `true\&', options will +be completed after an initial \fB\-\fP unless there is a preceding +\fB\-\fP\fB\-\fP on the command line\&. +.TP +\fBcompleter\fP +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 +the section `Control Functions\&' below\&. +.RS +.PP +Each string may be either the name of a completer function or a string +of the form `\fIfunction\fP\fB:\fP\fIname\fP\&'\&. In the first case the +\fIcompleter\fP 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 +\fIfunction\fP is the name of the completer to call, but the context +will contain the user\-defined \fIname\fP in the \fIcompleter\fP field of +the context\&. If the \fIname\fP 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 \fIname\fP appended to it\&. For example: +.PP +.RS +.nf +\fBzstyle \&':completion:*' completer _complete _complete:\-foo\fP +.fi +.RE +.PP +Here, completion will call the \fB_complete\fP completer twice, once +using `\fBcomplete\fP\&' and once using `\fBcomplete\-foo\fP' in the +\fIcompleter\fP field of the context\&. Normally, using the same +completer more than once only makes sense when used with the +`\fIfunctions\fP\fB:\fP\fIname\fP\&' form, because otherwise the context +name will be the same in all calls to the completer; possible +exceptions to this rule are the \fB_ignored\fP and \fB_prefix\fP +completers\&. +.PP +The default value for this style is `\fB_complete _ignored\fP\&': +only completion will be done, first using the \fBignored\-patterns\fP style +and the \fB$fignore\fP array and then without ignoring matches\&. +.RE +.TP +\fBcondition\fP +This style is used by the \fB_list\fP completer function to decide if +insertion of matches should be delayed unconditionally\&. The default is +`true\&'\&. +.TP +\fBdelimiters\fP +This style is used when adding a delimiter for use with history +modifiers or glob qualifiers that have delimited arguments\&. It is +an array of preferred delimiters to add\&. Non\-special characters are +preferred as the completion system may otherwise become confused\&. +The default list is \fB:\fP, \fB+\fP, \fB/\fP, \fB\-\fP, \fB%\fP\&. The list +may be empty to force a delimiter to be typed\&. +.TP +\fBdisabled\fP +If this is set to `true\&', the \fB_expand_alias\fP completer and bindable +command will try to expand disabled aliases, too\&. The default is +`false\&'\&. +.TP +\fBdomains\fP +A list of names of network domains for completion\&. +If this is not set, domain names will be taken from +the file \fB/etc/resolv\&.conf\fP\&. +.TP +\fBenviron\fP +The environ style is used when completing for `\fBsudo\fP\&'\&. It is set to an +array of `\fIVAR\fP\fB=\fP\fIvalue\fP\&' assignments to be exported into the +local environment before the completion for the target command is invoked\&. +.RS +.nf +\fBzstyle \&':completion:*:sudo::' environ \e + PATH="/sbin:/usr/sbin:$PATH" HOME="/root"\fP +.fi +.RE +.TP +\fBexpand\fP +This style is used when completing strings consisting of multiple +parts, such as path names\&. +.RS +.PP +If one of its values is the string `\fBprefix\fP\&', the partially typed +word from the line will be expanded as far as possible even if trailing +parts cannot be completed\&. +.PP +If one of its values is the string `\fBsuffix\fP\&', 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\&. +.RE +.TP +\fBextra\-verbose\fP +If set, the completion listing is more verbose at the cost of +a probable decrease in completion speed\&. Completion performance +will suffer if this style is set to `true\&'\&. +.TP +\fBfake\fP +This style may be set for any completion context\&. It +specifies additional strings that will always be completed in that +context\&. The form of each string is `\fIvalue\fP\fB:\fP\fIdescription\fP\&'; +the colon and description may be omitted, but any literal colons in +\fIvalue\fP must be quoted with a backslash\&. Any \fIdescription\fP +provided is shown alongside the value in completion listings\&. +.RS +.PP +It is important to use a sufficiently restrictive context when specifying +fake strings\&. Note that the styles \fBfake\-files\fP and \fBfake\-parameters\fP +provide additional features when completing files or parameters\&. +.RE +.TP +\fBfake\-always\fP +This works identically to the \fBfake\fP style except that +the \fBignored\-patterns\fP style is not applied to it\&. This makes it +possible to override a set of matches completely by setting the +ignored patterns to `\fB*\fP\&'\&. +.RS +.PP +The following shows a way of supplementing any tag with arbitrary data, but +having it behave for display purposes like a separate tag\&. In this example +we use the features of the \fBtag\-order\fP style to divide the +\fBnamed\-directories\fP tag into two when performing completion with +the standard completer \fBcomplete\fP for arguments of \fBcd\fP\&. The tag +\fBnamed\-directories\-normal\fP behaves as normal, but the tag +\fBnamed\-directories\-mine\fP contains a fixed set of directories\&. +This has the effect of adding the match group `\fBextra directories\fP\&' with +the given completions\&. +.PP +.RS +.nf +\fBzstyle \&':completion::complete:cd:*' tag\-order \e + \&'named\-directories:\-mine:extra\e directories + named\-directories:\-normal:named\e directories *\&' +zstyle \&':completion::complete:cd:*:named\-directories\-mine' \e + fake\-always mydir1 mydir2 +zstyle \&':completion::complete:cd:*:named\-directories\-mine' \e + ignored\-patterns \&'*'\fP +.fi +.RE +.RE +.TP +\fBfake\-files\fP +This style is used when completing files and looked up +without a tag\&. Its values are of the form +`\fIdir\fP\fB:\fP\fInames\&.\&.\&.\fP\&'\&. This will add the \fInames\fP (strings +separated by spaces) as +possible matches when completing in the directory \fIdir\fP, even if no +such files really exist\&. The dir may be a pattern; pattern characters +or colons in \fIdir\fP should be quoted with a backslash to be treated +literally\&. +.RS +.PP +This can be useful on systems that support special file systems whose +top\-level pathnames can not be listed or generated with glob patterns +(but see \fBaccept\-exact\-dirs\fP for a more general way of dealing +with this problem)\&. It can also be used for directories for which one +does not have read permission\&. +.PP +The pattern form can be used to add a certain `magic\&' entry +to all directories on a particular file system\&. +.RE +.TP +\fBfake\-parameters\fP +This is used by the completion function for parameter names\&. +Its values are names of parameters that might not yet be +set but should be completed nonetheless\&. Each name may also be +followed by a colon and a string specifying the type of the parameter +(like `\fBscalar\fP\&', `\fBarray\fP' or `\fBinteger\fP')\&. If the type is +given, the name will only be completed if parameters of that type are +required in the particular context\&. Names for which no type is +specified will always be completed\&. +.TP +\fBfile\-list\fP +This style controls whether files completed using the standard builtin +mechanism are to be listed with a long list similar to \fBls \-l\fP\&. +Note that this feature uses the shell module +\fBzsh/stat\fP for file information; this loads the builtin \fBstat\fP +which will replace any external \fBstat\fP executable\&. To avoid +this the following code can be included in an initialization file: +.RS +.PP +.RS +.nf +\fBzmodload \-i zsh/stat +disable stat\fP +.fi +.RE +.PP +The style may either be set to a `true\&' value (or `\fBall\fP'), or +one of the values `\fBinsert\fP\&' or `\fBlist\fP', indicating that files +are to be listed in long format in all circumstances, or when +attempting to insert a file name, or when listing file names +without attempting to insert one\&. +.PP +More generally, the value may be an array of any of the above values, +optionally followed by \fB=\fP\fInum\fP\&. If \fInum\fP is present it +gives the maximum number of matches for which long listing style +will be used\&. For example, +.PP +.RS +.nf +\fBzstyle \&':completion:*' file\-list list=20 insert=10\fP +.fi +.RE +.PP +specifies that long format will be used when listing up to 20 files +or inserting a file with up to 10 matches (assuming a listing +is to be shown at all, for example on an ambiguous completion), else short +format will be used\&. +.PP +.RS +.nf +\fBzstyle \-e \&':completion:*' file\-list \e + \&'(( ${+NUMERIC} )) && reply=(true)'\fP +.fi +.RE +.PP +specifies that long format will be used any time a numeric argument is +supplied, else short format\&. +.RE +.TP +\fBfile\-patterns\fP +This is used by the standard function for completing filenames, +\fB_files\fP\&. If the style is unset up to three tags are offered, +`\fBglobbed\-files\fP\&',`\fBdirectories\fP' and `\fBall\-files\fP', depending on +the types of files expected by the caller of \fB_files\fP\&. The first two +(`\fBglobbed\-files\fP\&' and `\fBdirectories\fP') are normally offered +together to make it easier to complete files in sub\-directories\&. +.RS +.PP +The \fBfile\-patterns\fP style provides alternatives to the default tags, +which are not used\&. Its value consists of elements of the form +`\fIpattern\fP\fB:\fP\fItag\fP\&'; each string may contain any number of +such specifications separated by spaces\&. +.PP +The \fIpattern\fP is a pattern that is to be used to generate filenames\&. +Any occurrence of the sequence `\fB%p\fP\&' is replaced by any +pattern(s) +passed by the function calling \fB_files\fP\&. Colons in the pattern must +be preceded by a backslash to make them distinguishable from the colon +before the \fItag\fP\&. If more than one pattern is needed, the patterns +can be given inside braces, separated by commas\&. +.PP +The \fItag\fPs of all strings in the value will be offered by \fB_files\fP +and used when looking up other styles\&. Any \fItag\fPs in the same +word will be offered at the same time and before later words\&. +If no `\fB:\fP\fItag\fP\&' is given the `\fBfiles\fP' tag will be used\&. +.PP +The \fItag\fP may also be followed by an optional second colon and a +description, which will be used for the `\fB%d\fP\&' in the value of +the \fBformat\fP style (if that is set) instead of the default +description supplied by the completion function\&. The inclusion +of a description also gives precedence to associated options such as +for completion grouping so it can be used where files should be +separated\&. +.PP +For example, to make the \fBrm\fP command first complete only names of +object files and then the names of all files if there is no matching +object file: +.PP +.RS +.nf +\fBzstyle \&':completion:*:*:rm:*:*' file\-patterns \e + \&'*\&.o:object\-files' '%p:all\-files'\fP +.fi +.RE +.PP +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: +.PP +.RS +.nf +\fBzstyle \&':completion:*' file\-patterns \e + \&'%p:globbed\-files' '*(\-/):directories' '*:all\-files'\fP +.fi +.RE +.PP +This works even where there is no special pattern: \fB_files\fP matches +all files using the pattern `\fB*\fP\&' 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\&. +.PP +To separate directories into a separate group from the files but still +complete them at the first attempt, a description needs to be given\&. +Note that directories need to be explicitly excluded from the +globbed\-files because `\fB*\fP\&' will match directories\&. For grouping, it +is also necessary to set the \fBgroup\-name\fP style\&. +.PP +.RS +.nf +\fBzstyle \&':completion:*' file\-patterns \e + \&'%p(^\-/):globbed\-files *(\-/):directories:location'\fP +.fi +.RE +.PP +During the execution of completion functions, the \fBEXTENDED_GLOB\fP +option is in effect, so the characters `\fB#\fP\&', `\fB~\fP' and `\fB^\fP' have +special meanings in the patterns\&. +.RE +.TP +\fBfile\-sort\fP +The standard filename completion function uses this style without a tag +to determine in which order the names should be listed; menu completion +will cycle through them in the same order\&. The possible +values are: `\fBsize\fP\&' to sort by the size of the file; +`\fBlinks\fP\&' to sort by the number of links to the file; +`\fBmodification\fP\&' (or `\fBtime\fP' or `\fBdate\fP') to sort by the last +modification time; `\fBaccess\fP\&' to sort by the last access time; and +`\fBinode\fP\&' (or `\fBchange\fP') to sort 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 +`\fBreverse\fP\&', sorting is done in the opposite order\&. If the value +contains the string `\fBfollow\fP\&', timestamps are associated with the +targets of symbolic links; the default is to use the timestamps +of the links themselves\&. +.TP +\fBfile\-split\-chars\fP +A set of characters that will cause \fIall\fP file completions for +the given context to be split at the point where any of the characters +occurs\&. A typical use is to set the style to \fB:\fP; then everything +up to and including the last \fB:\fP in the string so far is ignored when +completing files\&. As this is quite heavy\-handed, it is usually +preferable to update completion functions for contexts where this +behaviour is useful\&. +.TP +\fBfilter\fP +The \fBldap\fP plugin of email address completion (see \fB_email_addresses\fP) uses +this style to specify +the attributes to match against when filtering entries\&. So for example, if +the style is set to `\fBsn\fP\&', matching is done against surnames\&. Standard +LDAP filtering is used so normal completion matching is bypassed\&. If this +style is not set, the LDAP plugin is skipped\&. You may also need to set the +\fBcommand\fP style to specify how to connect to your LDAP server\&. +.TP +\fBforce\-list\fP +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 +`\fBalways\fP\&', the list will always be shown, even if there is only a +single match that will immediately be 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\&. +.RS +.PP +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\&. +.RE +.TP +\fBformat\fP +If this is set for the \fBdescriptions\fP tag, its value is used as a +string to display above matches in completion lists\&. The sequence +`\fB%d\fP\&' in this string will be replaced with a short description of +what these matches are\&. This string may also contain the output +attribute sequences understood by \fBcompadd \-X\fP +(see +\fIzshcompwid\fP(1))\&. +.RS +.PP +The style is tested with each tag valid for the current completion +before it is tested for the \fBdescriptions\fP tag\&. Hence different format +strings can be defined for different types of match\&. +.PP +Note also that some completer functions define additional +`\fB%\fP\&'\-sequences\&. These are described for the completer functions that +make use of them\&. +.PP +Some completion functions display messages that may be customised by +setting this style for the \fBmessages\fP tag\&. Here, the `\fB%d\fP\&' is +replaced with a message given by the completion function\&. +.PP +Finally, the format string is looked up with the \fBwarnings\fP tag, +for use when no matches could be generated at all\&. In this case the +`\fB%d\fP\&' is replaced with the descriptions for the matches that were +expected separated by spaces\&. The sequence `\fB%D\fP\&' is replaced with +the same descriptions separated by newlines\&. +.PP +It is possible to use printf\-style field width specifiers with `\fB%d\fP\&' +and similar escape sequences\&. This is handled by the \fBzformat\fP +builtin command from the \fBzsh/zutil\fP module, see +\fIzshmodules\fP(1)\&. +.RE +.TP +\fBgain\-privileges\fP +If set to \fBtrue\fP, this style enables the use of commands like \fBsudo\fP +or \fBdoas\fP to gain extra privileges when retrieving information for +completion\&. This is only done when a command such as \fBsudo\fP appears on +the command\-line\&. To force the use of, e\&.g\&. \fBsudo\fP or to override any +prefix that might be added due to \fBgain\-privileges\fP, the \fBcommand\fP +style can be used with a value that begins with a hyphen\&. +.TP +\fBglob\fP +This is used by the \fB_expand\fP completer\&. If +it is set to `true\&' (the default), globbing will be attempted on the +words resulting from a previous substitution (see the \fBsubstitute\fP +style) or else the original string from the line\&. +.TP +\fBglobal\fP +If this is set to `true\&' (the default), the \fB_expand_alias\fP +completer and bindable command will try to expand global aliases\&. +.TP +\fBgroup\-name\fP +The completion system can group different types of matches, which appear +in separate lists\&. This style can be used to give the names of 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: +.RS +.PP +.RS +.nf +\fBzstyle \&':completion:*:*:\-command\-:*:commands' \e + group\-name commands +zstyle \&':completion:*:*:\-command\-:*:functions' \e + group\-name functions\fP +.fi +.RE +.PP +As a consequence, any match with the same tag will be displayed in the +same group\&. +.PP +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: +.PP +.RS +.nf +\fBzstyle \&':completion:*' group\-name ''\fP +.fi +.RE +.PP +All matches for which no group name is defined will be put in a group +named \fB\-default\-\fP\&. +.PP +To display the group name in the output, see the \fBformat\fP style (q\&.v\&.) +under the \fBdescriptions\fP tag\&. +.RE +.TP +\fBgroup\-order\fP +This style is additional to the \fBgroup\-name\fP style to specify the +order for display of the groups defined by that style (compare \fBtag\-order\fP, +which determines which completions appear at all)\&. The groups named +are shown in the given order; any other groups +are shown in the order defined by the completion function\&. +.RS +.PP +For example, to have names of builtin commands, shell functions and +external commands appear in that order when completing in command +position: +.PP +.RS +.nf +\fBzstyle \&':completion:*:*:\-command\-:*:*' group\-order \e + builtins functions commands\fP +.fi +.RE +.RE +.TP +\fBgroups\fP +A list of names of UNIX groups\&. If this is not set, +group names are taken from the YP database or the file `\fB/etc/group\fP\&'\&. +.TP +\fBhidden\fP +If this is set to `true\&', matches for the given context +will not be listed, although +any description for the matches set with the \fBformat\fP style will be +shown\&. If it is set to `\fBall\fP\&', not even the description will be +displayed\&. +.RS +.PP +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 \fBtag\-order\fP style can be modified as described +below\&. +.RE +.TP +\fBhosts\fP +A list of names of hosts that should be completed\&. If this is not set, +hostnames are taken from the file `\fB/etc/hosts\fP\&'\&. +.TP +\fBhosts\-ports\fP +This style is used by commands that need or accept hostnames and +network ports\&. The strings in the value should be of the form +`\fIhost\fP\fB:\fP\fIport\fP\&'\&. Valid ports are determined by the presence +of hostnames; multiple ports for the same host may appear\&. +.TP +\fBignore\-line\fP +This is tested for each tag valid for the current completion\&. If +it is set to `true\&', none of the words that are already on the line +will be considered as possible completions\&. If it is set to +`\fBcurrent\fP\&', the word the cursor is on will not be considered as a +possible completion\&. The value `\fBcurrent\-shown\fP\&' is similar but only +applies if the list of completions is currently shown on the screen\&. +Finally, if the style is set to `\fBother\fP\&', all words on the line except +for the current one will be excluded from the possible completions\&. +.RS +.PP +The values `\fBcurrent\fP\&' and `\fBcurrent\-shown\fP' are a bit like the +opposite of the \fBaccept\-exact\fP style: only strings with +missing characters will be completed\&. +.PP +Note that you almost certainly don\&'t want to set this to `true' or +`\fBother\fP\&' for a general +context such as `\fB:completion:*\fP\&'\&. 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\&. +.RE +.TP +\fBignore\-parents\fP +The style is tested without a tag by the function completing pathnames +in order 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: +.RS +.PP +.PD 0 +.TP +.PD +\fBparent\fP +The name of any directory whose path is already contained in the word on +the line is ignored\&. For example, when completing after \fBfoo/\&.\&./\fP, the +directory \fBfoo\fP will not be considered a valid completion\&. +.TP +\fBpwd\fP +The name of the current working directory will not be completed; hence, +for example, completion after \fB\&.\&./\fP will not use the name of the current +directory\&. +.PP +In addition, the value may include one or both of: +.PP +.PD 0 +.TP +.PD +\fB\&.\&.\fP +Ignore the specified directories only when the word on the line contains +the substring `\fB\&.\&./\fP\&'\&. +.TP +\fBdirectory\fP +Ignore the specified directories only when names of directories are +completed, not when completing names of files\&. +.PP +Excluded values act in a similar fashion to values of the +\fBignored\-patterns\fP style, so they can be restored to consideration by +the \fB_ignored\fP completer\&. +.RE +.TP +\fBignored\-patterns\fP +A list of patterns; any trial completion matching one of the patterns +will be excluded from consideration\&. The +\fB_ignored\fP completer can appear in the list of completers to +restore the ignored matches\&. This is a more configurable +version of the shell parameter \fB$fignore\fP\&. +.RS +.PP +Note that the +\fBEXTENDED_GLOB\fP option is set during the execution of completion +functions, so the characters `\fB#\fP\&', `\fB~\fP' and `\fB^\fP' have special +meanings in the patterns\&. +.RE +.TP +\fBinsert\fP +This style is used by the \fB_all_matches\fP completer to decide whether to +insert the list of all matches unconditionally instead of adding the +list as another match\&. +.TP +\fBinsert\-ids\fP +When completing process IDs, for example as arguments to the \fBkill\fP and +\fBwait\fP builtins the name of a +command may 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 `\fBmenu\fP\&') the name will be converted +immediately to a set of possible IDs, and menu completion will be started +to cycle through them\&. +.RS +.PP +If the value of the style is `\fBsingle\fP\&', +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\&. +.RE +.TP +\fBinsert\-sections\fP +This style is used with tags of the form `\fBmanuals\&.\fP\fIX\fP\&' when +completing names of manual pages\&. If set and the \fIX\fP in the tag name matches +the section number of the page being completed, the section number is inserted +along with the page name\&. For example, given +.RS +.PP +.RS +.nf +\fBzstyle \&':completion:*:manuals\&.*' insert\-sections true\fP +.fi +.RE +.PP +\fBman ssh_<TAB>\fP may be completed to \fBman 5 ssh_config\fP\&. +.PP +The value may also be set to one of `\fBprepend\fP\&', or `\fBsuffix\fP'\&. +`\fBprepend\fP\&' behaves the same as `true' as in the above example, while +`\fBsuffix\fP\&' would complete \fBman ssh_<TAB>\fP as \fBman ssh_config\&.5\fP\&. +.PP +This is especially useful in conjunction with \fBseparate\-sections\fP, as +it ensures that the page requested of \fBman\fP corresponds to the one +displayed in the completion listing when there are multiple pages with the +same name (e\&.g\&., \fBprintf(1)\fP and \fBprintf(3)\fP)\&. +.PP +The default for this style is `false\&'\&. +.RE +.TP +\fBinsert\-tab\fP +If this is set to `true\&', the completion system will +insert a TAB character (assuming that was used to start completion) instead +of performing completion when there is no non\-blank character to the left +of the cursor\&. If it is set to `false\&', completion will be done even there\&. +.RS +.PP +The value may also contain the substrings `\fBpending\fP\&' or +`\fBpending=\fP\fIval\fP\&'\&. In this case, the typed character will be +inserted instead of starting completion when there is unprocessed input +pending\&. If a \fIval\fP 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 \fB$PENDING\fP special parameter from the +\fBzsh/zle\fP module being set properly which is not guaranteed on all +platforms\&. +.PP +The default value of this style is `true\&' except for completion within +\fBvared\fP builtin command where it is `false\&'\&. +.RE +.TP +\fBinsert\-unambiguous\fP +This is used by the \fB_match\fP and \fB_approximate\fP completers\&. +These completers are often used with menu completion since the word typed +may bear little resemblance to the final completion\&. +However, if this style is `true\&', the completer will start menu +completion only if it could find no unambiguous initial string at +least as long as the original string typed by the user\&. +.RS +.PP +In the case of the \fB_approximate\fP completer, the completer +field in the context will already have been set to one of +\fBcorrect\-\fP\fInum\fP or \fBapproximate\-\fP\fInum\fP, where \fInum\fP is the +number of errors that were accepted\&. +.PP +In the case of the \fB_match\fP completer, the style may also be set to +the string `\fBpattern\fP\&'\&. Then the pattern on the line is left +unchanged if it does not match unambiguously\&. +.RE +.TP +\fBkeep\-prefix\fP +This style is used by the \fB_expand\fP completer\&. If it is `true\&', the +completer will try to keep a prefix containing a tilde or parameter +expansion\&. Hence, for example, the string `\fB~/f*\fP\&' would be expanded to +`\fB~/foo\fP\&' instead of `\fB/home/user/foo\fP'\&. If the style is set to +`\fBchanged\fP\&' (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 forces the prefix to be +expanded unconditionally\&. +.RS +.PP +The behaviour of \fB_expand\fP when this style is `true\&' is to cause \fB_expand\fP +to give up when a single expansion with the restored prefix is the same +as the original; hence any remaining completers may be called\&. +.RE +.TP +\fBknown\-hosts\-files\fP +This style should contain a list of files to search for host names and +(if the \fBuse\-ip\fP style is set) IP addresses in a format compatible with +ssh \fBknown_hosts\fP files\&. If it is not set, the files +\fB/etc/ssh/ssh_known_hosts\fP and \fB~/\&.ssh/known_hosts\fP are used\&. +.TP +\fBlast\-prompt\fP +This is a more flexible form of the \fBALWAYS_LAST_PROMPT\fP option\&. +If it is `true\&', the completion system will try to return the cursor to +the previous command line after displaying a completion list\&. It is +tested for all tags valid for the current completion, then the +\fBdefault\fP tag\&. The cursor will be moved back to the +previous line if this style is `true\&' for all types of match\&. Note +that unlike the \fBALWAYS_LAST_PROMPT\fP option this is independent of the +numeric argument\&. +.TP +\fBlist\fP +This style is used by the \fB_history_complete_word\fP bindable command\&. +If it is set to `true\&' it has no effect\&. If it is set to `false' +matches will not be listed\&. This overrides the setting of the options +controlling listing behaviour, in particular \fBAUTO_LIST\fP\&. The context +always starts with `\fB:completion:history\-words\fP\&'\&. +.TP +\fBlist\-colors\fP +If the \fBzsh/complist\fP module is loaded, this style can be used to set +color specifications\&. This mechanism replaces the use of the +\fBZLS_COLORS\fP and \fBZLS_COLOURS\fP parameters described in +the section `The zsh/complist Module\&' in \fIzshmodules\fP(1), but the syntax is the same\&. +.RS +.PP +If this style is set for the \fBdefault\fP 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 \fBgroup\-name\fP +style must be set to an empty string\&. +.PP +In addition to setting styles for specific tags, it is also possible to +use group names specified explicitly by the \fBgroup\-name\fP tag together +with the `\fB(group)\fP\&' syntax allowed by the \fBZLS_COLORS\fP and +\fBZLS_COLOURS\fP parameters and simply using the \fBdefault\fP tag\&. +.PP +It is possible to use any color specifications already set up for the GNU +version of the \fBls\fP command: +.PP +.RS +.nf +\fBzstyle \&':completion:*:default' list\-colors \e + ${(s\&.:\&.)LS_COLORS}\fP +.fi +.RE +.PP +The default colors are the same as for the GNU \fBls\fP command and can be +obtained by setting the style to an empty string (i\&.e\&. \fB\&''\fP)\&. +.RE +.TP +\fBlist\-dirs\-first\fP +This is used by file completion and corresponds to a particular +setting of the \fBfile\-patterns\fP style\&. +If set, the default directories to be completed +are listed separately from and before completion for other files\&. +.TP +\fBlist\-grouped\fP +If this style is `true\&' (the default), the completion system will try to +make certain completion listings more compact by grouping matches\&. +For example, options for commands that have the same description (shown +when the \fBverbose\fP style is set to `true\&') will appear as a single +entry\&. However, menu selection can be used to cycle through all the +matches\&. +.TP +\fBlist\-packed\fP +This is tested for each tag valid in the current context as well as the +\fBdefault\fP tag\&. If it is set to `true\&', the corresponding matches +appear in listings as if the \fBLIST_PACKED\fP option were set\&. If it is +set to `false\&', they are listed normally\&. +.TP +\fBlist\-prompt\fP +If this style is set for the \fBdefault\fP tag, +completion lists that don\&'t fit on the screen can be scrolled (see +the description of the \fBzsh/complist\fP module in \fIzshmodules\fP(1))\&. 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\&. +.RS +.PP +The value may contain the escape sequences: +`\fB%l\fP\&' or `\fB%L\fP', which will be replaced by the number of the last line +displayed and the total number of lines; `\fB%m\fP\&' or `\fB%M\fP', +the number of the last match shown and the total number of +matches; and `\fB%p\fP\&' and `\fB%P\fP', `\fBTop\fP' +when at the beginning of the list, `\fBBottom\fP\&' 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 `\fB%S\fP\&', `\fB%s\fP', `\fB%B\fP', `\fB%b\fP', `\fB%U\fP', +`\fB%u\fP\&' for entering and leaving the display modes +standout, bold and underline, and `\fB%F\fP\&', `\fB%f\fP', `\fB%K\fP', `\fB%k\fP' for +changing the foreground background colour, are also available, as is the form +`\fB%{\fP\&.\&.\&.\fB%}\fP\&' for enclosing escape sequences which display with zero +(or, with a numeric argument, some other) width\&. +.PP +After deleting this prompt the variable \fBLISTPROMPT\fP should be unset for +the removal to take effect\&. +.RE +.TP +\fBlist\-rows\-first\fP +This style is tested in the same way as the \fBlist\-packed\fP style and +determines whether matches are to be listed in a rows\-first fashion as +if the \fBLIST_ROWS_FIRST\fP option were set\&. +.TP +\fBlist\-separator\fP +The value of this style is used in completion listing to separate the +string to complete from a description when possible (e\&.g\&. when +completing options)\&. It defaults to `\fB\-\fP\fB\-\fP\&' (two hyphens)\&. +.TP +\fBlist\-suffixes\fP +This style is used by the function that completes filenames\&. If it is +`true\&', and completion is attempted on a string containing multiple partially +typed pathname components, all ambiguous components will be shown\&. +Otherwise, completion stops at the first ambiguous component\&. +.TP +\fBlocal\fP +This is for use with functions that complete URLs for which the +corresponding files are available directly from the 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\&. +.RS +.PP +For example: +.PP +.RS +.nf +\fBzstyle \&':completion:*' local toast \e + /var/http/public/toast public_html\fP +.fi +.RE +.PP +Completion after `\fBhttp://toast/stuff/\fP\&' will look for files in the +directory \fB/var/http/public/toast/stuff\fP, while completion after +`\fBhttp://toast/~yousir/\fP\&' will look for files in the directory +\fB~yousir/public_html\fP\&. +.RE +.TP +\fBmail\-directory\fP +If set, zsh will assume that mailbox files can be found in +the directory specified\&. It defaults to `\fB~/Mail\fP\&'\&. +.TP +\fBmatch\-original\fP +This is used by the \fB_match\fP completer\&. If it is set to +\fBonly\fP, \fB_match\fP will try to generate matches without inserting a +`\fB*\fP\&' at the cursor position\&. If set to any other non\-empty value, +it will first try to generate matches without inserting the `\fB*\fP\&' +and if that yields no matches, it will try again with the `\fB*\fP\&' +inserted\&. If it is unset or set to the empty string, matching will +only be performed with the `\fB*\fP\&' inserted\&. +.TP +\fBmatcher\fP +This style is tested separately for each tag valid in the current +context\&. Its value is placed before any match specifications given by the +\fBmatcher\-list\fP style so can override them via the use of an \fBx:\fP +specification\&. The value should be in the form described in +the section `Completion Matching Control\&' in \fIzshcompwid\fP(1)\&. For examples of this, see the description of the \fBtag\-order\fP style\&. +.RS +.PP +For notes comparing the use of this and the \fBmatcher\-list\fP style, see +under the description of the \fBtag\-order\fP style\&. +.RE +.TP +\fBmatcher\-list\fP +This style can be set to a list of match specifications that are to +be applied everywhere\&. Match specifications are described in +the section `Completion Matching Control\&' in \fIzshcompwid\fP(1)\&. +The completion system will try them one after another for each completer +selected\&. For example, to try first simple completion and, if that +generates no matches, case\-insensitive completion: +.RS +.PP +.RS +.nf +\fBzstyle \&':completion:*' matcher\-list '' 'm:{a\-zA\-Z}={A\-Za\-z}'\fP +.fi +.RE +.PP +By default each specification replaces the previous one; however, if a +specification is prefixed with \fB+\fP, it is added to the existing list\&. +Hence it is possible to create increasingly general specifications +without repetition: +.PP +.RS +.nf +\fBzstyle \&':completion:*' matcher\-list \e + \&'' '+m:{a\-z}={A\-Z}' '+m:{A\-Z}={a\-z}'\fP +.fi +.RE +.PP +It is possible to create match specifications valid for particular +completers by using the third field of the context\&. This applies only +to completers that override the global matcher\-list, which as of this +writing includes only \fB_prefix\fP and \fB_ignored\fP\&. For example, to +use the completers \fB_complete\fP and \fB_prefix\fP but allow +case\-insensitive completion only with \fB_complete\fP: +.PP +.RS +.nf +\fBzstyle \&':completion:*' completer _complete _prefix +zstyle \&':completion:*:complete:*:*:*' matcher\-list \e + \&'' 'm:{a\-zA\-Z}={A\-Za\-z}'\fP +.fi +.RE +.PP +User\-defined names, as explained for the \fBcompleter\fP 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: +.PP +.RS +.nf +\fBzstyle \&':completion:*' completer \e + _complete _correct _complete:foo +zstyle \&':completion:*:complete:*:*:*' matcher\-list \e + \&'' 'm:{a\-zA\-Z}={A\-Za\-z}' +zstyle \&':completion:*:foo:*:*:*' matcher\-list \e + \&'m:{a\-zA\-Z}={A\-Za\-z} r:|[\-_\&./]=* r:|=*'\fP +.fi +.RE +.PP +If the style is unset in any context no match specification is applied\&. +Note also that some completers such as \fB_correct\fP and \fB_approximate\fP +do not use the match specifications at all, though these completers will +only ever be called once even if the \fBmatcher\-list\fP contains more than +one element\&. +.PP +Where multiple specifications are useful, note that the \fIentire\fP +completion is done for each element of \fBmatcher\-list\fP, 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\&. +.PP +If there is no current matcher or it is empty, and the option +\fBNO_CASE_GLOB\fP is in effect, the matching for files is performed +case\-insensitively in any case\&. However, any matcher must +explicitly specify case\-insensitive matching if that is required\&. +.PP +For notes comparing the use of this and the \fBmatcher\fP style, see +under the description of the \fBtag\-order\fP style\&. +.RE +.TP +\fBmax\-errors\fP +This is used by the \fB_approximate\fP and \fB_correct\fP 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\&. +.RS +.PP +If the value for this style contains the string `\fBnumeric\fP\&', the +completer function will take any numeric argument as the +maximum number of errors allowed\&. For example, with +.PP +.RS +.nf +\fBzstyle \&':completion:*:approximate:::' max\-errors 2 numeric\fP +.fi +.RE +.PP +two errors are allowed if no numeric argument is given, but with +a numeric argument of six (as in `\fBESC\-6 TAB\fP\&'), up to six +errors are accepted\&. Hence with a value of `\fB0 numeric\fP\&', no correcting +completion will be attempted unless a numeric argument is given\&. +.PP +If the value contains the string `\fBnot\-numeric\fP\&', the completer +will \fInot\fP try to generate corrected +completions when given a numeric argument, so in this case the number given +should be greater than zero\&. For example, `\fB2 not\-numeric\fP\&' specifies that +correcting completion with two errors will usually be performed, but if a +numeric argument is given, correcting completion will not be +performed\&. +.PP +The default value for this style is `\fB2 numeric\fP\&'\&. +.RE +.TP +\fBmax\-matches\-width\fP +This style is used to determine the trade off between the width of the +display used for matches and the width used for their descriptions when +the \fBverbose\fP style is in effect\&. The value gives the number of +display columns to reserve for the matches\&. The default is half the +width of the screen\&. +.RS +.PP +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\&. +.RE +.TP +\fBmenu\fP +If this is `true\&' in the context of any of the tags defined +for the current completion menu completion will be used\&. The value for +a specific tag will take precedence over that for the `\fBdefault\fP\&' tag\&. +.RS +.PP +If none of the values found in this way is `true\&' but at least +one is set to `\fBauto\fP\&', the shell behaves as if the \fBAUTO_MENU\fP +option is set\&. +.PP +If one of the values is explicitly set to `false\&', menu +completion will be explicitly turned off, overriding the +\fBMENU_COMPLETE\fP option and other settings\&. +.PP +In the form `\fByes=\fP\fInum\fP\&', where `\fByes\fP' may be any of the +`true\&' values (`\fByes\fP', `\fBtrue\fP', `\fBon\fP' and `\fB1\fP'), +menu completion will be turned on if there are at least \fInum\fP matches\&. +In the form `\fByes=long\fP\&', 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 `\fByes=long\-list\fP\&' +(Typically, the value `\fBselect=long\-list\fP\&' described later is more +useful as it provides control over scrolling\&.) +.PP +Similarly, with any of the `false\&' values (as in `\fBno=10\fP'), menu +completion will \fInot\fP be used if there are \fInum\fP or more matches\&. +.PP +The value of this widget also controls menu selection, as implemented by +the \fBzsh/complist\fP module\&. The following values may appear either +alongside or instead of the values above\&. +.PP +If the value contains the string `\fBselect\fP\&', menu selection +will be started unconditionally\&. +.PP +In the form `\fBselect=\fP\fInum\fP\&', menu selection will only be started if +there are at least \fInum\fP matches\&. If the values for more than one +tag provide a number, the smallest number is taken\&. +.PP +Menu selection can be turned off explicitly by defining a value +containing the string`\fBno\-select\fP\&'\&. +.PP +It is also possible to start menu selection only if the list of +matches does not fit on the screen by using the value +`\fBselect=long\fP\&'\&. To start menu selection even if the current widget +only performs listing, use the value `\fBselect=long\-list\fP\&'\&. +.PP +To turn on menu completion or menu selection when there are a certain +number of matches \fIor\fP the list of matches does not fit on the +screen, both of `\fByes=\fP\&' and `\fBselect=\fP' may be given twice, once +with a number and once with `\fBlong\fP\&' or `\fBlong\-list\fP'\&. +.PP +Finally, it is possible to activate two special modes of menu selection\&. +The word `\fBinteractive\fP\&' in the value causes interactive mode +to be entered immediately when menu selection is started; see +the description of the \fBzsh/complist\fP module in \fIzshmodules\fP(1) +for a description of interactive mode\&. Including the string +`\fBsearch\fP\&' does the same for incremental search mode\&. To select backward +incremental search, include the string `\fBsearch\-backward\fP\&'\&. +.RE +.TP +\fBmuttrc\fP +If set, gives the location of the mutt configuration file\&. It defaults +to `\fB~/\&.muttrc\fP\&'\&. +.TP +\fBnumbers\fP +This is used with the \fBjobs\fP tag\&. If it is `true\&', the shell will +complete job numbers instead of the shortest unambiguous prefix +of the job command text\&. 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 `\fB1\fP\&', strings will +only be used if all jobs differ in the first word on their command lines\&. +.TP +\fBold\-list\fP +This is used by the \fB_oldlist\fP completer\&. If it is set to `\fBalways\fP\&', +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 `\fBnever\fP\&', giving the behaviour without the \fB_oldlist\fP +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 +\fB_oldlist\fP\&. 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\&. +.RS +.PP +For example, suppose you type \fB^Xc\fP to use the \fB_correct_word\fP +widget, which generates a list of corrections for the word under the +cursor\&. Usually, typing \fB^D\fP would generate a standard list of +completions for the word on the command line, and show that\&. With +\fB_oldlist\fP, it will instead show the list of corrections already +generated\&. +.PP +As another example consider the \fB_match\fP completer: with the +\fBinsert\-unambiguous\fP 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 \fB_oldlist\fP completer and setting this style +to \fB_match\fP, the list of matches generated on the first attempt will be +used again\&. +.RE +.TP +\fBold\-matches\fP +This is used by the \fB_all_matches\fP completer to decide if an old +list of matches should be used if one exists\&. This is selected by one of +the `true\&' values or by the string `\fBonly\fP'\&. If +the value is `\fBonly\fP\&', \fB_all_matches\fP will only use an old list +and won\&'t have any effect on the list of matches currently being +generated\&. +.RS +.PP +If this style is set it is generally unwise to call the \fB_all_matches\fP +completer unconditionally\&. One possible use is for either this style or +the \fBcompleter\fP style to be defined with the \fB\-e\fP option to +\fBzstyle\fP to make the style conditional\&. +.RE +.TP +\fBold\-menu\fP +This is used by the \fB_oldlist\fP completer\&. It controls how menu +completion behaves when a completion has already been inserted and the +user types a standard completion key such as \fBTAB\fP\&. The default +behaviour of \fB_oldlist\fP 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 \fB_oldlist\fP completer\&. +.RS +.PP +For example, suppose you type \fB^Xc\fP 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 \fBTAB\fP at this point would start +trying to complete the line as it now appears\&. With \fB_oldlist\fP, it +instead continues to cycle through the list of corrections\&. +.RE +.TP +\fBoriginal\fP +This is used by the \fB_approximate\fP and \fB_correct\fP +completers to decide if the original string should be added as +a 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 the style will be examined with the +completer field in the context name set to \fBcorrect\-\fP\fInum\fP or +\fBapproximate\-\fP\fInum\fP, where \fInum\fP is the number of errors that +were accepted\&. +.TP +\fBpackageset\fP +This style is used when completing arguments of the Debian `\fBdpkg\fP\&' +program\&. It contains an override for the default package set +for a given context\&. For example, +.RS +.PP +.RS +.nf +\fBzstyle \&':completion:*:complete:dpkg:option\-\-status\-1:*' \e + packageset avail\fP +.fi +.RE +.PP +causes available packages, rather than only installed packages, +to be completed for `\fBdpkg \-\fP\fB\-status\fP\&'\&. +.RE +.TP +\fBpath\fP +The function that completes color names uses this style with the +\fBcolors\fP tag\&. The value should be the pathname of a file +containing color names in the format of an X11 \fBrgb\&.txt\fP 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\&. +.TP +\fBpath\-completion\fP +This is used by filename completion\&. By default, filename completion +examines all components of a path to see if there are completions of +that component\&. For example, \fB/u/b/z\fP can be completed to +\fB/usr/bin/zsh\fP\&. Explicitly setting this style to `false\&' inhibits this +behaviour for path components up to the \fB/\fP before the cursor; this +overrides the setting of \fBaccept\-exact\-dirs\fP\&. +.RS +.PP +Even with the style set to `false\&', it is still possible to complete +multiple paths by setting the option \fBCOMPLETE_IN_WORD\fP and moving the +cursor back to the first component in the path to be completed\&. For +example, \fB/u/b/z\fP can be completed to \fB/usr/bin/zsh\fP if the cursor is +after the \fB/u\fP\&. +.RE +.TP +\fBpine\-directory\fP +If set, specifies the directory containing PINE mailbox files\&. There +is no default, since recursively searching this directory is inconvenient +for anyone who doesn\&'t use PINE\&. +.TP +\fBports\fP +A list of Internet service names (network ports) to complete\&. If this is +not set, service names are taken from the file `\fB/etc/services\fP\&'\&. +.TP +\fBprefix\-hidden\fP +This is used for certain completions which share a common prefix, for +example command options beginning with dashes\&. If it is `true\&', the +prefix will not be shown in the list of matches\&. +.RS +.PP +The default value for this style is `false\&'\&. +.RE +.TP +\fBprefix\-needed\fP +This style is also relevant for matches with a common prefix\&. If it is +set to `true\&' this common prefix must be typed by the user to generate +the matches\&. +.RS +.PP +The style is applicable to the \fBoptions\fP, \fBsignals\fP, \fBjobs\fP, +\fBfunctions\fP, and \fBparameters\fP completion tags\&. +.PP +For command options, this means that the initial `\fB\-\fP\&', `\fB+\fP', or +`\fB\-\fP\fB\-\fP\&' must be typed explicitly before option names will be +completed\&. +.PP +For signals, an initial `\fB\-\fP\&' is required before signal names will +be completed\&. +.PP +For jobs, an initial `\fB%\fP\&' is required before job names will be +completed\&. +.PP +For function and parameter names, an initial `\fB_\fP\&' or `\fB\&.\fP' is +required before function or parameter names starting with those +characters will be completed\&. +.PP +The default value for this style is `false\&' for \fBfunction\fP and +\fBparameter\fP completions, and `true\&' otherwise\&. +.RE +.TP +\fBpreserve\-prefix\fP +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 `\fB//\fP\&' (double slash) has a special meaning; setting +this style to the string `\fB//\fP\&' will preserve it\&. As another example, +setting this style to `\fB?:/\fP\&' under Cygwin would allow completion +after `\fBa:/\&.\&.\&.\fP\&' and so on\&. +.TP +\fBrange\fP +This is used by the \fB_history\fP completer and the +\fB_history_complete_word\fP bindable command to decide which words +should be completed\&. +.RS +.PP +If it is a single number, only the last \fIN\fP words from the history +will be completed\&. +.PP +If it is a range of the form `\fImax\fP\fB:\fP\fIslice\fP\&', +the last \fIslice\fP words will be completed; then if that +yields no matches, the \fIslice\fP words before those will be tried and +so on\&. This process stops either when at least one match has been +found, or \fImax\fP words have been tried\&. +.PP +The default is to complete all words from the history at once\&. +.RE +.TP +\fBrecursive\-files\fP +If this style is set, its value is an array of patterns to be +tested against `\fB$PWD/\fP\&': note the trailing slash, which allows +directories in the pattern to be delimited unambiguously by including +slashes on both sides\&. If an ordinary file completion fails +and the word on the command line does not yet have a directory part to its +name, the style is retrieved using the same tag as for the completion +just attempted, then the elements tested against \fB$PWD/\fP in turn\&. +If one matches, then the shell reattempts completion by prepending the word +on the command line with each directory in the expansion of \fB**/*(/)\fP +in turn\&. Typically the elements of the style will be set to restrict +the number of directories beneath the current one to a manageable +number, for example `\fB*/\&.git/*\fP\&'\&. +.RS +.PP +For example, +.PP +.RS +.nf +\fBzstyle \&':completion:*' recursive\-files '*/zsh/*'\fP +.fi +.RE +.PP +If the current directory is \fB/home/pws/zsh/Src\fP, then +\fBzle_tr<TAB>\fP can be completed to \fBZle/zle_tricky\&.c\fP\&. +.RE +.TP +\fBregular\fP +This style is used by the \fB_expand_alias\fP 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\&. If it is set to `\fBalways\fP\&', +regular aliases will be expanded even if not in command position\&. +.TP +\fBrehash\fP +If this is set when completing external commands, the internal +list (hash) of commands will be updated for each search by issuing +the \fBrehash\fP command\&. There is a speed penalty for this which +is only likely to be noticeable when directories in the path have +slow file access\&. +.TP +\fBremote\-access\fP +If set to `false\&', certain commands will be prevented from making +Internet connections to retrieve remote information\&. This includes the +completion for the \fBCVS\fP command\&. +.RS +.PP +It is not always possible to know if connections are in fact to a remote +site, so some may be prevented unnecessarily\&. +.RE +.TP +\fBremove\-all\-dups\fP +The \fB_history_complete_word\fP bindable command and the \fB_history\fP +completer use this to decide if all duplicate matches should be +removed, rather than just consecutive duplicates\&. +.TP +\fBselect\-prompt\fP +If this is set for the \fBdefault\fP tag, its +value will be displayed during menu selection (see the \fBmenu\fP style +above) when the completion list does not fit on the screen as a +whole\&. The same escapes as for the \fBlist\-prompt\fP style are +understood, except that the numbers refer to the match or line the mark is +on\&. A default prompt is used when the value is the empty string\&. +.TP +\fBselect\-scroll\fP +This style is tested for the \fBdefault\fP tag and determines how a +completion list is scrolled during a menu selection (see the \fBmenu\fP +style above) when the completion list does not fit on the screen as a +whole\&. If the value is `\fB0\fP\&' (zero), the list is scrolled by +half\-screenfuls; if it is a positive integer, the list is scrolled by the +given number of lines; if it is a negative number, the list is scrolled by a +screenful minus the absolute value of the given number of lines\&. +The default is to scroll by single lines\&. +.TP +\fBseparate\-sections\fP +This style is used with the \fBmanuals\fP tag when completing names of +manual pages\&. If it is `true\&', entries for different sections are +added separately using tag names of the form `\fBmanuals\&.\fP\fIX\fP\&', +where \fIX\fP is the section number\&. When the \fBgroup\-name\fP style is +also in effect, pages from different sections will appear separately\&. +This style is also used similarly with the \fBwords\fP style when +completing words for the dict command\&. It allows words from different +dictionary databases to be added separately\&. See also \fBinsert\-sections\fP\&. +.RS +.PP +The default for this style is `false\&'\&. +.RE +.TP +\fBshow\-ambiguity\fP +If the \fBzsh/complist\fP module is loaded, this style can be used to +highlight the first ambiguous character in completion lists\&. The +value is either a color indication such as those supported by the +\fBlist\-colors\fP style or, with a value of `true\&', a default of +underlining is selected\&. The highlighting is only applied if the +completion display strings correspond to the actual matches\&. +.TP +\fBshow\-completer\fP +Tested whenever a new completer is tried\&. If it is `true\&', the completion +system outputs a progress message in the listing area showing what +completer is being tried\&. The message will be overwritten by any output +when completions are found and is removed after completion is finished\&. +.TP +\fBsingle\-ignored\fP +This is used by the \fB_ignored\fP completer when there is only one match\&. +If its value is `\fBshow\fP\&', the single match will be +displayed but not inserted\&. If the value is `\fBmenu\fP\&', then the single +match and the original string are both added as matches and menu completion +is started, making it easy to select either of them\&. +.TP +\fBsort\fP +This allows the standard ordering of matches to be overridden\&. +.RS +.PP +If its value is `\fBtrue\fP\&' or `\fBfalse\fP', sorting is enabled or disabled\&. +Additionally the values associated with the `\fB\-o\fP\&' option to \fBcompadd\fP can +also be listed: \fBmatch\fP, \fBnosort\fP, \fBnumeric\fP, \fBreverse\fP\&. If it is not +set for the context, the standard behaviour of the calling widget is used\&. +.PP +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\&. +.PP +In many cases where a calling widget explicitly selects a particular ordering +in lieu of the default, a value of `\fBtrue\fP\&' is not honoured\&. An example of +where this is not the case is for command history where the default of sorting +matches chronologically may be overridden by setting the style to `true\&'\&. +.PP +In the \fB_expand\fP completer, if it is set to +`true\&', the expansions generated will always be sorted\&. If it is set +to `\fBmenu\fP\&', then the expansions are only sorted when they are offered +as single strings but not in the string containing all possible +expansions\&. +.RE +.TP +\fBspecial\-dirs\fP +Normally, the completion code will not produce the directory names +`\fB\&.\fP\&' and `\fB\&.\&.\fP' as possible completions\&. If this style is set to +`true\&', it will add both `\fB\&.\fP' and `\fB\&.\&.\fP' as possible completions; +if it is set to `\fB\&.\&.\fP\&', only `\fB\&.\&.\fP' will be added\&. +.RS +.PP +The following example sets \fBspecial\-dirs\fP to `\fB\&.\&.\fP\&' when the +current prefix is empty, is a single `\fB\&.\fP\&', or consists only of a path +beginning with `\fB\&.\&./\fP\&'\&. Otherwise the value is `false'\&. +.PP +.RS +.nf +\fBzstyle \-e \&':completion:*' special\-dirs \e + \&'[[ $PREFIX = (\&.\&./)#(|\&.|\&.\&.) ]] && reply=(\&.\&.)'\fP +.fi +.RE +.RE +.TP +\fBsqueeze\-slashes\fP +If set to `true\&', sequences of slashes in filename paths (for example in +`\fBfoo//bar\fP\&') will be treated as a single slash\&. This is the usual +behaviour of UNIX paths\&. However, by default the file completion +function behaves as if there were a `\fB*\fP\&' between the slashes\&. +.TP +\fBstop\fP +If set to `true\&', the \fB_history_complete_word\fP bindable +command will stop once when reaching the beginning or end of the +history\&. Invoking \fB_history_complete_word\fP will then wrap around to +the opposite end of the history\&. If this style is set to `false\&' (the +default), \fB_history_complete_word\fP will loop immediately as in a +menu completion\&. +.TP +\fBstrip\-comments\fP +If set to `true\&', this style causes non\-essential comment text to be +removed from completion matches\&. Currently it is only used when +completing e\-mail addresses where it removes any display name from the +addresses, cutting them down to plain \fIuser@host\fP form\&. +.TP +\fBsubst\-globs\-only\fP +This is used by the \fB_expand\fP 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 \fBsubstitute\fP style +described below, but these were not further changed by globbing, the +expansions will be rejected\&. +.RS +.PP +The default for this style is `false\&'\&. +.RE +.TP +\fBsubstitute\fP +This boolean style controls whether the \fB_expand\fP completer will +first try to expand all substitutions in the string (such as +`\fB$(\fP\fI\&.\&.\&.\fP\fB)\fP\&' and `\fB${\fP\fI\&.\&.\&.\fP\fB}\fP')\&. +.RS +.PP +The default is `true\&'\&. +.RE +.TP +\fBsuffix\fP +This is used by the \fB_expand\fP 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 `\fB~foo\fP\&' or `\fB$foo\fP' rather than `\fB~foo/\fP' or +`\fB$foo/bar\fP\&', unless that suffix itself contains characters eligible +for expansion\&. The default for this style is `true\&'\&. +.TP +\fBtag\-order\fP +This provides a mechanism for sorting how the tags available in a +particular context will be used\&. +.RS +.PP +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 \fBfile\-patterns\fP style for +an exception to this behavior\&.) +.PP +For example: +.PP +.RS +.nf +\fBzstyle \&':completion:*:complete:\-command\-:*:*' tag\-order \e + \&'commands functions'\fP +.fi +.RE +.PP +specifies that completion in command position first offers +external commands and shell functions\&. Remaining tags will be tried if +no completions are found\&. +.PP +In addition to tag names, each string in the value may take one of the +following forms: +.PP +.PD 0 +.TP +.PD +\fB\-\fP +If any value consists of only a hyphen, +then \fIonly\fP the tags specified in the other values are +generated\&. Normally all tags not explicitly selected are tried last +if the specified tags fail to generate any matches\&. This means +that a single value consisting only of a single hyphen +turns off completion\&. +.TP +\fB!\fP \fItags\fP\&.\&.\&. +A string starting with an exclamation mark +specifies names of tags that are \fInot\fP to be used\&. The effect is +the same as if all other possible tags for the context had been +listed\&. +.TP +\fItag\fP\fB:\fP\fIlabel\fP \&.\&.\&. +Here, \fItag\fP is one of the standard tags and \fIlabel\fP is an +arbitrary name\&. Matches are generated as normal but the name \fIlabel\fP +is used in contexts instead of \fItag\fP\&. This is not useful in words +starting with \fB!\fP\&. +.RS +.PP +If the \fIlabel\fP starts with a hyphen, the \fItag\fP is prepended to the +\fIlabel\fP 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\&. +.RE +.TP +\fItag\fP\fB:\fP\fIlabel\fP\fB:\fP\fIdescription\fP +As before, but \fBdescription\fP will replace the `\fB%d\fP\&' in +the value of the \fBformat\fP style instead of the default description +supplied by the completion function\&. Spaces in the description must +be quoted with a backslash\&. A `\fB%d\fP\&' appearing +in \fIdescription\fP is replaced with the description given by the +completion function\&. +.PP +In any of the forms above the tag may be a pattern or several +patterns in the form `\fB{\fP\fIpat1\fP\fB,\fP\fIpat2\&.\&.\&.\fP\fB}\fP\&'\&. In this +case all matching tags will be used except +for any given explicitly in the same string\&. +.PP +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: +.PP +.RS +.nf +\fBzstyle \&':completion:*:*:\-command\-:*:*' tag\-order \e + \&'functions:\-non\-comp *' functions +zstyle \&':completion:*:functions\-non\-comp' \e + ignored\-patterns \&'_*'\fP +.fi +.RE +.PP +On the first attempt, all tags will be offered but the \fBfunctions\fP tag +will be replaced by \fBfunctions\-non\-comp\fP\&. The \fBignored\-patterns\fP style +is set for this tag to exclude functions starting with an underscore\&. +If there are no matches, the second value of the +\fBtag\-order\fP style is used which completes functions using the default +tag, this time presumably including all function names\&. +.PP +The matches for one tag can be split into different groups\&. For example: +.PP +.RS +.nf +\fBzstyle \&':completion:*' tag\-order \e + \&'options:\-long:long\e options + options:\-short:short\e options + options:\-single\-letter:single\e letter\e options\&' +zstyle \&':completion:*:options\-long' \e + ignored\-patterns \&'[\-+](|\-|[^\-]*)' +zstyle \&':completion:*:options\-short' \e + ignored\-patterns \&'\-\-*' '[\-+]?' +zstyle \&':completion:*:options\-single\-letter' \e + ignored\-patterns \&'???*'\fP +.fi +.RE +.PP +With the \fBgroup\-names\fP style set, options beginning with +`\fB\-\fP\fB\-\fP\&', options beginning with a single `\fB\-\fP' or `\fB+\fP' but +containing multiple characters, and single\-letter options will be +displayed in separate groups with different descriptions\&. +.PP +Another use of patterns is to +try multiple match specifications one after another\&. The +\fBmatcher\-list\fP 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 \fBfoo\fP: +.PP +.RS +.nf +\fBzstyle \&':completion:*:*:foo:*:*' tag\-order '*' '*:\-case' +zstyle \&':completion:*\-case' matcher 'm:{a\-z}={A\-Z}'\fP +.fi +.RE +.PP +First, all the tags offered when completing after \fBfoo\fP are tried using +the normal tag name\&. If that generates no matches, the second value of +\fBtag\-order\fP is used, which tries all tags again except that this time +each has \fB\-case\fP appended to its name for lookup of styles\&. Hence this +time the value for the \fBmatcher\fP style from the second call to \fBzstyle\fP +in the example is used to make completion case\-insensitive\&. +.PP +It is possible to use the \fB\-e\fP option of the \fBzstyle\fP builtin +command to specify conditions for the use of particular tags\&. For +example: +.PP +.RS +.nf +\fBzstyle \-e \&'*:\-command\-:*' tag\-order ' + if [[ \-n $PREFIX$SUFFIX ]]; then + reply=( ) + else + reply=( \- ) + fi\&'\fP +.fi +.RE +.PP +Completion in command position will be attempted only if the string +typed so far is not empty\&. This is tested using the \fBPREFIX\fP +special parameter; see +zshcompwid +for a description of parameters which are special inside completion widgets\&. +Setting \fBreply\fP 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\&. +.PP +If no \fBtag\-order\fP style has been defined for a context, the strings +`\fB(|*\-)argument\-* (|*\-)option\-* values\fP\&' and `\fBoptions\fP' 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\&. +.RE +.TP +\fBurls\fP +This is used together with the \fBurls\fP tag by +functions completing URLs\&. +.RS +.PP +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\&. +.PP +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)\&. +.PP +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 +`\fBhttp\fP\&', `\fBftp\fP', `\fBbookmark\fP' and so on\&. In many cases the next +level of directories will be a filename\&. The directory hierarchy can +descend as deep as necessary\&. +.PP +For example, +.PP +.RS +.nf +\fBzstyle \&':completion:*' urls ~/\&.urls +mkdir \-p ~/\&.urls/ftp/ftp\&.zsh\&.org/pub +\fP +.fi +.RE +.PP +allows completion of all the components of the URL +\fBftp://ftp\&.zsh\&.org/pub\fP after suitable commands such as +`\fBnetscape\fP\&' or `\fBlynx\fP'\&. Note, however, that access methods and +files are completed separately, so if the \fBhosts\fP style is set hosts +can be completed without reference to the \fBurls\fP style\&. +.PP +See the description in the function \fB_urls\fP itself +for more information (e\&.g\&. `\fBmore $^fpath/_urls(N)\fP\&')\&. +.RE +.TP +\fBuse\-cache\fP +If this is set, the completion caching layer is activated for any completions +which use it (via the \fB_store_cache\fP, \fB_retrieve_cache\fP, and +\fB_cache_invalid\fP functions)\&. The directory containing the cache +files can be changed with the \fBcache\-path\fP style\&. +.TP +\fBuse\-compctl\fP +If this style is set to a string \fInot\fP equal to \fBfalse\fP, \fB0\fP, +\fBno\fP, and \fBoff\fP, the completion system may use any completion +specifications defined with the \fBcompctl\fP builtin command\&. If the +style is unset, this is done only if the \fBzsh/compctl\fP module +is loaded\&. The string may also contain the substring `\fBfirst\fP\&' to +use completions defined with `\fBcompctl \-T\fP\&', and the substring +`\fBdefault\fP\&' to use the completion defined with `\fBcompctl \-D\fP'\&. +.RS +.PP +Note that this is only intended to smooth the transition from +\fBcompctl\fP to the new completion system and may disappear in the +future\&. +.PP +Note also that the definitions from \fBcompctl\fP will only be used if +there is no specific completion function for the command in question\&. For +example, if there is a function \fB_foo\fP to complete arguments to the +command \fBfoo\fP, \fBcompctl\fP will never be invoked for \fBfoo\fP\&. +However, the \fBcompctl\fP version will be tried if \fBfoo\fP only uses +default completion\&. +.RE +.TP +\fBuse\-ip\fP +By default, the function \fB_hosts\fP that completes host names strips +IP addresses from entries read from host databases such as NIS and +ssh files\&. If this style is `true\&', the corresponding IP addresses +can be completed as well\&. This style is not use in any context +where the \fBhosts\fP style is set; note also it must be set before +the cache of host names is generated (typically the first completion +attempt)\&. +.TP +\fBusers\fP +This may be set to a list of usernames to be completed\&. +If it is not set all usernames will be completed\&. +Note that if it is set only that list of users will be completed; +this is because on some systems querying all users can take +a prohibitive amount of time\&. +.TP +\fBusers\-hosts\fP +The values of this style should be of the form +`\fIuser\fP\fB@\fP\fIhost\fP\&' or `\fIuser\fP\fB:\fP\fIhost\fP'\&. It is used for +commands that need pairs of +user\- and hostnames\&. These commands will complete usernames from this +style (only), and will restrict subsequent hostname completion to hosts +paired with that user in one of the values of the style\&. +.RS +.PP +It is possible to group values for sets of commands which allow a remote +login, such as \fBrlogin\fP and \fBssh\fP, by using the \fBmy\-accounts\fP tag\&. +Similarly, values for sets of commands which usually refer to the +accounts of other people, such as \fBtalk\fP and \fBfinger\fP, can be +grouped by using the \fBother\-accounts\fP tag\&. More ambivalent commands +may use the \fBaccounts\fP tag\&. +.RE +.TP +\fBusers\-hosts\-ports\fP +Like \fBusers\-hosts\fP but used for commands like \fBtelnet\fP and +containing strings of the form `\fIuser\fP\fB@\fP\fIhost\fP\fB:\fP\fIport\fP\&'\&. +.TP +\fBverbose\fP +If set, as it is by default, the completion listing is more verbose\&. +In particular many commands show descriptions for options if this +style is `true\&'\&. +.TP +\fBword\fP +This is used by the \fB_list\fP 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\&. +.PP +.SH "CONTROL FUNCTIONS" +.PP +The initialization script \fBcompinit\fP redefines all the widgets +which perform completion to call the supplied widget function +\fB_main_complete\fP\&. This function acts as a wrapper calling the +so\-called `completer\&' functions that generate matches\&. If +\fB_main_complete\fP 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 +\fBcompleter\fP style\&. For example, to use normal completion and +correction if that doesn\&'t generate any matches: +.PP +.RS +.nf +\fBzstyle \&':completion:*' completer _complete _correct\fP +.fi +.RE +.PP +after calling \fBcompinit\fP\&. The default value for this style is +`\fB_complete _ignored\fP\&', i\&.e\&. normally only ordinary completion is tried, +first with the effect of the \fBignored\-patterns\fP style and then without +it\&. The \fB_main_complete\fP function uses the return status of the completer +functions to decide if other completers should be called\&. If the return +status is zero, no other completers are tried and the \fB_main_complete\fP +function returns\&. +.PP +If the first argument to \fB_main_complete\fP 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 \fIcompleter\fP field of the +context and the other arguments give a command name and arguments to +call to generate the matches\&. +.PP +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 `\fB:completion::complete:\fP\fI\&.\&.\&.\fP\&'\&. +.PP +.PD 0 +.TP +.PD +\fB_all_matches\fP +This completer can be used to add a string consisting of all other +matches\&. As it influences later completers it must appear as the first +completer in the list\&. The list of all matches is affected by the +\fBavoid\-completer\fP and \fBold\-matches\fP styles described above\&. +.RS +.PP +It may be useful to use the \fB_generic\fP function described below +to bind \fB_all_matches\fP to its own keystroke, for example: +.PP +.RS +.nf +\fBzle \-C all\-matches complete\-word _generic +bindkey \&'^Xa' all\-matches +zstyle \&':completion:all\-matches:*' old\-matches only +zstyle \&':completion:all\-matches::::' completer _all_matches\fP +.fi +.RE +.PP +Note that this does not generate completions by itself: first use +any of the standard ways of generating a list of completions, +then use \fB^Xa\fP to show all matches\&. It is possible instead to +add a standard completer to the list and request that the +list of all matches should be directly inserted: +.PP +.RS +.nf +\fBzstyle \&':completion:all\-matches::::' completer \e + _all_matches _complete +zstyle \&':completion:all\-matches:*' insert true\fP +.fi +.RE +.PP +In this case the \fBold\-matches\fP style should not be set\&. +.RE +.TP +\fB_approximate\fP +This is similar to the basic \fB_complete\fP completer but allows the +completions to undergo corrections\&. The maximum number of errors can be +specified by the \fBmax\-errors\fP style; see the description of +approximate matching in +\fIzshexpn\fP(1) +for how errors are counted\&. Normally this completer will only be tried +after the normal \fB_complete\fP completer: +.RS +.PP +.RS +.nf +\fBzstyle \&':completion:*' completer _complete _approximate\fP +.fi +.RE +.PP +This will give correcting completion if and only if +normal completion yields no possible completions\&. When +corrected completions are found, the completer will normally start +menu completion allowing you to cycle through these strings\&. +.PP +This completer uses the tags \fBcorrections\fP and \fBoriginal\fP when +generating the possible corrections and the original string\&. The +\fBformat\fP style for the former may contain the additional sequences +`\fB%e\fP\&' and `\fB%o\fP' which will be replaced by the number of errors +accepted to generate the corrections and the original string, +respectively\&. +.PP +The completer progressively increases the number of errors allowed up to +the limit by the \fBmax\-errors\fP style, hence if a completion is found +with one error, no completions with two errors will be shown, and so on\&. +It modifies the completer name in the context to indicate the number of +errors being tried: on the first try the completer field contains +`\fBapproximate\-1\fP\&', on the second try `\fBapproximate\-2\fP', and so on\&. +.PP +When \fB_approximate\fP is called from another function, the number of +errors to accept may be passed with the \fB\-a\fP option\&. The argument +is in the same format as the \fBmax\-errors\fP style, all in one string\&. +.PP +Note that this completer (and the \fB_correct\fP completer mentioned +below) can be quite expensive to call, especially when a large number +of errors are allowed\&. One way to avoid this is to set up the +\fBcompleter\fP style using the \fB\-e\fP option to zstyle so that some +completers are only used when completion is attempted a second time on +the same string, e\&.g\&.: +.PP +.RS +.nf +\fBzstyle \-e \&':completion:*' completer ' + if [[ $_last_try != "$HISTNO$BUFFER$CURSOR" ]]; then + _last_try="$HISTNO$BUFFER$CURSOR" + reply=(_complete _match _prefix) + else + reply=(_ignored _correct _approximate) + fi\&'\fP +.fi +.RE +.PP +This uses the \fBHISTNO\fP parameter and the \fBBUFFER\fP and \fBCURSOR\fP +special parameters that are available inside zle and completion +widgets to find out if the command line hasn\&'t changed since the last +time completion was tried\&. Only then are the \fB_ignored\fP, +\fB_correct\fP and \fB_approximate\fP completers called\&. +.RE +.TP +\fB_canonical_paths\fP [ \fB\-A\fP \fIvar\fP ] [ \fB\-N\fP ] [ \fB\-MJV12nfX\fP ] \fItag\fP \fIdescr\fP [ \fIpaths\fP \&.\&.\&. ] +This completion function completes all paths given to it, and also tries to +offer completions which point to the same file as one of the paths given +(relative path when an absolute path is given, and vice versa; when \fB\&.\&.\fP\&'s +are present in the word to be completed; and some paths got from symlinks)\&. +.RS +.PP +\fB\-A\fP, if specified, takes the paths from the array variable specified\&. Paths can +also be specified on the command line as shown above\&. \fB\-N\fP, if specified, +prevents canonicalizing the paths given before using them for completion, in +case they are already so\&. The options \fB\-M\fP, \fB\-J\fP, \fB\-V\fP, \fB\-1\fP, \fB\-2\fP, +\fB\-n\fP, \fB\-F\fP, \fB\-X\fP are passed to \fBcompadd\fP\&. +.PP +See \fB_description\fP for a description of \fItag\fP and \fIdescr\fP\&. +.RE +.TP +\fB_cmdambivalent\fP +Completes the remaining positional arguments as an external command\&. +The external command and its arguments are completed as separate arguments +(in a manner appropriate for completing \fB/usr/bin/env\fP) +if there are two or more remaining positional arguments on the command line, +and as a quoted command string (in the manner of \fBsystem(\&.\&.\&.)\fP) otherwise\&. +See also \fB_cmdstring\fP and \fB_precommand\fP\&. +.RS +.PP +This function takes no arguments\&. +.RE +.TP +\fB_cmdstring\fP +Completes an external command as a single argument, as for +\fBsystem(\&.\&.\&.)\fP\&. +.TP +\fB_complete\fP +This completer generates all possible completions in a context\-sensitive +manner, i\&.e\&. using the settings defined with the \fBcompdef\fP function +explained above and the current settings of all special parameters\&. +This gives the normal completion behaviour\&. +.RS +.PP +To complete arguments of commands, \fB_complete\fP uses the utility function +\fB_normal\fP, which is in turn responsible for finding the particular +function; it is described below\&. Various contexts of the form +\fB\-\fP\fIcontext\fP\fB\-\fP are handled specifically\&. These are all +mentioned above as possible arguments to the \fB#compdef\fP tag\&. +.PP +Before trying to find a function for a specific context, \fB_complete\fP +checks if the parameter `\fBcompcontext\fP\&' is set\&. Setting +`\fBcompcontext\fP\&' allows the usual completion dispatching to be +overridden which is useful in places such as a function that uses +\fBvared\fP for input\&. If it is set to an array, the elements are taken +to be the possible matches which will be completed using the tag +`\fBvalues\fP\&' and the description `\fBvalue\fP'\&. If it is set to an +associative array, the keys are used as the possible completions and +the values (if non\-empty) are used as descriptions for the matches\&. If +`\fBcompcontext\fP\&' is set to a string containing colons, it should be of +the form `\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP\&'\&. In this case the +\fItag\fP and \fIdescr\fP give the tag and description to use and the +\fIaction\fP indicates what should be completed in one of the forms +accepted by the \fB_arguments\fP utility function described below\&. +.PP +Finally, if `\fBcompcontext\fP\&' is set to a string without colons, the +value is taken as the name of the context to use and the function +defined for that context will be called\&. For this purpose, there is a +special context named \fB\-command\-line\-\fP that completes whole command +lines (commands and their arguments)\&. This is not used by the completion +system itself but is nonetheless handled when explicitly called\&. +.RE +.TP +\fB_correct\fP +Generate corrections, but not completions, for the current word; this is +similar to \fB_approximate\fP but will not allow any number of extra +characters at the cursor as that completer does\&. The effect is +similar to spell\-checking\&. It is based on \fB_approximate\fP, but the +completer field in the context name is \fBcorrect\fP\&. +.RS +.PP +For example, with: +.PP +.RS +.nf +\fBzstyle \&':completion:::::' completer \e + _complete _correct _approximate +zstyle \&':completion:*:correct:::' max\-errors 2 not\-numeric +zstyle \&':completion:*:approximate:::' max\-errors 3 numeric\fP +.fi +.RE +.PP +correction will accept up to two errors\&. If a numeric argument is +given, correction will not be performed, but correcting completion +will be, and will accept as many errors as given by the numeric +argument\&. Without a numeric argument, first correction and then +correcting completion will be tried, with the first one accepting two +errors and the second one accepting three errors\&. +.PP +When \fB_correct\fP is called as a function, the number of errors to accept +may be given following the \fB\-a\fP option\&. The argument is in the same +form a values to the \fBaccept\fP style, all in one string\&. +.PP +This completer function is intended to be used without the +\fB_approximate\fP completer or, as in the example, just before +it\&. Using it after the \fB_approximate\fP completer is useless since +\fB_approximate\fP will at least generate the corrected strings +generated by the \fB_correct\fP completer \-\- and probably more\&. +.RE +.TP +\fB_expand\fP +This completer function does not really perform completion, but instead +checks if the word on the command line is eligible for expansion and, +if it is, gives detailed control over how this expansion is done\&. For +this to happen, the completion system needs to be invoked with +\fBcomplete\-word\fP, not \fBexpand\-or\-complete\fP (the default binding for +\fBTAB\fP), as otherwise the string will be expanded by the shell\&'s +internal mechanism before the completion system is started\&. +Note also this completer should be called before the \fB_complete\fP +completer function\&. +.RS +.PP +The tags used when generating expansions are \fBall\-expansions\fP for the +string containing all possible expansions, \fBexpansions\fP when adding +the possible expansions as single matches and \fBoriginal\fP when adding +the original string from the line\&. The order in which these strings are +generated, if at all, can be controlled by the \fBgroup\-order\fP and +\fBtag\-order\fP styles, as usual\&. +.PP +The format string for \fBall\-expansions\fP and for \fBexpansions\fP may +contain the sequence `\fB%o\fP\&' which will be replaced by the original +string from the line\&. +.PP +The kind of expansion to be tried is controlled by the \fBsubstitute\fP, +\fBglob\fP and \fBsubst\-globs\-only\fP styles\&. +.PP +It is also possible to call \fB_expand\fP as a function, in which case the +different modes may be selected with options: \fB\-s\fP for +\fBsubstitute\fP, \fB\-g\fP for \fBglob\fP and \fB\-o\fP for \fBsubst\-globs\-only\fP\&. +.RE +.TP +\fB_expand_alias\fP +If the word the cursor is on is an alias, it is expanded and no other +completers are called\&. The types of aliases which are to be expanded can +be controlled with the styles \fBregular\fP, \fBglobal\fP and \fBdisabled\fP\&. +.RS +.PP +This function is also a bindable command, see +the section `Bindable Commands\&' below\&. +.RE +.TP +\fB_extensions\fP +If the cursor follows the string `\fB*\&.\fP\&', filename extensions are +completed\&. The extensions are taken from files in current directory or a +directory specified at the beginning of the current word\&. For exact matches, +completion continues to allow other completers such as \fB_expand\fP to +expand the pattern\&. The standard \fBadd\-space\fP and \fBprefix\-hidden\fP +styles are observed\&. +.TP +\fB_external_pwds\fP +Completes current directories of other zsh processes belonging to the +current user\&. +.RS +.PP +This is intended to be used via \fB_generic\fP, bound to a custom key +combination\&. Note that pattern matching is enabled so matching is +performed similar to how it works with the \fB_match\fP completer\&. +.RE +.TP +\fB_history\fP +Complete words from the shell\&'s command history\&. This completer +can be controlled by the \fBremove\-all\-dups\fP, and \fBsort\fP styles as for the +\fB_history_complete_word\fP bindable command, see +the section `Bindable Commands\&' below +and +the section `Completion System Configuration\&' above\&. +.TP +\fB_ignored\fP +The \fBignored\-patterns\fP style can be set to a list of patterns which are +compared against possible completions; matching ones are removed\&. +With this completer those matches can be reinstated, as +if no \fBignored\-patterns\fP style were set\&. The completer actually +generates its own list of matches; which completers are invoked +is determined in the same way as for the \fB_prefix\fP completer\&. +The \fBsingle\-ignored\fP style is also available as described above\&. +.TP +\fB_list\fP +This completer allows the insertion of matches to be delayed until +completion is attempted a second time without the word on the line +being changed\&. On the first attempt, only the list of matches will be +shown\&. It is affected by the styles \fBcondition\fP and \fBword\fP, see +the section `Completion System Configuration\&' above\&. +.TP +\fB_match\fP +This completer is intended to be used after the \fB_complete\fP +completer\&. It behaves similarly but the string on the command line may +be a pattern to match against trial completions\&. This gives the effect +of the \fBGLOB_COMPLETE\fP option\&. +.RS +.PP +Normally completion will be performed by taking the pattern from the line, +inserting a `\fB*\fP\&' at the cursor position and comparing the resulting +pattern with the possible completions generated\&. This can be modified +with the \fBmatch\-original\fP style described above\&. +.PP +The generated matches will be offered in a menu completion unless the +\fBinsert\-unambiguous\fP style is set to `true\&'; see the description above +for other options for this style\&. +.PP +Note that matcher specifications defined globally or used by the +completion functions (the styles \fBmatcher\-list\fP and \fBmatcher\fP) will +not be used\&. +.RE +.TP +\fB_menu\fP +This completer was written as simple example function to show how menu +completion can be enabled in shell code\&. However, it has the notable +effect of disabling menu selection which can be useful with +\fB_generic\fP based widgets\&. It should be used as the first completer in +the list\&. Note that this is independent of the setting of the +\fBMENU_COMPLETE\fP option and does not work with the other menu +completion widgets such as \fBreverse\-menu\-complete\fP, or +\fBaccept\-and\-menu\-complete\fP\&. +.TP +\fB_oldlist\fP +This completer controls how the standard completion widgets behave +when there is an existing list of completions which may have been +generated by a special completion (i\&.e\&. a separately\-bound completion +command)\&. It allows the ordinary completion keys to continue to use the +list of completions thus generated, instead of producing a new list of +ordinary contextual completions\&. +It should appear in the list of completers before any of +the widgets which generate matches\&. It uses two styles: \fBold\-list\fP and +\fBold\-menu\fP, see +the section `Completion System Configuration\&' above\&. +.TP +\fB_precommand\fP +Complete an external command in word\-separated arguments, as for +\fBexec\fP and \fB/usr/bin/env\fP\&. +.TP +\fB_prefix\fP +This completer can be used to try completion with the suffix (everything +after the cursor) ignored\&. In other words, the suffix will not be +considered to be part of the word to complete\&. The effect is similar +to the \fBexpand\-or\-complete\-prefix\fP command\&. +.RS +.PP +The \fBcompleter\fP style is used to decide which other completers are to +be called to generate matches\&. If this style is unset, the list of +completers set for the current context is used \-\- except, of course, the +\fB_prefix\fP completer itself\&. Furthermore, if this completer appears +more than once in the list of completers only those completers not +already tried by the last invocation of \fB_prefix\fP will be called\&. +.PP +For example, consider this global \fBcompleter\fP style: +.PP +.RS +.nf +\fBzstyle \&':completion:*' completer \e + _complete _prefix _correct _prefix:foo\fP +.fi +.RE +.PP +Here, the \fB_prefix\fP completer tries normal completion but ignoring the +suffix\&. If that doesn\&'t generate any matches, and neither does +the call to the \fB_correct\fP completer after it, \fB_prefix\fP will +be called a second time and, now only trying correction with the +suffix ignored\&. On the second invocation the completer part of the +context appears as `\fBfoo\fP\&'\&. +.PP +To use \fB_prefix\fP as the last resort and try only normal completion +when it is invoked: +.PP +.RS +.nf +\fBzstyle \&':completion:*' completer _complete \&.\&.\&. _prefix +zstyle \&':completion::prefix:*' completer _complete\fP +.fi +.RE +.PP +The \fBadd\-space\fP style is also respected\&. If it is set to `true\&' then +\fB_prefix\fP will insert a space between the matches generated (if any) +and the suffix\&. +.PP +Note that this completer is only useful if the +\fBCOMPLETE_IN_WORD\fP option is set; otherwise, the cursor will +be moved to the end of the current word before the completion code is +called and hence there will be no suffix\&. +.RE +.TP +\fB_user_expand\fP +This completer behaves similarly to the \fB_expand\fP completer but +instead performs expansions defined by users\&. The styles \fBadd\-space\fP and +\fBsort\fP styles specific to the \fB_expand\fP completer are usable with +\fB_user_expand\fP in addition to other styles handled more generally by +the completion system\&. The tag \fBall\-expansions\fP is also available\&. +.RS +.PP +The expansion depends on the array style \fBuser\-expand\fP being defined +for the current context; remember that the context for completers is less +specific than that for contextual completion as the full context has not +yet been determined\&. Elements of the array may have one of the following +forms: +.PP +.PD 0 +.TP +\fB$\fP\fIhash\fP + +\fIhash\fP is the name of an associative array\&. Note this is not a full +parameter expression, merely a \fB$\fP, suitably quoted to prevent immediate +expansion, followed by the name of an associative array\&. If the trial +expansion word matches a key in \fIhash\fP, the resulting expansion is the +corresponding value\&. +.PP +.TP +\fI_func\fP + +\fI_func\fP is the name of a shell function whose name must begin with +\fB_\fP but is not otherwise special to the completion system\&. The function +is called with the trial word as an argument\&. If the word is to be +expanded, the function should set the array \fBreply\fP to a list of +expansions\&. Optionally, it can set \fBREPLY\fP to a word that will +be used as a description for the set of expansions\&. +The return status of the function is irrelevant\&. +.PP +.PD +.RE +.PP +.SH "BINDABLE COMMANDS" +.PP +In addition to the context\-dependent completions provided, which are +expected to work in an intuitively obvious way, there are a few widgets +implementing special behaviour which can be bound separately to keys\&. The +following is a list of these and their default bindings\&. +.PP +.PD 0 +.TP +.PD +\fB_bash_completions\fP +This function is used by two widgets, \fB_bash_complete\-word\fP and +\fB_bash_list\-choices\fP\&. It exists to provide compatibility with +completion bindings in bash\&. The last character of the binding determines +what is completed: `\fB!\fP\&', command names; `\fB$\fP', environment variables; +`\fB@\fP\&', host names; `\fB/\fP', file names; `\fB~\fP' user names\&. In bash, the +binding preceded by `\fB\ee\fP\&' gives completion, and preceded by `\fB^X\fP' +lists options\&. As some of these bindings clash with standard zsh +bindings, only `\fB\ee~\fP\&' and `\fB^X~\fP' are bound by default\&. To add the +rest, the following should be added to \fB\&.zshrc\fP after \fBcompinit\fP has +been run: +.RS +.PP +.RS +.nf +\fBfor key in \&'!' '$' '@' '/' '~'; do + bindkey "\ee$key" _bash_complete\-word + bindkey "^X$key" _bash_list\-choices +done\fP +.fi +.RE +.PP +This includes the bindings for `\fB~\fP\&' in case they were already bound to +something else; the completion code does not override user bindings\&. +.RE +.TP +\fB_correct_filename\fP (\fB^XC\fP) +Correct the filename path at the cursor position\&. Allows up to six errors +in the name\&. Can also be called with an argument to correct +a filename path, independently of zle; the correction is printed on +standard output\&. +.TP +\fB_correct_word\fP (\fB^Xc\fP) +Performs correction of the current argument using the usual contextual +completions as possible choices\&. This stores the string +`\fBcorrect\-word\fP\&' in the \fIfunction\fP field of the context name and +then calls the \fB_correct\fP completer\&. +.TP +\fB_expand_alias\fP (\fB^Xa\fP) +This function can be used as a completer and as a bindable command\&. +It expands the word the cursor is on if it is an alias\&. The types of +alias expanded can be controlled with the styles \fBregular\fP, \fBglobal\fP +and \fBdisabled\fP\&. +.RS +.PP +When used as a bindable command there is one additional feature that +can be selected by setting the \fBcomplete\fP style to `true\&'\&. In this +case, if the word is not the name of an alias, \fB_expand_alias\fP tries +to complete the word to a full alias name without expanding it\&. It +leaves the cursor directly after the completed word so that invoking +\fB_expand_alias\fP once more will expand the now\-complete alias name\&. +.RE +.TP +\fB_expand_word\fP (\fB^Xe\fP) +Performs expansion on the current word: equivalent to the standard +\fBexpand\-word\fP command, but using the \fB_expand\fP completer\&. Before +calling it, the \fIfunction\fP field of the context is set to +`\fBexpand\-word\fP\&'\&. +.TP +\fB_generic\fP +This function is not defined as a widget and not bound by +default\&. However, it can be used to define a widget and will then +store the name of the widget in the \fIfunction\fP field of the context +and call the completion system\&. This allows custom completion widgets +with their own set of style settings to be defined easily\&. For example, +to define a widget that performs normal completion and starts +menu selection: +.RS +.PP +.RS +.nf +\fBzle \-C foo complete\-word _generic +bindkey \&'\&.\&.\&.' foo +zstyle \&':completion:foo:*' menu yes select=1\fP +.fi +.RE +.PP +Note in particular that the \fBcompleter\fP style may be set for the context +in order to change the set of functions used to generate possible matches\&. +If \fB_generic\fP is called with arguments, those are passed through to +\fB_main_complete\fP as the list of completers in place of those defined by +the \fBcompleter\fP style\&. +.RE +.TP +\fB_history_complete_word\fP (\fB\ee/\fP) +Complete words from the shell\&'s command history\&. This uses the +\fBlist\fP, \fBremove\-all\-dups\fP, \fBsort\fP, and \fBstop\fP styles\&. +.TP +\fB_most_recent_file\fP (\fB^Xm\fP) +Complete the name of the most recently modified file matching the pattern +on the command line (which may be blank)\&. If given a numeric argument +\fIN\fP, complete the \fIN\fPth most recently modified file\&. Note the +completion, if any, is always unique\&. +.TP +\fB_next_tags\fP (\fB^Xn\fP) +This command alters the set of matches used to that for the next tag, or +set of tags, either as given by the \fBtag\-order\fP style or as set by +default; these matches would otherwise not be available\&. +Successive invocations of the command cycle through all possible sets of +tags\&. +.TP +\fB_read_comp\fP (\fB^X^R\fP) +Prompt the user for a string, and use that to perform completion on the +current word\&. There are two possibilities for the string\&. First, it can +be a set of words beginning `\fB_\fP\&', for example `\fB_files \-/\fP', in which +case the function with any arguments will be called to generate the +completions\&. Unambiguous parts of the function name will be completed +automatically (normal completion is not available at this point) until a +space is typed\&. +.RS +.PP +Second, any other string will be passed as a set of arguments to +\fBcompadd\fP and should hence be an expression specifying what should +be completed\&. +.PP +A very restricted set of editing commands is available when reading the +string: `\fBDEL\fP\&' and `\fB^H\fP' delete the last character; `\fB^U\fP' deletes +the line, and `\fB^C\fP\&' and `\fB^G\fP' abort the function, while `\fBRET\fP' +accepts the completion\&. Note the string is used verbatim as a command +line, so arguments must be quoted in accordance with standard shell rules\&. +.PP +Once a string has been read, the next call to \fB_read_comp\fP will use the +existing string instead of reading a new one\&. To force a new string to be +read, call \fB_read_comp\fP with a numeric argument\&. +.RE +.TP +\fB_complete_debug\fP (\fB^X?\fP) +This widget performs ordinary completion, but captures in a temporary file +a trace of the shell commands executed by the completion system\&. Each +completion attempt gets its own file\&. A command to view each of these +files is pushed onto the editor buffer stack\&. +.TP +\fB_complete_help\fP (\fB^Xh\fP) +This widget displays information about the context names, +the tags, and the completion functions used +when completing at the current cursor position\&. If given a numeric +argument other than \fB1\fP (as in `\fBESC\-2 ^Xh\fP\&'), then the styles +used and the contexts for which they are used will be shown, too\&. +.RS +.PP +Note that the information about styles may be incomplete; it depends on the +information available from the completion functions called, which in turn +is determined by the user\&'s own styles and other settings\&. +.RE +.TP +\fB_complete_help_generic\fP +Unlike other commands listed here, this must be created as a normal ZLE +widget rather than a completion widget (i\&.e\&. with \fBzle \-N\fP)\&. It +is used for generating help with a widget bound to the \fB_generic\fP +widget that is described above\&. +.RS +.PP +If this widget is created using the name of the function, as it is by +default, then when executed it will read a key sequence\&. This is expected +to be bound to a call to a completion function that uses the \fB_generic\fP +widget\&. That widget will be executed, and information provided in +the same format that the \fB_complete_help\fP widget displays for +contextual completion\&. +.PP +If the widget\&'s name contains \fBdebug\fP, for example if it is created +as `\fBzle \-N _complete_debug_generic _complete_help_generic\fP\&', it +will read and execute the keystring for a generic widget as before, +but then generate debugging information as done by \fB_complete_debug\fP +for contextual completion\&. +.PP +If the widget\&'s name contains \fBnoread\fP, it will not read a keystring +but instead arrange that the next use of a generic widget run in +the same shell will have the effect as described above\&. +.PP +The widget works by setting the shell parameter +\fBZSH_TRACE_GENERIC_WIDGET\fP which is read by \fB_generic\fP\&. Unsetting +the parameter cancels any pending effect of the \fBnoread\fP form\&. +.PP +For example, after executing the following: +.PP +.RS +.nf +\fBzle \-N _complete_debug_generic _complete_help_generic +bindkey \&'^x:' _complete_debug_generic\fP +.fi +.RE +.PP +typing `\fBC\-x :\fP\&' followed by the key sequence for a generic widget +will cause trace output for that widget to be saved to a file\&. +.RE +.TP +\fB_complete_tag\fP (\fB^Xt\fP) +This widget completes symbol tags created by the \fBetags\fP or \fBctags\fP +programmes (note there is no connection with the completion system\&'s tags) +stored in a file \fBTAGS\fP, in the format used by \fBetags\fP, or \fBtags\fP, in the +format created by \fBctags\fP\&. It will look back up the path hierarchy for +the first occurrence of either file; if both exist, the file \fBTAGS\fP is +preferred\&. You can specify the full path to a \fBTAGS\fP or \fBtags\fP file by +setting the parameter \fB$TAGSFILE\fP or \fB$tagsfile\fP respectively\&. +The corresponding completion tags used are \fBetags\fP and \fBvtags\fP, after +emacs and vi respectively\&. +.PP +.SH "UTILITY FUNCTIONS" +.PP +Descriptions follow for utility functions that may be +useful when writing completion functions\&. If functions are installed in +subdirectories, most of these reside in the +\fBBase\fP subdirectory\&. Like the example +functions for commands in the distribution, the utility functions +generating matches all follow the convention of returning status zero if they +generated completions and non\-zero if no matching completions could be +added\&. +.PP +.PD 0 +.TP +.PD +\fB_absolute_command_paths\fP +This function completes external commands as absolute paths (unlike +\fB_command_names \-e\fP which completes their basenames)\&. It takes no +arguments\&. +.TP +\fB_all_labels\fP [ \fB\-x\fP ] [ \fB\-12VJ\fP ] \fItag\fP \fIname\fP \fIdescr\fP [ \fIcommand\fP \fIarg\fP \&.\&.\&. ] +This is a convenient interface to the \fB_next_label\fP function below, +implementing the loop shown in the \fB_next_label\fP example\&. The +\fIcommand\fP and its arguments are called to generate the matches\&. The +options stored in the parameter \fIname\fP will automatically be inserted +into the \fIarg\fPs passed to the \fIcommand\fP\&. Normally, they are put +directly after the \fIcommand\fP, but if one of the \fIarg\fPs is a single +hyphen, they are inserted directly before that\&. If the hyphen is the last +argument, it will be removed from the argument list before the +\fIcommand\fP is called\&. This allows \fB_all_labels\fP to be used in almost all +cases where the matches can be generated by a single call to the +\fBcompadd\fP builtin command or by a call to one of the utility functions\&. +.RS +.PP +For example: +.PP +.RS +.nf +\fBlocal expl +\&.\&.\&. +if _requested foo; then + \&.\&.\&. + _all_labels foo expl \&'\&.\&.\&.' compadd \&.\&.\&. \- $matches +fi\fP +.fi +.RE +.PP +Will complete the strings from the \fBmatches\fP parameter, using +\fBcompadd\fP with additional options which will take precedence over +those generated by \fB_all_labels\fP\&. +.RE +.TP +\fB_alternative\fP [ \fB\-O\fP \fIname\fP ] [ \fB\-C\fP \fIname\fP ] \fIspec\fP \&.\&.\&. +This function is useful in simple cases where multiple tags are available\&. +Essentially it implements a loop like the one described for the \fB_tags\fP +function below\&. +.RS +.PP +The tags to use and the action to perform if a tag is requested are +described using the \fIspec\fPs which are of the form: +`\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP\&'\&. The \fItag\fPs are offered using +\fB_tags\fP and if the tag is requested, the \fIaction\fP is executed with the +given description \fIdescr\fP\&. The \fIaction\fPs are those accepted +by the \fB_arguments\fP function (described below), with the following +exceptions: +.PD 0 +.TP +.PD +\(bu +The `\fB\->\fP\fIstate\fP\&' and `\fB=\fP\fI\&.\&.\&.\fP' forms are not supported\&. + +.TP +\(bu +The `\fB((a\e:bar b\e:baz\fP\fB))\fP\&' form does not need +the colon to be escaped, since the \fIspec\fPs have no colon\-separated fields +after the \fIaction\fP\&. + +.PP +For example, the \fIaction\fP may be a simple function call: +.PP +.RS +.nf +\fB_alternative \e + \&'users:user:_users' \e + \&'hosts:host:_hosts'\fP +.fi +.RE +.PP +offers usernames and hostnames as possible matches, +generated by the \fB_users\fP and \fB_hosts\fP functions respectively\&. +.PP +Like \fB_arguments\fP, this function uses \fB_all_labels\fP to execute +the actions, which will loop over all sets of tags\&. Special handling is +only required if there is an additional valid tag, for example inside a +function called from \fB_alternative\fP\&. +.PP +The option `\fB\-O\fP \fIname\fP\&' is used in the same way as by the +\fB_arguments\fP function\&. In other words, the elements of the \fIname\fP +array will be passed to \fBcompadd\fP when executing an action\&. +.PP +Like \fB_tags\fP this function supports the \fB\-C\fP option to give a +different name for the argument context field\&. +.RE + +.TP +.PD 0 +\fB_arguments \fP[ \fB\-nswWCRS\fP ] [ \fB\-A\fP \fIpat\fP ] [ \fB\-O\fP \fIname\fP ] [ \fB\-M\fP \fImatchspec\fP ] +.TP +.PD 0 +\fB \fP[ \fB:\fP ] \fIspec\fP \&.\&.\&. +.TP +.PD 0 +\fB_arguments \fP[ \fIopt\fP \&.\&.\&. ] \fB\-\fP\fB\-\fP [ \fB\-l\fP ] [ \fB\-i\fP \fIpats\fP ] [ \fB\-s\fP \fIpair\fP ] +.TP +.PD +\fB \fP[ \fIhelpspec\fP \&.\&.\&.] +This function can be used to give a complete specification for completion +for a command whose arguments follow standard UNIX option and argument +conventions\&. +.RS +.PP +\fIOptions Overview\fP +.PP +Options to \fB_arguments\fP itself must be in separate words, i\&.e\&. \fB\-s \-w\fP, +not \fB\-sw\fP\&. The options are followed by \fIspec\fPs that describe options and +arguments of the analyzed command\&. To avoid ambiguity, all +options to \fB_arguments\fP itself may be separated from the \fIspec\fP forms +by a single colon\&. +.PP +The `\fB\-\fP\fB\-\fP\&' +form is used to intuit \fIspec\fP forms from the help output of the command +being analyzed, and is described in detail below\&. The \fIopts\fP for the +`\fB\-\fP\fB\-\fP\&' form are otherwise the same options as the first form\&. Note +that `\fB\-s\fP\&' following `\fB\-\fP\fB\-\fP' has a distinct meaning from `\fB\-s\fP' +preceding `\fB\-\fP\fB\-\fP\&', and both may appear\&. +.PP +The option switches \fB\-s\fP, \fB\-S\fP, \fB\-A\fP, \fB\-w\fP, and \fB\-W\fP affect how +\fB_arguments\fP parses the analyzed command line\&'s options\&. These switches are +useful for commands with standard argument parsing\&. +.PP +The options of \fB_arguments\fP have the following meanings: +.PP +.PD 0 +.TP +.PD +\fB\-n\fP +With this option, \fB_arguments\fP sets the parameter \fBNORMARG\fP +to the position of the first normal argument in the \fB$words\fP array, +i\&.e\&. the position after the end of the options\&. If that argument +has not been reached, \fBNORMARG\fP is set to \fB\-1\fP\&. The caller +should declare `\fBinteger NORMARG\fP\&' if the \fB\-n\fP option is passed; +otherwise the parameter is not used\&. +.TP +\fB\-s\fP +Enable \fIoption stacking\fP for single\-letter options, whereby multiple +single\-letter options may be combined into a single word\&. For example, +the two options `\fB\-x\fP\&' and `\fB\-y\fP' may be combined into +a single word `\fB\-xy\fP\&'\&. By default, every word corresponds to a single +option name (`\fB\-xy\fP\&' is a single option named `\fBxy\fP')\&. +.RS +.PP +Options beginning with a single hyphen or plus sign are eligible for stacking; +words beginning with two hyphens are not\&. +.PP +Note that \fB\-s\fP after \fB\-\fP\fB\-\fP has a different meaning, which is documented +in the segment entitled `Deriving \fIspec\fP forms from the help output\&'\&. +.RE +.TP +\fB\-w\fP +In combination with \fB\-s\fP, allow option stacking +even if one or more of the options take +arguments\&. For example, if \fB\-x\fP takes an argument, with no +\fB\-s\fP, `\fB\-xy\fP\&' is considered as a single (unhandled) option; with +\fB\-s\fP, \fB\-xy\fP is an option with the argument `\fBy\fP\&'; with both \fB\-s\fP +and \fB\-w\fP, \fB\-xy\fP is the option \fB\-x\fP and the option \fB\-y\fP with +arguments to \fB\-x\fP (and to \fB\-y\fP, if it takes arguments) still to come +in subsequent words\&. +.TP +\fB\-W\fP +This option takes \fB\-w\fP a stage further: it is possible to +complete single\-letter options even after an argument that occurs in the +same word\&. However, it depends on the action performed whether options +will really be completed at this point\&. For more control, use a +utility function like \fB_guard\fP as part of the action\&. +.TP +\fB\-C\fP +Modify the \fBcurcontext\fP parameter for an action of the form `\fB\->\fP\fIstate\fP\&'\&. +This is discussed in detail below\&. +.TP +\fB\-R\fP +Return status 300 instead of zero when a \fB$state\fP is to +be handled, in the `\fB\->\fP\fIstring\fP\&' syntax\&. +.TP +\fB\-S\fP +Do not complete options after a `\fB\-\fP\fB\-\fP\&' appearing on the line, +and ignore the `\fB\-\fP\fB\-\fP\&'\&. For example, with \fB\-S\fP, in the line +.RS +.PP +.RS +.nf +\fBfoobar \-x \-\- \-y\fP +.fi +.RE +.PP +the `\fB\-x\fP\&' is considered an option, the `\fB\-y\fP' is considered an +argument, and the `\fB\-\fP\fB\-\fP\&' is considered to be neither\&. +.RE +.TP +\fB\-A\fP \fIpat\fP +Do not complete options after the first non\-option +argument on the line\&. \fIpat\fP is a pattern matching +all strings which are not to be taken as arguments\&. For example, to make +\fB_arguments\fP stop completing options after the first normal argument, but +ignoring all strings starting with a hyphen even if they are not described +by one of the \fIoptspec\fPs, the form is `\fB\-A "\-*"\fP\&'\&. +.TP +\fB\-O\fP \fIname\fP +Pass the elements of the array \fIname\fP as arguments to functions called to +execute \fIaction\fPs\&. +This is discussed in detail below\&. +.TP +\fB\-M\fP \fImatchspec\fP +Use the match specification \fImatchspec\fP for completing option names and values\&. +The default \fImatchspec\fP allows partial word completion after `\fB_\fP\&' and +`\fB\-\fP\&', such as completing `\fB\-f\-b\fP' to `\fB\-foo\-bar\fP'\&. The default +\fImatchspec\fP is: +.RS +.nf +\fB\fBr:|[_\-]=* r:|=*\fP\fP +.fi +.RE +.TP +\fB\-0\fP +When populating values of the `\fBopt_args\fP\&' associative array, don't +backslash\-escape colons and backslashes and use NUL rather than colon for +joining multiple values\&. This option is described in more detail below, under +the heading \fI\fIspec\fPs: actions\fP\&. +.PP +\fI\fIspec\fPs: overview\fP +.PP +Each of the following forms is a \fIspec\fP describing individual sets of +options or arguments on the command line being analyzed\&. +.PP +.PD 0 +.TP +.PD 0 +\fIn\fP\fB:\fP\fImessage\fP\fB:\fP\fIaction\fP +.TP +.PD +\fIn\fP\fB::\fP\fImessage\fP\fB:\fP\fIaction\fP +This describes the \fIn\fP\&'th normal argument\&. The \fImessage\fP will be +printed above the matches generated and the \fIaction\fP indicates what can +be completed in this position (see below)\&. If there are two colons +before the \fImessage\fP the argument is optional\&. If the +\fImessage\fP contains only white space, nothing will be printed above +the matches unless the action adds an explanation string itself\&. +.TP +.PD 0 +\fB:\fP\fImessage\fP\fB:\fP\fIaction\fP +.TP +.PD +\fB::\fP\fImessage\fP\fB:\fP\fIaction\fP +Similar, but describes the \fInext\fP argument, whatever number that +happens to be\&. If all arguments are specified in this form in the +correct order the numbers are unnecessary\&. +.TP +.PD 0 +\fB*:\fP\fImessage\fP\fB:\fP\fIaction\fP +.TP +.PD 0 +\fB*::\fP\fImessage\fP\fB:\fP\fIaction\fP +.TP +.PD +\fB*:::\fP\fImessage\fP\fB:\fP\fIaction\fP +This describes how arguments (usually non\-option arguments, those not +beginning with \fB\-\fP or \fB+\fP) are to be completed when neither +of the first two forms was provided\&. Any number of arguments can +be completed in this fashion\&. +.RS +.PP +With two colons before the \fImessage\fP, the \fBwords\fP special array and +the \fBCURRENT\fP special parameter are modified to refer only to the +normal arguments when the \fIaction\fP is executed or evaluated\&. With +three colons before the \fImessage\fP they are modified to refer only to +the normal arguments covered by this description\&. +.RE +.TP +.PD 0 +\fIoptspec\fP +.TP +.PD +\fIoptspec\fP\fB:\fP\fI\&.\&.\&.\fP +This describes an option\&. The colon indicates handling for one or more +arguments to the option; if it is not present, the option is assumed to +take no arguments\&. +.RS +.PP +The following forms are available for the initial \fIoptspec\fP, whether +or not the option has arguments\&. +.PP +.PD 0 +.TP +.PD +\fB*\fP\fIoptspec\fP +Here \fIoptspec\fP is one of the remaining forms below\&. This indicates +the following \fIoptspec\fP may be repeated\&. Otherwise if the +corresponding option is already present on the command line to the left +of the cursor it will not be offered again\&. +.TP +.PD 0 +\fB\-\fP\fIoptname\fP +.TP +.PD +\fB+\fP\fIoptname\fP +In the simplest form the \fIoptspec\fP is just the option name beginning +with a minus or a plus sign, such as `\fB\-foo\fP\&'\&. The first argument for +the option (if any) must follow as a \fIseparate\fP word directly after the +option\&. +.RS +.PP +Either of `\fB\-+\fP\fIoptname\fP\&' and `\fB+\-\fP\fIoptname\fP' can be used to +specify that \fB\-\fP\fIoptname\fP and \fB+\fP\fIoptname\fP are both valid\&. +.PP +In all the remaining forms, the leading `\fB\-\fP\&' may be replaced by or +paired with `\fB+\fP\&' in this way\&. +.RE +.TP +\fB\-\fP\fIoptname\fP\fB\-\fP +The first argument of the option must come directly after the option name +\fIin the same word\fP\&. For example, `\fB\-foo\-:\fP\fI\&.\&.\&.\fP\&' specifies that +the completed option and argument will look like `\fB\-foo\fP\fIarg\fP\&'\&. +.TP +\fB\-\fP\fIoptname\fP\fB+\fP +The first argument may appear immediately after \fIoptname\fP in the same +word, or may appear as a separate word after the option\&. For example, +`\fB\-foo+:\fP\fI\&.\&.\&.\fP\&' specifies that the completed option and argument +will look like either `\fB\-foo\fP\fIarg\fP\&' or `\fB\-foo\fP \fIarg\fP'\&. +.TP +\fB\-\fP\fIoptname\fP\fB=\fP +The argument may appear as the next word, or in same word as the option +name provided that it is separated from it by an equals sign, for +example `\fB\-foo=\fP\fIarg\fP\&' or `\fB\-foo\fP \fIarg\fP'\&. +.TP +\fB\-\fP\fIoptname\fP\fB=\-\fP +The argument to the option must appear after an equals sign in the same +word, and may not be given in the next argument\&. +.TP +\fIoptspec\fP\fB[\fP\fIexplanation\fP\fB]\fP +An explanation string may be appended to any of the preceding forms of +\fIoptspec\fP by enclosing it in brackets, as in `\fB\-q[query operation]\fP\&'\&. +.RS +.PP +The \fBverbose\fP style is used to decide whether the explanation strings +are displayed with the option in a completion listing\&. +.PP +If no bracketed explanation string is given but the \fBauto\-description\fP +style is set and only one argument is described for this \fIoptspec\fP, the +value of the style is displayed, with any appearance of the sequence +`\fB%d\fP\&' in it replaced by the \fImessage\fP of the first \fIoptarg\fP +that follows the \fIoptspec\fP; see below\&. +.RE +.PP +It is possible for options with a literal `\fB+\fP\&' or `\fB=\fP' to +appear, but that character must be quoted, for example `\fB\-\e+\fP\&'\&. +.PP +Each \fIoptarg\fP following an \fIoptspec\fP must take one of the +following forms: +.PP +.PD 0 +.TP +.PD 0 +\fB:\fP\fImessage\fP\fB:\fP\fIaction\fP +.TP +.PD +\fB::\fP\fImessage\fP\fB:\fP\fIaction\fP +An argument to the option; \fImessage\fP and \fIaction\fP are treated as +for ordinary arguments\&. In the first form, the argument is mandatory, +and in the second form it is optional\&. +.RS +.PP +This group may be repeated for options which take multiple arguments\&. +In other words, +\fB:\fP\fImessage1\fP\fB:\fP\fIaction1\fP\fB:\fP\fImessage2\fP\fB:\fP\fIaction2\fP +specifies that the option takes two arguments\&. +.RE +.TP +.PD 0 +\fB:*\fP\fIpattern\fP\fB:\fP\fImessage\fP\fB:\fP\fIaction\fP +.TP +.PD 0 +\fB:*\fP\fIpattern\fP\fB::\fP\fImessage\fP\fB:\fP\fIaction\fP +.TP +.PD +\fB:*\fP\fIpattern\fP\fB:::\fP\fImessage\fP\fB:\fP\fIaction\fP +This describes multiple arguments\&. Only the last \fIoptarg\fP for +an option taking multiple arguments may be +given in this form\&. If the \fIpattern\fP is empty (i\&.e\&. \fB:*:\fP), all +the remaining words on the line are to be completed as described by the +\fIaction\fP; otherwise, all the words up to and including a word matching +the \fIpattern\fP are to be completed using the \fIaction\fP\&. +.RS +.PP +Multiple colons are treated as for the `\fB*:\fP\fI\&.\&.\&.\fP\&' forms for +ordinary arguments: when the \fImessage\fP is preceded by two colons, +the \fBwords\fP special array and the \fBCURRENT\fP special parameter are +modified during the execution or evaluation of the \fIaction\fP to refer +only to the words after the option\&. When preceded by three colons, they +are modified to refer only to the words covered by this description\&. +.RE +.RE +.PP +Any literal colon in an \fIoptname\fP, \fImessage\fP, or \fIaction\fP +must be preceded by a backslash, `\fB\e:\fP\&'\&. +.PP +Each of the forms above may be preceded by a list in parentheses +of option names and argument numbers\&. If the given option is on +the command line, the options and arguments indicated in parentheses +will not be offered\&. For example, +`\fB(\-two \-three 1)\-one:\fP\fI\&.\&.\&.\fP\&' completes the option `\fB\-one\fP'; if this +appears on the command line, the options \fB\-two\fP and \fB\-three\fP and the +first ordinary argument will not be completed after it\&. +`\fB(\-foo):\fP\fI\&.\&.\&.\fP\&' specifies an ordinary argument completion; +\fB\-foo\fP will not be completed if that argument is already present\&. +.PP +Other items may appear in the list of excluded options to indicate +various other items that should not be applied when the current +specification is matched: a single star (\fB*\fP) for the rest arguments +(i\&.e\&. a specification of the form `\fB*:\fP\fI\&.\&.\&.\fP\&'); a colon (\fB:\fP) +for all normal (non\-option\-) arguments; and a hyphen (\fB\-\fP) for all +options\&. For example, if `\fB(*)\fP\&' appears before an option and the +option appears on the command line, the list of remaining arguments +(those shown in the above table beginning with `\fB*:\fP\&') will not be +completed\&. +.PP +To aid in reuse of specifications, it is possible to precede any of the +forms above with `\fB!\fP\&'; then the form will no longer be completed, +although if the option or argument appears on the command line they will +be skipped as normal\&. The main use for this is when the arguments are +given by an array, and \fB_arguments\fP is called repeatedly for more +specific contexts: on the first call `\fB_arguments $global_options\fP\&' is +used, and on subsequent calls `\fB_arguments !$^global_options\fP\&'\&. +.PP +\fI\fIspec\fPs: actions\fP + +.PP +In each of the forms above the \fIaction\fP determines how +completions should be generated\&. Except for the `\fB\->\fP\fIstring\fP\&' +form below, the \fIaction\fP will be executed by calling the +\fB_all_labels\fP function to process all tag labels\&. No special handling +of tags is needed unless a function call introduces a new one\&. +.PP +The functions called to execute \fIaction\fPs will be called with the +elements of the array named by the `\fB\-O\fP \fIname\fP\&' option as arguments\&. +This can be used, for example, to pass the same set of options for the +\fBcompadd\fP builtin to all \fIaction\fPs\&. +.PP +The forms for \fIaction\fP are as follows\&. +.PP +.PD 0 +.TP +.PD +\fB \fP(single unquoted space) +This is useful where an argument is required but it is not possible or +desirable to generate matches for it\&. The +\fImessage\fP will be displayed but no completions listed\&. Note +that even in this case the colon at the end of the \fImessage\fP is +needed; it may only be omitted when neither a \fImessage\fP +nor an \fIaction\fP is given\&. +.TP +\fB(\fP\fIitem1\fP \fIitem2\fP \fI\&.\&.\&.\fP\fB)\fP +One of a list of possible matches, for example: +.RS +.PP +.RS +.nf +\fB\fB:foo:(foo bar baz\fP\fB)\fP\fP +.fi +.RE +.RE +.TP +\fB((\fIitem1\fP\e:\fIdesc1\fP \fI\&.\&.\&.\fP))\fP +Similar to the above, but with descriptions for each possible match\&. +Note the backslash before the colon\&. For example, +.RS +.PP +.RS +.nf +\fB\fB:foo:((a\e:bar b\e:baz\fP\fB))\fP\fP +.fi +.RE +.PP +The matches will be listed together with their descriptions if the +\fBdescription\fP style is set with the \fBvalues\fP tag in the context\&. +.RE +.TP +\fB\->\fP\fIstring\fP +In this form, \fB_arguments\fP processes the arguments and options and then +returns control to the calling function with parameters set to indicate the +state of processing; the calling function then makes its own arrangements +for generating completions\&. For example, functions that implement a state +machine can use this type of action\&. +.RS +.PP +Where \fB_arguments\fP encounters \fIaction\fP in the `\fB\->\fP\fIstring\fP\&' +format, it will strip all leading and trailing whitespace from \fIstring\fP +and set the array \fBstate\fP to the set of all \fIstring\fPs for which an +action is to be performed\&. The elements of the array \fBstate_descr\fP are +assigned the corresponding \fImessage\fP field from each \fIoptarg\fP +containing such an \fIaction\fP\&. +.PP +By default and in common with all other well behaved completion +functions, _arguments returns status zero if it was able to add matches and +non\-zero otherwise\&. However, if the \fB\-R\fP option is given, +\fB_arguments\fP will instead return a status of 300 to indicate that +\fB$state\fP is to be handled\&. +.PP +In addition to \fB$state\fP and \fB$state_descr\fP, \fB_arguments\fP also +sets the global +parameters `\fBcontext\fP\&', `\fBline\fP' and `\fBopt_args\fP' as described +below, and does not reset any changes made to the special parameters +such as \fBPREFIX\fP and \fBwords\fP\&. This gives the calling function the +choice of resetting these parameters or propagating changes in them\&. +.PP +A function calling \fB_arguments\fP with at least +one action containing a `\fB\->\fP\fIstring\fP\&' must therefore declare +appropriate local parameters: +.PP +.RS +.nf +\fBlocal context state state_descr line +typeset \-A opt_args\fP +.fi +.RE +.PP +to prevent \fB_arguments\fP from altering the global environment\&. +.RE +.TP +\fB{\fP\fIeval\-string\fP\fB}\fP +A string in braces is evaluated as shell code to generate matches\&. If the +\fIeval\-string\fP itself does not begin with an opening parenthesis or +brace it is split into separate words before execution\&. +.TP +\fB= \fP\fIaction\fP +If the \fIaction\fP starts with `\fB= \fP\&' (an equals sign followed by a +space), \fB_arguments\fP will insert the contents of the \fIargument\fP +field of the current context as the new first element in the \fBwords\fP +special array and increment the value of the \fBCURRENT\fP special +parameter\&. This has the effect of inserting a dummy word onto the +completion command line while not changing the point at which completion is +taking place\&. +.RS +.PP +This is most useful with one of the specifiers that restrict the words on +the command line on which the \fIaction\fP is to operate (the two\- and +three\-colon forms above)\&. One particular use is when an \fIaction\fP itself +causes \fB_arguments\fP on a restricted range; it is necessary to use this +trick to insert an appropriate command name into the range for the second +call to \fB_arguments\fP to be able to parse the line\&. +.RE +.TP +.PD 0 +\fI\fB \fPword\&.\&.\&.\fP +.TP +.PD +\fIword\&.\&.\&.\fP +This covers all forms other than those above\&. If the \fIaction\fP +starts with a space, the remaining list of words will be invoked unchanged\&. +.RS +.PP +Otherwise it will be invoked with some extra strings placed after the +first word; these are to be passed down as options to the \fBcompadd\fP +builtin\&. They ensure that the state specified by \fB_arguments\fP, in +particular the descriptions of options and arguments, is correctly passed +to the completion command\&. These additional arguments +are taken from the array parameter `\fBexpl\fP\&'; this will be set up +before executing the \fIaction\fP and hence may be referred to inside it, +typically in an expansion of the form `\fB$expl[@]\fP\&' which preserves empty +elements of the array\&. +.RE +.PP +During the performance of the action the array `\fBline\fP\&' will be set to +the normal arguments from the command line, i\&.e\&. the words from the +command line after the command name excluding all options and their +arguments\&. Options are stored in the associative array +`\fBopt_args\fP\&' with option names as keys and their arguments as +the values\&. By default, all colons and backslashes in the value are escaped +with backslashes, and if an option has multiple arguments (for example, when +using an \fIoptspec\fP of the form `\fB*\fP\fIoptspec\fP\&'), they are joined with +(unescaped) colons\&. However, if the \fB\-0\fP option was passed, no backslash +escaping is performed, and multiple values are joined with NUL bytes\&. For +example, after `\fBzsh \-o foo:foo \-o bar:bar \-o <TAB>\fP\&', the contents of +`\fBopt_args\fP\&' would be +.PP +.RS +.nf +\fBtypeset \-A opt_args=( [\-o]=\&'foo\e:foo:bar\e:bar:' )\fP +.fi +.RE +.PP +by default, and +.PP +.RS +.nf +\fBtypeset \-A opt_args=( [\-o]=$\&'foo:foo\ex00bar:bar\ex00' )\fP +.fi +.RE +.PP +if \fB_arguments\fP had been called with the \fB\-0\fP option\&. +.PP +The parameter `\fBcontext\fP\&' is set when returning to the calling function +to perform an action of the form `\fB\->\fP\fIstring\fP\&'\&. It is set to an +array of elements corresponding to the elements of \fB$state\fP\&. Each +element is a suitable name for the argument field of the context: either a +string of the form `\fBoption\fP\fI\-opt\fP\fB\-\fP\fIn\fP\&' for the \fIn\fP'th +argument of the option \fI\-opt\fP, or a string of the form +`\fBargument\-\fP\fIn\fP\&' for the \fIn\fP'th argument\&. For `rest' arguments, +that is those in the list at the end not handled by position, \fIn\fP is the +string `\fBrest\fP\&'\&. For example, when completing the argument of the \fB\-o\fP +option, the name is `\fBoption\-o\-1\fP\&', while for the second normal +(non\-option\-) argument it is `\fBargument\-2\fP\&'\&. +.PP +Furthermore, during the evaluation of the \fIaction\fP the context name in +the \fBcurcontext\fP parameter is altered to append the same string that is +stored in the \fBcontext\fP parameter\&. +.PP +The option \fB\-C\fP tells \fB_arguments\fP to modify the \fBcurcontext\fP +parameter for an action of the form `\fB\->\fP\fIstate\fP\&'\&. This is the +standard parameter used to keep track of the current context\&. Here it +(and not the \fBcontext\fP array) should be made local to the calling +function to avoid passing back the modified value and should be +initialised to the current value at the start of the function: +.PP +.RS +.nf +\fBlocal curcontext="$curcontext"\fP +.fi +.RE +.PP +This is useful where it is not possible for multiple states to be valid +together\&. +.PP +\fIGrouping Options\fP +.PP +Options can be grouped to simplify exclusion lists\&. A group is +introduced with `\fB+\fP\&' followed by a name for the group in the +subsequent word\&. Whole groups can then be referenced in an exclusion +list or a group name can be used to disambiguate between two forms of +the same option\&. For example: +.PP +.RS +.nf +\fB_arguments \e + \&'(group2\-\-x)\-a' \e + + group1 \e + \-m \e + \&'(group2)\-n' \e + + group2 \e + \-x \-y\fP +.fi +.RE +.PP +If the name of a group is specified in the form +`\fB(\fP\fIname\fP\fB)\fP\&' then only one value from that group +will ever be completed; more formally, all specifications are mutually +exclusive to all other specifications in that group\&. This is useful for +defining options that are aliases for each other\&. For example: +.PP +.RS +.nf +\fB_arguments \e + \-a \-b \e + + \&'(operation)' \e + {\-c,\-\-compress}\&'[compress]' \e + {\-d,\-\-decompress}\&'[decompress]' \e + {\-l,\-\-list}\&'[list]'\fP +.fi +.RE +.PP +If an option in a group appears on the command line, it is stored in the +associative array `\fBopt_args\fP\&' with '\fIgroup\fP\fB\-\fP\fIoption\fP' +as a key\&. In the example above, a key `\fBoperation\-\-c\fP\&' is used if the option +`\fB\-c\fP\&' is present on the command line\&. +.PP +\fISpecifying Multiple Sets of Arguments\fP +.PP +It is possible to specify multiple sets of options and arguments with +the sets separated by single hyphens\&. This differs from groups in that +sets are considered to be mutually exclusive of each other\&. +.PP +Specifications before the first set and from any group are common to +all sets\&. For example: +.PP +.RS +.nf +\fB_arguments \e + \-a \e + \- set1 \e + \-c \e + \- set2 \e + \-d \e + \&':arg:(x2 y2)'\fP +.fi +.RE +.PP +This defines two sets\&. When the command line contains the option +`\fB\-c\fP\&', the `\fB\-d\fP' option and the argument will not be considered +possible completions\&. When it contains `\fB\-d\fP\&' or an argument, the +option `\fB\-c\fP\&' will not be considered\&. However, after `\fB\-a\fP' +both sets will still be considered valid\&. +.PP +As for groups, the name of a set may appear in exclusion lists, either +alone or preceding a normal option or argument specification\&. +.PP +The completion code has to parse the command line separately for each +set\&. This can be slow so sets should only be used when necessary\&. +A useful alternative is often an option specification with rest\-arguments +(as in `\fB\-foo:*:\&.\&.\&.\fP\&'); here the option \fB\-foo\fP swallows up all +remaining arguments as described by the \fIoptarg\fP definitions\&. +.PP +\fIDeriving \fIspec\fP forms from the help output\fP +.PP +The option `\fB\-\fP\fB\-\fP\&' allows \fB_arguments\fP to work out the names of long +options that support the `\fB\-\fP\fB\-help\fP\&' option which is standard in many +GNU commands\&. The command word is called with the argument +`\fB\-\fP\fB\-help\fP\&' and the output examined for option names\&. Clearly, it can +be dangerous to pass this to commands which may not support this option as +the behaviour of the command is unspecified\&. +.PP +In addition to options, `\fB_arguments \-\fP\fB\-\fP\&' will try to deduce the +types of arguments available for options when the form +`\fB\-\fP\fB\-\fP\fIopt\fP\fB=\fP\fIval\fP\&' is valid\&. It is also possible to provide +hints by examining the help text of the command and adding \fIhelpspec\fP of +the form `\fIpattern\fP\fB:\fP\fImessage\fP\fB:\fP\fIaction\fP\&'; note that other +\fB_arguments\fP \fIspec\fP forms are not used\&. The \fIpattern\fP is matched +against the help text for an option, and if it matches the \fImessage\fP and +\fIaction\fP are used as for other argument specifiers\&. The special case +of `\fB*:\fP\&' means both \fImessage\fP and \fIaction\fP are empty, which has +the effect of causing options having no description in the help output to +be ordered in listings ahead of options that have a description\&. +.PP +For example: +.PP +.RS +.nf +\fB_arguments \-\- \&'*\e*:toggle:(yes no)' \e + \&'*=FILE*:file:_files' \e + \&'*=DIR*:directory:_files \-/' \e + \&'*=PATH*:directory:_files \-/'\fP +.fi +.RE +.PP +Here, `\fByes\fP\&' and `\fBno\fP' will be completed as the argument of +options whose description ends in a star; file names will be completed for +options that contain the substring `\fB=FILE\fP\&' in the description; and +directories will be completed for options whose description contains +`\fB=DIR\fP\&' or `\fB=PATH\fP'\&. The last three are in fact the default and so +need not be given explicitly, although it is possible to override the use +of these patterns\&. A typical help text which uses this feature is: +.PP +.RS +.nf +\fB \-C, \-\-directory=DIR change to directory DIR\fP +.fi +.RE +.PP +so that the above specifications will cause directories to be completed +after `\fB\-\fP\fB\-directory\fP\&', though not after `\fB\-C\fP'\&. +.PP +Note also that \fB_arguments\fP tries to find out automatically if the +argument for an option is optional\&. This can be specified explicitly by +doubling the colon before the \fImessage\fP\&. +.PP +If the \fIpattern\fP ends in `\fB(\-)\fP\&', this will be removed from the +pattern and the \fIaction\fP will be used only directly after the +`\fB=\fP\&', not in the next word\&. This is the behaviour of a normal +specification defined with the form `\fB=\-\fP\&'\&. +.PP +By default, the command (with the option `\fB\-\-help\fP\&') is run after +resetting all the locale categories (except for \fBLC_CTYPE\fP) to `\fBC\fP\&'\&. +If the localized help output is known to work, the option `\fB\-l\fP\&' can +be specified after the `\fB_arguments \-\fP\fB\-\fP\&' so that the command is +run in the current locale\&. +.PP +The `\fB_arguments \-\fP\fB\-\fP\&' can be followed by the option `\fB\-i\fP +\fIpatterns\fP\&' to give patterns for options which are not to be +completed\&. The patterns can be given as the name of an array parameter +or as a literal list in parentheses\&. For example, +.PP +.RS +.nf +\fB_arguments \-\- \-i \e + "(\-\-(en|dis)able\-FEATURE*)"\fP +.fi +.RE +.PP +will cause completion to ignore the options +`\fB\-\fP\fB\-enable\-FEATURE\fP\&' and `\fB\-\fP\fB\-disable\-FEATURE\fP' (this example is +useful with GNU \fBconfigure\fP)\&. +.PP +The `\fB_arguments \-\fP\fB\-\fP\&' form can also be followed by the option `\fB\-s\fP +\fIpair\fP\&' to describe option aliases\&. The \fIpair\fP consists of a list +of alternating patterns and corresponding replacements, enclosed in parens +and quoted so that it forms a single argument word in the \fB_arguments\fP +call\&. +.PP +For example, some \fBconfigure\fP\-script help output describes options only +as `\fB\-\fP\fB\-enable\-foo\fP\&', but the script also accepts the negated form +`\fB\-\fP\fB\-disable\-foo\fP\&'\&. To allow completion of the second form: +.PP +.RS +.nf +\fB_arguments \-\- \-s "((#s)\-\-enable\- \-\-disable\-)"\fP +.fi +.RE +.PP +\fIMiscellaneous notes\fP +.PP +Finally, note that \fB_arguments\fP generally expects to be the primary +function handling any completion for which it is used\&. It may have side +effects which change the treatment of any matches added by other functions +called after it\&. To combine \fB_arguments\fP with other functions, those +functions should be called either before \fB_arguments\fP, as an \fIaction\fP +within a \fIspec\fP, or in handlers for `\fB\->\fP\fIstate\fP\&' actions\&. +.PP +Here is a more general example of the use of \fB_arguments\fP: +.PP +.RS +.nf +\fB_arguments \&'\-l+:left border:' \e + \&'\-format:paper size:(letter A4)' \e + \&'*\-copy:output file:_files::resolution:(300 600)' \e + \&':postscript file:_files \-g \e*\&.\e(ps\e|eps\e)' \e + \&'*:page number:'\fP +.fi +.RE +.PP +This describes three options: `\fB\-l\fP\&', `\fB\-format\fP', and +`\fB\-copy\fP\&'\&. The first takes one argument described as `\fIleft +border\fP\&' for which no completion will be offered because of the empty +action\&. Its argument may come directly after the `\fB\-l\fP\&' or it may be +given as the next word on the line\&. +.PP +The `\fB\-format\fP\&' option takes one +argument in the next word, described as `\fIpaper size\fP\&' for which +only the strings `\fBletter\fP\&' and `\fBA4\fP' will be completed\&. +.PP +The `\fB\-copy\fP\&' option may appear more than once on the command line and +takes two arguments\&. The first is mandatory and will be completed as a +filename\&. The second is optional (because of the second colon before +the description `\fIresolution\fP\&') and will be completed from the strings +`\fB300\fP\&' and `\fB600\fP'\&. +.PP +The last two descriptions say what should be completed as +arguments\&. The first describes the first argument as a +`\fIpostscript file\fP\&' and makes files ending in `\fBps\fP' or `\fBeps\fP' +be completed\&. The last description gives all other arguments the +description `\fIpage number\fP\&' but does not offer completions\&. +.RE +.TP +\fB_cache_invalid\fP \fIcache_identifier\fP +This function returns status zero if the completions cache corresponding to +the given cache identifier needs rebuilding\&. It determines this by +looking up the \fBcache\-policy\fP style for the current context\&. +This should provide a function name which is run with the full path to the +relevant cache file as the only argument\&. +.RS +.PP +Example: +.PP +.RS +.nf +\fB_example_caching_policy () { + # rebuild if cache is more than a week old + local \-a oldp + oldp=( "$1"(Nm+7) ) + (( $#oldp )) +}\fP +.fi +.RE +.RE +.TP +\fB_call_function\fP \fIreturn\fP \fIname\fP [ \fIarg\fP \&.\&.\&. ] +If a function \fIname\fP exists, it is called with the arguments +\fIarg\fPs\&. The \fIreturn\fP argument gives the name of a parameter in which +the return status from the function \fIname\fP should be stored; if \fIreturn\fP +is empty or a single hyphen it is ignored\&. +.RS +.PP +The return status of \fB_call_function\fP itself is zero if the function +\fIname\fP exists and was called and non\-zero otherwise\&. +.RE +.TP +\fB_call_program\fP [ \fB\-l\fP ] [ \fB\-p\fP ] \fItag\fP \fIstring\fP \&.\&.\&. +This function provides a mechanism for the user to override the use of an +external command\&. It looks up the \fBcommand\fP style with the supplied +\fItag\fP\&. If the style is set, its value is used as the command to +execute\&. The \fIstring\fPs from the call to \fB_call_program\fP, or from the +style if set, are concatenated with spaces between them and the resulting +string is evaluated\&. The return status is the return status of the command +called\&. +.RS +.PP +By default, the command is run in an environment where all the locale +categories (except for \fBLC_CTYPE\fP) are reset to `\fBC\fP\&' by calling the +utility function \fB_comp_locale\fP (see below)\&. If the option `\fB\-l\fP\&' is +given, the command is run with the current locale\&. +.PP +If the option `\fB\-p\fP\&' is supplied it indicates that the command +output is influenced by the permissions it is run with\&. If the +\fBgain\-privileges\fP style is set to true, \fB_call_program\fP will make +use of commands such as \fBsudo\fP, if present on the command\-line, to +match the permissions to whatever the final command is likely to run +under\&. When looking up the \fBgain\-privileges\fP and \fBcommand\fP styles, +the command component of the zstyle context will end with a slash +(`\fB/\fP\&') followed by the command that would be used to gain privileges\&. +.RE +.TP +\fB_combination\fP [ \fB\-s\fP \fIpattern\fP ] \fItag\fP \fIstyle\fP \fIspec\fP \&.\&.\&. \fIfield\fP \fIopts\fP \&.\&.\&. +This function is used to complete combinations of values, for example +pairs of hostnames and usernames\&. The \fIstyle\fP argument gives the style +which defines the pairs; it is looked up in a context with the \fItag\fP +specified\&. +.RS +.PP +The style name consists of field names separated by hyphens, for example +`\fBusers\-hosts\-ports\fP\&'\&. For each field for a value is already known, a +\fIspec\fP of the form `\fIfield\fP\fB=\fP\fIpattern\fP\&' is given\&. For example, +if the command line so far specifies a user `\fBpws\fP\&', the argument +`\fBusers=pws\fP\&' should appear\&. +.PP +The next argument with no equals sign is taken as the name of the field +for which completions should be generated (presumably not one of the +\fIfield\fPs for which the value is known)\&. +.PP +The matches generated will be taken from the value of the style\&. These +should contain the possible values for the combinations in the appropriate +order (users, hosts, ports in the example above)\&. +The values for the different fields are separated by colons\&. This +can be altered with the option \fB\-s\fP to \fB_combination\fP which specifies a +pattern\&. Typically this is a character class, as for example +`\fB\-s "[:@]"\fP\&' in the case of the \fBusers\-hosts\fP style\&. Each +`\fIfield\fP\fB=\fP\fIpattern\fP\&' specification restricts the +completions which apply to elements of the style with appropriately +matching fields\&. +.PP +If no style with the given name is defined for the given tag, +or if none of the strings in style\&'s value match, but a +function name of the required field preceded by an +underscore is defined, that function will be called to generate the +matches\&. For example, if there is no `\fBusers\-hosts\-ports\fP\&' or no +matching hostname when a host is required, the function `\fB_hosts\fP\&' will +automatically be called\&. +.PP +If the same name is used for more than one field, in both the +`\fIfield\fP\fB=\fP\fIpattern\fP\&' and the argument that gives the name of the +field to be completed, the number of the field (starting with one) may +be given after the fieldname, separated from it by a colon\&. +.PP +All arguments after the required field name are passed to +\fBcompadd\fP when generating matches from the style value, or to +the functions for the fields if they are called\&. +.RE +.TP +\fB_command_names\fP [ \fB\-e\fP | \fB\-\fP ] +This function completes words that are valid at command position: names of +aliases, builtins, hashed commands, functions, and so on\&. With the \fB\-e\fP +flag, only hashed commands are completed\&. The \fB\-\fP flag is ignored\&. +.TP +\fB_comp_locale\fP +This function resets all the locale categories other than \fBLC_CTYPE\fP to +`\fBC\fP\&' so that the output from external commands can be easily analyzed by +the completion system\&. \fBLC_CTYPE\fP retains the current value (taking +\fBLC_ALL\fP and \fBLANG\fP into account), ensuring that non\-ASCII characters +in file names are still handled properly\&. +.RS +.PP +This function should normally be run only in a subshell, because the new +locale is exported to the environment\&. Typical usage would be +`\fB$(_comp_locale; \fP\fIcommand\fP \&.\&.\&.\fB)\fP\&'\&. +.RE +.TP +\fB_completers\fP [ \fB\-p\fP ] +This function completes names of completers\&. +.RS +.PP +.PD 0 +.TP +.PD +\fB\-p\fP +Include the leading underscore (`\fB_\fP\&') in the matches\&. +.RE +.TP +\fB_default\fP +This function corresponds to the \fB\-default\-\fP special context which is +applied where no completion is defined\&. It is useful to call it under +certain error conditions such as completion after an unrecognised +subcommand\&. This applies the concept of graceful degradation to the +completion system, allowing it to fallback on basic completion of +commonly useful things like filenames\&. + +.TP +.PD 0 +\fB_describe \fP[\fB\-12JVx\fP] [ \fB\-oO\fP | \fB\-t\fP \fItag\fP ] \fIdescr\fP \fIname1\fP [ \fIname2\fP ] [ \fIopt\fP \&.\&.\&. ] +.TP +.PD +\fB \fP[ \fB\-\fP\fB\-\fP \fIname1\fP [ \fIname2\fP ] [ \fIopt\fP \&.\&.\&. ] \&.\&.\&. ] +This function associates completions with descriptions\&. +Multiple groups separated by \fB\-\fP\fB\-\fP can be supplied, potentially with +different completion options \fIopt\fPs\&. +.RS +.PP +The \fIdescr\fP is taken as a string to display above the matches if the +\fBformat\fP style for the \fBdescriptions\fP tag is set\&. This is followed by +one or two names of arrays followed by options to pass to \fBcompadd\fP\&. The +array \fIname1\fP contains the possible completions with their descriptions in +the form `\fIcompletion\fP\fB:\fP\fIdescription\fP\&'\&. Any literal colons in +\fIcompletion\fP must be quoted with a backslash\&. If a \fIname2\fP is +given, it should have the same number of elements as \fIname1\fP; in this +case the corresponding elements are added as possible completions instead +of the \fIcompletion\fP strings from \fIname1\fP\&. The completion list +will retain the descriptions from \fIname1\fP\&. Finally, a set of +completion options can appear\&. +.PP +If the option `\fB\-o\fP\&' appears before the first argument, the matches added +will be treated as names of command options (N\&.B\&. not shell options), +typically following a `\fB\-\fP\&', `\fB\-\fP\fB\-\fP' or `\fB+\fP' on the command +line\&. In this case \fB_describe\fP uses the \fBprefix\-hidden\fP, +\fBprefix\-needed\fP and \fBverbose\fP styles to find out if the strings should +be added as completions and if the descriptions should be shown\&. Without +the `\fB\-o\fP\&' option, only the \fBverbose\fP style is used to decide how +descriptions are shown\&. If `\fB\-O\fP\&' is used instead of `\fB\-o\fP', command +options are completed as above but \fB_describe\fP will not handle the +\fBprefix\-needed\fP style\&. +.PP +With the \fB\-t\fP option a \fItag\fP can be specified\&. The default is +`\fBvalues\fP\&' or, if the \fB\-o\fP option is given, `\fBoptions\fP'\&. +.PP +The options \fB\-1\fP, \fB\-2\fP, \fB\-J\fP, \fB\-V\fP, \fB\-x\fP are passed to +\fB_next_label\fP\&. +.PP +If selected by the \fBlist\-grouped\fP style, strings with the same +description will appear together in the list\&. +.PP +\fB_describe\fP uses the \fB_all_labels\fP function to generate the matches, so +it does not need to appear inside a loop over tag labels\&. +.RE +.TP +\fB_description\fP [ \fB\-x\fP ] [ \fB\-12VJ\fP ] \fItag\fP \fIname\fP \fIdescr\fP [ \fIspec\fP \&.\&.\&. ] +This function is not to be confused with the previous one; it is used as +a helper function for creating options to \fBcompadd\fP\&. It is buried +inside many of the higher level completion functions and so often does +not need to be called directly\&. +.RS +.PP +The styles listed below are tested in the current context using the +given \fItag\fP\&. The resulting options for \fBcompadd\fP are put into the +array named \fIname\fP (this is traditionally `\fBexpl\fP\&', but this +convention is not enforced)\&. The description for the corresponding set +of matches is passed to the function in \fIdescr\fP\&. +.PP +The styles tested are: \fBformat\fP, \fBhidden\fP, \fBmatcher\fP, +\fBignore\-line\fP, \fBignored\-patterns\fP, \fBgroup\-name\fP and \fBsort\fP\&. +The \fBformat\fP style is first tested for the given \fItag\fP and then for +the \fBdescriptions\fP tag if no value was found, while the remainder are +only tested for the tag given as the first argument\&. The function also +calls \fB_setup\fP which tests some more styles\&. +.PP +The string returned by the \fBformat\fP style (if any) will be modified so +that the sequence `\fB%d\fP\&' is replaced by the \fIdescr\fP given as the third +argument without any leading or trailing white space\&. If, after +removing the white space, the \fIdescr\fP is the empty string, the format +style will not be used and the options put into the \fIname\fP array will +not contain an explanation string to be displayed above the matches\&. +.PP +If \fB_description\fP is called with more than three arguments, +the additional \fIspec\fPs should be of the form `\fIchar\fP\fB:\fP\fIstr\fP\&'\&. +These supply escape sequence replacements for the \fBformat\fP style: +every appearance of `\fB%\fP\fIchar\fP\&' will be replaced by \fIstring\fP\&. +If no additional \fIspec\fPs are given but the description in \fIdescr\fP +conforms to a common form then further escape sequences are set for +elements of that description\&. These elements correspond to a default +value (`\fB%o\fP\&'), the units (`\fB%m\fP') range of acceptable values +(`\fB%r\fP\&') and the remaining initial part of the description (`\fB%h\fP')\&. +The form the description takes consists of specifying the units and +range in parentheses and the default value in square brackets, for +example: +.PP +.RS +.nf +\fB_description times expl \&'timeout (seconds) (0\-60) [20]'\fP +.fi +.RE +.PP +It is possible to use \fBzformat\fP conditional expressions when styling +these elements\&. So, for example, to add `\fBdefault:\fP\&' as a tag but only +when there is a default value to show, the \fBformat\fP style might +include `\fB%(o\&.default: %o\&.)\fP\&'\&. +.PP +If the \fB\-x\fP option is given, the description will be passed to +\fBcompadd\fP using the \fB\-x\fP option instead of the default \fB\-X\fP\&. This +means that the description will be displayed even if there are no +corresponding matches\&. +.PP +The options placed in the array \fIname\fP take account of the +\fBgroup\-name\fP style, so matches are placed in a separate group where +necessary\&. The group normally has its elements sorted (by passing the +option \fB\-J\fP to \fBcompadd\fP), but if an option starting with `\fB\-V\fP\&', +`\fB\-J\fP\&', `\fB\-1\fP', or `\fB\-2\fP' is passed to \fB_description\fP, that +option will be included in the array\&. Hence it is possible for the +completion group to be unsorted by giving the option `\fB\-V\fP\&', +`\fB\-1V\fP\&', or `\fB\-2V\fP'\&. +.PP +In most cases, the function will be used like this: +.PP +.RS +.nf +\fBlocal expl +_description files expl file +compadd "$expl[@]" \- "$files[@]"\fP +.fi +.RE +.PP +Note the use of the parameter \fBexpl\fP, the hyphen, and the list of +matches\&. Almost all calls to \fBcompadd\fP within the completion system use +a similar format; this ensures that user\-specified styles are correctly +passed down to the builtins which implement the internals of completion\&. +.RE +.TP +\fB_dir_list\fP [ \fB\-s\fP \fIsep\fP ] [ \fB\-S\fP ] +Complete a list of directory names separated by colons +(the same format as \fB$PATH\fP)\&. +.RS +.PP +.PD 0 +.TP +.PD +\fB\-s\fP \fIsep\fP +Use \fIsep\fP as separator between items\&. +\fIsep\fP defaults to a colon (`\fB:\fP\&')\&. +.TP +\fB\-S\fP +Add \fIsep\fP instead of slash (`\fB/\fP\&') as an autoremoveable suffix\&. +.RE +.TP +\fB_dispatch\fP \fIcontext string\fP \&.\&.\&. +This sets the current context to \fIcontext\fP and looks for completion +functions to handle this context by hunting through the list of command +names or special contexts (as described above for \fBcompdef\fP) +given as \fIstring\fPs\&. The first completion function to be defined +for one of the contexts in the list is used to generate matches\&. +Typically, the last \fIstring\fP is \fB\-default\-\fP to cause the function +for default completion to be used as a fallback\&. +.RS +.PP +The function sets the parameter +\fB$service\fP to the \fIstring\fP being tried, and sets +the \fIcontext/command\fP field (the fourth) of the \fB$curcontext\fP +parameter to the \fIcontext\fP given as the first argument\&. +.RE +.TP +\fB_email_addresses\fP [ \fB\-c\fP ] [ \fB\-n\fP \fIplugin\fP ] +Complete email addresses\&. Addresses are provided by plugins\&. +.RS +.PP +.PD 0 +.TP +.PD +\fB\-c\fP +Complete bare \fBlocalhost@domain\&.tld\fP addresses, without a name part or +a comment\&. +Without this option, RFC822 `\fIFirstname Lastname\fP \fB<\fP\fIaddress\fP\fB>\fP\&' +strings are completed\&. +.TP +\fB\-n\fP \fIplugin\fP +Complete aliases from \fIplugin\fP\&. +.PP +The following plugins are available by default: +\fB_email\-ldap\fP (see the \fBfilter\fP style), +\fB_email\-local\fP (completes \fIuser\fP\fB@\fP\fIhostname\fP Unix addresses), +\fB_email\-mail\fP (completes aliases from \fB~/\&.mailrc\fP), +\fB_email\-mush\fP, +\fB_email\-mutt\fP, +and +\fB_email\-pine\fP\&. +.PP +Addresses from the \fB_email\-\fP\fIfoo\fP plugin are added under the +tag `\fBemail\-\fP\fIfoo\fP\&'\&. +.PP +\fIWriting plugins\fP +.PP +Plugins are written as separate functions with names starting with `\fB_email\-\fP\&'\&. +They are invoked with the \fB\-c\fP option and \fBcompadd\fP options\&. +They should either do their own completion or +set the \fB$reply\fP array to a list of `\fIalias\fP\fB:\fP\fIaddress\fP\&' elements and return \fB300\fP\&. +New plugins will be picked up and run automatically\&. +.RE +.TP +\fB_files\fP +The function \fB_files\fP is a wrapper around \fB_path_files\fP\&. It supports +all of the same functionality, with some enhancements \-\- notably, it +respects the \fBlist\-dirs\-first\fP style, and it allows users to override +the behaviour of the \fB\-g\fP and \fB\-/\fP options with the \fBfile\-patterns\fP +style\&. \fB_files\fP should therefore be preferred over \fB_path_files\fP in +most cases\&. +.RS +.PP +This function accepts the full set of options allowed by +\fB_path_files\fP, described below\&. +.RE +.TP +\fB_gnu_generic\fP +This function is a simple wrapper around the \fB_arguments\fP function +described above\&. It can be used to determine automatically the long +options understood by commands that produce a list when passed the +option `\fB\-\fP\fB\-help\fP\&'\&. It is intended to be used as a top\-level +completion function in its own right\&. For example, to enable option +completion for the commands \fBfoo\fP and \fBbar\fP, use +.RS +.PP +.RS +.nf +\fBcompdef _gnu_generic foo bar\fP +.fi +.RE +.PP +after the call to \fBcompinit\fP\&. +.PP +The completion system as supplied is conservative in its use of this +function, since it is important to be sure the command understands the +option `\fB\-\fP\fB\-help\fP\&'\&. +.RE +.TP +\fB_guard\fP [ \fIoptions\fP ] \fIpattern descr\fP +This function displays \fIdescr\fP if \fIpattern\fP matches the string to +be completed\&. It is intended to be used in the \fIaction\fP for the +specifications passed to \fB_arguments\fP and similar functions\&. +.RS +.PP +The return status is zero if the message was displayed and the word to +complete is not empty, and non\-zero otherwise\&. +.PP +The \fIpattern\fP may be preceded by any of the options understood by +\fBcompadd\fP that are passed down from \fB_description\fP, namely \fB\-M\fP, +\fB\-J\fP, \fB\-V\fP, \fB\-1\fP, \fB\-2\fP, \fB\-n\fP, \fB\-F\fP and \fB\-X\fP\&. All of these +options will be ignored\&. This fits in conveniently with the +argument\-passing conventions of actions for \fB_arguments\fP\&. +.PP +As an example, consider a command taking the options \fB\-n\fP and +\fB\-none\fP, where \fB\-n\fP must be followed by a numeric value in the +same word\&. By using: +.PP +.RS +.nf +\fB_arguments \&'\-n\-: :_guard "[0\-9]#" "numeric value"' '\-none'\fP +.fi +.RE +.PP +\fB_arguments\fP can be made to both display the message `\fBnumeric +value\fP\&' and complete options after `\fB\-n<TAB>\fP'\&. If the `\fB\-n\fP' is +already followed by one or more digits (the pattern passed to +\fB_guard\fP) only the message will be displayed; if the `\fB\-n\fP\&' is +followed by another character, only options are completed\&. +.RE +.TP +.PD 0 +\fB_message\fP [ \fB\-r12\fP ] [ \fB\-VJ\fP \fIgroup\fP ] \fIdescr\fP +.TP +.PD +\fB_message \-e\fP [ \fItag\fP ] \fIdescr\fP +The \fIdescr\fP is used in the same way as the third +argument to the \fB_description\fP function, except that the resulting +string will always be shown whether or not matches were +generated\&. This is useful for displaying a help message in places where +no completions can be generated\&. +.RS +.PP +The \fBformat\fP style is examined with the \fBmessages\fP tag to find a +message; the usual tag, \fBdescriptions\fP, is used only if the style is +not set with the former\&. +.PP +If the \fB\-r\fP option is given, no style is used; the \fIdescr\fP is +taken literally as the string to display\&. This is most useful +when the \fIdescr\fP comes from a pre\-processed argument list +which already contains an expanded description\&. Note that this +option does not disable the `\fB%\fP\&'\-sequence parsing done by +\fBcompadd\fP\&. +.PP +The \fB\-12VJ\fP options and the \fIgroup\fP are passed to \fBcompadd\fP and +hence determine the group the message string is added to\&. +.PP +The second \fB\-e\fP form gives a description for completions with the tag +\fItag\fP to be shown even if there are no matches for that tag\&. This form +is called by \fB_arguments\fP in the event that there is no action for an +option specification\&. The tag can be omitted and if so the tag is taken +from the parameter \fB$curtag\fP; this is maintained by the completion +system and so is usually correct\&. Note that if there are no matches at +the time this function is called, \fBcompstate[insert]\fP is cleared, so +additional matches generated later are not inserted on the command line\&. +.RE +.TP +\fB_multi_parts\fP [ \fB\-i\fP ] \fIsep\fP \fIarray\fP +The argument \fIsep\fP is a separator character\&. +The \fIarray\fP may be either the +name of an array parameter or a literal array in the form +`\fB(foo bar\fP\fB)\fP\&', a parenthesised list of words separated +by whitespace\&. The possible completions are the +strings from the array\&. However, each chunk delimited by \fIsep\fP will be +completed separately\&. For example, the \fB_tar\fP function uses +`\fB_multi_parts\fP \fB/\fP \fIpatharray\fP\&' to complete partial file paths +from the given array of complete file paths\&. +.RS +.PP +The \fB\-i\fP option causes \fB_multi_parts\fP to insert a unique match even +if that requires multiple separators to be inserted\&. This is not usually +the expected behaviour with filenames, but certain other types of +completion, for example those with a fixed set of possibilities, may be +more suited to this form\&. +.PP +Like other utility functions, this function accepts the `\fB\-V\fP\&', +`\fB\-J\fP\&', `\fB\-1\fP', `\fB\-2\fP', `\fB\-n\fP', `\fB\-f\fP', `\fB\-X\fP', `\fB\-M\fP', +`\fB\-P\fP\&', `\fB\-S\fP', `\fB\-r\fP', `\fB\-R\fP', and `\fB\-q\fP' options and passes +them to the \fBcompadd\fP builtin\&. +.RE +.TP +\fB_next_label\fP [ \fB\-x\fP ] [ \fB\-12VJ\fP ] \fItag\fP \fIname\fP \fIdescr\fP [ \fIoption\fP \&.\&.\&. ] +This function is used to implement the loop over different tag +labels for a particular tag as described above for the \fBtag\-order\fP +style\&. On each call it checks to see if there are any more tag labels; if +there is it returns status zero, otherwise non\-zero\&. +As this function requires a current tag to be set, it must always follow +a call to \fB_tags\fP or \fB_requested\fP\&. +.RS +.PP +The \fB\-x12VJ\fP options and the first three arguments are passed to the +\fB_description\fP function\&. Where appropriate the \fItag\fP will be +replaced by a tag label in this call\&. Any description given in +the \fBtag\-order\fP style is preferred to the \fIdescr\fP passed to +\fB_next_label\fP\&. +.PP +The \fIoption\fPs given after the \fIdescr\fP +are set in the parameter given by \fIname\fP, and hence are to be passed +to \fBcompadd\fP or whatever function is called to add the matches\&. +.PP +Here is a typical use of this function for the tag \fBfoo\fP\&. The call to +\fB_requested\fP determines if tag \fBfoo\fP is required at all; the loop +over \fB_next_label\fP handles any labels defined for the tag in the +\fBtag\-order\fP style\&. +.PP +.RS +.nf +\fBlocal expl ret=1 +\&.\&.\&. +if _requested foo; then + \&.\&.\&. + while _next_label foo expl \&'\&.\&.\&.'; do + compadd "$expl[@]" \&.\&.\&. && ret=0 + done + \&.\&.\&. +fi +return ret\fP +.fi +.RE +.RE +.TP +\fB_normal\fP [ \fB\-P\fP | \fB\-p\fP \fIprecommand\fP ] +This is the standard function called to handle completion outside +any special \fB\-\fP\fIcontext\fP\fB\-\fP\&. It is called both to complete the command +word and also the arguments for a command\&. In the second case, +\fB_normal\fP looks for a special completion for that command, and if +there is none it uses the completion for the \fB\-default\-\fP context\&. +.RS +.PP +A second use is to reexamine the command line specified by the \fB$words\fP +array and the \fB$CURRENT\fP parameter after those have been modified\&. +For example, the function \fB_precommand\fP, which +completes after precommand specifiers such as \fBnohup\fP, removes the +first word from the \fBwords\fP array, decrements the \fBCURRENT\fP parameter, +then calls `\fB_normal \-p $service\fP\&'\&. The effect is that +`\fBnohup\fP \fIcmd \&.\&.\&.\fP\&' is treated in the same way as `\fIcmd \&.\&.\&.\fP'\&. +.PP +.PD 0 +.TP +.PD +\fB\-P\fP +Reset the list of precommands\&. This option should be used if completing +a command line which allows internal commands (e\&.g\&. builtins and +functions) regardless of prior precommands (e\&.g\&. `\fBzsh \-c\fP\&')\&. +.TP +\fB\-p\fP \fIprecommand\fP +Append \fIprecommand\fP to the list of precommands\&. This option should be +used in nearly all cases in which \fB\-P\fP is not applicable\&. +.PP +If the command name matches one of the patterns given by one of the +options \fB\-p\fP or \fB\-P\fP to \fBcompdef\fP, the corresponding completion +function is called and then the parameter \fB_compskip\fP is +checked\&. If it is set completion is terminated at that point even if +no matches have been found\&. This is the same effect as in the +\fB\-first\-\fP context\&. +.RE +.TP +\fB_numbers\fP [ \fIoption\fP \&.\&.\&. ] [ \fIdescription\fP ] [ \fIsuffix\fP \&.\&.\&. ] +This can be used where a number is followed by a suffix to indicate the units\&. +The unit suffixes are completed and can also be included in the description +used when completion is invoked for the preceding number\&. +.RS +.PP +In addition to common \fBcompadd\fP options, \fB_numbers\fP accepts the following +options: +.PP +.PD 0 +.TP +.PD +\fB\-t\fP \fItag\fP +Specify a tag to use instead of the default of \fBnumbers\fP\&. +.TP +\fB\-u\fP \fIunits\fP +Indicate the default units for the number, e\&.g\&. \fBbytes\fP\&. +.TP +\fB\-l\fP \fImin\fP +Specify the lowest possible value for the number\&. +.TP +\fB\-m\fP \fImax\fP +Specify the highest possible value for the number\&. +.TP +\fB\-d\fP \fIdefault\fP +Specify the default value\&. +.TP +\fB\-N\fP +Allow negative numbers\&. This is implied if the range includes a negative\&. +.TP +\fB\-f\fP +Allow decimal numbers\&. +.PP +Where a particular suffix represents the default units for a number, it +should be prefixed with a colon\&. Additionally, suffixes can be followed +by a colon and a description\&. So for example, the following allows the +age of something to be specified, either in seconds or with an optional +suffix with a longer unit of time: +.PP +.RS +.nf +\fB_numbers \-u seconds age :s:seconds m:minutes h:hours d:days\fP +.fi +.RE +.PP +It is typically helpful for units to be presented in order of magnitude +when completed\&. To facilitate this, the order in which they are given +is preserved\&. +.PP +When the \fBformat\fP style is looked up with the \fBdescriptions\fP tag or +the tag specified with \fB\-t\fP, the list of suffixes is available as a +`\fB%x\fP\&' escape sequence\&. This is in addition to the usual sequences +documented under the \fBformat\fP style\&. The form this list takes can also +be configured\&. To this end, the \fBformat\fP style is first looked up with +the tag \fBunit\-suffixes\fP\&. The retrieved format is applied to each +suffix in turn and the results are then concatenated to form the +completed list\&. For the \fBunit\-suffixes\fP format, `\fB%x\fP\&' expands to +the individual suffix and `\fB%X\fP\&' to its description\&. \fB%d\fP' indicates +a default suffix and can be used in a condition\&. The index and reverse +index are set in `\fB%i\fP\&' and `\fB%r\fP' respectively and are useful for +text included only with the first and last suffixes in the list\&. So for +example, the following joins the suffixes together as a comma\-separated +list: +.PP +.RS +.nf +\fBzstyle \&':completion:*:unit\-suffixes' format '%x%(r::,)'\fP +.fi +.RE +.RE +.PP +.TP +\fB_options\fP +This can be used to complete the names of shell options\&. It provides a +matcher specification that ignores a leading `\fBno\fP\&', ignores +underscores and allows upper\-case letters to +match their lower\-case counterparts (for example, `\fBglob\fP\&', +`\fBnoglob\fP\&', `\fBNO_GLOB\fP' are all completed)\&. Any arguments +are propagated to the \fBcompadd\fP builtin\&. +.TP +\fB_options_set\fP and \fB_options_unset\fP +These functions complete only set or unset options, with the same +matching specification used in the \fB_options\fP function\&. +.RS +.PP +Note that you need to uncomment a few lines in the \fB_main_complete\fP +function for these functions to work properly\&. The lines in question +are used to store the option settings in effect before the completion +widget locally sets the options it needs\&. Hence these functions are not +generally used by the completion system\&. +.RE +.TP +\fB_parameters\fP +This is used to complete the names of shell parameters\&. +.RS +.PP +The option `\fB\-g\fP \fIpattern\fP\&' limits the completion to parameters +whose type matches the \fIpattern\fP\&. The type of a parameter is that +shown by `\fBprint ${(t)\fP\fIparam\fP\fB}\fP\&', hence judicious use of +`\fB*\fP\&' in \fIpattern\fP is probably necessary\&. +.PP +All other arguments are passed to the \fBcompadd\fP builtin\&. +.RE +.TP +\fB_path_files\fP +This function is used throughout the completion system +to complete filenames\&. It allows completion of partial paths\&. For +example, the string `\fB/u/i/s/sig\fP\&' may be completed to +`\fB/usr/include/sys/signal\&.h\fP\&'\&. +.RS +.PP +The options accepted by both \fB_path_files\fP and \fB_files\fP are: +.PP +.PD 0 +.TP +.PD +\fB\-f\fP +Complete all filenames\&. This is the default\&. +.TP +\fB\-/\fP +Specifies that only directories should be completed\&. +.TP +\fB\-g\fP \fIpattern\fP +Specifies that only files matching the \fIpattern\fP should be completed\&. +.TP +\fB\-W\fP \fIpaths\fP +Specifies path prefixes that are to be prepended to the string from the +command line to generate the filenames but that should not be inserted +as completions nor shown in completion listings\&. Here, \fIpaths\fP may be +the name of an array parameter, a literal list of paths enclosed in +parentheses or an absolute pathname\&. +.TP +\fB\-F\fP \fIignored\-files\fP +This behaves as for the corresponding option to the \fBcompadd\fP builtin\&. +It gives direct control over which +filenames should be ignored\&. If the option is not present, the +\fBignored\-patterns\fP style is used\&. +.PP +Both \fB_path_files\fP and \fB_files\fP also accept the following options +which are passed to \fBcompadd\fP: `\fB\-J\fP\&', `\fB\-V\fP', +`\fB\-1\fP\&', `\fB\-2\fP', `\fB\-n\fP', `\fB\-X\fP', `\fB\-M\fP', `\fB\-P\fP', `\fB\-S\fP', +`\fB\-q\fP\&', `\fB\-r\fP', and `\fB\-R\fP'\&. +.PP +Finally, the \fB_path_files\fP function uses the styles \fBexpand\fP, +\fBambiguous\fP, \fBspecial\-dirs\fP, \fBlist\-suffixes\fP and \fBfile\-sort\fP +described above\&. +.RE + +.TP +.PD 0 +\fB_pick_variant \fP[ \fB\-b\fP \fIbuiltin\-label\fP ] [ \fB\-c\fP \fIcommand\fP ] [ \fB\-r\fP \fIname\fP ] +.TP +.PD +\fB \fP\fIlabel\fP\fB=\fP\fIpattern\fP \&.\&.\&. \fIlabel\fP [ \fIarg\fP \&.\&.\&. ] +This function is used to resolve situations where a single command name +requires more than one type of handling, either because it +has more than one variant or because there is a name clash between two +different commands\&. +.RS +.PP +The command to run is taken from the first element of the array +\fBwords\fP unless this is overridden by the option \fB\-c\fP\&. This command +is run and its output is compared with a series of patterns\&. Arguments +to be passed to the command can be specified at the end after all the +other arguments\&. The patterns to try in order are given by the arguments +\fIlabel\fP\fB=\fP\fIpattern\fP; if the output of `\fIcommand\fP \fIarg\fP +\&.\&.\&.\&' contains \fIpattern\fP, then \fIlabel\fP is selected as the label +for the command variant\&. If none of the patterns match, the final +command label is selected and status 1 is returned\&. +.PP +If the `\fB\-b\fP \fIbuiltin\-label\fP\&' is given, the command is tested to +see if it is provided as a shell builtin, possibly autoloaded; if so, +the label \fIbuiltin\-label\fP is selected as the label for the variant\&. +.PP +If the `\fB\-r\fP \fIname\fP\&' is given, the \fIlabel\fP picked is stored in +the parameter named \fIname\fP\&. +.PP +The results are also cached in the \fB_cmd_variant\fP associative array +indexed by the name of the command run\&. +.RE +.TP +\fB_regex_arguments\fP \fIname\fP \fIspec\fP \&.\&.\&. +This function generates a completion function \fIname\fP which matches +the specifications \fIspec\fPs, a set of regular expressions as +described below\&. After running \fB_regex_arguments\fP, the function +\fIname\fP should be called as a normal completion function\&. +The pattern to be matched is given by the contents of +the \fBwords\fP array up to the current cursor position joined together +with null characters; no quotation is applied\&. +.RS +.PP +The arguments are grouped as sets of alternatives separated by `\fB|\fP\&', +which are tried one after the other until one matches\&. Each alternative +consists of a one or more specifications which are tried left to right, +with each pattern matched being stripped in turn from the command line +being tested, until all of the group succeeds or until one fails; in the +latter case, the next alternative is tried\&. This structure can be +repeated to arbitrary depth by using parentheses; matching proceeds from +inside to outside\&. +.PP +A special procedure is applied if no test succeeds but the remaining +command line string contains no null character (implying the remaining +word is the one for which completions are to be generated)\&. The +completion target is restricted to the remaining word and any +\fIaction\fPs for the corresponding patterns are executed\&. In this case, +nothing is stripped from the command line string\&. The order of +evaluation of the \fIaction\fPs can be determined by the \fBtag\-order\fP +style; the various formats supported by \fB_alternative\fP can be used +in \fIaction\fP\&. The \fIdescr\fP is used for setting up the array +parameter \fBexpl\fP\&. +.PP +Specification arguments take one of following forms, in which +metacharacters such as `\fB(\fP\&', `\fB)\fP', `\fB#\fP' and `\fB|\fP' +should be quoted\&. +.PP +.PD 0 +.TP +.PD +\fB/\fP\fIpattern\fP\fB/\fP [\fB%\fP\fIlookahead\fP\fB%\fP] [\fB\-\fP\fIguard\fP] [\fB:\fP\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP] +This is a single primitive component\&. +The function tests whether the combined pattern +`\fB(#b)((#B)\fP\fIpattern\fP\fB)\fP\fIlookahead\fP\fB*\fP\&' matches +the command line string\&. If so, `\fIguard\fP\&' is evaluated and +its return status is examined to determine if the test has succeeded\&. +The \fIpattern\fP string `\fB[]\fP\&' is guaranteed never to match\&. +The \fIlookahead\fP is not stripped from the command line before the next +pattern is examined\&. +.RS +.PP +The argument starting with \fB:\fP is used in the same manner as an argument to +\fB_alternative\fP\&. +.PP +A component is used as follows: \fIpattern\fP is tested to +see if the component already exists on the command line\&. If +it does, any following specifications are examined to find something to +complete\&. If a component is reached but no such pattern exists yet on the +command line, the string containing the \fIaction\fP is used to generate +matches to insert at that point\&. +.RE +.TP +\fB/\fP\fIpattern\fP\fB/+\fP [\fB%\fP\fIlookahead\fP\fB%\fP] [\fB\-\fP\fIguard\fP] [\fB:\fP\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP] +This is similar to `\fB/\fP\fIpattern\fP\fB/\fP \&.\&.\&.\&' but the left part of the +command line string (i\&.e\&. the part already matched by previous patterns) +is also considered part of the completion target\&. +.TP +\fB/\fP\fIpattern\fP\fB/\-\fP [\fB%\fP\fIlookahead\fP\fB%\fP] [\fB\-\fP\fIguard\fP] [\fB:\fP\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP] +This is similar to `\fB/\fP\fIpattern\fP\fB/\fP \&.\&.\&.\&' but the \fIaction\fPs of the +current and previously matched patterns are ignored even if the +following `\fIpattern\fP\&' matches the empty string\&. +.TP +\fB(\fP \fIspec\fP \fB)\fP +Parentheses may be used to groups \fIspec\fPs; note each parenthesis +is a single argument to \fB_regex_arguments\fP\&. +.TP +\fIspec\fP \fB#\fP +This allows any number of repetitions of \fIspec\fP\&. +.TP +\fIspec\fP \fIspec\fP +The two \fIspec\fPs are to be matched one after the other as described +above\&. +.TP +\fIspec\fP \fB|\fP \fIspec\fP +Either of the two \fIspec\fPs can be matched\&. +.PP +The function \fB_regex_words\fP can be used as a helper function to +generate matches for a set of alternative words possibly with +their own arguments as a command line argument\&. +.PP +Examples: +.PP +.RS +.nf +\fB_regex_arguments _tst /$\&'[^\e0]#\e0'/ \e + /$\&'[^\e0]#\e0'/ :'compadd aaa'\fP +.fi +.RE +.PP +This generates a function \fB_tst\fP that completes \fBaaa\fP as its only +argument\&. The \fItag\fP and \fIdescription\fP for the action have been +omitted for brevity (this works but is not recommended in normal use)\&. +The first component matches the command word, which is arbitrary; the +second matches any argument\&. As the argument is also arbitrary, any +following component would not depend on \fBaaa\fP being present\&. +.PP +.RS +.nf +\fB_regex_arguments _tst /$\&'[^\e0]#\e0'/ \e + /$\&'aaa\e0'/ :'compadd aaa'\fP +.fi +.RE +.PP +This is a more typical use; it is similar, but any following patterns +would only match if \fBaaa\fP was present as the first argument\&. +.PP +.RS +.nf +\fB_regex_arguments _tst /$\&'[^\e0]#\e0'/ \e( \e + /$\&'aaa\e0'/ :'compadd aaa' \e + /$\&'bbb\e0'/ :'compadd bbb' \e) \e#\fP +.fi +.RE +.PP +In this example, an indefinite number of command arguments may be +completed\&. Odd arguments are completed as \fBaaa\fP and even arguments +as \fBbbb\fP\&. Completion fails unless the set of \fBaaa\fP and \fBbbb\fP +arguments before the current one is matched correctly\&. +.PP +.RS +.nf +\fB_regex_arguments _tst /$\&'[^\e0]#\e0'/ \e + \e( /$\&'aaa\e0'/ :'compadd aaa' \e| \e + /$\&'bbb\e0'/ :'compadd bbb' \e) \e#\fP +.fi +.RE +.PP +This is similar, but either \fBaaa\fP or \fBbbb\fP may be completed for +any argument\&. In this case \fB_regex_words\fP could be used to generate +a suitable expression for the arguments\&. +.PP +.RE +.TP +\fB_regex_words\fP \fItag\fP \fIdescription\fP \fIspec\fP \&.\&.\&. +This function can be used to generate arguments for the +\fB_regex_arguments\fP command which may be inserted at any point where +a set of rules is expected\&. The \fItag\fP and \fIdescription\fP give a +standard tag and description pertaining to the current context\&. Each +\fIspec\fP contains two or three arguments separated by a colon: note +that there is no leading colon in this case\&. +.RS +.PP +Each \fIspec\fP gives one of a set of words that may be completed at +this point, together with arguments\&. It is thus roughly equivalent to +the \fB_arguments\fP function when used in normal (non\-regex) completion\&. +.PP +The part of the \fIspec\fP before the first colon is the word to be +completed\&. This may contain a \fB*\fP; the entire word, before and after +the \fB*\fP is completed, but only the text before the \fB*\fP is required +for the context to be matched, so that further arguments may be +completed after the abbreviated form\&. +.PP +The second part of \fIspec\fP is a description for the word being +completed\&. +.PP +The optional third part of the \fIspec\fP describes how words following +the one being completed are themselves to be completed\&. It will be +evaluated in order to avoid problems with quoting\&. This means that +typically it contains a reference to an array containing previously +generated regex arguments\&. +.PP +The option \fB\-t\fP \fIterm\fP specifies a terminator for the word +instead of the usual space\&. This is handled as an auto\-removable suffix +in the manner of the option \fB\-s\fP \fIsep\fP to \fB_values\fP\&. +.PP +The result of the processing by \fB_regex_words\fP is placed in the array +\fBreply\fP, which should be made local to the calling function\&. +If the set of words and arguments may be matched repeatedly, a \fB#\fP +should be appended to the generated array at that point\&. +.PP +For example: +.PP +.RS +.nf +\fBlocal \-a reply +_regex_words mydb\-commands \&'mydb commands' \e + \&'add:add an entry to mydb:$mydb_add_cmds' \e + \&'show:show entries in mydb' +_regex_arguments _mydb "$reply[@]" +_mydb "$@"\fP +.fi +.RE +.PP +This shows a completion function for a command \fBmydb\fP which takes +two command arguments, \fBadd\fP and \fBshow\fP\&. \fBshow\fP takes no arguments, +while the arguments for \fBadd\fP have already been prepared in an +array \fBmydb_add_cmds\fP, quite possibly by a previous call to +\fB_regex_words\fP\&. +.RE +.TP +\fB_requested\fP [ \fB\-x\fP ] [ \fB\-12VJ\fP ] \fItag\fP [ \fIname\fP \fIdescr\fP [ \fIcommand\fP [ \fIarg\fP \&.\&.\&. ] ] +This function is called to decide whether a tag already registered by a +call to \fB_tags\fP (see below) has been requested by the user and hence +completion should be performed for it\&. It returns status zero if the +tag is requested and non\-zero otherwise\&. The function is typically used +as part of a loop over different tags as follows: +.RS +.PP +.RS +.nf +\fB_tags foo bar baz +while _tags; do + if _requested foo; then + \&.\&.\&. # perform completion for foo + fi + \&.\&.\&. # test the tags bar and baz in the same way + \&.\&.\&. # exit loop if matches were generated +done\fP +.fi +.RE +.PP +Note that the test for whether matches were generated is not performed +until the end of the \fB_tags\fP loop\&. This is so that the user can set +the \fBtag\-order\fP style to specify a set of tags to be completed at the +same time\&. +.PP +If \fIname\fP and \fIdescr\fP are given, \fB_requested\fP calls the +\fB_description\fP function with these arguments together with the options +passed to \fB_requested\fP\&. +.PP +If \fIcommand\fP is given, the \fB_all_labels\fP function will be called +immediately with the same arguments\&. In simple cases this makes it +possible to perform the test for the tag and the matching in one go\&. +For example: +.PP +.RS +.nf +\fBlocal expl ret=1 +_tags foo bar baz +while _tags; do + _requested foo expl \&'description' \e + compadd foobar foobaz && ret=0 + \&.\&.\&. + (( ret )) || break +done\fP +.fi +.RE +.PP +If the \fIcommand\fP is not \fBcompadd\fP, it must nevertheless be prepared +to handle the same options\&. +.RE +.TP +\fB_retrieve_cache\fP \fIcache_identifier\fP +This function retrieves completion information from the file given by +\fIcache_identifier\fP, stored in a directory specified by the +\fBcache\-path\fP style which defaults to \fB~/\&.zcompcache\fP\&. The return status +is zero if retrieval was successful\&. It will only attempt retrieval +if the \fBuse\-cache\fP style is set, so you can call this function +without worrying about whether the user wanted to use the caching +layer\&. +.RS +.PP +See \fB_store_cache\fP below for more details\&. +.RE +.TP +\fB_sep_parts\fP +This function is passed alternating arrays and separators as arguments\&. +The arrays specify completions for parts of strings to be separated by the +separators\&. The arrays may be the names of array parameters or +a quoted list of words in parentheses\&. For example, with the array +`\fBhosts=(ftp news)\fP\&' the call `\fB_sep_parts '(foo bar)' @ hosts\fP' will +complete the string `\fBf\fP\&' to `\fBfoo\fP' and the string `\fBb@n\fP' to +`\fBbar@news\fP\&'\&. +.RS +.PP +This function accepts the \fBcompadd\fP options `\fB\-V\fP\&', `\fB\-J\fP', +`\fB\-1\fP\&', `\fB\-2\fP', `\fB\-n\fP', `\fB\-X\fP', `\fB\-M\fP', `\fB\-P\fP', `\fB\-S\fP', +`\fB\-r\fP\&', `\fB\-R\fP', and `\fB\-q\fP' and passes them on to the \fBcompadd\fP +builtin used to add the matches\&. +.RE +.TP +\fB_sequence\fP [ \fB\-s\fP \fIsep\fP ] [ \fB\-n\fP \fImax\fP ] [ \fB\-d\fP ] \fIfunction\fP [ \fB\-\fP ] \&.\&.\&. +This function is a wrapper to other functions for completing items in a +separated list\&. The same function is used to complete each item in the +list\&. The separator is specified with the \fB\-s\fP option\&. If \fB\-s\fP is +omitted it will use `\fB,\fP\&'\&. Duplicate values are not matched unless +\fB\-d\fP is specified\&. If there is a fixed or maximum number of items in +the list, this can be specified with the \fB\-n\fP option\&. +.RS +.PP +Common \fBcompadd\fP options are passed on to the function\&. It is possible +to use \fBcompadd\fP directly with \fB_sequence\fP, though \fB_values\fP may +be more appropriate in this situation\&. +.RE +.TP +\fB_setup\fP \fItag\fP [ \fIgroup\fP ] +This function sets up the special +parameters used by the completion system appropriately for the \fItag\fP +given as the first argument\&. It uses the styles \fBlist\-colors\fP, +\fBlist\-packed\fP, \fBlist\-rows\-first\fP, \fBlast\-prompt\fP, \fBaccept\-exact\fP, +\fBmenu\fP and \fBforce\-list\fP\&. +.RS +.PP +The optional \fIgroup\fP supplies the name of the group in which the +matches will be placed\&. If it is not given, the \fItag\fP is used as +the group name\&. +.PP +This function is called automatically from \fB_description\fP +and hence is not normally called explicitly\&. +.RE +.TP +\fB_store_cache\fP \fIcache_identifier\fP \fIparam\fP \&.\&.\&. +This function, together with \fB_retrieve_cache\fP and +\fB_cache_invalid\fP, implements a caching layer which can be used +in any completion function\&. Data obtained by +costly operations are stored in parameters; +this function then dumps the values of those parameters to a file\&. The +data can then be retrieved quickly from that file via \fB_retrieve_cache\fP, +even in different instances of the shell\&. +.RS +.PP +The \fIcache_identifier\fP specifies the file which the data should be +dumped to\&. The file is stored in a directory specified by the +\fBcache\-path\fP style which defaults to \fB~/\&.zcompcache\fP\&. The remaining +\fIparam\fPs arguments are the parameters to dump to the file\&. +.PP +The return status is zero if storage was successful\&. The function will +only attempt storage if the \fBuse\-cache\fP style is set, so you can +call this function without worrying about whether the user wanted to +use the caching layer\&. +.PP +The completion function may avoid calling \fB_retrieve_cache\fP when it +already has the completion data available as parameters\&. +However, in that case it should +call \fB_cache_invalid\fP to check whether the data in the parameters and +in the cache are still valid\&. +.PP +See the _perl_modules completion function for a simple example of +the usage of the caching layer\&. +.RE +.TP +\fB_tags\fP [ [ \fB\-C\fP \fIname\fP ] \fItag\fP \&.\&.\&. ] +If called with arguments, these are taken to be the names of tags +valid for completions in the current context\&. These tags are stored +internally and sorted by using the \fBtag\-order\fP style\&. +.RS +.PP +Next, \fB_tags\fP is called repeatedly without arguments from the same +completion function\&. This successively selects the first, second, +etc\&. set of tags requested by the user\&. The return status is zero if at +least one of the tags is requested and non\-zero otherwise\&. To test if a +particular tag is to be tried, the \fB_requested\fP function should be +called (see above)\&. +.PP +If `\fB\-C\fP \fIname\fP\&' is given, \fIname\fP is temporarily stored in the +\fIargument\fP field (the fifth) of the context in the \fBcurcontext\fP parameter +during the call to \fB_tags\fP; the field is restored on exit\&. This +allows \fB_tags\fP to use a more +specific context without having to change and reset the +\fBcurcontext\fP parameter (which has the same effect)\&. +.RE +.TP +\fB_tilde_files\fP +Like \fB_files\fP, but resolve leading tildes according to the rules of +filename expansion, so the suggested completions don\&'t start with +a `\fB~\fP\&' even if the filename on the command\-line does\&. +.TP +\fB_values\fP [ \fB\-O\fP \fIname\fP ] [ \fB\-s\fP \fIsep\fP ] [ \fB\-S\fP \fIsep\fP ] [ \fB\-wC\fP ] \fIdesc\fP \fIspec\fP \&.\&.\&. +This is used to complete arbitrary keywords (values) and their arguments, +or lists of such combinations\&. +.RS +.PP +If the first argument is the option `\fB\-O\fP \fIname\fP\&', it will be used +in the same way as by the \fB_arguments\fP function\&. In other words, the +elements of the \fIname\fP array will be passed to \fBcompadd\fP +when executing an action\&. +.PP +If the first argument (or the first argument after `\fB\-O\fP \fIname\fP\&') +is `\fB\-s\fP\&', the next argument is used as the character that separates +multiple values\&. This character is automatically added after each value +in an auto\-removable fashion (see below); all values completed by +`\fB_values \-s\fP\&' appear in the same word on the command line, unlike +completion using \fB_arguments\fP\&. If this option is not present, only a +single value will be completed per word\&. +.PP +Normally, \fB_values\fP will only use the current word to determine +which values are already present on the command line and hence are not +to be completed again\&. If the \fB\-w\fP option is given, other arguments +are examined as well\&. +.PP +The first non\-option argument, \fIdesc\fP, is used as a string to print as a +description before listing the values\&. +.PP +All other arguments describe the possible values and their +arguments in the same format used for the description of options by +the \fB_arguments\fP function (see above)\&. The only differences are that +no minus or plus sign is required at the beginning, +values can have only one argument, and the forms of action +beginning with an equal sign are not supported\&. +.PP +The character separating a value from its argument can be set using the +option \fB\-S\fP (like \fB\-s\fP, followed by the character to use as the +separator in the next argument)\&. By default the equals +sign will be used as the separator between values and arguments\&. +.PP +Example: +.PP +.RS +.nf +\fB_values \-s , \&'description' \e + \&'*foo[bar]' \e + \&'(two)*one[number]:first count:' \e + \&'two[another number]::second count:(1 2 3)'\fP +.fi +.RE +.PP +This describes three possible values: `\fBfoo\fP\&', `\fBone\fP', and +`\fBtwo\fP\&'\&. The first is described as `\fBbar\fP', takes no argument +and may appear more than once\&. The second is described as +`\fBnumber\fP\&', may appear more than once, and takes one mandatory +argument described as `\fBfirst count\fP\&'; no action is +specified, so it will not be completed\&. The +`\fB(two)\fP\&' at the beginning says that if the value `\fBone\fP' is on +the line, the value `\fBtwo\fP\&' will no longer be considered a possible +completion\&. Finally, the last value (`\fBtwo\fP\&') is described +as `\fBanother number\fP\&' and takes an optional argument described as +`\fBsecond count\fP\&' for which the completions (to appear after an +`\fB=\fP\&') are `\fB1\fP', `\fB2\fP', and `\fB3\fP'\&. The \fB_values\fP function +will complete lists of these values separated by commas\&. +.PP +Like \fB_arguments\fP, this function temporarily adds another context name +component to the arguments element (the fifth) of the current context +while executing the \fIaction\fP\&. Here this name is just the name of the +value for which the argument is completed\&. +.PP +The style \fBverbose\fP is used to decide if the descriptions for the +values (but not those for the arguments) should be printed\&. +.PP +The associative array \fBval_args\fP is used to report values and their +arguments; this works similarly to the \fBopt_args\fP associative array +used by \fB_arguments\fP\&. Hence the function calling \fB_values\fP should +declare the local parameters \fBstate\fP, \fBstate_descr\fP, \fBline\fP, +\fBcontext\fP and \fBval_args\fP: +.PP +.RS +.nf +\fBlocal context state state_descr line +typeset \-A val_args\fP +.fi +.RE +.PP +when using an action of the form `\fB\->\fP\fIstring\fP\&'\&. With this +function the \fBcontext\fP parameter will be set to the name of the +value whose argument is to be completed\&. Note that for \fB_values\fP, +the \fBstate\fP and \fBstate_descr\fP are scalars rather than arrays\&. +Only a single matching state is returned\&. +.PP +Note also that \fB_values\fP normally adds the character used as the +separator between values as an auto\-removable suffix (similar to a +`\fB/\fP\&' after a directory)\&. However, this is not possible for a +`\fB\->\fP\fIstring\fP\&' action as the matches for the argument are +generated by the calling function\&. To get the usual behaviour, +the calling function can add the separator \fIx\fP as a suffix by +passing the options `\fB\-qS\fP \fIx\fP\&' either directly or indirectly to +\fBcompadd\fP\&. +.PP +The option \fB\-C\fP is treated in the same way as it is by \fB_arguments\fP\&. +In that case the parameter \fBcurcontext\fP should be made local instead +of \fBcontext\fP (as described above)\&. +.RE +.TP +\fB_wanted\fP [ \fB\-x\fP ] [ \fB\-C\fP \fIname\fP ] [ \fB\-12VJ\fP ] \fItag\fP \fIname\fP \fIdescr\fP \fIcommand\fP [ \fIarg\fP \&.\&.\&.] +In many contexts, completion can only generate one particular set of +matches, usually corresponding to a single tag\&. However, it is +still necessary to decide whether the user requires matches of this type\&. +This function is useful in such a case\&. +.RS +.PP +The arguments to \fB_wanted\fP are the same as those to \fB_requested\fP, +i\&.e\&. arguments to be passed to \fB_description\fP\&. However, in this case +the \fIcommand\fP is not optional; all the processing of tags, including +the loop over both tags and tag labels and the generation of matches, +is carried out automatically by \fB_wanted\fP\&. +.PP +Hence to offer only one tag and immediately add the corresponding +matches with the given description: +.PP +.RS +.nf +\fBlocal expl +_wanted tag expl \&'description' \e + compadd \-\- \fImatch1\fP \fImatch2\fP\&.\&.\&.\fP +.fi +.RE +.PP +See also the use of \fB_wanted\fP in the example function in +the subsection `Dynamic named directories\&' in \fIzshexpn\fP(1)\&. +.PP +Note that, as for \fB_requested\fP, the \fIcommand\fP must be able to +accept options to be passed down to \fBcompadd\fP\&. +.PP +Like \fB_tags\fP this function supports the \fB\-C\fP option to give a +different name for the argument context field\&. The \fB\-x\fP option has +the same meaning as for \fB_description\fP\&. +.RE +.TP +\fB_widgets\fP [ \fB\-g\fP \fIpattern\fP ] +This function completes names of zle widgets (see +the section `Widgets\&' in \fIzshzle\fP(1))\&. The \fIpattern\fP, if present, is matched against values of the \fB$widgets\fP +special parameter, documented in +the section `The zsh/zleparameter Module\&' in \fIzshmodules\fP(1)\&. +.PP +.SH "COMPLETION SYSTEM VARIABLES" +.PP +There are some standard variables, initialised by the \fB_main_complete\fP +function and then used from other functions\&. +.PP +The standard variables are: +.PP +.PD 0 +.TP +.PD +\fB_comp_caller_options\fP +The completion system uses \fBsetopt\fP to set a number of options\&. This +allows functions to be written without concern for compatibility with +every possible combination of user options\&. However, sometimes completion +needs to know what the user\&'s option preferences are\&. These are saved +in the \fB_comp_caller_options\fP associative array\&. Option names, spelled +in lowercase without underscores, are mapped to one or other of the +strings `\fBon\fP\&' and `\fBoff\fP'\&. +.TP +\fB_comp_priv_prefix\fP +Completion functions such as \fB_sudo\fP can set the \fB_comp_priv_prefix\fP +array to a command prefix that may then be used by \fB_call_program\fP to +match the privileges when calling programs to generate matches\&. +.PP +Two more features are offered by the \fB_main_complete\fP function\&. The +arrays \fBcompprefuncs\fP and \fBcomppostfuncs\fP may contain +names of functions that are to be called immediately before or after +completion has been tried\&. A function will only be called once unless +it explicitly reinserts itself into the array\&. +.PP +.SH "COMPLETION DIRECTORIES" +.PP +In the source distribution, the files are contained in various +subdirectories of the \fBCompletion\fP directory\&. They may have been +installed in the same structure, or into one single function directory\&. +The following is a description of the files found in the original directory +structure\&. If you wish to alter an installed file, you will need to copy +it to some directory which appears earlier in your \fBfpath\fP than the +standard directory where it appears\&. +.PP +.PD 0 +.TP +.PD +\fBBase\fP +The core functions and special completion widgets automatically bound +to keys\&. You will certainly need most of these, though will +probably not need to alter them\&. Many of these are documented above\&. +.TP +\fBZsh\fP +Functions for completing arguments of shell builtin commands and +utility functions for this\&. Some of these are also used by functions from +the \fBUnix\fP directory\&. +.TP +\fBUnix\fP +Functions for completing arguments of external commands and suites of +commands\&. They may need modifying for your system, although in many cases +some attempt is made to decide which version of a command is present\&. For +example, completion for the \fBmount\fP command tries to determine the system +it is running on, while completion for many other utilities try to decide +whether the GNU version of the command is in use, and hence whether the +\fB\-\fP\fB\-help\fP option is supported\&. +.TP +\fBX\fP, \fBAIX\fP, \fBBSD\fP, \&.\&.\&. +Completion and utility function for commands available only on some systems\&. +These are not arranged hierarchically, so, for example, both the +\fBLinux\fP and \fBDebian\fP directories, as well as the \fBX\fP directory, +may be useful on your system\&. |