1ZSHCOMPSYS(1) General Commands Manual ZSHCOMPSYS(1)
2
6 zshcompsys - zsh completion system
7
9 This describes the shell code for the `new' completion system, referred
10 to as compsys. It is written in shell functions based on the features
11 described in zshcompwid(1).
12 The features are contextual, sensitive to the point at which completion
14 is started. Many completions are already provided. For this reason, a
15 user can perform a great many tasks without knowing any details beyond
16 how to initialize the system, which is described below in INITIALIZA‐
17 TION.
18 The context that decides what completion is to be performed may be
20 · an argument or option position: these describe the position on
21 the command line at which completion is requested. For example
22 `first argument to rmdir, the word being completed names a
23 directory';
24 · a special context, denoting an element in the shell's syntax.
27 For example `a word in command position' or `an array sub‐
28 script'.
29 A full context specification contains other elements, as we shall
32 describe.
33 Besides commands names and contexts, the system employs two more con‐
35 cepts, styles and tags. These provide ways for the user to configure
36 the system's behaviour.
37 Tags play a dual role. They serve as a classification system for the
39 matches, typically indicating a class of object that the user may need
40 to distinguish. For example, when completing arguments of the ls com‐
41 mand the user may prefer to try files before directories, so both of
42 these are tags. They also appear as the rightmost element in a context
43 specification.
44 Styles modify various operations of the completion system, such as out‐
46 put formatting, but also what kinds of completers are used (and in what
47 order), or which tags are examined. Styles may accept arguments and
48 are manipulated using the zstyle command described in see zshmod‐
49 ules(1).
50 In summary, tags describe what the completion objects are, and style
52 how they are to be completed. At various points of execution, the com‐
53 pletion system checks what styles and/or tags are defined for the cur‐
54 rent context, and uses that to modify its behavior. The full descrip‐
55 tion of context handling, which determines how tags and other elements
56 of the context influence the behaviour of styles, is described below in
57 COMPLETION SYSTEM CONFIGURATION.
58 When a completion is requested, a dispatcher function is called; see
60 the description of _main_complete in the list of control functions
61 below. This dispatcher decides which function should be called to pro‐
62 duce the completions, and calls it. The result is passed to one or more
63 completers, functions that implement individual completion strategies:
64 simple completion, error correction, completion with error correction,
65 menu selection, etc.
66 More generally, the shell functions contained in the completion system
68 are of two types:
69 · those beginning `comp' are to be called directly; there are only
70 a few of these;
71 · those beginning `_' are called by the completion code. The
74 shell functions of this set, which implement completion behav‐
75 iour and may be bound to keystrokes, are referred to as `wid‐
76 gets'. These proliferate as new completions are required.
77
80 If the system was installed completely, it should be enough to call the
81 shell function compinit from your initialization file; see the next
82 section. However, the function compinstall can be run by a user to
83 configure various aspects of the completion system.
84 Usually, compinstall will insert code into .zshrc, although if that is
86 not writable it will save it in another file and tell you that file's
87 location. Note that it is up to you to make sure that the lines added
88 to .zshrc are actually run; you may, for example, need to move them to
89 an earlier place in the file if .zshrc usually returns early. So long
90 as you keep them all together (including the comment lines at the start
91 and finish), you can rerun compinstall and it will correctly locate and
92 modify these lines. Note, however, that any code you add to this sec‐
93 tion by hand is likely to be lost if you rerun compinstall, although
94 lines using the command `zstyle' should be gracefully handled.
95 The new code will take effect next time you start the shell, or run
97 .zshrc by hand; there is also an option to make them take effect imme‐
98 diately. However, if compinstall has removed definitions, you will
99 need to restart the shell to see the changes.
100 To run compinstall you will need to make sure it is in a directory men‐
102 tioned in your fpath parameter, which should already be the case if zsh
103 was properly configured as long as your startup files do not remove the
104 appropriate directories from fpath. Then it must be autoloaded
105 (`autoload -U compinstall' is recommended). You can abort the instal‐
106 lation any time you are being prompted for information, and your .zshrc
107 will not be altered at all; changes only take place right at the end,
108 where you are specifically asked for confirmation.
109 Use of compinit
111 This section describes the use of compinit to initialize completion for
112 the current session when called directly; if you have run compinstall
113 it will be called automatically from your .zshrc.
114 To initialize the system, the function compinit should be in a direc‐
116 tory mentioned in the fpath parameter, and should be autoloaded
117 (`autoload -U compinit' is recommended), and then run simply as
118 `compinit'. This will define a few utility functions, arrange for all
119 the necessary shell functions to be autoloaded, and will then re-define
120 all widgets that do completion to use the new system. If you use the
121 menu-select widget, which is part of the zsh/complist module, you
122 should make sure that that module is loaded before the call to compinit
123 so that that widget is also re-defined. If completion styles (see
124 below) are set up to perform expansion as well as completion by
125 default, and the TAB key is bound to expand-or-complete, compinit will
126 rebind it to complete-word; this is necessary to use the correct form
127 of expansion.
128 Should you need to use the original completion commands, you can still
130 bind keys to the old widgets by putting a `.' in front of the widget
131 name, e.g. `.expand-or-complete'.
132 To speed up the running of compinit, it can be made to produce a dumped
134 configuration that will be read in on future invocations; this is the
135 default, but can be turned off by calling compinit with the option -D.
136 The dumped file is .zcompdump in the same directory as the startup
137 files (i.e. $ZDOTDIR or $HOME); alternatively, an explicit file name
138 can be given by `compinit -d dumpfile'. The next invocation of
139 compinit will read the dumped file instead of performing a full ini‐
140 tialization.
141 If the number of completion files changes, compinit will recognise this
143 and produce a new dump file. However, if the name of a function or the
144 arguments in the first line of a #compdef function (as described below)
145 change, it is easiest to delete the dump file by hand so that compinit
146 will re-create it the next time it is run. The check performed to see
147 if there are new functions can be omitted by giving the option -C. In
148 this case the dump file will only be created if there isn't one
149 already.
150 The dumping is actually done by another function, compdump, but you
152 will only need to run this yourself if you change the configuration
153 (e.g. using compdef) and then want to dump the new one. The name of
154 the old dumped file will be remembered for this purpose.
155 If the parameter _compdir is set, compinit uses it as a directory where
157 completion functions can be found; this is only necessary if they are
158 not already in the function search path.
159 For security reasons compinit also checks if the completion system
161 would use files not owned by root or by the current user, or files in
162 directories that are world- or group-writable or that are not owned by
163 root or by the current user. If such files or directories are found,
164 compinit will ask if the completion system should really be used. To
165 avoid these tests and make all files found be used without asking, use
166 the option -u, and to make compinit silently ignore all insecure files
167 and directories use the option -i. This security check is skipped
168 entirely when the -C option is given.
169 The security check can be retried at any time by running the function
171 compaudit. This is the same check used by compinit, but when it is
172 executed directly any changes to fpath are made local to the function
173 so they do not persist. The directories to be checked may be passed as
174 arguments; if none are given, compaudit uses fpath and _compdir to find
175 completion system directories, adding missing ones to fpath as neces‐
176 sary. To force a check of exactly the directories currently named in
177 fpath, set _compdir to an empty string before calling compaudit or
178 compinit.
179 The function bashcompinit provides compatibility with bash's program‐
181 mable completion system. When run it will define the functions, comp‐
182 gen and complete which correspond to the bash builtins with the same
183 names. It will then be possible to use completion specifications and
184 functions written for bash.
185 Autoloaded files
187 The convention for autoloaded functions used in completion is that they
188 start with an underscore; as already mentioned, the fpath/FPATH parame‐
189 ter must contain the directory in which they are stored. If zsh was
190 properly installed on your system, then fpath/FPATH automatically con‐
191 tains the required directories for the standard functions.
192 For incomplete installations, if compinit does not find enough files
194 beginning with an underscore (fewer than twenty) in the search path, it
195 will try to find more by adding the directory _compdir to the search
196 path. If that directory has a subdirectory named Base, all subdirecto‐
197 ries will be added to the path. Furthermore, if the subdirectory Base
198 has a subdirectory named Core, compinit will add all subdirectories of
199 the subdirectories is to the path: this allows the functions to be in
200 the same format as in the zsh source distribution.
201 When compinit is run, it searches all such files accessible via
203 fpath/FPATH and reads the first line of each of them. This line should
204 contain one of the tags described below. Files whose first line does
205 not start with one of these tags are not considered to be part of the
206 completion system and will not be treated specially.
207 The tags are:
209 #compdef names... [ -[pP] patterns... [ -N names... ] ]
211 The file will be made autoloadable and the function defined in
212 it will be called when completing names, each of which is either
213 the name of a command whose arguments are to be completed or one
214 of a number of special contexts in the form -context- described
215 below.
216 Each name may also be of the form `cmd=service'. When complet‐
218 ing the command cmd, the function typically behaves as if the
219 command (or special context) service was being completed
220 instead. This provides a way of altering the behaviour of func‐
221 tions that can perform many different completions. It is imple‐
222 mented by setting the parameter $service when calling the func‐
223 tion; the function may choose to interpret this how it wishes,
224 and simpler functions will probably ignore it.
225 If the #compdef line contains one of the options -p or -P, the
227 words following are taken to be patterns. The function will be
228 called when completion is attempted for a command or context
229 that matches one of the patterns. The options -p and -P are
230 used to specify patterns to be tried before or after other com‐
231 pletions respectively. Hence -P may be used to specify default
232 actions.
233 The option -N is used after a list following -p or -P; it speci‐
235 fies that remaining words no longer define patterns. It is pos‐
236 sible to toggle between the three options as many times as nec‐
237 essary.
238 #compdef -k style key-sequences...
240 This option creates a widget behaving like the builtin widget
241 style and binds it to the given key-sequences, if any. The
242 style must be one of the builtin widgets that perform comple‐
243 tion, namely complete-word, delete-char-or-list, expand-or-com‐
244 plete, expand-or-complete-prefix, list-choices, menu-complete,
245 menu-expand-or-complete, or reverse-menu-complete. If the
246 zsh/complist module is loaded (see zshmodules(1)) the widget
247 menu-select is also available.
248 When one of the key-sequences is typed, the function in the file
250 will be invoked to generate the matches. Note that a key will
251 not be re-bound if it already was (that is, was bound to some‐
252 thing other than undefined-key). The widget created has the
253 same name as the file and can be bound to any other keys using
254 bindkey as usual.
255 #compdef -K widget-name style key-sequences ...
257 This is similar to -k except that only one key-sequences argu‐
258 ment may be given for each widget-name style pair. However, the
259 entire set of three arguments may be repeated with a different
260 set of arguments. Note in particular that the widget-name must
261 be distinct in each set. If it does not begin with `_' this
262 will be added. The widget-name should not clash with the name
263 of any existing widget: names based on the name of the function
264 are most useful. For example,
265 #compdef -K _foo_complete complete-word "^X^C" \
267 _foo_list list-choices "^X^D"
268 (all on one line) defines a widget _foo_complete for completion,
270 bound to `^X^C', and a widget _foo_list for listing, bound to
271 `^X^D'.
272 #autoload [ options ]
274 Functions with the #autoload tag are marked for autoloading but
275 are not otherwise treated specially. Typically they are to be
276 called from within one of the completion functions. Any options
277 supplied will be passed to the autoload builtin; a typical use
278 is +X to force the function to be loaded immediately. Note that
279 the -U and -z flags are always added implicitly.
280 The # is part of the tag name and no white space is allowed after it.
282 The #compdef tags use the compdef function described below; the main
283 difference is that the name of the function is supplied implicitly.
284 The special contexts for which completion functions can be defined are:
286 -array-value-
288 The right hand side of an array-assignment (`foo=(...)')
289 -brace-parameter-
291 The name of a parameter expansion within braces (`${...}')
292 -assign-parameter-
294 The name of a parameter in an assignment, i.e. on the left hand
295 side of an `='
296 -command-
298 A word in command position
299 -condition-
301 A word inside a condition (`[[...]]')
302 -default-
304 Any word for which no other completion is defined
305 -equal-
307 A word beginning with an equals sign
308 -first-
310 This is tried before any other completion function. The func‐
311 tion called may set the _compskip parameter to one of various
312 values: all: no further completion is attempted; a string con‐
313 taining the substring patterns: no pattern completion functions
314 will be called; a string containing default: the function for
315 the `-default-' context will not be called, but functions
316 defined for commands will
317 -math- Inside mathematical contexts, such as `((...))'
319 -parameter-
321 The name of a parameter expansion (`$...')
322 -redirect-
324 The word after a redirection operator.
325 -subscript-
327 The contents of a parameter subscript.
328 -tilde-
330 After an initial tilde (`~'), but before the first slash in the
331 word.
332 -value-
334 On the right hand side of an assignment.
335 Default implementations are supplied for each of these contexts. In
337 most cases the context -context- is implemented by a corresponding
338 function _context, for example the context `-tilde-' and the function
339 `_tilde').
340 The contexts -redirect- and -value- allow extra context-specific infor‐
342 mation. (Internally, this is handled by the functions for each context
343 calling the function _dispatch.) The extra information is added sepa‐
344 rated by commas.
345 For the -redirect- context, the extra information is in the form `-re‐
347 direct-,op,command', where op is the redirection operator and command
348 is the name of the command on the line. If there is no command on the
349 line yet, the command field will be empty.
350 For the -value- context, the form is `-value-,name,command', where name
352 is the name of the parameter. In the case of elements of an associa‐
353 tive array, for example `assoc=(key <TAB>', name is expanded to
354 `name-key'. In certain special contexts, such as completing after
355 `make CFLAGS=', the command part gives the name of the command, here
356 make; otherwise it is empty.
357 It is not necessary to define fully specific completions as the func‐
359 tions provided will try to generate completions by progressively
360 replacing the elements with `-default-'. For example, when completing
361 after `foo=<TAB>', _value will try the names `-value-,foo,' (note the
362 empty command part), `-value-,foo,-default-'
363 and`-value-,-default-,-default-', in that order, until it finds a func‐
364 tion to handle the context.
365 As an example:
367 compdef '_files -g "*.log"' '-redirect-,2>,-default-'
369 completes files matching `*.log' after `2> <TAB>' for any command with
371 no more specific handler defined.
372 Also:
374 compdef _foo -value-,-default-,-default-
376 specifies that _foo provides completions for the values of parameters
378 for which no special function has been defined. This is usually han‐
379 dled by the function _value itself.
380 The same lookup rules are used when looking up styles (as described
382 below); for example
383 zstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log'
385 is another way to make completion after `2> <TAB>' complete files
387 matching `*.log'.
388 Functions
390 The following function is defined by compinit and may be called
391 directly.
392 compdef [ -an ] function names... [ -[pP] patterns... [ -N names... ] ]
394 compdef -d names...
395 compdef -k [ -an ] function style key-sequences...
396 compdef -K [ -an ] function name style key-sequences ...
397 The first form defines the function to call for completion in
398 the given contexts as described for the #compdef tag above.
399 Alternatively, all the arguments may have the form `cmd=ser‐
401 vice'. Here service should already have been defined by
402 `cmd1=service' lines in #compdef files, as described above. The
403 argument for cmd will be completed in the same way as service.
404 The function argument may alternatively be a string containing
406 any shell code. The string will be executed using the eval
407 builtin command to generate completions. This provides a way of
408 avoiding having to define a new completion function. For exam‐
409 ple, to complete files ending in `.h' as arguments to the com‐
410 mand foo:
411 compdef '_files -g "*.h"' foo
413 The option -n prevents any completions already defined for the
415 command or context from being overwritten.
416 The option -d deletes any completion defined for the command or
418 contexts listed.
419 The names may also contain -p, -P and -N options as described
421 for the #compdef tag. The effect on the argument list is iden‐
422 tical, switching between definitions of patterns tried ini‐
423 tially, patterns tried finally, and normal commands and con‐
424 texts.
425 The parameter $_compskip may be set by any function defined for
427 a pattern context. If it is set to a value containing the sub‐
428 string `patterns' none of the pattern-functions will be called;
429 if it is set to a value containing the substring `all', no other
430 function will be called.
431 The form with -k defines a widget with the same name as the
433 function that will be called for each of the key-sequences; this
434 is like the #compdef -k tag. The function should generate the
435 completions needed and will otherwise behave like the builtin
436 widget whose name is given as the style argument. The widgets
437 usable for this are: complete-word, delete-char-or-list,
438 expand-or-complete, expand-or-complete-prefix, list-choices,
439 menu-complete, menu-expand-or-complete, and reverse-menu-com‐
440 plete, as well as menu-select if the zsh/complist module is
441 loaded. The option -n prevents the key being bound if it is
442 already to bound to something other than undefined-key.
443 The form with -K is similar and defines multiple widgets based
445 on the same function, each of which requires the set of three
446 arguments name, style and key-sequences, where the latter two
447 are as for -k and the first must be a unique widget name begin‐
448 ning with an underscore.
449 Wherever applicable, the -a option makes the function autoload‐
451 able, equivalent to autoload -U function.
452 The function compdef can be used to associate existing completion func‐
454 tions with new commands. For example,
455 compdef _pids foo
457 uses the function _pids to complete process IDs for the command foo.
459 Note also the _gnu_generic function described below, which can be used
461 to complete options for commands that understand the `--help' option.
462
464 This section gives a short overview of how the completion system works,
465 and then more detail on how users can configure how and when matches
466 are generated.
467 Overview
469 When completion is attempted somewhere on the command line the comple‐
470 tion system first works out the context. This takes account of a num‐
471 ber of things including the command word (such as `grep' or `zsh') and
472 options to which the current word may be an argument (such as the `-o'
473 option to zsh which takes a shell option as an argument).
474 This context information is condensed into a string consisting of mul‐
476 tiple fields separated by colons, referred to simply as `the context'
477 in the remainder of the documentation. This is used to look up styles,
478 context-sensitive options that can be used to configure the completion
479 system. The context used for lookup may vary during the same call to
480 the completion system.
481 The context string always consists of a fixed set of fields, separated
483 by colons and with a leading colon before the first, in the form :com‐
484 pletion:function:completer:command:argument:tag. These have the fol‐
485 lowing meaning:
486 · The literal string completion, saying that this style is used by
488 the completion system. This distinguishes the context from
489 those used by, for example, zle widgets and ZFTP functions.
490 · The function, if completion is called from a named widget rather
493 than through the normal completion system. Typically this is
494 blank, but it is set by special widgets such as predict-on and
495 the various functions in the Widget directory of the distribu‐
496 tion to the name of that function, often in an abbreviated form.
497 · The completer currently active, the name of the function without
500 the leading underscore and with other underscores converted to
501 hyphens. A `completer' is in overall control of how completion
502 is to be performed; `complete' is the simplest, but other com‐
503 pleters exist to perform related tasks such as correction, or to
504 modify the behaviour of a later completer. See the section
505 `Control Functions' below for more information.
506 · The command or a special -context-, just at it appears following
509 the #compdef tag or the compdef function. Completion functions
510 for commands that have sub-commands usually modify this field to
511 contain the name of the command followed by a minus sign and the
512 sub-command. For example, the completion function for the cvs
513 command sets this field to cvs-add when completing arguments to
514 the add subcommand.
515 · The argument; this indicates which command line or option argu‐
518 ment we are completing. For command arguments this generally
519 takes the form argument-n, where n is the number of the argu‐
520 ment, and for arguments to options the form option-opt-n where n
521 is the number of the argument to option opt. However, this is
522 only the case if the command line is parsed with standard
523 UNIX-style options and arguments, so many completions do not set
524 this.
525 · The tag. As described previously, tags are used to discriminate
528 between the types of matches a completion function can generate
529 in a certain context. Any completion function may use any tag
530 name it likes, but a list of the more common ones is given
531 below.
532 The context is gradually put together as the functions are executed,
535 starting with the main entry point, which adds :completion: and the
536 function element if necessary. The completer then adds the completer
537 element. The contextual completion adds the command and argument
538 options. Finally, the tag is added when the types of completion are
539 known. For example, the context name
540 :completion::complete:dvips:option-o-1:files
542 says that normal completion was attempted as the first argument to the
544 option -o of the command dvips:
545 dvips -o ...
547 and the completion function will generate filenames.
549 Usually completion will be tried for all possible tags in an order
551 given by the completion function. However, this can be altered by
552 using the tag-order style. Completion is then restricted to the list
553 of given tags in the given order.
554 The _complete_help bindable command shows all the contexts and tags
556 available for completion at a particular point. This provides an easy
557 way of finding information for tag-order and other styles. It is
558 described in the section `Bindable Commands' below.
559 Styles determine such things as how the matches are generated, simi‐
561 larly to shell options but with much more control. They can have any
562 number of strings as their value. They are defined with the zstyle
563 builtin command (see zshmodules(1)).
564 When looking up styles the completion system uses full context names,
566 including the tag. Looking up the value of a style therefore consists
567 of two things: the context, which may be matched as a pattern, and the
568 name of the style itself, which must be given exactly.
569 For example, many completion functions can generate matches in a simple
571 and a verbose form and use the verbose style to decide which form
572 should be used. To make all such functions use the verbose form, put
573 zstyle ':completion:*' verbose yes
575 in a startup file (probably .zshrc). This gives the verbose style the
577 value yes in every context inside the completion system, unless that
578 context has a more specific definition. It is best to avoid giving the
579 context as `*' in case the style has some meaning outside the comple‐
580 tion system.
581 Many such general purpose styles can be configured simply by using the
583 compinstall function.
584 A more specific example of the use of the verbose style is by the com‐
586 pletion for the kill builtin. If the style is set, the builtin lists
587 full job texts and process command lines; otherwise it shows the bare
588 job numbers and PIDs. To turn the style off for this use only:
589 zstyle ':completion:*:*:kill:*' verbose no
591 For even more control, the style can use one of the tags `jobs' or
593 `processes'. To turn off verbose display only for jobs:
594 zstyle ':completion:*:*:kill:*:jobs' verbose no
596 The -e option to zstyle even allows completion function code to appear
598 as the argument to a style; this requires some understanding of the
599 internals of completion functions (see see zshcompwid(1))). For exam‐
600 ple,
601 zstyle -e ':completion:*' hosts 'reply=($myhosts)'
603 This forces the value of the hosts style to be read from the variable
605 myhosts each time a host name is needed; this is useful if the value of
606 myhosts can change dynamically. For another useful example, see the
607 example in the description of the file-list style below. This form can
608 be slow and should be avoided for commonly examined styles such as menu
609 and list-rows-first.
610 Note that the order in which styles are defined does not matter; the
612 style mechanism uses the most specific possible match for a particular
613 style to determine the set of values. More precisely, strings are pre‐
614 ferred over patterns (for example, `:completion::complete:foo' is more
615 specific than `:completion::complete:*'), and longer patterns are pre‐
616 ferred over shorter patterns.
617 Style names like those of tags are arbitrary and depend on the comple‐
619 tion function. However, the following two sections list some of the
620 most common tags and styles.
621 Standard Tags
623 Some of the following are only used when looking up particular styles
624 and do not refer to a type of match.
625 accounts
627 used to look up the users-hosts style
628 all-expansions
630 used by the _expand completer when adding the single string con‐
631 taining all possible expansions
632 all-files
634 for the names of all files (as distinct from a particular sub‐
635 set, see the globbed-files tag).
636 arguments
638 for arguments to a command
639 arrays for names of array parameters
641 association-keys
643 for keys of associative arrays; used when completing inside a
644 subscript to a parameter of this type
645 bookmarks
647 when completing bookmarks (e.g. for URLs and the zftp function
648 suite)
649 builtins
651 for names of builtin commands
652 characters
654 for single characters in arguments of commands such as stty.
655 Also used when completing character classes after an opening
656 bracket
657 colormapids
659 for X colormap ids
660 colors for color names
662 commands
664 for names of external commands. Also used by complex commands
665 such as cvs when completing names subcommands.
666 contexts
668 for contexts in arguments to the zstyle builtin command
669 corrections
671 used by the _approximate and _correct completers for possible
672 corrections
673 cursors
675 for cursor names used by X programs
676 default
678 used in some contexts to provide a way of supplying a default
679 when more specific tags are also valid. Note that this tag is
680 used when only the function field of the context name is set
681 descriptions
683 used when looking up the value of the format style to generate
684 descriptions for types of matches
685 devices
687 for names of device special files
688 directories
690 for names of directories
691 directory-stack
693 for entries in the directory stack
694 displays
696 for X display names
697 domains
699 for network domains
700 expansions
702 used by the _expand completer for individual words (as opposed
703 to the complete set of expansions) resulting from the expansion
704 of a word on the command line
705 extensions
707 for X server extensions
708 file-descriptors
710 for numbers of open file descriptors
711 files the generic file-matching tag used by functions completing file‐
713 names
714 fonts for X font names
716 fstypes
718 for file system types (e.g. for the mount command)
719 functions
721 names of functions -- normally shell functions, although certain
722 commands may understand other kinds of function
723 globbed-files
725 for filenames when the name has been generated by pattern match‐
726 ing
727 groups for names of user groups
729 history-words
731 for words from the history
732 hosts for hostnames
734 indexes
736 for array indexes
737 jobs for jobs (as listed by the `jobs' builtin)
739 interfaces
741 for network interfaces
742 keymaps
744 for names of zsh keymaps
745 keysyms
747 for names of X keysyms
748 libraries
750 for names of system libraries
751 limits for system limits
753 local-directories
755 for names of directories that are subdirectories of the current
756 working directory when completing arguments of cd and related
757 builtin commands (compare path-directories)
758 manuals
760 for names of manual pages
761 mailboxes
763 for e-mail folders
764 maps for map names (e.g. NIS maps)
766 messages
768 used to look up the format style for messages
769 modifiers
771 for names of X modifiers
772 modules
774 for modules (e.g. zsh modules)
775 my-accounts
777 used to look up the users-hosts style
778 named-directories
780 for named directories (you wouldn't have guessed that, would
781 you?)
782 names for all kinds of names
784 newsgroups
786 for USENET groups
787 nicknames
789 for nicknames of NIS maps
790 options
792 for command options
793 original
795 used by the _approximate, _correct and _expand completers when
796 offering the original string as a match
797 other-accounts
799 used to look up the users-hosts style
800 other-files
802 for the names of any non-directory files. This is used instead
803 of all-files when the list-dirs-first style is in effect.
804 packages
806 for packages (e.g. rpm or installed Debian packages)
807 parameters
809 for names of parameters
810 path-directories
812 for names of directories found by searching the cdpath array
813 when completing arguments of cd and related builtin commands
814 (compare local-directories)
815 paths used to look up the values of the expand, ambiguous and spe‐
817 cial-dirs styles
818 pods for perl pods (documentation files)
820 ports for communication ports
822 prefixes
824 for prefixes (like those of a URL)
825 printers
827 for print queue names
828 processes
830 for process identifiers
831 processes-names
833 used to look up the command style when generating the names of
834 processes for killall
835 sequences
837 for sequences (e.g. mh sequences)
838 sessions
840 for sessions in the zftp function suite
841 signals
843 for signal names
844 strings
846 for strings (e.g. the replacement strings for the cd builtin
847 command)
848 styles for styles used by the zstyle builtin command
850 suffixes
852 for filename extensions
853 tags for tags (e.g. rpm tags)
855 targets
857 for makefile targets
858 time-zones
860 for time zones (e.g. when setting the TZ parameter)
861 types for types of whatever (e.g. address types for the xhost command)
863 urls used to look up the urls and local styles when completing URLs
865 users for usernames
867 values for one of a set of values in certain lists
869 variant
871 used by _pick_variant to look up the command to run when deter‐
872 mining what program is installed for a particular command name.
873 visuals
875 for X visuals
876 warnings
878 used to look up the format style for warnings
879 widgets
881 for zsh widget names
882 windows
884 for IDs of X windows
885 zsh-options
887 for shell options
888 Standard Styles
890 Note that the values of several of these styles represent boolean val‐
891 ues. Any of the strings `true', `on', `yes', and `1' can be used for
892 the value `true' and any of the strings `false', `off', `no', and `0'
893 for the value `false'. The behavior for any other value is undefined
894 except where explicitly mentioned. The default value may be either
895 true or false if the style is not set.
896 Some of these styles are tested first for every possible tag corre‐
898 sponding to a type of match, and if no style was found, for the default
899 tag. The most notable styles of this type are menu, list-colors and
900 styles controlling completion listing such as list-packed and
901 last-prompt). When tested for the default tag, only the function field
902 of the context will be set so that a style using the default tag will
903 normally be defined along the lines of:
904 zstyle ':completion:*:default' menu ...
906 accept-exact
908 This is tested for the default tag in addition to the tags valid
909 for the current context. If it is set to `true' and any of the
910 trial matches is the same as the string on the command line,
911 this match will immediately be accepted (even if it would other‐
912 wise be considered ambiguous).
913 When completing pathnames (where the tag used is `paths') this
915 style accepts any number of patterns as the value in addition to
916 the boolean values. Pathnames matching one of these patterns
917 will be accepted immediately even if the command line contains
918 some more partially typed pathname components and these match no
919 file under the directory accepted.
920 This style is also used by the _expand completer to decide if
922 words beginning with a tilde or parameter expansion should be
923 expanded. For example, if there are parameters foo and foobar,
924 the string `$foo' will only be expanded if accept-exact is set
925 to `true'; otherwise the completion system will be allowed to
926 complete $foo to $foobar. If the style is set to `continue',
927 _expand will add the expansion as a match and the completion
928 system will also be allowed to continue.
929 accept-exact-dirs
931 This is used by filename completion. Unlike accept-exact it is
932 a boolean. By default, filename completion examines all compo‐
933 nents of a path to see if there are completions of that compo‐
934 nent, even if the component matches an existing directory. For
935 example, when completion after /usr/bin/, the function examines
936 possible completions to /usr.
937 When this style is true, any prefix of a path that matches an
939 existing directory is accepted without any attempt to complete
940 it further. Hence, in the given example, the path /usr/bin/ is
941 accepted immediately and completion tried in that directory.
942 If you wish to inhibit this behaviour entirely, set the
944 path-completion style (see below) to false.
945 add-space
947 This style is used by the _expand completer. If it is true (the
948 default), a space will be inserted after all words resulting
949 from the expansion, or a slash in the case of directory names.
950 If the value is `file', the completer will only add a space to
951 names of existing files. Either a boolean true or the value
952 `file' may be combined with `subst', in which case the completer
953 will not add a space to words generated from the expansion of a
954 substitution of the form `$(...)' or `${...}'.
955 The _prefix completer uses this style as a simple boolean value
957 to decide if a space should be inserted before the suffix.
958 ambiguous
960 This applies when completing non-final components of filename
961 paths, in other words those with a trailing slash. If it is
962 set, the cursor is left after the first ambiguous component,
963 even if menu completion is in use. The style is always tested
964 with the paths tag.
965 assign-list
967 When completing after an equals sign that is being treated as an
968 assignment, the completion system normally completes only one
969 filename. In some cases the value may be a list of filenames
970 separated by colons, as with PATH and similar parameters. This
971 style can be set to a list of patterns matching the names of
972 such parameters.
973 The default is to complete lists when the word on the line
975 already contains a colon.
976 auto-description
978 If set, this style's value will be used as the description for
979 options that are not described by the completion functions, but
980 that have exactly one argument. The sequence `%d' in the value
981 will be replaced by the description for this argument. Depend‐
982 ing on personal preferences, it may be useful to set this style
983 to something like `specify: %d'. Note that this may not work
984 for some commands.
985 avoid-completer
987 This is used by the _all_matches completer to decide if the
988 string consisting of all matches should be added to the list
989 currently being generated. Its value is a list of names of com‐
990 pleters. If any of these is the name of the completer that gen‐
991 erated the matches in this completion, the string will not be
992 added.
993 The default value for this style is `_expand _old_list _correct
995 _approximate', i.e. it contains the completers for which a
996 string with all matches will almost never be wanted.
997 cache-path
999 This style defines the path where any cache files containing
1000 dumped completion data are stored. It defaults to `$ZDOT‐
1001 DIR/.zcompcache', or `$HOME/.zcompcache' if $ZDOTDIR is not
1002 defined. The completion cache will not be used unless the
1003 use-cache style is set.
1004 cache-policy
1006 This style defines the function that will be used to determine
1007 whether a cache needs rebuilding. See the section on the
1008 _cache_invalid function below.
1009 call-command
1011 This style is used in the function for commands such as make and
1012 ant where calling the command directly to generate matches suf‐
1013 fers problems such as being slow or, as in the case of make can
1014 potentially cause actions in the makefile to be executed. If it
1015 is set to `true' the command is called to generate matches. The
1016 default value of this style is `false'.
1017 command
1019 In many places, completion functions need to call external com‐
1020 mands to generate the list of completions. This style can be
1021 used to override the command that is called in some such cases.
1022 The elements of the value are joined with spaces to form a com‐
1023 mand line to execute. The value can also start with a hyphen,
1024 in which case the usual command will be added to the end; this
1025 is most useful for putting `builtin' or `command' in front to
1026 make sure the appropriate version of a command is called, for
1027 example to avoid calling a shell function with the same name as
1028 an external command.
1029 As an example, the completion function for process IDs uses this
1031 style with the processes tag to generate the IDs to complete and
1032 the list of processes to display (if the verbose style is
1033 `true'). The list produced by the command should look like the
1034 output of the ps command. The first line is not displayed, but
1035 is searched for the string `PID' (or `pid') to find the position
1036 of the process IDs in the following lines. If the line does not
1037 contain `PID', the first numbers in each of the other lines are
1038 taken as the process IDs to complete.
1039 Note that the completion function generally has to call the
1041 specified command for each attempt to generate the completion
1042 list. Hence care should be taken to specify only commands that
1043 take a short time to run, and in particular to avoid any that
1044 may never terminate.
1045 command-path
1047 This is a list of directories to search for commands to com‐
1048 plete. The default for this style is the value of the special
1049 parameter path.
1050 commands
1052 This is used by the function completing sub-commands for the
1053 system initialisation scripts (residing in /etc/init.d or some‐
1054 where not too far away from that). Its values give the default
1055 commands to complete for those commands for which the completion
1056 function isn't able to find them out automatically. The default
1057 for this style are the two strings `start' and `stop'.
1058 complete
1060 This is used by the _expand_alias function when invoked as a
1061 bindable command. If set to `true' and the word on the command
1062 line is not the name of an alias, matching alias names will be
1063 completed.
1064 complete-options
1066 This is used by the completer for cd, chdir and pushd. For
1067 these commands a - is used to introduce a directory stack entry
1068 and completion of these is far more common than completing
1069 options. Hence unless the value of this style is true options
1070 will not be completed, even after an initial -. If it is true,
1071 options will be completed after an initial - unless there is a
1072 preceding -- on the command line.
1073 completer
1075 The strings given as the value of this style provide the names
1076 of the completer functions to use. The available completer func‐
1077 tions are described in the section `Control Functions' below.
1078 Each string may be either the name of a completer function or a
1080 string of the form `function:name'. In the first case the com‐
1081 pleter field of the context will contain the name of the com‐
1082 pleter without the leading underscore and with all other under‐
1083 scores replaced by hyphens. In the second case the function is
1084 the name of the completer to call, but the context will contain
1085 the user-defined name in the completer field of the context. If
1086 the name starts with a hyphen, the string for the context will
1087 be build from the name of the completer function as in the first
1088 case with the name appended to it. For example:
1089 zstyle ':completion:*' completer _complete _complete:-foo
1091 Here, completion will call the _complete completer twice, once
1093 using `complete' and once using `complete-foo' in the completer
1094 field of the context. Normally, using the same completer more
1095 than once only makes sense when used with the `functions:name'
1096 form, because otherwise the context name will be the same in all
1097 calls to the completer; possible exceptions to this rule are the
1098 _ignored and _prefix completers.
1099 The default value for this style is `_complete _ignored': only
1101 completion will be done, first using the ignored-patterns style
1102 and the $fignore array and then without ignoring matches.
1103 condition
1105 This style is used by the _list completer function to decide if
1106 insertion of matches should be delayed unconditionally. The
1107 default is `true'.
1108 delimiters
1110 This style is used when adding a delimiter for use with history
1111 modifiers or glob qualifiers that have delimited arguments. It
1112 is an array of preferred delimiters to add. Non-special charac‐
1113 ters are preferred as the completion system may otherwise become
1114 confused. The default list is :, +, /, -, %. The list may be
1115 empty to force a delimiter to be typed.
1116 disabled
1118 If this is set to `true', the _expand_alias completer and bind‐
1119 able command will try to expand disabled aliases, too. The
1120 default is `false'.
1121 domains
1123 A list of names of network domains for completion. If this is
1124 not set, domain names will be taken from the file
1125 /etc/resolv.conf.
1126 environ
1128 The environ style is used when completing for `sudo'. It is set
1129 to an array of `VAR=value' assignments to be exported into the
1130 local environment before the completion for the target command
1131 is invoked.
1132 zstyle :complete:sudo: environ \
1133 PATH="/sbin:/usr/sbin:$PATH" HOME="/root"
1134 expand This style is used when completing strings consisting of multi‐
1136 ple parts, such as path names.
1137 If one of its values is the string `prefix', the partially typed
1139 word from the line will be expanded as far as possible even if
1140 trailing parts cannot be completed.
1141 If one of its values is the string `suffix', matching names for
1143 components after the first ambiguous one will also be added.
1144 This means that the resulting string is the longest unambiguous
1145 string possible. However, menu completion can be used to cycle
1146 through all matches.
1147 fake This style may be set for any completion context. It specifies
1149 additional strings that will always be completed in that con‐
1150 text. The form of each string is `value:description'; the colon
1151 and description may be omitted, but any literal colons in value
1152 must be quoted with a backslash. Any description provided is
1153 shown alongside the value in completion listings.
1154 It is important to use a sufficiently restrictive context when
1156 specifying fake strings. Note that the styles fake-files and
1157 fake-parameters provide additional features when completing
1158 files or parameters.
1159 fake-always
1161 This works identically to the fake style except that the
1162 ignored-patterns style is not applied to it. This makes it pos‐
1163 sible to override a set of matches completely by setting the
1164 ignored patterns to `*'.
1165 The following shows a way of supplementing any tag with arbi‐
1167 trary data, but having it behave for display purposes like a
1168 separate tag. In this example we use the features of the
1169 tag-order style to divide the named-directories tag into two
1170 when performing completion with the standard completer complete
1171 for arguments of cd. The tag named-directories-normal behaves
1172 as normal, but the tag named-directories-mine contains a fixed
1173 set of directories. This has the effect of adding the match
1174 group `extra directories' with the given completions.
1175 zstyle ':completion::complete:cd:*' tag-order \
1177 'named-directories:-mine:extra\ directories
1178 named-directories:-normal:named\ directories *'
1179 zstyle ':completion::complete:cd:*:named-directories-mine' \
1180 fake-always mydir1 mydir2
1181 zstyle ':completion::complete:cd:*:named-directories-mine' \
1182 ignored-patterns '*'
1183 fake-files
1185 This style is used when completing files and looked up without a
1186 tag. Its values are of the form `dir:names...'. This will add
1187 the names (strings separated by spaces) as possible matches when
1188 completing in the directory dir, even if no such files really
1189 exist. The dir may be a pattern; pattern characters or colons
1190 in dir should be quoted with a backslash to be treated liter‐
1191 ally.
1192 This can be useful on systems that support special file systems
1194 whose top-level pathnames can not be listed or generated with
1195 glob patterns. It can also be used for directories for which
1196 one does not have read permission.
1197 The pattern form can be used to add a certain `magic' entry to
1199 all directories on a particular file system.
1200 fake-parameters
1202 This is used by the completion function for parameter names.
1203 Its values are names of parameters that might not yet be set but
1204 should be completed nonetheless. Each name may also be followed
1205 by a colon and a string specifying the type of the parameter
1206 (like `scalar', `array' or `integer'). If the type is given,
1207 the name will only be completed if parameters of that type are
1208 required in the particular context. Names for which no type is
1209 specified will always be completed.
1210 file-list
1212 This style controls whether files completed using the standard
1213 builtin mechanism are to be listed with a long list similar to
1214 ls -l. Note that this feature uses the shell module zsh/stat
1215 for file information; this loads the builtin stat which will
1216 replace any external stat executable. To avoid this the follow‐
1217 ing code can be included in an initialization file:
1218 zmodload -i zsh/stat
1220 disable stat
1221 The style may either be set to a true value (or `all'), or one
1223 of the values `insert' or `list', indicating that files are to
1224 be listed in long format in all circumstances, or when attempt‐
1225 ing to insert a file name, or when listing file names without
1226 attempting to insert one.
1227 More generally, the value may be an array of any of the above
1229 values, optionally followed by =num. If num is present it gives
1230 the maximum number of matches for which long listing style will
1231 be used. For example,
1232 zstyle ':completion:*' file-list list=20 insert=10
1234 specifies that long format will be used when listing up to 20
1236 files or inserting a file with up to 10 matches (assuming a
1237 listing is to be shown at all, for example on an ambiguous com‐
1238 pletion), else short format will be used.
1239 zstyle -e ':completion:*' file-list '(( ${+NUMERIC} )) && reply=(true)'
1241 specifies that long format will be used any time a numeric argu‐
1243 ment is supplied, else short format.
1244 file-patterns
1246 This is used by the standard function for completing filenames,
1247 _files. If the style is unset up to three tags are offered,
1248 `globbed-files',`directories' and `all-files', depending on the
1249 types of files expected by the caller of _files. The first two
1250 (`globbed-files' and `directories') are normally offered
1251 together to make it easier to complete files in sub-directories.
1252 The file-patterns style provides alternatives to the default
1254 tags, which are not used. Its value consists of elements of the
1255 form `pattern:tag'; each string may contain any number of such
1256 specifications separated by spaces.
1257 The pattern is a pattern that is to be used to generate file‐
1259 names. Any occurrence of the sequence `%p' is replaced by any
1260 pattern(s) passed by the function calling _files. Colons in the
1261 pattern must be preceded by a backslash to make them distin‐
1262 guishable from the colon before the tag. If more than one pat‐
1263 tern is needed, the patterns can be given inside braces, sepa‐
1264 rated by commas.
1265 The tags of all strings in the value will be offered by _files
1267 and used when looking up other styles. Any tags in the same
1268 word will be offered at the same time and before later words.
1269 If no `:tag' is given the `files' tag will be used.
1270 The tag may also be followed by an optional second colon and a
1272 description, which will be used for the `%d' in the value of the
1273 format style (if that is set) instead of the default description
1274 supplied by the completion function. If the description given
1275 here contains itself a `%d', that is replaced with the descrip‐
1276 tion supplied by the completion function.
1277 For example, to make the rm command first complete only names of
1279 object files and then the names of all files if there is no
1280 matching object file:
1281 zstyle ':completion:*:*:rm:*' file-patterns \
1283 '*.o:object-files' '%p:all-files'
1284 To alter the default behaviour of file completion -- offer files
1286 matching a pattern and directories on the first attempt, then
1287 all files -- to offer only matching files on the first attempt,
1288 then directories, and finally all files:
1289 zstyle ':completion:*' file-patterns \
1291 '%p:globbed-files' '*(-/):directories' '*:all-files'
1292 This works even where there is no special pattern: _files
1294 matches all files using the pattern `*' at the first step and
1295 stops when it sees this pattern. Note also it will never try a
1296 pattern more than once for a single completion attempt.
1297 During the execution of completion functions, the EXTENDED_GLOB
1299 option is in effect, so the characters `#', `~' and `^' have
1300 special meanings in the patterns.
1301 file-sort
1303 The standard filename completion function uses this style with‐
1304 out a tag to determine in which order the names should be
1305 listed; menu completion will cycle through them in the same
1306 order. The possible values are: `size' to sort by the size of
1307 the file; `links' to sort by the number of links to the file;
1308 `modification' (or `time' or `date') to sort by the last modifi‐
1309 cation time; `access' to sort by the last access time; and
1310 `inode' (or `change') to sort by the last inode change time. If
1311 the style is set to any other value, or is unset, files will be
1312 sorted alphabetically by name. If the value contains the string
1313 `reverse', sorting is done in the opposite order. If the value
1314 contains the string `follow', timestamps are associated with the
1315 targets of symbolic links; the default is to use the timestamps
1316 of the links themselves.
1317 filter This is used by the LDAP plugin for e-mail address completion to
1319 specify the attributes to match against when filtering entries.
1320 So for example, if the style is set to `sn', matching is done
1321 against surnames. Standard LDAP filtering is used so normal
1322 completion matching is bypassed. If this style is not set, the
1323 LDAP plugin is skipped. You may also need to set the command
1324 style to specify how to connect to your LDAP server.
1325 force-list
1327 This forces a list of completions to be shown at any point where
1328 listing is done, even in cases where the list would usually be
1329 suppressed. For example, normally the list is only shown if
1330 there are at least two different matches. By setting this style
1331 to `always', the list will always be shown, even if there is
1332 only a single match that will immediately be accepted. The
1333 style may also be set to a number. In this case the list will
1334 be shown if there are at least that many matches, even if they
1335 would all insert the same string.
1336 This style is tested for the default tag as well as for each tag
1338 valid for the current completion. Hence the listing can be
1339 forced only for certain types of match.
1340 format If this is set for the descriptions tag, its value is used as a
1342 string to display above matches in completion lists. The
1343 sequence `%d' in this string will be replaced with a short
1344 description of what these matches are. This string may also
1345 contain the following sequences to specify output attributes, as
1346 described in the section EXPANSION OF PROMPT SEQUENCES in zsh‐
1347 misc(1): `%B', `%S', `%U', `%F', `%K' and their lower case coun‐
1348 terparts, as well as `%{...%}'. `%F', `%K' and `%{...%}' take
1349 arguments in the same form as prompt expansion. Note that the
1350 %G sequence is not available; an argument to `%{' should be used
1351 instead.
1352 The style is tested with each tag valid for the current comple‐
1354 tion before it is tested for the descriptions tag. Hence dif‐
1355 ferent format strings can be defined for different types of
1356 match.
1357 Note also that some completer functions define additional
1359 `%'-sequences. These are described for the completer functions
1360 that make use of them.
1361 Some completion functions display messages that may be cus‐
1363 tomised by setting this style for the messages tag. Here, the
1364 `%d' is replaced with a message given by the completion func‐
1365 tion.
1366 Finally, the format string is looked up with the warnings tag,
1368 for use when no matches could be generated at all. In this case
1369 the `%d' is replaced with the descriptions for the matches that
1370 were expected separated by spaces. The sequence `%D' is
1371 replaced with the same descriptions separated by newlines.
1372 It is possible to use printf-style field width specifiers with
1374 `%d' and similar escape sequences. This is handled by the zfor‐
1375 mat builtin command from the zsh/zutil module, see zshmod‐
1376 ules(1).
1377 glob This is used by the _expand completer. If it is set to `true'
1379 (the default), globbing will be attempted on the words resulting
1380 from a previous substitution (see the substitute style) or else
1381 the original string from the line.
1382 global If this is set to `true' (the default), the _expand_alias com‐
1384 pleter and bindable command will try to expand global aliases.
1385 group-name
1387 The completion system can group different types of matches,
1388 which appear in separate lists. This style can be used to give
1389 the names of groups for particular tags. For example, in com‐
1390 mand position the completion system generates names of builtin
1391 and external commands, names of aliases, shell functions and
1392 parameters and reserved words as possible completions. To have
1393 the external commands and shell functions listed separately:
1394 zstyle ':completion:*:*:-command-:*:commands' group-name commands
1396 zstyle ':completion:*:*:-command-:*:functions' group-name functions
1397 As a consequence, any match with the same tag will be displayed
1399 in the same group.
1400 If the name given is the empty string the name of the tag for
1402 the matches will be used as the name of the group. So, to have
1403 all different types of matches displayed separately, one can
1404 just set:
1405 zstyle ':completion:*' group-name ''
1407 All matches for which no group name is defined will be put in a
1409 group named -default-.
1410 group-order
1412 This style is additional to the group-name style to specify the
1413 order for display of the groups defined by that style (compare
1414 tag-order, which determines which completions appear at all).
1415 The groups named are shown in the given order; any other groups
1416 are shown in the order defined by the completion function.
1417 For example, to have names of builtin commands, shell functions
1419 and external commands appear in that order when completing in
1420 command position:
1421 zstyle ':completion:*:*:-command-:*' group-order \
1423 builtins functions commands
1424 groups A list of names of UNIX groups. If this is not set, group names
1426 are taken from the YP database or the file `/etc/group'.
1427 hidden If this is set to true, matches for the given context will not
1429 be listed, although any description for the matches set with the
1430 format style will be shown. If it is set to `all', not even the
1431 description will be displayed.
1432 Note that the matches will still be completed; they are just not
1434 shown in the list. To avoid having matches considered as possi‐
1435 ble completions at all, the tag-order style can be modified as
1436 described below.
1437 hosts A list of names of hosts that should be completed. If this is
1439 not set, hostnames are taken from the file `/etc/hosts'.
1440 hosts-ports
1442 This style is used by commands that need or accept hostnames and
1443 network ports. The strings in the value should be of the form
1444 `host:port'. Valid ports are determined by the presence of
1445 hostnames; multiple ports for the same host may appear.
1446 ignore-line
1448 This is tested for each tag valid for the current completion.
1449 If it is set to `true', none of the words that are already on
1450 the line will be considered as possible completions. If it is
1451 set to `current', the word the cursor is on will not be consid‐
1452 ered as a possible completion. The value `current-shown' is
1453 similar but only applies if the list of completions is currently
1454 shown on the screen. Finally, if the style is set to `other',
1455 no word apart from the current one will be considered as a pos‐
1456 sible completion.
1457 The values `current' and `current-shown' are a bit like the
1459 opposite of the accept-exact style: only strings with missing
1460 characters will be completed.
1461 Note that you almost certainly don't want to set this to `true'
1463 or `other' for a general context such as `:completion:*'. This
1464 is because it would disallow completion of, for example, options
1465 multiple times even if the command in question accepts the
1466 option more than once.
1467 ignore-parents
1469 The style is tested without a tag by the function completing
1470 pathnames in order to determine whether to ignore the names of
1471 directories already mentioned in the current word, or the name
1472 of the current working directory. The value must include one or
1473 both of the following strings:
1474 parent The name of any directory whose path is already contained
1476 in the word on the line is ignored. For example, when
1477 completing after foo/../, the directory foo will not be
1478 considered a valid completion.
1479 pwd The name of the current working directory will not be
1481 completed; hence, for example, completion after ../ will
1482 not use the name of the current directory.
1483 In addition, the value may include one or both of:
1485 .. Ignore the specified directories only when the word on
1487 the line contains the substring `../'.
1488 directory
1490 Ignore the specified directories only when names of
1491 directories are completed, not when completing names of
1492 files.
1493 Excluded values act in a similar fashion to values of the
1495 ignored-patterns style, so they can be restored to consideration
1496 by the _ignored completer.
1497 extra-verbose
1499 If set, the completion listing is more verbose at the cost of a
1500 probable decrease in completion speed. Completion performance
1501 will suffer if this style is set to `true'.
1502 ignored-patterns
1504 A list of patterns; any trial completion matching one of the
1505 patterns will be excluded from consideration. The _ignored com‐
1506 pleter can appear in the list of completers to restore the
1507 ignored matches. This is a more configurable version of the
1508 shell parameter $fignore.
1509 Note that the EXTENDED_GLOB option is set during the execution
1511 of completion functions, so the characters `#', `~' and `^' have
1512 special meanings in the patterns.
1513 insert This style is used by the _all_matches completer to decide
1515 whether to insert the list of all matches unconditionally
1516 instead of adding the list as another match.
1517 insert-ids
1519 When completing process IDs, for example as arguments to the
1520 kill and wait builtins the name of a command may be converted to
1521 the appropriate process ID. A problem arises when the process
1522 name typed is not unique. By default (or if this style is set
1523 explicitly to `menu') the name will be converted immediately to
1524 a set of possible IDs, and menu completion will be started to
1525 cycle through them.
1526 If the value of the style is `single', the shell will wait until
1528 the user has typed enough to make the command unique before con‐
1529 verting the name to an ID; attempts at completion will be unsuc‐
1530 cessful until that point. If the value is any other string,
1531 menu completion will be started when the string typed by the
1532 user is longer than the common prefix to the corresponding IDs.
1533 insert-tab
1535 If this is set to `true', the completion system will insert a
1536 TAB character (assuming that was used to start completion)
1537 instead of performing completion when there is no non-blank
1538 character to the left of the cursor. If it is set to `false',
1539 completion will be done even there.
1540 The value may also contain the substrings `pending' or `pend‐
1542 ing=val'. In this case, the typed character will be inserted
1543 instead of starting completion when there is unprocessed input
1544 pending. If a val is given, completion will not be done if
1545 there are at least that many characters of unprocessed input.
1546 This is often useful when pasting characters into a terminal.
1547 Note however, that it relies on the $PENDING special parameter
1548 from the zsh/zle module being set properly which is not guaran‐
1549 teed on all platforms.
1550 The default value of this style is `true' except for completion
1552 within vared builtin command where it is `false'.
1553 insert-unambiguous
1555 This is used by the _match and _approximate completers. These
1556 completers are often used with menu completion since the word
1557 typed may bear little resemblance to the final completion. How‐
1558 ever, if this style is `true', the completer will start menu
1559 completion only if it could find no unambiguous initial string
1560 at least as long as the original string typed by the user.
1561 In the case of the _approximate completer, the completer field
1563 in the context will already have been set to one of correct-num
1564 or approximate-num, where num is the number of errors that were
1565 accepted.
1566 In the case of the _match completer, the style may also be set
1568 to the string `pattern'. Then the pattern on the line is left
1569 unchanged if it does not match unambiguously.
1570 keep-prefix
1572 This style is used by the _expand completer. If it is `true',
1573 the completer will try to keep a prefix containing a tilde or
1574 parameter expansion. Hence, for example, the string `~/f*'
1575 would be expanded to `~/foo' instead of `/home/user/foo'. If
1576 the style is set to `changed' (the default), the prefix will
1577 only be left unchanged if there were other changes between the
1578 expanded words and the original word from the command line. Any
1579 other value forces the prefix to be expanded unconditionally.
1580 The behaviour of expand when this style is true is to cause
1582 _expand to give up when a single expansion with the restored
1583 prefix is the same as the original; hence any remaining com‐
1584 pleters may be called.
1585 last-prompt
1587 This is a more flexible form of the ALWAYS_LAST_PROMPT option.
1588 If it is true, the completion system will try to return the cur‐
1589 sor to the previous command line after displaying a completion
1590 list. It is tested for all tags valid for the current comple‐
1591 tion, then the default tag. The cursor will be moved back to
1592 the previous line if this style is `true' for all types of
1593 match. Note that unlike the ALWAYS_LAST_PROMPT option this is
1594 independent of the numeric prefix argument.
1595 known-hosts-files
1597 This style should contain a list of files to search for host
1598 names and (if the use-ip style is set) IP addresses in a format
1599 compatible with ssh known_hosts files. If it is not set, the
1600 files /etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts are used.
1601 list This style is used by the _history_complete_word bindable com‐
1603 mand. If it is set to `true' it has no effect. If it is set to
1604 `false' matches will not be listed. This overrides the setting
1605 of the options controlling listing behaviour, in particular
1606 AUTO_LIST. The context always starts with `:completion:his‐
1607 tory-words'.
1608 list-colors
1610 If the zsh/complist module is loaded, this style can be used to
1611 set color specifications. This mechanism replaces the use of
1612 the ZLS_COLORS and ZLS_COLOURS parameters described in the sec‐
1613 tion `The zsh/complist Module' in zshmodules(1), but the syntax
1614 is the same.
1615 If this style is set for the default tag, the strings in the
1617 value are taken as specifications that are to be used every‐
1618 where. If it is set for other tags, the specifications are used
1619 only for matches of the type described by the tag. For this to
1620 work best, the group-name style must be set to an empty string.
1621 In addition to setting styles for specific tags, it is also pos‐
1623 sible to use group names specified explicitly by the group-name
1624 tag together with the `(group)' syntax allowed by the ZLS_COLORS
1625 and ZLS_COLOURS parameters and simply using the default tag.
1626 It is possible to use any color specifications already set up
1628 for the GNU version of the ls command:
1629 zstyle ':completion:*:default' list-colors ${(s.:.)LS_COLORS}
1631 The default colors are the same as for the GNU ls command and
1633 can be obtained by setting the style to an empty string (i.e.
1634 '').
1635 list-dirs-first
1637 This is used by file completion. If set, directories to be com‐
1638 pleted are listed separately from and before completion for
1639 other files, regardless of tag ordering. In addition, the tag
1640 other-files is used in place of all-files for the remaining
1641 files, to indicate that no directories are presented with that
1642 tag.
1643 list-grouped
1645 If this style is `true' (the default), the completion system
1646 will try to make certain completion listings more compact by
1647 grouping matches. For example, options for commands that have
1648 the same description (shown when the verbose style is set to
1649 `true') will appear as a single entry. However, menu selection
1650 can be used to cycle through all the matches.
1651 list-packed
1653 This is tested for each tag valid in the current context as well
1654 as the default tag. If it is set to `true', the corresponding
1655 matches appear in listings as if the LIST_PACKED option were
1656 set. If it is set to `false', they are listed normally.
1657 list-prompt
1659 If this style is set for the default tag, completion lists that
1660 don't fit on the screen can be scrolled (see the description of
1661 the zsh/complist module in zshmodules(1)). The value, if not
1662 the empty string, will be displayed after every screenful and
1663 the shell will prompt for a key press; if the style is set to
1664 the empty string, a default prompt will be used.
1665 The value may contain the escape sequences: `%l' or `%L', which
1667 will be replaced by the number of the last line displayed and
1668 the total number of lines; `%m' or `%M', the number of the last
1669 match shown and the total number of matches; and `%p' and `%P',
1670 `Top' when at the beginning of the list, `Bottom' when at the
1671 end and the position shown as a percentage of the total length
1672 otherwise. In each case the form with the uppercase letter will
1673 be replaced by a string of fixed width, padded to the right
1674 with spaces, while the lowercase form will be replaced by a
1675 variable width string. As in other prompt strings, the escape
1676 sequences `%S', `%s', `%B', `%b', `%U', `%u' for entering and
1677 leaving the display modes standout, bold and underline, and
1678 `%F', `%f', `%K', `%k' for changing the foreground background
1679 colour, are also available, as is the form `%{...%}' for enclos‐
1680 ing escape sequences which display with zero (or, with a numeric
1681 argument, some other) width.
1682 After deleting this prompt the variable LISTPROMPT should be
1684 unset for the the removal to take effect.
1685 list-rows-first
1687 This style is tested in the same way as the list-packed style
1688 and determines whether matches are to be listed in a rows-first
1689 fashion as if the LIST_ROWS_FIRST option were set.
1690 list-suffixes
1692 This style is used by the function that completes filenames. If
1693 it is true, and completion is attempted on a string containing
1694 multiple partially typed pathname components, all ambiguous com‐
1695 ponents will be shown. Otherwise, completion stops at the first
1696 ambiguous component.
1697 list-separator
1699 The value of this style is used in completion listing to sepa‐
1700 rate the string to complete from a description when possible
1701 (e.g. when completing options). It defaults to `--' (two
1702 hyphens).
1703 local This is for use with functions that complete URLs for which the
1705 corresponding files are available directly from the file system.
1706 Its value should consist of three strings: a hostname, the path
1707 to the default web pages for the server, and the directory name
1708 used by a user placing web pages within their home area.
1709 For example:
1711 zstyle ':completion:*' local toast \
1713 /var/http/public/toast public_html
1714 Completion after `http://toast/stuff/' will look for files in
1716 the directory /var/http/public/toast/stuff, while completion
1717 after `http://toast/~yousir/' will look for files in the direc‐
1718 tory ~yousir/public_html.
1719 mail-directory
1721 If set, zsh will assume that mailbox files can be found in the
1722 directory specified. It defaults to `~/Mail'.
1723 match-original
1725 This is used by the _match completer. If it is set to only,
1726 _match will try to generate matches without inserting a `*' at
1727 the cursor position. If set to any other non-empty value, it
1728 will first try to generate matches without inserting the `*' and
1729 if that yields no matches, it will try again with the `*'
1730 inserted. If it is unset or set to the empty string, matching
1731 will only be performed with the `*' inserted.
1732 matcher
1734 This style is tested separately for each tag valid in the cur‐
1735 rent context. Its value is added to any match specifications
1736 given by the matcher-list style. It should be in the form
1737 described in the section `Completion Matching Control' in zsh‐
1738 compwid(1).
1739 matcher-list
1741 This style can be set to a list of match specifications that are
1742 to be applied everywhere. Match specifications are described in
1743 the section `Completion Matching Control' in zshcompwid(1). The
1744 completion system will try them one after another for each com‐
1745 pleter selected. For example, to try first simple completion
1746 and, if that generates no matches, case-insensitive completion:
1747 zstyle ':completion:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}'
1749 By default each specification replaces the previous one; how‐
1751 ever, if a specification is prefixed with +, it is added to the
1752 existing list. Hence it is possible to create increasingly gen‐
1753 eral specifications without repetition:
1754 zstyle ':completion:*' matcher-list '' '+m{a-z}={A-Z}' '+m{A-Z}={a-z}'
1756 It is possible to create match specifications valid for particu‐
1758 lar completers by using the third field of the context. For
1759 example, to use the completers _complete and _prefix but only
1760 allow case-insensitive completion with _complete:
1761 zstyle ':completion:*' completer _complete _prefix
1763 zstyle ':completion:*:complete:*' matcher-list \
1764 '' 'm:{a-zA-Z}={A-Za-z}'
1765 User-defined names, as explained for the completer style, are
1767 available. This makes it possible to try the same completer
1768 more than once with different match specifications each time.
1769 For example, to try normal completion without a match specifica‐
1770 tion, then normal completion with case-insensitive matching,
1771 then correction, and finally partial-word completion:
1772 zstyle ':completion:*' completer _complete _correct _complete:foo
1774 zstyle ':completion:*:complete:*' matcher-list \
1775 '' 'm:{a-zA-Z}={A-Za-z}'
1776 zstyle ':completion:*:foo:*' matcher-list \
1777 'm:{a-zA-Z}={A-Za-z} r:|[-_./]=* r:|=*'
1778 If the style is unset in any context no match specification is
1780 applied. Note also that some completers such as _correct and
1781 _approximate do not use the match specifications at all, though
1782 these completers will only ever be called once even if the
1783 matcher-list contains more than one element.
1784 Where multiple specifications are useful, note that the entire
1786 completion is done for each element of matcher-list, which can
1787 quickly reduce the shell's performance. As a rough rule of
1788 thumb, one to three strings will give acceptable performance.
1789 On the other hand, putting multiple space-separated values into
1790 the same string does not have an appreciable impact on perfor‐
1791 mance.
1792 If there is no current matcher or it is empty, and the option
1794 NO_CASE_GLOB is in effect, the matching for files is performed
1795 case-insensitively in any case. However, any matcher must
1796 explicitly specify case-insensitive matching if that is
1797 required.
1798 max-errors
1800 This is used by the _approximate and _correct completer func‐
1801 tions to determine the maximum number of errors to allow. The
1802 completer will try to generate completions by first allowing one
1803 error, then two errors, and so on, until either a match or
1804 matches were found or the maximum number of errors given by this
1805 style has been reached.
1806 If the value for this style contains the string `numeric', the
1808 completer function will take any numeric argument as the maximum
1809 number of errors allowed. For example, with
1810 zstyle ':completion:*:approximate:::' max-errors 2 numeric
1812 two errors are allowed if no numeric argument is given, but with
1814 a numeric argument of six (as in `ESC-6 TAB'), up to six errors
1815 are accepted. Hence with a value of `0 numeric', no correcting
1816 completion will be attempted unless a numeric argument is given.
1817 If the value contains the string `not-numeric', the completer
1819 will not try to generate corrected completions when given a
1820 numeric argument, so in this case the number given should be
1821 greater than zero. For example, `2 not-numeric' specifies that
1822 correcting completion with two errors will usually be performed,
1823 but if a numeric argument is given, correcting completion will
1824 not be performed.
1825 The default value for this style is `2 numeric'.
1827 max-matches-width
1829 This style is used to determine the trade off between the width
1830 of the display used for matches and the width used for their
1831 descriptions when the verbose style is in effect. The value
1832 gives the number of display columns to reserve for the matches.
1833 The default is half the width of the screen.
1834 This has the most impact when several matches have the same
1836 description and so will be grouped together. Increasing the
1837 style will allow more matches to be grouped together; decreasing
1838 it will allow more of the description to be visible.
1839 menu If this is true in the context of any of the tags defined for
1841 the current completion menu completion will be used. The value
1842 for a specific tag will take precedence over that for the
1843 `default' tag.
1844 If none of the values found in this way is true but at least one
1846 is set to `auto', the shell behaves as if the AUTO_MENU option
1847 is set.
1848 If one of the values is explicitly set to false, menu completion
1850 will be explicitly turned off, overriding the MENU_COMPLETE
1851 option and other settings.
1852 In the form `yes=num', where `yes' may be any of the true values
1854 (`yes', `true', `on' and `1'), menu completion will be turned on
1855 if there are at least num matches. In the form `yes=long', menu
1856 completion will be turned on if the list does not fit on the
1857 screen. This does not activate menu completion if the widget
1858 normally only lists completions, but menu completion can be
1859 activated in that case with the value `yes=long-list' (Typi‐
1860 cally, the value `select=long-list' described later is more use‐
1861 ful as it provides control over scrolling.)
1862 Similarly, with any of the `false' values (as in `no=10'), menu
1864 completion will not be used if there are num or more matches.
1865 The value of this widget also controls menu selection, as imple‐
1867 mented by the zsh/complist module. The following values may
1868 appear either alongside or instead of the values above.
1869 If the value contains the string `select', menu selection will
1871 be started unconditionally.
1872 In the form `select=num', menu selection will only be started if
1874 there are at least num matches. If the values for more than one
1875 tag provide a number, the smallest number is taken.
1876 Menu selection can be turned off explicitly by defining a value
1878 containing the string`no-select'.
1879 It is also possible to start menu selection only if the list of
1881 matches does not fit on the screen by using the value
1882 `select=long'. To start menu selection even if the current wid‐
1883 get only performs listing, use the value `select=long-list'.
1884 To turn on menu completion or menu selection when a there are a
1886 certain number of matches or the list of matches does not fit on
1887 the screen, both of `yes=' and `select=' may be given twice,
1888 once with a number and once with `long' or `long-list'.
1889 Finally, it is possible to activate two special modes of menu
1891 selection. The word `interactive' in the value causes interac‐
1892 tive mode to be entered immediately when menu selection is
1893 started; see the description of the zsh/complist module in zsh‐
1894 modules(1) for a description of interactive mode. Including the
1895 string `search' does the same for incremental search mode. To
1896 select backward incremental search, include the string
1897 `search-backward'.
1898 muttrc If set, gives the location of the mutt configuration file. It
1900 defaults to `~/.muttrc'.
1901 numbers
1903 This is used with the jobs tag. If it is `true', the shell will
1904 complete job numbers instead of the shortest unambiguous prefix
1905 of the job command text. If the value is a number, job numbers
1906 will only be used if that many words from the job descriptions
1907 are required to resolve ambiguities. For example, if the value
1908 is `1', strings will only be used if all jobs differ in the
1909 first word on their command lines.
1910 old-list
1912 This is used by the _oldlist completer. If it is set to
1913 `always', then standard widgets which perform listing will
1914 retain the current list of matches, however they were generated;
1915 this can be turned off explicitly with the value `never', giving
1916 the behaviour without the _oldlist completer. If the style is
1917 unset, or any other value, then the existing list of completions
1918 is displayed if it is not already; otherwise, the standard com‐
1919 pletion list is generated; this is the default behaviour of
1920 _oldlist. However, if there is an old list and this style con‐
1921 tains the name of the completer function that generated the
1922 list, then the old list will be used even if it was generated by
1923 a widget which does not do listing.
1924 For example, suppose you type ^Xc to use the _correct_word wid‐
1926 get, which generates a list of corrections for the word under
1927 the cursor. Usually, typing ^D would generate a standard list
1928 of completions for the word on the command line, and show that.
1929 With _oldlist, it will instead show the list of corrections
1930 already generated.
1931 As another example consider the _match completer: with the
1933 insert-unambiguous style set to `true' it inserts only a common
1934 prefix string, if there is any. However, this may remove parts
1935 of the original pattern, so that further completion could pro‐
1936 duce more matches than on the first attempt. By using the
1937 _oldlist completer and setting this style to _match, the list of
1938 matches generated on the first attempt will be used again.
1939 old-matches
1941 This is used by the _all_matches completer to decide if an old
1942 list of matches should be used if one exists. This is selected
1943 by one of the `true' values or by the string `only'. If the
1944 value is `only', _all_matches will only use an old list and
1945 won't have any effect on the list of matches currently being
1946 generated.
1947 If this style is set it is generally unwise to call the
1949 _all_matches completer unconditionally. One possible use is for
1950 either this style or the completer style to be defined with the
1951 -e option to zstyle to make the style conditional.
1952 old-menu
1954 This is used by the _oldlist completer. It controls how menu
1955 completion behaves when a completion has already been inserted
1956 and the user types a standard completion key such as TAB. The
1957 default behaviour of _oldlist is that menu completion always
1958 continues with the existing list of completions. If this style
1959 is set to `false', however, a new completion is started if the
1960 old list was generated by a different completion command; this
1961 is the behaviour without the _oldlist completer.
1962 For example, suppose you type ^Xc to generate a list of correc‐
1964 tions, and menu completion is started in one of the usual ways.
1965 Usually, or with this style set to false, typing TAB at this
1966 point would start trying to complete the line as it now appears.
1967 With _oldlist, it instead continues to cycle through the list of
1968 corrections.
1969 original
1971 This is used by the _approximate and _correct completers to
1972 decide if the original string should be added as a possible com‐
1973 pletion. Normally, this is done only if there are at least two
1974 possible corrections, but if this style is set to `true', it is
1975 always added. Note that the style will be examined with the
1976 completer field in the context name set to correct-num or
1977 approximate-num, where num is the number of errors that were
1978 accepted.
1979 packageset
1981 This style is used when completing arguments of the Debian
1982 `dpkg' program. It contains an override for the default package
1983 set for a given context. For example,
1984 zstyle ':completion:*:complete:dpkg:option--status-1:*' \
1986 packageset avail
1987 causes available packages, rather than only installed packages,
1989 to be completed for `dpkg --status'.
1990 path The function that completes color names uses this style with the
1992 colors tag. The value should be the pathname of a file contain‐
1993 ing color names in the format of an X11 rgb.txt file. If the
1994 style is not set but this file is found in one of various stan‐
1995 dard locations it will be used as the default.
1996 path-completion
1998 This is used by filename completion. By default, filename com‐
1999 pletion examines all components of a path to see if there are
2000 completions of that component. For example, /u/b/z can be com‐
2001 pleted to /usr/bin/zsh. Explicitly setting this style to false
2002 inhibits this behaviour for path components up to the / before
2003 the cursor; this overrides the setting of accept-exact-dirs.
2004 Even with the style set to false, it is still possible to com‐
2006 plete multiple paths by setting the option COMPLETE_IN_WORD and
2007 moving the cursor back to the first component in the path to be
2008 completed. For example, /u/b/z can be completed to /usr/bin/zsh
2009 if the cursor is after the /u.
2010 pine-directory
2012 If set, specifies the directory containing PINE mailbox files.
2013 There is no default, since recursively searching this directory
2014 is inconvenient for anyone who doesn't use PINE.
2015 ports A list of Internet service names (network ports) to complete.
2017 If this is not set, service names are taken from the file
2018 `/etc/services'.
2019 prefix-hidden
2021 This is used for certain completions which share a common pre‐
2022 fix, for example command options beginning with dashes. If it
2023 is `true', the prefix will not be shown in the list of matches.
2024 The default value for this style is `false'.
2026 prefix-needed
2028 This, too, is used for matches with a common prefix. If it is
2029 set to `true' this common prefix must be typed by the user to
2030 generate the matches. In the case of command options, this
2031 means that the initial `-', `+', or `--' must be typed explic‐
2032 itly before option names will be completed.
2033 The default value for this style is `true'.
2035 preserve-prefix
2037 This style is used when completing path names. Its value should
2038 be a pattern matching an initial prefix of the word to complete
2039 that should be left unchanged under all circumstances. For
2040 example, on some Unices an initial `//' (double slash) has a
2041 special meaning; setting this style to the string `//' will pre‐
2042 serve it. As another example, setting this style to `?:/' under
2043 Cygwin would allow completion after `a:/...' and so on.
2044 range This is used by the _history completer and the _history_com‐
2046 plete_word bindable command to decide which words should be com‐
2047 pleted.
2048 If it is a singe number, only the last N words from the history
2050 will be completed.
2051 If it is a range of the form `max:slice', the last slice words
2053 will be completed; then if that yields no matches, the slice
2054 words before those will be tried and so on. This process stops
2055 either when at least one match was been found, or max words have
2056 been tried.
2057 The default is to complete all words from the history at once.
2059 regular
2061 This style is used by the _expand_alias completer and bindable
2062 command. If set to `true' (the default), regular aliases will
2063 be expanded but only in command position. If it is set to
2064 `false', regular aliases will never be expanded. If it is set
2065 to `always', regular aliases will be expanded even if not in
2066 command position.
2067 rehash If this is set when completing external commands, the internal
2069 list (hash) of commands will be updated for each search by issu‐
2070 ing the rehash command. There is a speed penalty for this which
2071 is only likely to be noticeable when directories in the path
2072 have slow file access.
2073 remote-access
2075 If set to false, certain commands will be prevented from making
2076 Internet connections to retrieve remote information. This
2077 includes the completion for the CVS command.
2078 It is not always possible to know if connections are in fact to
2080 a remote site, so some may be prevented unnecessarily.
2081 remove-all-dups
2083 The _history_complete_word bindable command and the _history
2084 completer use this to decide if all duplicate matches should be
2085 removed, rather than just consecutive duplicates.
2086 select-prompt
2088 If this is set for the default tag, its value will be displayed
2089 during menu selection (see the menu style above) when the com‐
2090 pletion list does not fit on the screen as a whole. The same
2091 escapes as for the list-prompt style are understood, except that
2092 the numbers refer to the match or line the mark is on. A
2093 default prompt is used when the value is the empty string.
2094 select-scroll
2096 This style is tested for the default tag and determines how a
2097 completion list is scrolled during a menu selection (see the
2098 menu style above) when the completion list does not fit on the
2099 screen as a whole. If the value is `0' (zero), the list is
2100 scrolled by half-screenfuls; if it is a positive integer, the
2101 list is scrolled by the given number of lines; if it is a nega‐
2102 tive number, the list is scrolled by a screenful minus the abso‐
2103 lute value of the given number of lines. The default is to
2104 scroll by single lines.
2105 separate-sections
2107 This style is used with the manuals tag when completing names of
2108 manual pages. If it is `true', entries for different sections
2109 are added separately using tag names of the form `manual.X',
2110 where X is the section number. When the group-name style is
2111 also in effect, pages from different sections will appear sepa‐
2112 rately. This style is also used similarly with the words style
2113 when completing words for the dict command. It allows words from
2114 different dictionary databases to be added separately. The
2115 default for this style is `false'.
2116 show-completer
2118 Tested whenever a new completer is tried. If it is true, the
2119 completion system outputs a progress message in the listing area
2120 showing what completer is being tried. The message will be
2121 overwritten by any output when completions are found and is
2122 removed after completion is finished.
2123 single-ignored
2125 This is used by the _ignored completer when there is only one
2126 match. If its value is `show', the single match will be dis‐
2127 played but not inserted. If the value is `menu', then the sin‐
2128 gle match and the original string are both added as matches and
2129 menu completion is started, making it easy to select either of
2130 them.
2131 sort Many completion widgets call _description at some point which
2133 decides whether the matches are added sorted or unsorted (often
2134 indirectly via _wanted or _requested). This style can be set
2135 explicitly to one of the usual true or false values as an over‐
2136 ride. If it is not set for the context, the standard behaviour
2137 of the calling widget is used.
2138 The style is tested first against the full context including the
2140 tag, and if that fails to produce a value against the context
2141 without the tag.
2142 If the calling widget explicitly requests unsorted matches, this
2144 is usually honoured. However, the default (unsorted) behaviour
2145 of completion for the command history may be overridden by set‐
2146 ting the style to true.
2147 In the _expand completer, if it is set to `true', the expansions
2149 generated will always be sorted. If it is set to `menu', then
2150 the expansions are only sorted when they are offered as single
2151 strings but not in the string containing all possible expan‐
2152 sions.
2153 special-dirs
2155 Normally, the completion code will not produce the directory
2156 names `.' and `..' as possible completions. If this style is
2157 set to `true', it will add both `.' and `..' as possible comple‐
2158 tions; if it is set to `..', only `..' will be added.
2159 The following example sets special-dirs to `..' when the current
2161 prefix is empty, is a single `.', or consists only of a path
2162 beginning with `../'. Otherwise the value is `false'.
2163 zstyle -e ':completion:*' special-dirs \
2165 '[[ $PREFIX = (../)#(|.|..) ]] && reply=(..)'
2166 squeeze-slashes
2168 If set to `true', sequences of slashes in filename paths (for
2169 example in `foo//bar') will be treated as a single slash. This
2170 is the usual behaviour of UNIX paths. However, by default the
2171 file completion function behaves as if there were a `*' between
2172 the slashes.
2173 stop If set to `true', the _history_complete_word bindable command
2175 will stop once when reaching the beginning or end of the his‐
2176 tory. Invoking _history_complete_word will then wrap around to
2177 the opposite end of the history. If this style is set to
2178 `false' (the default), _history_complete_word will loop immedi‐
2179 ately as in a menu completion.
2180 strip-comments
2182 If set to `true', this style causes non-essential comment text
2183 to be removed from completion matches. Currently it is only
2184 used when completing e-mail addresses where it removes any dis‐
2185 play name from the addresses, cutting them down to plain
2186 user@host form.
2187 subst-globs-only
2189 This is used by the _expand completer. If it is set to `true',
2190 the expansion will only be used if it resulted from globbing;
2191 hence, if expansions resulted from the use of the substitute
2192 style described below, but these were not further changed by
2193 globbing, the expansions will be rejected.
2194 The default for this style is `false'.
2196 substitute
2198 This boolean style controls whether the _expand completer will
2199 first try to expand all substitutions in the string (such as
2200 `$(...)' and `${...}').
2201 The default is `true'.
2203 suffix This is used by the _expand completer if the word starts with a
2205 tilde or contains a parameter expansion. If it is set to
2206 `true', the word will only be expanded if it doesn't have a suf‐
2207 fix, i.e. if it is something like `~foo' or `$foo' rather than
2208 `~foo/' or `$foo/bar', unless that suffix itself contains char‐
2209 acters eligible for expansion. The default for this style is
2210 `true'.
2211 tag-order
2213 This provides a mechanism for sorting how the tags available in
2214 a particular context will be used.
2215 The values for the style are sets of space-separated lists of
2217 tags. The tags in each value will be tried at the same time; if
2218 no match is found, the next value is used. (See the file-pat‐
2219 terns style for an exception to this behavior.)
2220 For example:
2222 zstyle ':completion:*:complete:-command-:*' tag-order \
2224 'commands functions'
2225 specifies that completion in command position first offers
2227 external commands and shell functions. Remaining tags will be
2228 tried if no completions are found.
2229 In addition to tag names, each string in the value may take one
2231 of the following forms:
2232 - If any value consists of only a hyphen, then only the
2234 tags specified in the other values are generated. Nor‐
2235 mally all tags not explicitly selected are tried last if
2236 the specified tags fail to generate any matches. This
2237 means that a single value consisting only of a single
2238 hyphen turns off completion.
2239 ! tags...
2241 A string starting with an exclamation mark specifies
2242 names of tags that are not to be used. The effect is the
2243 same as if all other possible tags for the context had
2244 been listed.
2245 tag:label ...
2247 Here, tag is one of the standard tags and label is an
2248 arbitrary name. Matches are generated as normal but the
2249 name label is used in contexts instead of tag. This is
2250 not useful in words starting with !.
2251 If the label starts with a hyphen, the tag is prepended
2253 to the label to form the name used for lookup. This can
2254 be used to make the completion system try a certain tag
2255 more than once, supplying different style settings for
2256 each attempt; see below for an example.
2257 tag:label:description
2259 As before, but description will replace the `%d' in the
2260 value of the format style instead of the default descrip‐
2261 tion supplied by the completion function. Spaces in the
2262 description must be quoted with a backslash. A `%d'
2263 appearing in description is replaced with the description
2264 given by the completion function.
2265 In any of the forms above the tag may be a pattern or several
2267 patterns in the form `{pat1,pat2...}'. In this case all match‐
2268 ing tags will be used except for any given explicitly in the
2269 same string.
2270 One use of these features is to try one tag more than once, set‐
2272 ting other styles differently on each attempt, but still to use
2273 all the other tags without having to repeat them all. For exam‐
2274 ple, to make completion of function names in command position
2275 ignore all the completion functions starting with an underscore
2276 the first time completion is tried:
2277 zstyle ':completion:*:*:-command-:*' tag-order \
2279 'functions:-non-comp *' functions
2280 zstyle ':completion:*:functions-non-comp' ignored-patterns '_*'
2281 On the first attempt, all tags will be offered but the functions
2283 tag will be replaced by functions-non-comp. The ignored-pat‐
2284 terns style is set for this tag to exclude functions starting
2285 with an underscore. If there are no matches, the second value
2286 of the tag-order style is used which completes functions using
2287 the default tag, this time presumably including all function
2288 names.
2289 The matches for one tag can be split into different groups. For
2291 example:
2292 zstyle ':completion:*' tag-order \
2294 'options:-long:long\ options
2295 options:-short:short\ options
2296 options:-single-letter:single\ letter\ options'
2297 zstyle ':completion:*:options-long' ignored-patterns '[-+](|-|[^-]*)'
2299 zstyle ':completion:*:options-short' ignored-patterns '--*' '[-+]?'
2300 zstyle ':completion:*:options-single-letter' ignored-patterns '???*'
2301 With the group-names style set, options beginning with `--',
2303 options beginning with a single `-' or `+' but containing multi‐
2304 ple characters, and single-letter options will be displayed in
2305 separate groups with different descriptions.
2306 Another use of patterns is to try multiple match specifications
2308 one after another. The matcher-list style offers something sim‐
2309 ilar, but it is tested very early in the completion system and
2310 hence can't be set for single commands nor for more specific
2311 contexts. Here is how to try normal completion without any
2312 match specification and, if that generates no matches, try again
2313 with case-insensitive matching, restricting the effect to argu‐
2314 ments of the command foo:
2315 zstyle ':completion:*:*:foo:*' tag-order '*' '*:-case'
2317 zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}'
2318 First, all the tags offered when completing after foo are tried
2320 using the normal tag name. If that generates no matches, the
2321 second value of tag-order is used, which tries all tags again
2322 except that this time each has -case appended to its name for
2323 lookup of styles. Hence this time the value for the matcher
2324 style from the second call to zstyle in the example is used to
2325 make completion case-insensitive.
2326 It is possible to use the -e option of the zstyle builtin com‐
2328 mand to specify conditions for the use of particular tags. For
2329 example:
2330 zstyle -e '*:-command-:*' tag-order '
2332 if [[ -n $PREFIX$SUFFIX ]]; then
2333 reply=( )
2334 else
2335 reply=( - )
2336 fi'
2337 Completion in command position will be attempted only if the
2339 string typed so far is not empty. This is tested using the PRE‐
2340 FIX special parameter; see zshcompwid for a description of
2341 parameters which are special inside completion widgets. Setting
2342 reply to an empty array provides the default behaviour of trying
2343 all tags at once; setting it to an array containing only a
2344 hyphen disables the use of all tags and hence of all comple‐
2345 tions.
2346 If no tag-order style has been defined for a context, the
2348 strings `(|*-)argument-* (|*-)option-* values' and `options'
2349 plus all tags offered by the completion function will be used to
2350 provide a sensible default behavior that causes arguments
2351 (whether normal command arguments or arguments of options) to be
2352 completed before option names for most commands.
2353 urls This is used together with the the urls tag by functions com‐
2355 pleting URLs.
2356 If the value consists of more than one string, or if the only
2358 string does not name a file or directory, the strings are used
2359 as the URLs to complete.
2360 If the value contains only one string which is the name of a
2362 normal file the URLs are taken from that file (where the URLs
2363 may be separated by white space or newlines).
2364 Finally, if the only string in the value names a directory, the
2366 directory hierarchy rooted at this directory gives the comple‐
2367 tions. The top level directory should be the file access
2368 method, such as `http', `ftp', `bookmark' and so on. In many
2369 cases the next level of directories will be a filename. The
2370 directory hierarchy can descend as deep as necessary.
2371 For example,
2373 zstyle ':completion:*' urls ~/.urls
2375 mkdir -p ~/.urls/ftp/ftp.zsh.org/pub/development
2376 allows completion of all the components of the URL
2378 ftp://ftp.zsh.org/pub/development after suitable commands such
2379 as `netscape' or `lynx'. Note, however, that access methods and
2380 files are completed separately, so if the hosts style is set
2381 hosts can be completed without reference to the urls style.
2382 See the description in the function _urls itself for more infor‐
2384 mation (e.g. `more $^fpath/_urls(N)').
2385 use-cache
2387 If this is set, the completion caching layer is activated for
2388 any completions which use it (via the _store_cache,
2389 _retrieve_cache, and _cache_invalid functions). The directory
2390 containing the cache files can be changed with the cache-path
2391 style.
2392 use-compctl
2394 If this style is set to a string not equal to false, 0, no, and
2395 off, the completion system may use any completion specifications
2396 defined with the compctl builtin command. If the style is
2397 unset, this is done only if the zsh/compctl module is loaded.
2398 The string may also contain the substring `first' to use comple‐
2399 tions defined with `compctl -T', and the substring `default' to
2400 use the completion defined with `compctl -D'.
2401 Note that this is only intended to smooth the transition from
2403 compctl to the new completion system and may disappear in the
2404 future.
2405 Note also that the definitions from compctl will only be used if
2407 there is no specific completion function for the command in
2408 question. For example, if there is a function _foo to complete
2409 arguments to the command foo, compctl will never be invoked for
2410 foo. However, the compctl version will be tried if foo only
2411 uses default completion.
2412 use-ip By default, the function _hosts that completes host names strips
2414 IP addresses from entries read from host databases such as NIS
2415 and ssh files. If this style is true, the corresponding IP
2416 addresses can be completed as well. This style is not use in
2417 any context where the hosts style is set; note also it must be
2418 set before the cache of host names is generated (typically the
2419 first completion attempt).
2420 use-perl
2422 Various parts of the function system use awk to extract words
2423 from files or command output as it is universally available.
2424 However, many versions of awk have arbitrary limits on the size
2425 of input. If this style is set, perl will be used instead.
2426 This is almost always preferable if perl is available on your
2427 system.
2428 Currently this is only used in completions for `make', but it
2430 may be extended depending on authorial frustration.
2431 users This may be set to a list of usernames to be completed. If it
2433 is not set all usernames will be completed. Note that if it is
2434 set only that list of users will be completed; this is because
2435 on some systems querying all users can take a prohibitive amount
2436 of time.
2437 users-hosts
2439 The values of this style should be of the form `user@host' or
2440 `user:host'. It is used for commands that need pairs of user-
2441 and hostnames. These commands will complete usernames from this
2442 style (only), and will restrict subsequent hostname completion
2443 to hosts paired with that user in one of the values of the
2444 style.
2445 It is possible to group values for sets of commands which allow
2447 a remote login, such as rlogin and ssh, by using the my-accounts
2448 tag. Similarly, values for sets of commands which usually refer
2449 to the accounts of other people, such as talk and finger, can be
2450 grouped by using the other-accounts tag. More ambivalent com‐
2451 mands may use the accounts tag.
2452 users-hosts-ports
2454 Like users-hosts but used for commands like telnet and contain‐
2455 ing strings of the form `user@host:port'.
2456 verbose
2458 If set, as it is by default, the completion listing is more ver‐
2459 bose. In particular many commands show descriptions for options
2460 if this style is `true'.
2461 word This is used by the _list completer, which prevents the inser‐
2463 tion of completions until a second completion attempt when the
2464 line has not changed. The normal way of finding out if the line
2465 has changed is to compare its entire contents between the two
2466 occasions. If this style is true, the comparison is instead
2467 performed only on the current word. Hence if completion is per‐
2468 formed on another word with the same contents, completion will
2469 not be delayed.
2470
2472 The initialization script compinit redefines all the widgets which per‐
2473 form completion to call the supplied widget function _main_complete.
2474 This function acts as a wrapper calling the so-called `completer' func‐
2475 tions that generate matches. If _main_complete is called with argu‐
2476 ments, these are taken as the names of completer functions to be called
2477 in the order given. If no arguments are given, the set of functions to
2478 try is taken from the completer style. For example, to use normal com‐
2479 pletion and correction if that doesn't generate any matches:
2480 zstyle ':completion:*' completer _complete _correct
2482 after calling compinit. The default value for this style is `_complete
2484 _ignored', i.e. normally only ordinary completion is tried, first with
2485 the effect of the ignored-patterns style and then without it. The
2486 _main_complete function uses the return status of the completer func‐
2487 tions to decide if other completers should be called. If the return
2488 status is zero, no other completers are tried and the _main_complete
2489 function returns.
2490 If the first argument to _main_complete is a single hyphen, the argu‐
2492 ments will not be taken as names of completers. Instead, the second
2493 argument gives a name to use in the completer field of the context and
2494 the other arguments give a command name and arguments to call to gener‐
2495 ate the matches.
2496 The following completer functions are contained in the distribution,
2498 although users may write their own. Note that in contexts the leading
2499 underscore is stripped, for example basic completion is performed in
2500 the context `:completion::complete:...'.
2501 _all_matches
2503 This completer can be used to add a string consisting of all
2504 other matches. As it influences later completers it must appear
2505 as the first completer in the list. The list of all matches is
2506 affected by the avoid-completer and old-matches styles described
2507 above.
2508 It may be useful to use the _generic function described below to
2510 bind _all_matches to its own keystroke, for example:
2511 zle -C all-matches complete-word _generic
2513 bindkey '^Xa' all-matches
2514 zstyle ':completion:all-matches:*' old-matches only
2515 zstyle ':completion:all-matches::::' completer _all_matches
2516 Note that this does not generate completions by itself: first
2518 use any of the standard ways of generating a list of comple‐
2519 tions, then use ^Xa to show all matches. It is possible instead
2520 to add a standard completer to the list and request that the
2521 list of all matches should be directly inserted:
2522 zstyle ':completion:all-matches::::' completer _all_matches _complete
2524 zstyle ':completion:all-matches:*' insert true
2525 In this case the old-matches style should not be set.
2527 _approximate
2529 This is similar to the basic _complete completer but allows the
2530 completions to undergo corrections. The maximum number of
2531 errors can be specified by the max-errors style; see the
2532 description of approximate matching in zshexpn(1) for how errors
2533 are counted. Normally this completer will only be tried after
2534 the normal _complete completer:
2535 zstyle ':completion:*' completer _complete _approximate
2537 This will give correcting completion if and only if normal com‐
2539 pletion yields no possible completions. When corrected comple‐
2540 tions are found, the completer will normally start menu comple‐
2541 tion allowing you to cycle through these strings.
2542 This completer uses the tags corrections and original when gen‐
2544 erating the possible corrections and the original string. The
2545 format style for the former may contain the additional sequences
2546 `%e' and `%o' which will be replaced by the number of errors
2547 accepted to generate the corrections and the original string,
2548 respectively.
2549 The completer progressively increases the number of errors
2551 allowed up to the limit by the max-errors style, hence if a com‐
2552 pletion is found with one error, no completions with two errors
2553 will be shown, and so on. It modifies the completer name in the
2554 context to indicate the number of errors being tried: on the
2555 first try the completer field contains `approximate-1', on the
2556 second try `approximate-2', and so on.
2557 When _approximate is called from another function, the number of
2559 errors to accept may be passed with the -a option. The argument
2560 is in the same format as the max-errors style, all in one
2561 string.
2562 Note that this completer (and the _correct completer mentioned
2564 below) can be quite expensive to call, especially when a large
2565 number of errors are allowed. One way to avoid this is to set
2566 up the completer style using the -e option to zstyle so that
2567 some completers are only used when completion is attempted a
2568 second time on the same string, e.g.:
2569 zstyle -e ':completion:*' completer '
2571 if [[ $_last_try != "$HISTNO$BUFFER$CURSOR" ]]; then
2572 _last_try="$HISTNO$BUFFER$CURSOR"
2573 reply=(_complete _match _prefix)
2574 else
2575 reply=(_ignored _correct _approximate)
2576 fi'
2577 This uses the HISTNO parameter and the BUFFER and CURSOR special
2579 parameters that are available inside zle and completion widgets
2580 to find out if the command line hasn't changed since the last
2581 time completion was tried. Only then are the _ignored, _correct
2582 and _approximate completers called.
2583 _complete
2585 This completer generates all possible completions in a con‐
2586 text-sensitive manner, i.e. using the settings defined with the
2587 compdef function explained above and the current settings of all
2588 special parameters. This gives the normal completion behaviour.
2589 To complete arguments of commands, _complete uses the utility
2591 function _normal, which is in turn responsible for finding the
2592 particular function; it is described below. Various contexts of
2593 the form -context- are handled specifically. These are all men‐
2594 tioned above as possible arguments to the #compdef tag.
2595 Before trying to find a function for a specific context, _com‐
2597 plete checks if the parameter `compcontext' is set. Setting
2598 `compcontext' allows the usual completion dispatching to be
2599 overridden which is useful in places such as a function that
2600 uses vared for input. If it is set to an array, the elements are
2601 taken to be the possible matches which will be completed using
2602 the tag `values' and the description `value'. If it is set to an
2603 associative array, the keys are used as the possible completions
2604 and the values (if non-empty) are used as descriptions for the
2605 matches. If `compcontext' is set to a string containing colons,
2606 it should be of the form `tag:descr:action'. In this case the
2607 tag and descr give the tag and description to use and the action
2608 indicates what should be completed in one of the forms accepted
2609 by the _arguments utility function described below.
2610 Finally, if `compcontext' is set to a string without colons, the
2612 value is taken as the name of the context to use and the func‐
2613 tion defined for that context will be called. For this purpose,
2614 there is a special context named -command-line- that completes
2615 whole command lines (commands and their arguments). This is not
2616 used by the completion system itself but is nonetheless handled
2617 when explicitly called.
2618 _correct
2620 Generate corrections, but not completions, for the current word;
2621 this is similar to _approximate but will not allow any number of
2622 extra characters at the cursor as that completer does. The
2623 effect is similar to spell-checking. It is based on _approxi‐
2624 mate, but the completer field in the context name is correct.
2625 For example, with:
2627 zstyle ':completion:::::' completer _complete _correct _approximate
2629 zstyle ':completion:*:correct:::' max-errors 2 not-numeric
2630 zstyle ':completion:*:approximate:::' max-errors 3 numeric
2631 correction will accept up to two errors. If a numeric argument
2633 is given, correction will not be performed, but correcting com‐
2634 pletion will be, and will accept as many errors as given by the
2635 numeric argument. Without a numeric argument, first correction
2636 and then correcting completion will be tried, with the first one
2637 accepting two errors and the second one accepting three errors.
2638 When _correct is called as a function, the number of errors to
2640 accept may be given following the -a option. The argument is in
2641 the same form a values to the accept style, all in one string.
2642 This completer function is intended to be used without the
2644 _approximate completer or, as in the example, just before it.
2645 Using it after the _approximate completer is useless since
2646 _approximate will at least generate the corrected strings gener‐
2647 ated by the _correct completer -- and probably more.
2648 _expand
2650 This completer function does not really perform completion, but
2651 instead checks if the word on the command line is eligible for
2652 expansion and, if it is, gives detailed control over how this
2653 expansion is done. For this to happen, the completion system
2654 needs to be invoked with complete-word, not expand-or-complete
2655 (the default binding for TAB), as otherwise the string will be
2656 expanded by the shell's internal mechanism before the completion
2657 system is started. Note also this completer should be called
2658 before the _complete completer function.
2659 The tags used when generating expansions are all-expansions for
2661 the string containing all possible expansions, expansions when
2662 adding the possible expansions as single matches and original
2663 when adding the original string from the line. The order in
2664 which these strings are generated, if at all, can be controlled
2665 by the group-order and tag-order styles, as usual.
2666 The format string for all-expansions and for expansions may con‐
2668 tain the sequence `%o' which will be replaced by the original
2669 string from the line.
2670 The kind of expansion to be tried is controlled by the substi‐
2672 tute, glob and subst-globs-only styles.
2673 It is also possible to call _expand as a function, in which case
2675 the different modes may be selected with options: -s for substi‐
2676 tute, -g for glob and -o for subst-globs-only.
2677 _expand_alias
2679 If the word the cursor is on is an alias, it is expanded and no
2680 other completers are called. The types of aliases which are to
2681 be expanded can be controlled with the styles regular, global
2682 and disabled.
2683 This function is also a bindable command, see the section `Bind‐
2685 able Commands' below.
2686 _history
2688 Complete words from the shell's command history. This com‐
2689 pleter can be controlled by the remove-all-dups, and sort styles
2690 as for the _history_complete_word bindable command, see the sec‐
2691 tion `Bindable Commands' below and the section `Completion Sys‐
2692 tem Configuration' above.
2693 _ignored
2695 The ignored-patterns style can be set to a list of patterns
2696 which are compared against possible completions; matching ones
2697 are removed. With this completer those matches can be rein‐
2698 stated, as if no ignored-patterns style were set. The completer
2699 actually generates its own list of matches; which completers are
2700 invoked is determined in the same way as for the _prefix com‐
2701 pleter. The single-ignored style is also available as described
2702 above.
2703 _list This completer allows the insertion of matches to be delayed
2705 until completion is attempted a second time without the word on
2706 the line being changed. On the first attempt, only the list of
2707 matches will be shown. It is affected by the styles condition
2708 and word, see the section `Completion System Configuration'
2709 above.
2710 _match This completer is intended to be used after the _complete com‐
2712 pleter. It behaves similarly but the string on the command line
2713 may be a pattern to match against trial completions. This gives
2714 the effect of the GLOB_COMPLETE option.
2715 Normally completion will be performed by taking the pattern from
2717 the line, inserting a `*' at the cursor position and comparing
2718 the resulting pattern with the possible completions generated.
2719 This can be modified with the match-original style described
2720 above.
2721 The generated matches will be offered in a menu completion
2723 unless the insert-unambiguous style is set to `true'; see the
2724 description above for other options for this style.
2725 Note that matcher specifications defined globally or used by the
2727 completion functions (the styles matcher-list and matcher) will
2728 not be used.
2729 _menu This completer was written as simple example function to show
2731 how menu completion can be enabled in shell code. However, it
2732 has the notable effect of disabling menu selection which can be
2733 useful with _generic based widgets. It should be used as the
2734 first completer in the list. Note that this is independent of
2735 the setting of the MENU_COMPLETE option and does not work with
2736 the other menu completion widgets such as reverse-menu-complete,
2737 or accept-and-menu-complete.
2738 _oldlist
2740 This completer controls how the standard completion widgets
2741 behave when there is an existing list of completions which may
2742 have been generated by a special completion (i.e. a sepa‐
2743 rately-bound completion command). It allows the ordinary com‐
2744 pletion keys to continue to use the list of completions thus
2745 generated, instead of producing a new list of ordinary contex‐
2746 tual completions. It should appear in the list of completers
2747 before any of the widgets which generate matches. It uses two
2748 styles: old-list and old-menu, see the section `Completion Sys‐
2749 tem Configuration' above.
2750 _prefix
2752 This completer can be used to try completion with the suffix
2753 (everything after the cursor) ignored. In other words, the suf‐
2754 fix will not be considered to be part of the word to complete.
2755 The effect is similar to the expand-or-complete-prefix command.
2756 The completer style is used to decide which other completers are
2758 to be called to generate matches. If this style is unset, the
2759 list of completers set for the current context is used --
2760 except, of course, the _prefix completer itself. Furthermore,
2761 if this completer appears more than once in the list of com‐
2762 pleters only those completers not already tried by the last
2763 invocation of _prefix will be called.
2764 For example, consider this global completer style:
2766 zstyle ':completion:*' completer \
2768 _complete _prefix _correct _prefix:foo
2769 Here, the _prefix completer tries normal completion but ignoring
2771 the suffix. If that doesn't generate any matches, and neither
2772 does the call to the _correct completer after it, _prefix will
2773 be called a second time and, now only trying correction with the
2774 suffix ignored. On the second invocation the completer part of
2775 the context appears as `foo'.
2776 To use _prefix as the last resort and try only normal completion
2778 when it is invoked:
2779 zstyle ':completion:*' completer _complete ... _prefix
2781 zstyle ':completion::prefix:*' completer _complete
2782 The add-space style is also respected. If it is set to `true'
2784 then _prefix will insert a space between the matches generated
2785 (if any) and the suffix.
2786 Note that this completer is only useful if the COMPLETE_IN_WORD
2788 option is set; otherwise, the cursor will be moved to the end of
2789 the current word before the completion code is called and hence
2790 there will be no suffix.
2791 _user_expand
2793 This completer behaves similarly to the _expand completer but
2794 instead performs expansions defined by users. The styles
2795 add-space and sort styles specific to the _expand completer are
2796 usable with _user_expand in addition to other styles handled
2797 more generally by the completion system. The tag all-expansions
2798 is also available.
2799 The expansion depends on the array style user-expand being
2801 defined for the current context; remember that the context for
2802 completers is less specific than that for contextual completion
2803 as the full context has not yet been determined. Elements of
2804 the array may have one of the following forms:
2805 $hash
2806 hash is the name of an associative array. Note this is
2808 not a full parameter expression, merely a $, suitably
2809 quoted to prevent immediate expansion, followed by the
2810 name of an associative array. If the trial expansion
2811 word matches a key in hash, the resulting expansion is
2812 the corresponding value.
2813 _func
2814 _func is the name of a shell function whose name must
2816 begin with _ but is not otherwise special to the comple‐
2817 tion system. The function is called with the trial word
2818 as an argument. If the word is to be expanded, the func‐
2819 tion should set the array reply to a list of expansions.
2820 The return status of the function is irrelevant.
2822 In addition to the context-dependent completions provided, which are
2823 expected to work in an intuitively obvious way, there are a few widgets
2824 implementing special behaviour which can be bound separately to keys.
2825 The following is a list of these and their default bindings.
2826 _bash_completions
2828 This function is used by two widgets, _bash_complete-word and
2829 _bash_list-choices. It exists to provide compatibility with
2830 completion bindings in bash. The last character of the binding
2831 determines what is completed: `!', command names; `$', environ‐
2832 ment variables; `@', host names; `/', file names; `~' user
2833 names. In bash, the binding preceded by `\e' gives completion,
2834 and preceded by `^X' lists options. As some of these bindings
2835 clash with standard zsh bindings, only `\e~' and `^X~' are bound
2836 by default. To add the rest, the following should be added to
2837 .zshrc after compinit has been run:
2838 for key in '!' '$' '@' '/' '~'; do
2840 bindkey "\e$key" _bash_complete-word
2841 bindkey "^X$key" _bash_list-choices
2842 done
2843 This includes the bindings for `~' in case they were already
2845 bound to something else; the completion code does not override
2846 user bindings.
2847 _correct_filename (^XC)
2849 Correct the filename path at the cursor position. Allows up to
2850 six errors in the name. Can also be called with an argument to
2851 correct a filename path, independently of zle; the correction is
2852 printed on standard output.
2853 _correct_word (^Xc)
2855 Performs correction of the current argument using the usual con‐
2856 textual completions as possible choices. This stores the string
2857 `correct-word' in the function field of the context name and
2858 then calls the _correct completer.
2859 _expand_alias (^Xa)
2861 This function can be used as a completer and as a bindable com‐
2862 mand. It expands the word the cursor is on if it is an alias.
2863 The types of alias expanded can be controlled with the styles
2864 regular, global and disabled.
2865 When used as a bindable command there is one additional feature
2867 that can be selected by setting the complete style to `true'.
2868 In this case, if the word is not the name of an alias,
2869 _expand_alias tries to complete the word to a full alias name
2870 without expanding it. It leaves the cursor directly after the
2871 completed word so that invoking _expand_alias once more will
2872 expand the now-complete alias name.
2873 _expand_word (^Xe)
2875 Performs expansion on the current word: equivalent to the stan‐
2876 dard expand-word command, but using the _expand completer.
2877 Before calling it, the function field of the context is set to
2878 `expand-word'.
2879 _generic
2881 This function is not defined as a widget and not bound by
2882 default. However, it can be used to define a widget and will
2883 then store the name of the widget in the function field of the
2884 context and call the completion system. This allows custom com‐
2885 pletion widgets with their own set of style settings to be
2886 defined easily. For example, to define a widget that performs
2887 normal completion and starts menu selection:
2888 zle -C foo complete-word _generic
2890 bindkey '...' foo
2891 zstyle ':completion:foo:*' menu yes select=1
2892 Note in particular that the completer style may be set for the
2894 context in order to change the set of functions used to generate
2895 possible matches. If _generic is called with arguments, those
2896 are passed through to _main_complete as the list of completers
2897 in place of those defined by the completer style.
2898 _history_complete_word (\e/)
2900 Complete words from the shell's command history. This uses the
2901 list, remove-all-dups, sort, and stop styles.
2902 _most_recent_file (^Xm)
2904 Complete the name of the most recently modified file matching
2905 the pattern on the command line (which may be blank). If given
2906 a numeric argument N, complete the Nth most recently modified
2907 file. Note the completion, if any, is always unique.
2908 _next_tags (^Xn)
2910 This command alters the set of matches used to that for the next
2911 tag, or set of tags, either as given by the tag-order style or
2912 as set by default; these matches would otherwise not be avail‐
2913 able. Successive invocations of the command cycle through all
2914 possible sets of tags.
2915 _read_comp (^X^R)
2917 Prompt the user for a string, and use that to perform completion
2918 on the current word. There are two possibilities for the
2919 string. First, it can be a set of words beginning `_', for
2920 example `_files -/', in which case the function with any argu‐
2921 ments will be called to generate the completions. Unambiguous
2922 parts of the function name will be completed automatically (nor‐
2923 mal completion is not available at this point) until a space is
2924 typed.
2925 Second, any other string will be passed as a set of arguments to
2927 compadd and should hence be an expression specifying what should
2928 be completed.
2929 A very restricted set of editing commands is available when
2931 reading the string: `DEL' and `^H' delete the last character;
2932 `^U' deletes the line, and `^C' and `^G' abort the function,
2933 while `RET' accepts the completion. Note the string is used
2934 verbatim as a command line, so arguments must be quoted in
2935 accordance with standard shell rules.
2936 Once a string has been read, the next call to _read_comp will
2938 use the existing string instead of reading a new one. To force
2939 a new string to be read, call _read_comp with a numeric argu‐
2940 ment.
2941 _complete_debug (^X?)
2943 This widget performs ordinary completion, but captures in a tem‐
2944 porary file a trace of the shell commands executed by the com‐
2945 pletion system. Each completion attempt gets its own file. A
2946 command to view each of these files is pushed onto the editor
2947 buffer stack.
2948 _complete_help (^Xh)
2950 This widget displays information about the context names, the
2951 tags, and the completion functions used when completing at the
2952 current cursor position. If given a numeric argument other than
2953 1 (as in `ESC-2 ^Xh'), then the styles used and the contexts for
2954 which they are used will be shown, too.
2955 Note that the information about styles may be incomplete; it
2957 depends on the information available from the completion func‐
2958 tions called, which in turn is determined by the user's own
2959 styles and other settings.
2960 _complete_help_generic
2962 Unlike other commands listed here, this must be created as a
2963 normal ZLE widget rather than a completion widget (i.e. with zle
2964 -N). It is used for generating help with a widget bound to the
2965 _generic widget that is described above.
2966 If this widget is created using the name of the function, as it
2968 is by default, then when executed it will read a key sequence.
2969 This is expected to be bound to a call to a completion function
2970 that uses the _generic widget. That widget will be executed,
2971 and information provided in the same format that the _com‐
2972 plete_help widget displays for contextual completion.
2973 If the widget's name contains debug, for example if it is cre‐
2975 ated as `zle -N _complete_debug_generic _complete_help_generic',
2976 it will read and execute the keystring for a generic widget as
2977 before, but then generate debugging information as done by _com‐
2978 plete_debug for contextual completion.
2979 If the widget's name contains noread, it will not read a
2981 keystring but instead arrange that the next use of a generic
2982 widget run in the same shell will have the effect as described
2983 above.
2984 The widget works by setting the shell parameter
2986 ZSH_TRACE_GENERIC_WIDGET which is read by _generic. Unsetting
2987 the parameter cancels any pending effect of the noread form.
2988 For example, after executing the following:
2990 zle -N _complete_debug_generic _complete_help_generic
2992 bindkey '^x:' _complete_debug_generic
2993 typing `C-x :' followed by the key sequence for a generic widget
2995 will cause trace output for that widget to be saved to a file.
2996 _complete_tag (^Xt)
2998 This widget completes symbol tags created by the etags or ctags
2999 programmes (note there is no connection with the completion sys‐
3000 tem's tags) stored in a file TAGS, in the format used by etags,
3001 or tags, in the format created by ctags. It will look back up
3002 the path hierarchy for the first occurrence of either file; if
3003 both exist, the file TAGS is preferred. You can specify the
3004 full path to a TAGS or tags file by setting the parameter $TAGS‐
3005 FILE or $tagsfile respectively. The corresponding completion
3006 tags used are etags and vtags, after emacs and vi respectively.
3007
3009 Descriptions follow for utility functions that may be useful when writ‐
3010 ing completion functions. If functions are installed in subdirecto‐
3011 ries, most of these reside in the Base subdirectory. Like the example
3012 functions for commands in the distribution, the utility functions gen‐
3013 erating matches all follow the convention of returning status zero if
3014 they generated completions and non-zero if no matching completions
3015 could be added.
3016 Two more features are offered by the _main_complete function. The
3018 arrays compprefuncs and comppostfuncs may contain names of functions
3019 that are to be called immediately before or after completion has been
3020 tried. A function will only be called once unless it explicitly rein‐
3021 serts itself into the array.
3022 _all_labels [ -x ] [ -12VJ ] tag name descr [ command args ... ]
3024 This is a convenient interface to the _next_label function
3025 below, implementing the loop shown in the _next_label example.
3026 The command and its arguments are called to generate the
3027 matches. The options stored in the parameter name will automat‐
3028 ically be inserted into the args passed to the command. Nor‐
3029 mally, they are put directly after the command, but if one of
3030 the args is a single hyphen, they are inserted directly before
3031 that. If the hyphen is the last argument, it will be removed
3032 from the argument list before the command is called. This
3033 allows _all_labels to be used in almost all cases where the
3034 matches can be generated by a single call to the compadd builtin
3035 command or by a call to one of the utility functions.
3036 For example:
3038 local expl
3040 ...
3041 if _requested foo; then
3042 ...
3043 _all_labels foo expl '...' compadd ... - $matches
3044 fi
3045 Will complete the strings from the matches parameter, using com‐
3047 padd with additional options which will take precedence over
3048 those generated by _all_labels.
3049 _alternative [ -C name ] spec ...
3051 This function is useful in simple cases where multiple tags are
3052 available. Essentially it implements a loop like the one
3053 described for the _tags function below.
3054 The tags to use and the action to perform if a tag is requested
3056 are described using the specs which are of the form:
3057 `tag:descr:action'. The tags are offered using _tags and if the
3058 tag is requested, the action is executed with the given descrip‐
3059 tion descr. The actions are those accepted by the _arguments
3060 function (described below), excluding the `->state' and `=...'
3061 forms.
3062 For example, the action may be a simple function call:
3064 _alternative \
3066 'users:user:_users' \
3067 'hosts:host:_hosts'
3068 offers usernames and hostnames as possible matches, generated by
3070 the _users and _hosts functions respectively.
3071 Like _arguments, this function uses _all_labels to execute the
3073 actions, which will loop over all sets of tags. Special han‐
3074 dling is only required if there is an additional valid tag, for
3075 example inside a function called from _alternative.
3076 Like _tags this function supports the -C option to give a dif‐
3078 ferent name for the argument context field.
3079 _arguments [ -nswWACRS ] [ -O name ] [ -M matchspec ] [ : ] spec ...
3081 This function can be used to give a complete specification for
3082 completion for a command whose arguments follow standard UNIX
3083 option and argument conventions. The following forms specify
3084 individual sets of options and arguments; to avoid ambiguity,
3085 these may be separated from the options to _arguments itself by
3086 a single colon. Options to _arguments itself must be in sepa‐
3087 rate words, i.e. -s -w, not -sw.
3088 With the option -n, _arguments sets the parameter NORMARG to the
3090 position of the first normal argument in the $words array, i.e.
3091 the position after the end of the options. If that argument has
3092 not been reached, NORMARG is set to -1. The caller should
3093 declare `integer NORMARG' if the -n option is passed; otherwise
3094 the parameter is not used.
3095 n:message:action
3097 n::message:action
3098 This describes the n'th normal argument. The message
3099 will be printed above the matches generated and the
3100 action indicates what can be completed in this position
3101 (see below). If there are two colons before the message
3102 the argument is optional. If the message contains only
3103 white space, nothing will be printed above the matches
3104 unless the action adds an explanation string itself.
3105 :message:action
3107 ::message:action
3108 Similar, but describes the next argument, whatever number
3109 that happens to be. If all arguments are specified in
3110 this form in the correct order the numbers are unneces‐
3111 sary.
3112 *:message:action
3114 *::message:action
3115 *:::message:action
3116 This describes how arguments (usually non-option argu‐
3117 ments, those not beginning with - or +) are to be com‐
3118 pleted when neither of the first two forms was provided.
3119 Any number of arguments can be completed in this fashion.
3120 With two colons before the message, the words special
3122 array and the CURRENT special parameter are modified to
3123 refer only to the normal arguments when the action is
3124 executed or evaluated. With three colons before the mes‐
3125 sage they are modified to refer only to the normal argu‐
3126 ments covered by this description.
3127 optspec
3129 optspec:...
3130 This describes an option. The colon indicates handling
3131 for one or more arguments to the option; if it is not
3132 present, the option is assumed to take no arguments.
3133 By default, options are multi-character name, one `-word'
3135 per option. With -s, options may be single characters,
3136 with more than one option per word, although words start‐
3137 ing with two hyphens, such as `--prefix', are still con‐
3138 sidered complete option names. This is suitable for
3139 standard GNU options.
3140 The combination of -s with -w allows single-letter
3142 options to be combined in a single word even if one or
3143 more of the options take arguments. For example, if -a
3144 takes an argument, with no -s `-ab' is considered as a
3145 single (unhandled) option; with -s -ab is an option with
3146 the argument `b'; with both -s and -w, -ab may be the
3147 option -a and the option -b with arguments still to come.
3148 The option -W takes this a stage further: it is possible
3150 to complete single-letter options even after an argument
3151 that occurs in the same word. However, it depends on the
3152 action performed whether options will really be completed
3153 at this point. For more control, use a utility function
3154 like _guard as part of the action.
3155 The following forms are available for the initial opt‐
3157 spec, whether or not the option has arguments.
3158 *optspec
3160 Here optspec is one of the remaining forms below.
3161 This indicates the following optspec may be
3162 repeated. Otherwise if the corresponding option
3163 is already present on the command line to the left
3164 of the cursor it will not be offered again.
3165 -optname
3167 +optname
3168 In the simplest form the optspec is just the
3169 option name beginning with a minus or a plus sign,
3170 such as `-foo'. The first argument for the option
3171 (if any) must follow as a separate word directly
3172 after the option.
3173 Either of `-+optname' and `+-optname' can be used
3175 to specify that -optname and +optname are both
3176 valid.
3177 In all the remaining forms, the leading `-' may be
3179 replaced by or paired with `+' in this way.
3180 -optname-
3182 The first argument of the option must come
3183 directly after the option name in the same word.
3184 For example, `-foo-:...' specifies that the com‐
3185 pleted option and argument will look like
3186 `-fooarg'.
3187 -optname+
3189 The first argument may appear immediately after
3190 optname in the same word, or may appear as a sepa‐
3191 rate word after the option. For example,
3192 `-foo+:...' specifies that the completed option
3193 and argument will look like either `-fooarg' or
3194 `-foo arg'.
3195 -optname=
3197 The argument may appear as the next word, or in
3198 same word as the option name provided that it is
3199 separated from it by an equals sign, for example
3200 `-foo=arg' or `-foo arg'.
3201 -optname=-
3203 The argument to the option must appear after an
3204 equals sign in the same word, and may not be given
3205 in the next argument.
3206 optspec[explanation]
3208 An explanation string may be appended to any of
3209 the preceding forms of optspec by enclosing it in
3210 brackets, as in `-q[query operation]'.
3211 The verbose style is used to decide whether the
3213 explanation strings are displayed with the option
3214 in a completion listing.
3215 If no bracketed explanation string is given but
3217 the auto-description style is set and only one
3218 argument is described for this optspec, the value
3219 of the style is displayed, with any appearance of
3220 the sequence `%d' in it replaced by the message of
3221 the first optarg that follows the optspec; see
3222 below.
3223 It is possible for options with a literal `+' or `=' to appear,
3225 but that character must be quoted, for example `-\+'.
3226 Each optarg following an optspec must take one of the following
3228 forms:
3229 :message:action
3231 ::message:action
3232 An argument to the option; message and action are treated
3233 as for ordinary arguments. In the first form, the argu‐
3234 ment is mandatory, and in the second form it is optional.
3235 This group may be repeated for options which take multi‐
3237 ple arguments. In other words, :message1:action1:mes‐
3238 sage2:action2 specifies that the option takes two argu‐
3239 ments.
3240 :*pattern:message:action
3242 :*pattern::message:action
3243 :*pattern:::message:action
3244 This describes multiple arguments. Only the last optarg
3245 for an option taking multiple arguments may be given in
3246 this form. If the pattern is empty (i.e., :*:), all the
3247 remaining words on the line are to be completed as
3248 described by the action; otherwise, all the words up to
3249 and including a word matching the pattern are to be com‐
3250 pleted using the action.
3251 Multiple colons are treated as for the `*:...' forms for
3253 ordinary arguments: when the message is preceded by two
3254 colons, the words special array and the CURRENT special
3255 parameter are modified during the execution or evaluation
3256 of the action to refer only to the words after the
3257 option. When preceded by three colons, they are modified
3258 to refer only to the words covered by this description.
3259 Any literal colon in an optname, message, or action must be preceded by
3261 a backslash, `\:'.
3262 Each of the forms above may be preceded by a list in parentheses of
3264 option names and argument numbers. If the given option is on the com‐
3265 mand line, the options and arguments indicated in parentheses will not
3266 be offered. For example, `(-two -three 1)-one:...' completes the
3267 option `-one'; if this appears on the command line, the options -two
3268 and -three and the first ordinary argument will not be completed after
3269 it. `(-foo):...' specifies an ordinary argument completion; -foo will
3270 not be completed if that argument is already present.
3271 Other items may appear in the list of excluded options to indicate var‐
3273 ious other items that should not be applied when the current specifica‐
3274 tion is matched: a single star (*) for the rest arguments (i.e. a spec‐
3275 ification of the form `*:...'); a colon (:) for all normal
3276 (non-option-) arguments; and a hyphen (-) for all options. For exam‐
3277 ple, if `(*)' appears before an option and the option appears on the
3278 command line, the list of remaining arguments (those shown in the above
3279 table beginning with `*:') will not be completed.
3280 To aid in reuse of specifications, it is possible to precede any of the
3282 forms above with `!'; then the form will no longer be completed,
3283 although if the option or argument appears on the command line they
3284 will be skipped as normal. The main use for this is when the arguments
3285 are given by an array, and _arguments is called repeatedly for more
3286 specific contexts: on the first call `_arguments $global_options' is
3287 used, and on subsequent calls `_arguments !$^global_options'.
3288 In each of the forms above the action determines how completions should
3290 be generated. Except for the `->string' form below, the action will be
3291 executed by calling the _all_labels function to process all tag labels.
3292 No special handling of tags is needed unless a function call introduces
3293 a new one.
3294 The forms for action are as follows.
3296 (single unquoted space)
3298 This is useful where an argument is required but it is not pos‐
3299 sible or desirable to generate matches for it. The message will
3300 be displayed but no completions listed. Note that even in this
3301 case the colon at the end of the message is needed; it may only
3302 be omitted when neither a message nor an action is given.
3303 (item1 item2 ...)
3305 One of a list of possible matches, for example:
3306 :foo:(foo bar baz)
3308 ((item1\:desc1 ...))
3310 Similar to the above, but with descriptions for each possible
3311 match. Note the backslash before the colon. For example,
3312 :foo:((a\:bar b\:baz))
3314 The matches will be listed together with their descriptions if
3316 the description style is set with the values tag in the context.
3317 ->string
3319 In this form, _arguments processes the arguments and options and
3320 then returns control to the calling function with parameters set
3321 to indicate the state of processing; the calling function then
3322 makes its own arrangements for generating completions. For
3323 example, functions that implement a state machine can use this
3324 type of action.
3325 Where _arguments encounters a `->string', it will strip all
3327 leading and trailing whitespace from string and set the array
3328 state to the set of all stringss for which an action is to be
3329 performed.
3330 By default and in common with all other well behaved completion
3332 functions, _arguments returns status zero if it was able to add
3333 matches and non-zero otherwise. However, if the -R option is
3334 given, _arguments will instead return a status of 300 to indi‐
3335 cate that $state is to be handled.
3336 In addition to $state, _arguments also sets the global parame‐
3338 ters `context', `line' and `opt_args' as described below, and
3339 does not reset any changes made to the special parameters such
3340 as PREFIX and words. This gives the calling function the choice
3341 of resetting these parameters or propagating changes in them.
3342 A function calling _arguments with at least one action contain‐
3344 ing a `->string' must therefore declare appropriate local param‐
3345 eters:
3346 local context state line
3348 typeset -A opt_args
3349 to prevent _arguments from altering the global environment.
3351 {eval-string}
3353 A string in braces is evaluated as shell code to generate
3354 matches. If the eval-string itself does not begin with an open‐
3355 ing parenthesis or brace it is split into separate words before
3356 execution.
3357 = action
3359 If the action starts with `= ' (an equals sign followed by a
3360 space), _arguments will insert the contents of the argument
3361 field of the current context as the new first element in the
3362 words special array and increment the value of the CURRENT spe‐
3363 cial parameter. This has the effect of inserting a dummy word
3364 onto the completion command line while not changing the point at
3365 which completion is taking place.
3366 This is most useful with one of the specifiers that restrict the
3368 words on the command line on which the action is to operate (the
3369 two- and three-colon forms above). One particular use is when
3370 an action itself causes _arguments on a restricted range; it is
3371 necessary to use this trick to insert an appropriate command
3372 name into the range for the second call to _arguments to be able
3373 to parse the line.
3374 word...
3376 word...
3377 This covers all forms other than those above. If the action
3378 starts with a space, the remaining list of words will be invoked
3379 unchanged.
3380 Otherwise it will be invoked with some extra strings placed
3382 after the first word; these are to be passed down as options to
3383 the compadd builtin. They ensure that the state specified by
3384 _arguments, in particular the descriptions of options and argu‐
3385 ments, is correctly passed to the completion command. These
3386 additional arguments are taken from the array parameter `expl';
3387 this will be set up before executing the action and hence may be
3388 referred to inside it, typically in an expansion of the form
3389 `$expl[@]' which preserves empty elements of the array.
3390 During the performance of the action the array `line' will be set to
3392 the command name and normal arguments from the command line, i.e. the
3393 words from the command line excluding all options and their arguments.
3394 Options are stored in the associative array `opt_args' with option
3395 names as keys and their arguments as the values. For options that have
3396 more than one argument these are given as one string, separated by
3397 colons. All colons in the original arguments are preceded with back‐
3398 slashes.
3399 The parameter `context' is set when returning to the calling function
3401 to perform an action of the form `->string'. It is set to an array of
3402 elements corresponding to the elements of $state. Each element is a
3403 suitable name for the argument field of the context: either a string of
3404 the form `option-opt-n' for the n'th argument of the option -opt, or a
3405 string of the form `argument-n' for the n'th argument. For `rest'
3406 arguments, that is those in the list at the end not handled by posi‐
3407 tion, n is the string `rest'. For example, when completing the argu‐
3408 ment of the -o option, the name is `option-o-1', while for the second
3409 normal (non-option-) argument it is `argument-2'.
3410 Furthermore, during the evaluation of the action the context name in
3412 the curcontext parameter is altered to append the same string that is
3413 stored in the context parameter.
3414 It is possible to specify multiple sets of options and arguments with
3416 the sets separated by single hyphens. The specifications before the
3417 first hyphen (if any) are shared by all the remaining sets. The first
3418 word in every other set provides a name for the set which may appear in
3419 exclusion lists in specifications, either alone or before one of the
3420 possible values described above. In the second case a `-' should
3421 appear between this name and the remainder.
3422 For example:
3424 _arguments \
3426 -a \
3427 - set1 \
3428 -c \
3429 - set2 \
3430 -d \
3431 ':arg:(x2 y2)'
3432 This defines two sets. When the command line contains the option `-c',
3434 the `-d' option and the argument will not be considered possible com‐
3435 pletions. When it contains `-d' or an argument, the option `-c' will
3436 not be considered. However, after `-a' both sets will still be consid‐
3437 ered valid.
3438 If the name given for one of the mutually exclusive sets is of the form
3440 `(name)' then only one value from each set will ever be completed; more
3441 formally, all specifications are mutually exclusive to all other speci‐
3442 fications in the same set. This is useful for defining multiple sets
3443 of options which are mutually exclusive and in which the options are
3444 aliases for each other. For example:
3445 _arguments \
3447 -a -b \
3448 - '(compress)' \
3449 {-c,--compress}'[compress]' \
3450 - '(uncompress)' \
3451 {-d,--decompress}'[decompress]'
3452 As the completion code has to parse the command line separately for
3454 each set this form of argument is slow and should only be used when
3455 necessary. A useful alternative is often an option specification with
3456 rest-arguments (as in `-foo:*:...'); here the option -foo swallows up
3457 all remaining arguments as described by the optarg definitions.
3458 The options -S and -A are available to simplify the specifications for
3460 commands with standard option parsing. With -S, no option will be com‐
3461 pleted after a `--' appearing on its own on the line; this argument
3462 will otherwise be ignored; hence in the line
3463 foobar -a -- -b
3465 the `-a' is considered an option but the `-b' is considered an argu‐
3467 ment, while the `--' is considered to be neither.
3468 With -A, no options will be completed after the first non-option argu‐
3470 ment on the line. The -A must be followed by a pattern matching all
3471 strings which are not to be taken as arguments. For example, to make
3472 _arguments stop completing options after the first normal argument, but
3473 ignoring all strings starting with a hyphen even if they are not
3474 described by one of the optspecs, the form is `-A "-*"'.
3475 The option `-O name' specifies the name of an array whose elements will
3477 be passed as arguments to functions called to execute actions. For
3478 example, this can be used to pass the same set of options for the com‐
3479 padd builtin to all actions.
3480 The option `-M spec' sets a match specification to use to completion
3482 option names and values. It must appear before the first argument
3483 specification. The default is `r:|[_-]=* r:|=*': this allows partial
3484 word completion after `_' and `-', for example `-f-b' can be completed
3485 to `-foo-bar'.
3486 The option -C tells _arguments to modify the curcontext parameter for
3488 an action of the form `->state'. This is the standard parameter used
3489 to keep track of the current context. Here it (and not the context
3490 array) should be made local to the calling function to avoid passing
3491 back the modified value and should be initialised to the current value
3492 at the start of the function:
3493 local curcontext="$curcontext"
3495 This is useful where it is not possible for multiple states to be valid
3497 together.
3498 The option `--' allows _arguments to work out the names of long options
3500 that support the `--help' option which is standard in many GNU com‐
3501 mands. The command word is called with the argument `--help' and the
3502 output examined for option names. Clearly, it can be dangerous to pass
3503 this to commands which may not support this option as the behaviour of
3504 the command is unspecified.
3505 In addition to options, `_arguments --' will try to deduce the types of
3507 arguments available for options when the form `--opt=val' is valid. It
3508 is also possible to provide hints by examining the help text of the
3509 command and adding specifiers of the form `pattern:message:action';
3510 note that normal _arguments specifiers are not used. The pattern is
3511 matched against the help text for an option, and if it matches the mes‐
3512 sage and action are used as for other argument specifiers. For exam‐
3513 ple:
3514 _arguments -- '*\*:toggle:(yes no)' \
3516 '*=FILE*:file:_files' \
3517 '*=DIR*:directory:_files -/' \
3518 '*=PATH*:directory:_files -/'
3519 Here, `yes' and `no' will be completed as the argument of options whose
3521 description ends in a star; file names will be completed for options
3522 that contain the substring `=FILE' in the description; and directories
3523 will be completed for options whose description contains `=DIR' or
3524 `=PATH'. The last three are in fact the default and so need not be
3525 given explicitly, although it is possible to override the use of these
3526 patterns. A typical help text which uses this feature is:
3527 -C, --directory=DIR change to directory DIR
3529 so that the above specifications will cause directories to be completed
3531 after `--directory', though not after `-C'.
3532 Note also that _arguments tries to find out automatically if the argu‐
3534 ment for an option is optional. This can be specified explicitly by
3535 doubling the colon before the message.
3536 If the pattern ends in `(-)', this will be removed from the pattern and
3538 the action will be used only directly after the `=', not in the next
3539 word. This is the behaviour of a normal specification defined with the
3540 form `=-'.
3541 The `_arguments --' can be followed by the option `-i patterns' to give
3543 patterns for options which are not to be completed. The patterns can
3544 be given as the name of an array parameter or as a literal list in
3545 parentheses. For example,
3546 _arguments -- -i \
3548 "(--(en|dis)able-FEATURE*)"
3549 will cause completion to ignore the options `--enable-FEATURE' and
3551 `--disable-FEATURE' (this example is useful with GNU configure).
3552 The `_arguments --' form can also be followed by the option `-s pair'
3554 to describe option aliases. Each pair consists of a pattern and a
3555 replacement. For example, some configure-scripts describe options only
3556 as `--enable-foo', but also accept `--disable-foo'. To allow comple‐
3557 tion of the second form:
3558 _arguments -- -s "(#--enable- --disable-)"
3560 Here is a more general example of the use of _arguments:
3562 _arguments '-l+:left border:' \
3564 '-format:paper size:(letter A4)' \
3565 '*-copy:output file:_files::resolution:(300 600)' \
3566 ':postscript file:_files -g \*.\(ps\|eps\)' \
3567 '*:page number:'
3568 This describes three options: `-l', `-format', and `-copy'. The first
3570 takes one argument described as `left border' for which no completion
3571 will be offered because of the empty action. Its argument may come
3572 directly after the `-l' or it may be given as the next word on the
3573 line.
3574 The `-format' option takes one argument in the next word, described as
3576 `paper size' for which only the strings `letter' and `A4' will be com‐
3577 pleted.
3578 The `-copy' option may appear more than once on the command line and
3580 takes two arguments. The first is mandatory and will be completed as a
3581 filename. The second is optional (because of the second colon before
3582 the description `resolution') and will be completed from the strings
3583 `300' and `600'.
3584 The last two descriptions say what should be completed as arguments.
3586 The first describes the first argument as a `postscript file' and makes
3587 files ending in `ps' or `eps' be completed. The last description gives
3588 all other arguments the description `page numbers' but does not offer
3589 completions.
3590 _cache_invalid cache_identifier
3592 This function returns status zero if the completions cache cor‐
3593 responding to the given cache identifier needs rebuilding. It
3594 determines this by looking up the cache-policy style for the
3595 current context. This should provide a function name which is
3596 run with the full path to the relevant cache file as the only
3597 argument.
3598 Example:
3600 _example_caching_policy () {
3602 # rebuild if cache is more than a week old
3603 local -a oldp
3604 oldp=( "$1"(Nmw+1) )
3605 (( $#oldp ))
3606 }
3607 _call_function return name [ args ... ]
3609 If a function name exists, it is called with the arguments args.
3610 The return argument gives the name of a parameter in which the
3611 return status from the function name should be stored; if return
3612 is empty or a single hyphen it is ignored.
3613 The return status of _call_function itself is zero if the func‐
3615 tion name exists and was called and non-zero otherwise.
3616 _call_program tag string ...
3618 This function provides a mechanism for the user to override the
3619 use of an external command. It looks up the command style with
3620 the supplied tag. If the style is set, its value is used as the
3621 command to execute. The strings from the call to _call_program,
3622 or from the style if set, are concatenated with spaces between
3623 them and the resulting string is evaluated. The return status
3624 is the return status of the command called.
3625 _combination [ -s pattern ] tag style spec ... field opts ...
3627 This function is used to complete combinations of values, for
3628 example pairs of hostnames and usernames. The style argument
3629 gives the style which defines the pairs; it is looked up in a
3630 context with the tag specified.
3631 The style name consists of field names separated by hyphens, for
3633 example `users-hosts-ports'. For each field for a value is
3634 already known, a spec of the form `field=pattern' is given. For
3635 example, if the command line so far specifies a user `pws', the
3636 argument `users=pws' should appear.
3637 The next argument with no equals sign is taken as the name of
3639 the field for which completions should be generated (presumably
3640 not one of the fields for which the value is known).
3641 The matches generated will be taken from the value of the style.
3643 These should contain the possible values for the combinations in
3644 the appropriate order (users, hosts, ports in the example
3645 above). The different fields the values for the different
3646 fields are separated by colons. This can be altered with the
3647 option -s to _combination which specifies a pattern. Typically
3648 this is a character class, as for example `-s "[:@]"' in the
3649 case of the users-hosts style. Each `field=pattern' specifi‐
3650 cation restricts the completions which apply to elements of the
3651 style with appropriately matching fields.
3652 If no style with the given name is defined for the given tag, or
3654 if none of the strings in style's value match, but a function
3655 name of the required field preceded by an underscore is defined,
3656 that function will be called to generate the matches. For exam‐
3657 ple, if there is no `users-hosts-ports' or no matching hostname
3658 when a host is required, the function `_hosts' will automati‐
3659 cally be called.
3660 If the same name is used for more than one field, in both the
3662 `field=pattern' and the argument that gives the name of the
3663 field to be completed, the number of the field (starting with
3664 one) may be given after the fieldname, separated from it by a
3665 colon.
3666 All arguments after the required field name are passed to com‐
3668 padd when generating matches from the style value, or to the
3669 functions for the fields if they are called.
3670 _describe [ -oO | -t tag ] descr name1 [ name2 ] opts ... -- ...
3672 This function associates completions with descriptions. Multi‐
3673 ple groups separated by -- can be supplied, potentially with
3674 different completion options opts.
3675 The descr is taken as a string to display above the matches if
3677 the format style for the descriptions tag is set. This is fol‐
3678 lowed by one or two names of arrays followed by options to pass
3679 to compadd. The first array contains the possible completions
3680 with their descriptions in the form `completion:description'.
3681 Any literal colons in completion must be quoted with a back‐
3682 slash. If a second array is given, it should have the same num‐
3683 ber of elements as the first; in this case the corresponding
3684 elements are added as possible completions instead of the com‐
3685 pletion strings from the first array. The completion list will
3686 retain the descriptions from the first array. Finally, a set of
3687 completion options can appear.
3688 If the option `-o' appears before the first argument, the
3690 matches added will be treated as names of command options (N.B.
3691 not shell options), typically following a `-', `--' or `+' on
3692 the command line. In this case _describe uses the prefix-hid‐
3693 den, prefix-needed and verbose styles to find out if the strings
3694 should be added as completions and if the descriptions should be
3695 shown. Without the `-o' option, only the verbose style is used
3696 to decide how descriptions are shown. If `-O' is used instead
3697 of `-o', command options are completed as above but _describe
3698 will not handle the prefix-needed style.
3699 With the -t option a tag can be specified. The default is `val‐
3701 ues' or, if the -o option is given, `options'.
3702 If selected by the list-grouped style, strings with the same
3704 description will appear together in the list.
3705 _describe uses the _all_labels function to generate the matches,
3707 so it does not need to appear inside a loop over tag labels.
3708 _description [ -x ] [ -12VJ ] tag name descr [ spec ... ]
3710 This function is not to be confused with the previous one; it is
3711 used as a helper function for creating options to compadd. It
3712 is buried inside many of the higher level completion functions
3713 and so often does not need to be called directly.
3714 The styles listed below are tested in the current context using
3716 the given tag. The resulting options for compadd are put into
3717 the array named name (this is traditionally `expl', but this
3718 convention is not enforced). The description for the corre‐
3719 sponding set of matches is passed to the function in descr.
3720 The styles tested are: format, hidden, matcher, ignored-patterns
3722 and group-name. The format style is first tested for the given
3723 tag and then for the descriptions tag if no value was found,
3724 while the remainder are only tested for the tag given as the
3725 first argument. The function also calls _setup which tests some
3726 more styles.
3727 The string returned by the format style (if any) will be modi‐
3729 fied so that the sequence `%d' is replaced by the descr given as
3730 the third argument without any leading or trailing white space.
3731 If, after removing the white space, the descr is the empty
3732 string, the format style will not be used and the options put
3733 into the name array will not contain an explanation string to be
3734 displayed above the matches.
3735 If _description is called with more than three arguments, the
3737 additional specs should be of the form `char:str'. These supply
3738 escape sequence replacements for the format style: every appear‐
3739 ance of `%char' will be replaced by string.
3740 If the -x option is given, the description will be passed to
3742 compadd using the -x option instead of the default -X. This
3743 means that the description will be displayed even if there are
3744 no corresponding matches.
3745 The options placed in the array name take account of the
3747 group-name style, so matches are placed in a separate group
3748 where necessary. The group normally has its elements sorted (by
3749 passing the option -J to compadd), but if an option starting
3750 with `-V', `-J', `-1', or `-2' is passed to _description, that
3751 option will be included in the array. Hence it is possible for
3752 the completion group to be unsorted by giving the option `-V',
3753 `-1V', or `-2V'.
3754 In most cases, the function will be used like this:
3756 local expl
3758 _description files expl file
3759 compadd "$expl[@]" - "$files[@]"
3760 Note the use of the parameter expl, the hyphen, and the list of
3762 matches. Almost all calls to compadd within the completion sys‐
3763 tem use a similar format; this ensures that user-specified
3764 styles are correctly passed down to the builtins which implement
3765 the internals of completion.
3766 _dispatch context string ...
3768 This sets the current context to context and looks for comple‐
3769 tion functions to handle this context by hunting through the
3770 list of command names or special contexts (as described above
3771 for compdef) given as string .... The first completion function
3772 to be defined for one of the contexts in the list is used to
3773 generate matches. Typically, the last string is -default- to
3774 cause the function for default completion to be used as a fall‐
3775 back.
3776 The function sets the parameter $service to the string being
3778 tried, and sets the context/command field (the fourth) of the
3779 $curcontext parameter to the context given as the first argu‐
3780 ment.
3781 _files The function _files calls _path_files with all the arguments it
3783 was passed except for -g and -/. The use of these two options
3784 depends on the setting of the file-patterns style.
3785 This function accepts the full set of options allowed by
3787 _path_files, described below.
3788 _gnu_generic
3790 This function is a simple wrapper around the _arguments function
3791 described above. It can be used to determine automatically the
3792 long options understood by commands that produce a list when
3793 passed the option `--help'. It is intended to be used as a
3794 top-level completion function in its own right. For example, to
3795 enable option completion for the commands foo and bar, use
3796 compdef _gnu_generic foo bar
3798 after the call to compinit.
3800 The completion system as supplied is conservative in its use of
3802 this function, since it is important to be sure the command
3803 understands the option `--help'.
3804 _guard [ options ] pattern descr
3806 This function is intended to be used in the action for the spec‐
3807 ifications passed to _arguments and similar functions. It
3808 returns immediately with a non-zero return status if the string
3809 to be completed does not match the pattern. If the pattern
3810 matches, the descr is displayed; the function then returns sta‐
3811 tus zero if the word to complete is not empty, non-zero other‐
3812 wise.
3813 The pattern may be preceded by any of the options understood by
3815 compadd that are passed down from _description, namely -M, -J,
3816 -V, -1, -2, -n, -F and -X. All of these options will be
3817 ignored. This fits in conveniently with the argument-passing
3818 conventions of actions for _arguments.
3819 As an example, consider a command taking the options -n and
3821 -none, where -n must be followed by a numeric value in the same
3822 word. By using:
3823 _arguments '-n-: :_guard "[0-9]#" "numeric value"' '-none'
3825 _arguments can be made to both display the message `numeric
3827 value' and complete options after `-n<TAB>'. If the `-n' is
3828 already followed by one or more digits (the pattern passed to
3829 _guard) only the message will be displayed; if the `-n' is fol‐
3830 lowed by another character, only options are completed.
3831 _message [ -r12 ] [ -VJ group ] descr
3833 _message -e [ tag ] descr
3834 The descr is used in the same way as the third argument to the
3835 _description function, except that the resulting string will
3836 always be shown whether or not matches were generated. This is
3837 useful for displaying a help message in places where no comple‐
3838 tions can be generated.
3839 The format style is examined with the messages tag to find a
3841 message; the usual tag, descriptions, is used only if the style
3842 is not set with the former.
3843 If the -r option is given, no style is used; the descr is taken
3845 literally as the string to display. This is most useful when
3846 the descr comes from a pre-processed argument list which already
3847 contains an expanded description.
3848 The -12VJ options and the group are passed to compadd and hence
3850 determine the group the message string is added to.
3851 The second form gives a description for completions with the tag
3853 tag to be shown even if there are no matches for that tag. The
3854 tag can be omitted and if so the tag is taken from the parameter
3855 $curtag; this is maintained by the completion system and so is
3856 usually correct.
3857 _multi_parts sep array
3859 The argument sep is a separator character. The array may be
3860 either the name of an array parameter or a literal array in the
3861 form `(foo bar)', a parenthesised list of words separated by
3862 whitespace. The possible completions are the strings from the
3863 array. However, each chunk delimited by sep will be completed
3864 separately. For example, the _tar function uses `_multi_parts /
3865 patharray' to complete partial file paths from the given array
3866 of complete file paths.
3867 The -i option causes _multi_parts to insert a unique match even
3869 if that requires multiple separators to be inserted. This is
3870 not usually the expected behaviour with filenames, but certain
3871 other types of completion, for example those with a fixed set of
3872 possibilities, may be more suited to this form.
3873 Like other utility functions, this function accepts the `-V',
3875 `-J', `-1', `-2', `-n', `-f', `-X', `-M', `-P', `-S', `-r',
3876 `-R', and `-q' options and passes them to the compadd builtin.
3877 _next_label [ -x ] [ -12VJ ] tag name descr [ options ... ]
3879 This function is used to implement the loop over different tag
3880 labels for a particular tag as described above for the tag-order
3881 style. On each call it checks to see if there are any more tag
3882 labels; if there is it returns status zero, otherwise non-zero.
3883 As this function requires a current tag to be set, it must
3884 always follow a call to _tags or _requested.
3885 The -x12VJ options and the first three arguments are passed to
3887 the _description function. Where appropriate the tag will be
3888 replaced by a tag label in this call. Any description given in
3889 the tag-order style is preferred to the descr passed to
3890 _next_label.
3891 The options given after the descr are set in the parameter given
3893 by name, and hence are to be passed to compadd or whatever func‐
3894 tion is called to add the matches.
3895 Here is a typical use of this function for the tag foo. The
3897 call to _requested determines if tag foo is required at all; the
3898 loop over _next_label handles any labels defined for the tag in
3899 the tag-order style.
3900 local expl ret=1
3902 ...
3903 if _requested foo; then
3904 ...
3905 while _next_label foo expl '...'; do
3906 compadd "$expl[@]" ... && ret=0
3907 done
3908 ...
3909 fi
3910 return ret
3911 _normal
3913 This is the standard function called to handle completion out‐
3914 side any special -context-. It is called both to complete the
3915 command word and also the arguments for a command. In the sec‐
3916 ond case, _normal looks for a special completion for that com‐
3917 mand, and if there is none it uses the completion for the
3918 -default- context.
3919 A second use is to reexamine the command line specified by the
3921 $words array and the $CURRENT parameter after those have been
3922 modified. For example, the function _precommand, which com‐
3923 pletes after pre-command specifiers such as nohup, removes the
3924 first word from the words array, decrements the CURRENT parame‐
3925 ter, then calls _normal again. The effect is that `nohup cmd
3926 ...' is treated in the same way as `cmd ...'.
3927 If the command name matches one of the patterns given by one of
3929 the options -p or -P to compdef, the corresponding completion
3930 function is called and then the parameter _compskip is checked.
3931 If it is set completion is terminated at that point even if no
3932 matches have been found. This is the same effect as in the
3933 -first- context.
3934 _options
3936 This can be used to complete the names of shell options. It
3937 provides a matcher specification that ignores a leading `no',
3938 ignores underscores and allows upper-case letters to match their
3939 lower-case counterparts (for example, `glob', `noglob',
3940 `NO_GLOB' are all completed). Any arguments are propagated to
3941 the compadd builtin.
3942 _options_set and _options_unset
3944 These functions complete only set or unset options, with the
3945 same matching specification used in the _options function.
3946 Note that you need to uncomment a few lines in the _main_com‐
3948 plete function for these functions to work properly. The lines
3949 in question are used to store the option settings in effect
3950 before the completion widget locally sets the options it needs.
3951 Hence these functions are not generally used by the completion
3952 system.
3953 _parameters
3955 This is used to complete the names of shell parameters.
3956 The option `-g pattern' limits the completion to parameters
3958 whose type matches the pattern. The type of a parameter is that
3959 shown by `print ${(t)param}', hence judicious use of `*' in pat‐
3960 tern is probably necessary.
3961 All other arguments are passed to the compadd builtin.
3963 _path_files
3965 This function is used throughout the completion system to com‐
3966 plete filenames. It allows completion of partial paths. For
3967 example, the string `/u/i/s/sig' may be completed to
3968 `/usr/include/sys/signal.h'.
3969 The options accepted by both _path_files and _files are:
3971 -f Complete all filenames. This is the default.
3973 -/ Specifies that only directories should be completed.
3975 -g pattern
3977 Specifies that only files matching the pattern should be
3978 completed.
3979 -W paths
3981 Specifies path prefixes that are to be prepended to the
3982 string from the command line to generate the filenames
3983 but that should not be inserted as completions nor shown
3984 in completion listings. Here, paths may be the name of
3985 an array parameter, a literal list of paths enclosed in
3986 parentheses or an absolute pathname.
3987 -F ignored-files
3989 This behaves as for the corresponding option to the com‐
3990 padd builtin. It gives direct control over which file‐
3991 names should be ignored. If the option is not present,
3992 the ignored-patterns style is used.
3993 Both _path_files and _files also accept the following options
3995 which are passed to compadd: `-J', `-V', `-1', `-2', `-n', `-X',
3996 `-M', `-P', `-S', `-q', `-r', and `-R'.
3997 Finally, the _path_files function uses the styles expand,
3999 ambiguous, special-dirs, list-suffixes and file-sort described
4000 above.
4001 _pick_variant [ -c command ] [ -r name ] label=pattern ... label [ args
4003 ... ]
4004 This function is used to resolve situations where a single com‐
4005 mand name requires more than one type of handling, either
4006 because it has more than one variant or because there is a name
4007 clash between two different commands.
4008 The command to run is taken from the first element of the array
4010 words unless this is overridden by the option -c. This command
4011 is run and its output is compared with a series of patterns.
4012 Arguments to be passed to the command can be specified at the
4013 end after all the other arguments. The patterns to try in order
4014 are given by the arguments label=pattern; if the output of `com‐
4015 mand args ...' contains pattern, then label is selected as the
4016 label for the command variant. If none of the patterns match,
4017 the final command label is selected and status 1 is returned.
4018 If the `-r name' is given, the label picked is stored in the
4020 parameter named name.
4021 The results are also cached in the _cmd_variant associative
4023 array indexed by the name of the command run.
4024 _regex_arguments name spec ...
4026 This function generates a completion function name which matches
4027 the specifications spec ..., a set of regular expressions as
4028 described below. After running _regex_arguments, the function
4029 name should be called as a normal completion function. The pat‐
4030 tern to be matched is given by the contents of the words array
4031 up to the current cursor position joined together with null
4032 characters; no quotation is applied.
4033 The arguments are grouped as sets of alternatives separated by
4035 `|', which are tried one after the other until one matches.
4036 Each alternative consists of a one or more specifications which
4037 are tried left to right, with each pattern matched being
4038 stripped in turn from the command line being tested, until all
4039 of the group succeeds or until one fails; in the latter case,
4040 the next alternative is tried. This structure can be repeated
4041 to arbitrary depth by using parentheses; matching proceeds from
4042 inside to outside.
4043 A special procedure is applied if no test succeeds but the
4045 remaining command line string contains no null character (imply‐
4046 ing the remaining word is the one for which completions are to
4047 be generated). The completion target is restricted to the
4048 remaining word and any actions for the corresponding patterns
4049 are executed. In this case, nothing is stripped from the com‐
4050 mand line string. The order of evaluation of the actions can be
4051 determined by the tag-order style; the various formats supported
4052 by _alternative can be used in action. The descr is used for
4053 setting up the array parameter expl.
4054 Specification arguments take one of following forms, in which
4056 metacharacters such as `(', `)', `#' and `|' should be quoted.
4057 /pattern/ [%lookahead%] [-guard] [:tag:descr:action]
4059 This is a single primitive component. The function tests
4060 whether the combined pattern `(#b)((#B)pattern)looka‐
4061 head*' matches the command line string. If so, `guard'
4062 is evaluated and its return status is examined to deter‐
4063 mine if the test has succeeded. The pattern string `[]'
4064 is guaranteed never to match. The lookahead is not
4065 stripped from the command line before the next pattern is
4066 examined.
4067 The argument starting with : is used in the same manner
4069 as an argument to _alternative.
4070 A component is used as follows: pattern is tested to see
4072 if the component already exists on the command line. If
4073 it does, any following specifications are examined to
4074 find something to complete. If a component is reached
4075 but no such pattern exists yet on the command line, the
4076 string containing the action is used to generate matches
4077 to insert at that point.
4078 /pattern/+ [%lookahead%] [-guard] [:tag:descr:action]
4080 This is similar to `/pattern/ ...' but the left part of
4081 the command line string (i.e. the part already matched by
4082 previous patterns) is also considered part of the comple‐
4083 tion target.
4084 /pattern/- [%lookahead%] [-guard] [:tag:descr:action]
4086 This is similar to `/pattern/ ...' but the actions of the
4087 current and previously matched patterns are ignored even
4088 if the following `pattern' matches the empty string.
4089 ( spec )
4091 Parentheses may be used to groups specs; note each paren‐
4092 thesis is a single argument to _regex_arguments.
4093 spec # This allows any number of repetitions of spec.
4095 spec spec
4097 The two specs are to be matched one after the other as
4098 described above.
4099 spec | spec
4101 Either of the two specs can be matched.
4102 The function _regex_words can be used as a helper function to
4104 generate matches for a set of alternative words possibly with
4105 their own arguments as a command line argument.
4106 Examples:
4108 _regex_arguments _tst /$'[^\0]#\0'/ \
4110 /$'[^\0]#\0'/ :'compadd aaa'
4111 This generates a function _tst that completes aaa as its only
4113 argument. The tag and description for the action have been
4114 omitted for brevity (this works but is not recommended in normal
4115 use). The first component matches the command word, which is
4116 arbitrary; the second matches any argument. As the argument is
4117 also arbitrary, any following component would not depend on aaa
4118 being present.
4119 _regex_arguments _tst /$'[^\0]#\0'/ \
4121 /$'aaa\0'/ :'compadd aaa'
4122 This is a more typical use; it is similar, but any following
4124 patterns would only match if aaa was present as the first argu‐
4125 ment.
4126 _regex_arguments _tst /$'[^\0]#\0'/ \( \
4128 /$'aaa\0'/ :'compadd aaa' \
4129 /$'bbb\0'/ :'compadd bbb' \) \#
4130 In this example, an indefinite number of command arguments may
4132 be completed. Odd arguments are completed as aaa and even argu‐
4133 ments as bbb. Completion fails unless the set of aaa and bbb
4134 arguments before the current one is matched correctly.
4135 _regex_arguments _tst /$'[^\0]#\0'/ \
4137 \( /$'aaa\0'/ :'compadd aaa' \| \
4138 /$'bbb\0'/ :'compadd bbb' \) \#
4139 This is similar, but either aaa or bbb may be completed for any
4141 argument. In this case _regex_words could be used to generate a
4142 suitable expression for the arguments.
4143 _regex_words tag description spec ...
4145 This function can be used to generate arguments for the
4146 _regex_arguments command which may be inserted at any point
4147 where a set of rules is expected. The tag and description give
4148 a standard tag and description pertaining to the current con‐
4149 text. Each spec contains two or three arguments separated by a
4150 colon: note that there is no leading colon in this case.
4151 Each spec gives one of a set of words that may be completed at
4153 this point, together with arguments. It is thus roughly equiva‐
4154 lent to the _arguments function when used in normal (non-regex)
4155 completion.
4156 The part of the spec before the first colon is the word to be
4158 completed. This may contain a *; the entire word, before and
4159 after the * is completed, but only the text before the * is
4160 required for the context to be matched, so that further argu‐
4161 ments may be completed after the abbreviated form.
4162 The second part of spec is a description for the word being com‐
4164 pleted.
4165 The optional third part of the spec describes how words follow‐
4167 ing the one being completed are themselves to be completed. It
4168 will be evaluated in order to avoid problems with quoting. This
4169 means that typically it contains a reference to an array con‐
4170 taining previously generated regex arguments.
4171 The option -t term specifies a terminator for the word instead
4173 of the usual space. This is handled as an auto-removable suffix
4174 in the manner of the option -s sep to _values.
4175 The result of the processing by _regex_words is placed in the
4177 array reply, which should be made local to the calling function.
4178 If the set of words and arguments may be matched repeatedly, a #
4179 should be appended to the generated array at that point.
4180 For example:
4182 local -a reply
4184 _regex_words mydb-commands 'mydb commands' \
4185 'add:add an entry to mydb:$mydb_add_cmds' \
4186 'show:show entries in mydb'
4187 _regex_arguments _mydb "$reply[@]"
4188 _mydb "$@"
4189 This shows a completion function for a command mydb which takes
4191 two command arguments, add and show. show takes no arguments,
4192 while the arguments for add have already been prepared in an
4193 array mydb_add_cmds, quite possibly by a previous call to
4194 _regex_words.
4195 _requested [ -x ] [ -12VJ ] tag [ name descr [ command args ... ] ]
4197 This function is called to decide whether a tag already regis‐
4198 tered by a call to _tags (see below) has been requested by the
4199 user and hence completion should be performed for it. It
4200 returns status zero if the tag is requested and non-zero other‐
4201 wise. The function is typically used as part of a loop over
4202 different tags as follows:
4203 _tags foo bar baz
4205 while _tags; do
4206 if _requested foo; then
4207 ... # perform completion for foo
4208 fi
4209 ... # test the tags bar and baz in the same way
4210 ... # exit loop if matches were generated
4211 done
4212 Note that the test for whether matches were generated is not
4214 performed until the end of the _tags loop. This is so that the
4215 user can set the tag-order style to specify a set of tags to be
4216 completed at the same time.
4217 If name and descr are given, _requested calls the _description
4219 function with these arguments together with the options passed
4220 to _requested.
4221 If command is given, the _all_labels function will be called
4223 immediately with the same arguments. In simple cases this makes
4224 it possible to perform the test for the tag and the matching in
4225 one go. For example:
4226 local expl ret=1
4228 _tags foo bar baz
4229 while _tags; do
4230 _requested foo expl 'description' \
4231 compadd foobar foobaz && ret=0
4232 ...
4233 (( ret )) || break
4234 done
4235 If the command is not compadd, it must nevertheless be prepared
4237 to handle the same options.
4238 _retrieve_cache cache_identifier
4240 This function retrieves completion information from the file
4241 given by cache_identifier, stored in a directory specified by
4242 the cache-path style which defaults to ~/.zcompcache. The
4243 return status is zero if retrieval was successful. It will only
4244 attempt retrieval if the use-cache style is set, so you can call
4245 this function without worrying about whether the user wanted to
4246 use the caching layer.
4247 See _store_cache below for more details.
4249 _sep_parts
4251 This function is passed alternating arrays and separators as
4252 arguments. The arrays specify completions for parts of strings
4253 to be separated by the separators. The arrays may be the names
4254 of array parameters or a quoted list of words in parentheses.
4255 For example, with the array `hosts=(ftp news)' the call
4256 `_sep_parts '(foo bar)' @ hosts' will complete the string `f'
4257 to `foo' and the string `b@n' to `bar@news'.
4258 This function accepts the compadd options `-V', `-J', `-1',
4260 `-2', `-n', `-X', `-M', `-P', `-S', `-r', `-R', and `-q' and
4261 passes them on to the compadd builtin used to add the matches.
4262 _setup tag [ group ]
4264 This function sets up the special parameters used by the comple‐
4265 tion system appropriately for the tag given as the first argu‐
4266 ment. It uses the styles list-colors, list-packed,
4267 list-rows-first, last-prompt, accept-exact, menu and force-list.
4268 The optional group supplies the name of the group in which the
4270 matches will be placed. If it is not given, the tag is used as
4271 the group name.
4272 This function is called automatically from _description and
4274 hence is not normally called explicitly.
4275 _store_cache cache_identifier params ...
4277 This function, together with _retrieve_cache and _cache_invalid,
4278 implements a caching layer which can be used in any completion
4279 function. Data obtained by costly operations are stored in
4280 parameters; this function then dumps the values of those parame‐
4281 ters to a file. The data can then be retrieved quickly from
4282 that file via _retrieve_cache, even in different instances of
4283 the shell.
4284 The cache_identifier specifies the file which the data should be
4286 dumped to. The file is stored in a directory specified by the
4287 cache-path style which defaults to ~/.zcompcache. The remaining
4288 params arguments are the parameters to dump to the file.
4289 The return status is zero if storage was successful. The func‐
4291 tion will only attempt storage if the use-cache style is set, so
4292 you can call this function without worrying about whether the
4293 user wanted to use the caching layer.
4294 The completion function may avoid calling _retrieve_cache when
4296 it already has the completion data available as parameters.
4297 However, in that case it should call _cache_invalid to check
4298 whether the data in the parameters and in the cache are still
4299 valid.
4300 See the _perl_modules completion function for a simple example
4302 of the usage of the caching layer.
4303 _tags [ [ -C name ] tags ... ]
4305 If called with arguments, these are taken to be the names of
4306 tags valid for completions in the current context. These tags
4307 are stored internally and sorted by using the tag-order style.
4308 Next, _tags is called repeatedly without arguments from the same
4310 completion function. This successively selects the first, sec‐
4311 ond, etc. set of tags requested by the user. The return status
4312 is zero if at least one of the tags is requested and non-zero
4313 otherwise. To test if a particular tag is to be tried, the
4314 _requested function should be called (see above).
4315 If `-C name' is given, name is temporarily stored in the argu‐
4317 ment field (the fifth) of the context in the curcontext parame‐
4318 ter during the call to _tags; the field is restored on exit.
4319 This allows _tags to use a more specific context without having
4320 to change and reset the curcontext parameter (which has the same
4321 effect).
4322 _values [ -O name ] [ -s sep ] [ -S sep ] [ -wC ] desc spec ...
4324 This is used to complete arbitrary keywords (values) and their
4325 arguments, or lists of such combinations.
4326 If the first argument is the option `-O name', it will be used
4328 in the same way as by the _arguments function. In other words,
4329 the elements of the name array will be passed to compadd when
4330 executing an action.
4331 If the first argument (or the first argument after `-O name') is
4333 `-s', the next argument is used as the character that separates
4334 multiple values. This character is automatically added after
4335 each value in an auto-removable fashion (see below); all values
4336 completed by `_values -s' appear in the same word on the command
4337 line, unlike completion using _arguments. If this option is not
4338 present, only a single value will be completed per word.
4339 Normally, _values will only use the current word to determine
4341 which values are already present on the command line and hence
4342 are not to be completed again. If the -w option is given, other
4343 arguments are examined as well.
4344 The first non-option argument is used as a string to print as a
4346 description before listing the values.
4347 All other arguments describe the possible values and their argu‐
4349 ments in the same format used for the description of options by
4350 the _arguments function (see above). The only differences are
4351 that no minus or plus sign is required at the beginning, values
4352 can have only one argument, and the forms of action beginning
4353 with an equal sign are not supported.
4354 The character separating a value from its argument can be set
4356 using the option -S (like -s, followed by the character to use
4357 as the separator in the next argument). By default the equals
4358 sign will be used as the separator between values and arguments.
4359 Example:
4361 _values -s , 'description' \
4363 '*foo[bar]' \
4364 '(two)*one[number]:first count:' \
4365 'two[another number]::second count:(1 2 3)'
4366 This describes three possible values: `foo', `one', and `two'.
4368 The first is described as `bar', takes no argument and may
4369 appear more than once. The second is described as `number', may
4370 appear more than once, and takes one mandatory argument
4371 described as `first count'; no action is specified, so it will
4372 not be completed. The `(two)' at the beginning says that if the
4373 value `one' is on the line, the value `two' will no longer be
4374 considered a possible completion. Finally, the last value
4375 (`two') is described as `another number' and takes an optional
4376 argument described as `second count' for which the completions
4377 (to appear after an `=') are `1', `2', and `3'. The _values
4378 function will complete lists of these values separated by com‐
4379 mas.
4380 Like _arguments, this function temporarily adds another context
4382 name component to the arguments element (the fifth) of the cur‐
4383 rent context while executing the action. Here this name is just
4384 the name of the value for which the argument is completed.
4385 The style verbose is used to decide if the descriptions for the
4387 values (but not those for the arguments) should be printed.
4388 The associative array val_args is used to report values and
4390 their arguments; this works similarly to the opt_args associa‐
4391 tive array used by _arguments. Hence the function calling _val‐
4392 ues should declare the local parameters state, line, context and
4393 val_args:
4394 local context state line
4396 typeset -A val_args
4397 when using an action of the form `->string'. With this function
4399 the context parameter will be set to the name of the value whose
4400 argument is to be completed.
4401 Note also that _values normally adds the character used as the
4403 separator between values as an auto-removable suffix (similar to
4404 a `/' after a directory). However, this is not possible for a
4405 `->string' action as the matches for the argument are generated
4406 by the calling function. To get the usual behaviour, the the
4407 calling function can add the separator x as a suffix by passing
4408 the options `-qS x' either directly or indirectly to compadd.
4409 The option -C is treated in the same way as it is by _arguments.
4411 In that case the parameter curcontext should be made local
4412 instead of context (as described above).
4413 _wanted [ -x ] [ -C name ] [ -12VJ ] tag name descr command args ...
4415 In many contexts, completion can only generate one particular
4416 set of matches, usually corresponding to a single tag. However,
4417 it is still necessary to decide whether the user requires
4418 matches of this type. This function is useful in such a case.
4419 The arguments to _wanted are the same as those to _requested,
4421 i.e. arguments to be passed to _description. However, in this
4422 case the command is not optional; all the processing of tags,
4423 including the loop over both tags and tag labels and the genera‐
4424 tion of matches, is carried out automatically by _wanted.
4425 Hence to offer only one tag and immediately add the correspond‐
4427 ing matches with the given description:
4428 local expl
4430 _wanted tag expl 'description' \
4431 compadd matches...
4432 Note that, as for _requested, the command must be able to accept
4434 options to be passed down to compadd.
4435 Like _tags this function supports the -C option to give a dif‐
4437 ferent name for the argument context field. The -x option has
4438 the same meaning as for _description.
4439
4441 In the source distribution, the files are contained in various subdi‐
4442 rectories of the Completion directory. They may have been installed in
4443 the same structure, or into one single function directory. The follow‐
4444 ing is a description of the files found in the original directory
4445 structure. If you wish to alter an installed file, you will need to
4446 copy it to some directory which appears earlier in your fpath than the
4447 standard directory where it appears.
4448 Base The core functions and special completion widgets automatically
4450 bound to keys. You will certainly need most of these, though
4451 will probably not need to alter them. Many of these are docu‐
4452 mented above.
4453 Zsh Functions for completing arguments of shell builtin commands and
4455 utility functions for this. Some of these are also used by
4456 functions from the Unix directory.
4457 Unix Functions for completing arguments of external commands and
4459 suites of commands. They may need modifying for your system,
4460 although in many cases some attempt is made to decide which ver‐
4461 sion of a command is present. For example, completion for the
4462 mount command tries to determine the system it is running on,
4463 while completion for many other utilities try to decide whether
4464 the GNU version of the command is in use, and hence whether the
4465 --help option is supported.
4466 X, AIX, BSD, ...
4468 Completion and utility function for commands available only on
4469 some systems. These are not arranged hierarchically, so, for
4470 example, both the Linux and Debian directories, as well as the X
4471 directory, may be useful on your system.
4472zsh 4.3.11 December 20, 2010 ZSHCOMPSYS(1)