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. It con‐
10 sists of various shell functions; those beginning `comp' are to be
11 called directly, while those beginning `_' are called by the completion
12 code. The shell functions of the second set, which implement comple‐
13 tion behaviour and may be bound to keystrokes, are referred to as `wid‐
14 gets'.
15
17 If the system was installed completely, it should be enough to call the
18 shell function compinit from your initialization file; see the next
19 section. However, the function compinstall can be run by a user to
20 configure various aspects of the completion system.
21 Usually, compinstall will insert code into .zshrc, although if that is
23 not writable it will save it in another file and tell you that file's
24 location. Note that it is up to you to make sure that the lines added
25 to .zshrc are actually run; you may, for example, need to move them to
26 an earlier place in the file if .zshrc usually returns early. So long
27 as you keep them all together (including the comment lines at the start
28 and finish), you can rerun compinstall and it will correctly locate and
29 modify these lines. Note, however, that any code you add to this sec‐
30 tion by hand is likely to be lost if you rerun compinstall, although
31 lines using the command `zstyle' should be gracefully handled.
32 The new code will take effect next time you start the shell, or run
34 .zshrc by hand; there is also an option to make them take effect imme‐
35 diately. However, if compinstall has removed definitions, you will
36 need to restart the shell to see the changes.
37 To run compinstall you will need to make sure it is in a directory men‐
39 tioned in your fpath parameter, which should already be the case if zsh
40 was properly configured as long as your startup files do not remove the
41 appropriate directories from fpath. Then it must be autoloaded
42 (`autoload -U compinstall' is recommended). You can abort the instal‐
43 lation any time you are being prompted for information, and your .zshrc
44 will not be altered at all; changes only take place right at the end,
45 where you are specifically asked for confirmation.
46 Use of compinit
48 This section describes the use of compinit to initialize completion for
49 the current session when called directly; if you have run compinstall
50 it will be called automatically from your .zshrc.
51 To initialize the system, the function compinit should be in a direc‐
53 tory mentioned in the fpath parameter, and should be autoloaded
54 (`autoload -U compinit' is recommended), and then run simply as
55 `compinit'. This will define a few utility functions, arrange for all
56 the necessary shell functions to be autoloaded, and will then re-define
57 all widgets that do completion to use the new system. If you use the
58 menu-select widget, which is part of the zsh/complist module, you
59 should make sure that that module is loaded before the call to compinit
60 so that that widget is also re-defined. If completion styles (see
61 below) are set up to perform expansion as well as completion by
62 default, and the TAB key is bound to expand-or-complete, compinit will
63 rebind it to complete-word; this is necessary to use the correct form
64 of expansion.
65 Should you need to use the original completion commands, you can still
67 bind keys to the old widgets by putting a `.' in front of the widget
68 name, e.g. `.expand-or-complete'.
69 To speed up the running of compinit, it can be made to produce a dumped
71 configuration that will be read in on future invocations; this is the
72 default, but can be turned off by calling compinit with the option -D.
73 The dumped file is .zcompdump in the same directory as the startup
74 files (i.e. $ZDOTDIR or $HOME); alternatively, an explicit file name
75 can be given by `compinit -d dumpfile'. The next invocation of
76 compinit will read the dumped file instead of performing a full ini‐
77 tialization.
78 If the number of completion files changes, compinit will recognise this
80 and produce a new dump file. However, if the name of a function or the
81 arguments in the first line of a #compdef function (as described below)
82 change, it is easiest to delete the dump file by hand so that compinit
83 will re-create it the next time it is run. The check performed to see
84 if there are new functions can be omitted by giving the option -C. In
85 this case the dump file will only be created if there isn't one
86 already.
87 The dumping is actually done by another function, compdump, but you
89 will only need to run this yourself if you change the configuration
90 (e.g. using compdef) and then want to dump the new one. The name of
91 the old dumped file will be remembered for this purpose.
92 If the parameter _compdir is set, compinit uses it as a directory where
94 completion functions can be found; this is only necessary if they are
95 not already in the function search path.
96 For security reasons compinit also checks if the completion system
98 would use files not owned by root or by the current user, or files in
99 directories that are world- or group-writable or that are not owned by
100 root or by the current user. If such files or directories are found,
101 compinit will ask if the completion system should really be used. To
102 avoid these tests and make all files found be used without asking, use
103 the option -u, and to make compinit silently ignore all insecure files
104 and directories use the option -i. This security check is skipped
105 entirely when the -C option is given.
106 The security check can be retried at any time by running the function
108 compaudit. This is the same check used by compinit, but when it is
109 executed directly any changes to fpath are made local to the function
110 so they do not persist. The directories to be checked may be passed as
111 arguments; if none are given, compaudit uses fpath and _compdir to find
112 completion system directories, adding missing ones to fpath as neces‐
113 sary. To force a check of exactly the directories currently named in
114 fpath, set _compdir to an empty string before calling compaudit or
115 compinit.
116 Autoloaded files
118 The convention for autoloaded functions used in completion is that they
119 start with an underscore; as already mentioned, the fpath/FPATH parame‐
120 ter must contain the directory in which they are stored. If zsh was
121 properly installed on your system, then fpath/FPATH automatically con‐
122 tains the required directories for the standard functions.
123 For incomplete installations, if compinit does not find enough files
125 beginning with an underscore (fewer than twenty) in the search path, it
126 will try to find more by adding the directory _compdir to the search
127 path. If that directory has a subdirectory named Base, all subdirecto‐
128 ries will be added to the path. Furthermore, if the subdirectory Base
129 has a subdirectory named Core, compinit will add all subdirectories of
130 the subdirectories is to the path: this allows the functions to be in
131 the same format as in the zsh source distribution.
132 When compinit is run, it searches all such files accessible via
134 fpath/FPATH and reads the first line of each of them. This line should
135 contain one of the tags described below. Files whose first line does
136 not start with one of these tags are not considered to be part of the
137 completion system and will not be treated specially.
138 The tags are:
140 #compdef names... [ -[pP] patterns... [ -N names... ] ]
142 The file will be made autoloadable and the function defined in
143 it will be called when completing names, each of which is either
144 the name of a command whose arguments are to be completed or one
145 of a number of special contexts in the form -context- described
146 below.
147 Each name may also be of the form `cmd=service'. When complet‐
149 ing the command cmd, the function typically behaves as if the
150 command (or special context) service was being completed
151 instead. This provides a way of altering the behaviour of func‐
152 tions that can perform many different completions. It is imple‐
153 mented by setting the parameter $service when calling the func‐
154 tion; the function may choose to interpret this how it wishes,
155 and simpler functions will probably ignore it.
156 If the #compdef line contains one of the options -p or -P, the
158 words following are taken to be patterns. The function will be
159 called when completion is attempted for a command or context
160 that matches one of the patterns. The options -p and -P are
161 used to specify patterns to be tried before or after other com‐
162 pletions respectively. Hence -P may be used to specify default
163 actions.
164 The option -N is used after a list following -p or -P; it speci‐
166 fies that remaining words no longer define patterns. It is pos‐
167 sible to toggle between the three options as many times as nec‐
168 essary.
169 #compdef -k style key-sequences...
171 This option creates a widget behaving like the builtin widget
172 style and binds it to the given key-sequences, if any. The
173 style must be one of the builtin widgets that perform comple‐
174 tion, namely complete-word, delete-char-or-list, expand-or-com‐
175 plete, expand-or-complete-prefix, list-choices, menu-complete,
176 menu-expand-or-complete, or reverse-menu-complete. If the
177 zsh/complist module is loaded (see zshmodules(1)) the widget
178 menu-select is also available.
179 When one of the key-sequences is typed, the function in the file
181 will be invoked to generate the matches. Note that a key will
182 not be re-bound if if it already was (that is, was bound to
183 something other than undefined-key). The widget created has the
184 same name as the file and can be bound to any other keys using
185 bindkey as usual.
186 #compdef -K widget-name style key-sequences ...
188 This is similar to -k except that only one key-sequences argu‐
189 ment may be given for each widget-name style pair. However, the
190 entire set of three arguments may be repeated with a different
191 set of arguments. Note in particular that the widget-name must
192 be distinct in each set. If it does not begin with `_' this
193 will be added. The widget-name should not clash with the name
194 of any existing widget: names based on the name of the function
195 are most useful. For example,
196 #compdef -K _foo_complete complete-word "^X^C" \
198 _foo_list list-choices "^X^D"
199 (all on one line) defines a widget _foo_complete for completion,
201 bound to `^X^C', and a widget _foo_list for listing, bound to
202 `^X^D'.
203 #autoload [ options ]
205 Functions with the #autoload tag are marked for autoloading but
206 are not otherwise treated specially. Typically they are to be
207 called from within one of the completion functions. Any options
208 supplied will be passed to the autoload builtin; a typical use
209 is +X to force the function to be loaded immediately. Note that
210 the -U and -z flags are always added implicitly.
211 The # is part of the tag name and no white space is allowed after it.
213 The #compdef tags use the compdef function described below; the main
214 difference is that the name of the function is supplied implicitly.
215 The special contexts for which completion functions can be defined are:
217 -array-value-
219 The right hand side of an array-assignment (`foo=(...)')
220 -brace-parameter-
222 The name of a parameter expansion within braces (`${...}')
223 -assign-parameter-
225 The name of a parameter in an assignment, i.e. on the left hand
226 side of an `='
227 -command-
229 A word in command position
230 -condition-
232 A word inside a condition (`[[...]]')
233 -default-
235 Any word for which no other completion is defined
236 -equal-
238 A word beginning with an equals sign
239 -first-
241 This is tried before any other completion function. The func‐
242 tion called may set the _compskip parameter to one of various
243 values: all: no further completion is attempted; a string con‐
244 taining the substring patterns: no pattern completion functions
245 will be called; a string containing default: the function for
246 the `-default-' context will not be called, but functions
247 defined for commands will
248 -math- Inside mathematical contexts, such as `((...))'
250 -parameter-
252 The name of a parameter expansion (`$...')
253 -redirect-
255 The word after a redirection operator.
256 -subscript-
258 The contents of a parameter subscript.
259 -tilde-
261 After an initial tilde (`~'), but before the first slash in the
262 word.
263 -value-
265 On the right hand side of an assignment.
266 Default implementations are supplied for each of these contexts. In
268 most cases the context -context- is implemented by a corresponding
269 function _context, for example the context `-tilde-' and the function
270 `_tilde').
271 The contexts -redirect- and -value- allow extra context-specific infor‐
273 mation. (Internally, this is handled by the functions for each context
274 calling the function _dispatch.) The extra information is added sepa‐
275 rated by commas.
276 For the -redirect- context, the extra information is in the form `-re‐
278 direct-,op,command', where op is the redirection operator and command
279 is the name of the command on the line. If there is no command on the
280 line yet, the command field will be empty.
281 For the -value- context, the form is `-value-,name,command', where name
283 is the name of the parameter. In the case of elements of an associa‐
284 tive array, for example `assoc=(key <TAB>', name is expanded to
285 `name-key'. In certain special contexts, such as completing after
286 `make CFLAGS=', the command part gives the name of the command, here
287 make; otherwise it is empty.
288 It is not necessary to define fully specific completions as the func‐
290 tions provided will try to generate completions by progressively
291 replacing the elements with `-default-'. For example, when completing
292 after `foo=<TAB>', _value will try the names `-value-,foo,' (note the
293 empty command part), `-value-,foo,-default-'
294 and`-value-,-default-,-default-', in that order, until it finds a func‐
295 tion to handle the context.
296 As an example:
298 compdef '_files -g "*.log"' '-redirect-,2>,-default-'
300 completes files matching `*.log' after `2> <TAB>' for any command with
302 no more specific handler defined.
303 Also:
305 compdef _foo -value-,-default-,-default-
307 specifies that _foo provides completions for the values of parameters
309 for which no special function has been defined. This is usually han‐
310 dled by the function _value itself.
311 The same lookup rules are used when looking up styles (as described
313 below); for example
314 zstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log'
316 is another way to make completion after `2> <TAB>' complete files
318 matching `*.log'.
319 Functions
321 The following function is defined by compinit and may be called
322 directly.
323 compdef [ -an ] function names... [ -[pP] patterns... [ -N names... ] ]
325 compdef -d names...
326 compdef -k [ -an ] function style key-sequences...
327 compdef -K [ -an ] function name style key-sequences ...
328 The first form defines the function to call for completion in
329 the given contexts as described for the #compdef tag above.
330 Alternatively, all the arguments may have the form `cmd=ser‐
332 vice'. Here service should already have been defined by
333 `cmd1=service' lines in #compdef files, as described above. The
334 argument for cmd will be completed in the same way as service.
335 The function argument may alternatively be a string containing
337 any shell code. The string will be executed using the eval
338 builtin command to generate completions. This provides a way of
339 avoiding having to define a new completion function. For exam‐
340 ple, to complete files ending in `.h' as arguments to the com‐
341 mand foo:
342 compdef '_files -g "*.h"' foo
344 The option -n prevents any completions already defined for the
346 command or context from being overwritten.
347 The option -d deletes any completion defined for the command or
349 contexts listed.
350 The names may also contain -p, -P and -N options as described
352 for the #compdef tag. The effect on the argument list is iden‐
353 tical, switching between definitions of patterns tried ini‐
354 tially, patterns tried finally, and normal commands and con‐
355 texts.
356 The parameter $_compskip may be set by any function defined for
358 a pattern context. If it is set to a value containing the sub‐
359 string `patterns' none of the pattern-functions will be called;
360 if it is set to a value containing the substring `all', no other
361 function will be called.
362 The form with -k defines a widget with the same name as the
364 function that will be called for each of the key-sequences; this
365 is like the #compdef -k tag. The function should generate the
366 completions needed and will otherwise behave like the builtin
367 widget whose name is given as the style argument. The widgets
368 usable for this are: complete-word, delete-char-or-list,
369 expand-or-complete, expand-or-complete-prefix, list-choices,
370 menu-complete, menu-expand-or-complete, and reverse-menu-com‐
371 plete, as well as menu-select if the zsh/complist module is
372 loaded. The option -n prevents the key being bound if it is
373 already to bound to something other than undefined-key.
374 The form with -K is similar and defines multiple widgets based
376 on the same function, each of which requires the set of three
377 arguments name, style and key-sequences, where the latter two
378 are as for -k and the first must be a unique widget name begin‐
379 ning with an underscore.
380 Wherever applicable, the -a option makes the function autoload‐
382 able, equivalent to autoload -U function.
383 The function compdef can be used to associate existing completion func‐
385 tions with new commands. For example,
386 compdef _pids foo
388 uses the function _pids to complete process IDs for the command foo.
390 Note also the _gnu_generic function described below, which can be used
392 to complete options for commands that understand the `--help' option.
393
395 This section gives a short overview of how the completion system works,
396 and then more detail on how users can configure how and when matches
397 are generated.
398 Overview
400 When completion is attempted somewhere on the command line the comple‐
401 tion system first works out the context. This takes account of a num‐
402 ber of things including the command word (such as `grep' or `zsh') and
403 options to which the current word may be an argument (such as the `-o'
404 option to zsh which takes a shell option as an argument).
405 This context information is condensed into a string consisting of mul‐
407 tiple fields separated by colons, referred to simply as `the context'
408 in the remainder of the documentation. This is used to look up styles,
409 context-sensitive options that can be used to configure the completion
410 system. The context used for lookup may vary during the same call to
411 the completion system.
412 The context string always consists of the following fields, separated
414 by colons and with a leading colon before the first:
415 · The literal string completion, saying that this style is used by
417 the completion system. This distinguishes the context from
418 those used by, for example, zle widgets and ZFTP functions.
419 · The function, if completion is called from a named widget rather
422 than through the normal completion system. Typically this is
423 blank, but it is set by special widgets such as predict-on and
424 the various functions in the Widget directory of the distribu‐
425 tion to the name of that function, often in an abbreviated form.
426 · The completer currently active, the name of the function without
429 the leading underscore. A `completer' is in overall control of
430 how completion is to be performed; `complete' is the simplest,
431 but other completers exist to perform related tasks such as cor‐
432 rection, or to modify the behaviour of a later completer. See
433 the section `Control Functions' below for more information.
434 · The command or a special -context-, just at it appears following
437 the #compdef tag or the compdef function. Completion functions
438 for commands that have sub-commands usually modify this field to
439 contain the name of the command followed by a minus sign and the
440 sub-command. For example, the completion function for the cvs
441 command sets this field to cvs-add when completing arguments to
442 the add subcommand.
443 · The argument; this indicates which command line or option argu‐
446 ment we are completing. For command arguments this generally
447 takes the form argument-n, where n is the number of the argu‐
448 ment, and for arguments to options the form option-opt-n where n
449 is the number of the argument to option opt. However, this is
450 only the case if the command line is parsed with standard
451 UNIX-style options and arguments, so many completions do not set
452 this.
453 · The tag. Tags are used to discriminate between the types of
456 matches a completion function can generate in a certain context
457 and are described further below.
458 As an example, the context name
461 :completion::complete:dvips:option-o-1:files
463 says that normal completion was attempted as the first argument to the
465 option -o of the command dvips:
466 dvips -o ...
468 and the completion function will generate filenames.
470 Each type of completion the system can perform in a given context is
472 described by a `tag', a short descriptive string such as files in the
473 example above. Any completion function may use any tag name it likes,
474 but a list of the more common ones is given below.
475 Usually completion will be tried by all possible tags in an order given
477 by the completion function. However, this can be altered by using the
478 tag-order style. Completion is then restricted to the list of given
479 tags in the given order.
480 The _complete_help bindable command shows all the contexts and tags
482 available for completion at a particular point. This provides an easy
483 way of finding information for tag-order and other styles. It is
484 described in the section `Bindable Commands' below.
485 Styles determine such things as how the matches are generated, simi‐
487 larly to shell options but with much more control. They can have any
488 number of strings as their value. They are defined with the zstyle
489 builtin command (see zshmodules(1)).
490 When looking up styles the completion system uses full context names,
492 including the tag. Looking up the value of a style therefore consists
493 of two things: the context, which may be matched as a pattern, and the
494 name of the style itself, which must be given exactly.
495 For example, many completion functions can generate matches in a simple
497 and a verbose form and use the verbose style to decide which form
498 should be used. To make all such functions use the verbose form, put
499 zstyle ':completion:*' verbose yes
501 in a startup file (probably .zshrc). This gives the verbose style the
503 value yes in every context inside the completion system, unless that
504 context has a more specific definition. It is best to avoid giving the
505 context as `*' in case the style has some meaning outside the comple‐
506 tion system.
507 Many such general purpose styles can be configured simply by using the
509 compinstall function.
510 A more specific example of the use of the verbose style is by the com‐
512 pletion for the kill builtin. If the style is set, the builtin lists
513 full job texts and process command lines; otherwise it shows the bare
514 job numbers and PIDs. To turn the style off for this use only:
515 zstyle ':completion:*:*:kill:*' verbose no
517 For even more control, the style can use one of the tags `jobs' or
519 `processes'. To turn off verbose display only for jobs:
520 zstyle ':completion:*:*:kill:*:jobs' verbose no
522 The -e option to zstyle even allows completion function code to appear
524 as the argument to a style; this requires some understanding of the
525 internals of completion functions (see see zshcompwid(1))). For exam‐
526 ple:
527 zstyle -e ':completion:*' completer '
529 if [[ $words[1] = cvs ]]; then
530 reply=(_complete)
531 else
532 reply=(_complete _approximate)
533 fi'
534 uses the value `_complete' for the completer style in most contexts,
536 but the value `_complete _approximate' when the first word on the com‐
537 mand line is `cvs'. This is probably more conveniently done by speci‐
538 fying the style for two different contexts. This form can be slow and
539 should be avoided for commonly examined styles such as menu and
540 list-rows-first.
541 Note that the order in which styles are defined does not matter; the
543 style mechanism uses the most specific possible match for a particular
544 style to determine the set of values. More precisely, strings are pre‐
545 ferred over patterns (for example, `:completion::complete:foo' is more
546 specific than `:completion::complete:*'), and longer patterns are pre‐
547 ferred over shorter patterns.
548 Style names like those of tags are arbitrary and depend on the comple‐
550 tion function. However, the following two sections list some of the
551 most common tags and styles.
552 Standard Tags
554 Some of the following are only used when looking up particular styles
555 and do not refer to a type of match.
556 accounts
558 used to look up the users-hosts style
559 all-expansions
561 used by the _expand completer when adding the single string con‐
562 taining all possible expansions
563 all-files
565 for the names of all files (as distinct from a particular sub‐
566 set, see the globbed-files tag).
567 arguments
569 for arguments to a command
570 arrays for names of array parameters
572 association-keys
574 for keys of associative arrays; used when completing inside a
575 subscript to a parameter of this type
576 bookmarks
578 when completing bookmarks (e.g. for URLs and the zftp function
579 suite)
580 builtins
582 for names of builtin commands
583 characters
585 for single characters in arguments of commands such as stty.
586 Also used when completing character classes after an opening
587 bracket
588 colormapids
590 for X colormap ids
591 colors for color names
593 commands
595 for names of external commands. Also used by complex commands
596 such as cvs when completing names subcommands.
597 contexts
599 for contexts in arguments to the zstyle builtin command
600 corrections
602 used by the _approximate and _correct completers for possible
603 corrections
604 cursors
606 for cursor names used by X programs
607 default
609 used in some contexts to provide a way of supplying a default
610 when more specific tags are also valid. Note that this tag is
611 used when only the function field of the context name is set
612 descriptions
614 used when looking up the value of the format style to generate
615 descriptions for types of matches
616 devices
618 for names of device special files
619 directories
621 for names of directories
622 directory-stack
624 for entries in the directory stack
625 displays
627 for X display names
628 domains
630 for network domains
631 expansions
633 used by the _expand completer for individual words (as opposed
634 to the complete set of expansions) resulting from the expansion
635 of a word on the command line
636 extensions
638 for X server extensions
639 file-descriptors
641 for numbers of open file descriptors
642 files the generic file-matching tag used by functions completing file‐
644 names
645 fonts for X font names
647 fstypes
649 for file system types (e.g. for the mount command)
650 functions
652 names of functions --- normally shell functions, although cer‐
653 tain commands may understand other kinds of function
654 globbed-files
656 for filenames when the name has been generated by pattern match‐
657 ing
658 groups for names of user groups
660 history-words
662 for words from the history
663 hosts for hostnames
665 indexes
667 for array indexes
668 jobs for jobs (as listed by the `jobs' builtin)
670 interfaces
672 for network interfaces
673 keymaps
675 for names of zsh keymaps
676 keysyms
678 for names of X keysyms
679 libraries
681 for names of system libraries
682 limits for system limits
684 local-directories
686 for names of directories that are subdirectories of the current
687 working directory when completing arguments of cd and related
688 builtin commands (compare path-directories)
689 manuals
691 for names of manual pages
692 mailboxes
694 for e-mail folders
695 maps for map names (e.g. NIS maps)
697 messages
699 used to look up the format style for messages
700 modifiers
702 for names of X modifiers
703 modules
705 for modules (e.g. zsh modules)
706 my-accounts
708 used to look up the users-hosts style
709 named-directories
711 for named directories (you wouldn't have guessed that, would
712 you?)
713 names for all kinds of names
715 newsgroups
717 for USENET groups
718 nicknames
720 for nicknames of NIS maps
721 options
723 for command options
724 original
726 used by the _approximate, _correct and _expand completers when
727 offering the original string as a match
728 other-accounts
730 used to look up the users-hosts style
731 packages
733 for packages (e.g. rpm or installed Debian packages)
734 parameters
736 for names of parameters
737 path-directories
739 for names of directories found by searching the cdpath array
740 when completing arguments of cd and related builtin commands
741 (compare local-directories)
742 paths used to look up the values of the expand, ambiguous and spe‐
744 cial-dirs styles
745 pods for perl pods (documentation files)
747 ports for communication ports
749 prefixes
751 for prefixes (like those of a URL)
752 printers
754 for print queue names
755 processes
757 for process identifiers
758 processes-names
760 used to look up the command style when generating the names of
761 processes for killall
762 sequences
764 for sequences (e.g. mh sequences)
765 sessions
767 for sessions in the zftp function suite
768 signals
770 for signal names
771 strings
773 for strings (e.g. the replacement strings for the cd builtin
774 command)
775 styles for styles used by the zstyle builtin command
777 suffixes
779 for filename extensions
780 tags for tags (e.g. rpm tags)
782 targets
784 for makefile targets
785 time-zones
787 for time zones (e.g. when setting the TZ parameter)
788 types for types of whatever (e.g. address types for the xhost command)
790 urls used to look up the urls and local styles when completing URLs
792 users for usernames
794 values for one of a set of values in certain lists
796 variant
798 used by _pick_variant to look up the command to run when deter‐
799 mining what program is installed for a particular command name.
800 visuals
802 for X visuals
803 warnings
805 used to look up the format style for warnings
806 widgets
808 for zsh widget names
809 windows
811 for IDs of X windows
812 zsh-options
814 for shell options
815 Standard Styles
817 Note that the values of several of these styles represent boolean val‐
818 ues. Any of the strings `true', `on', `yes', and `1' can be used for
819 the value `true' and any of the strings `false', `off', `no', and `0'
820 for the value `false'. The behavior for any other value is undefined
821 except where explicitly mentioned. The default value may be either
822 true or false if the style is not set.
823 Some of these styles are tested first for every possible tag corre‐
825 sponding to a type of match, and if no style was found, for the default
826 tag. The most notable styles of this type are menu, list-colors and
827 styles controlling completion listing such as list-packed and
828 last-prompt). When tested for the default tag, only the function field
829 of the context will be set so that a style using the default tag will
830 normally be defined along the lines of:
831 zstyle ':completion:*:default' menu ...
833 accept-exact
835 This is tested for the default tag in addition to the tags valid
836 for the current context. If it is set to `true' and any of the
837 trial matches is the same as the string on the command line,
838 this match will immediately be accepted (even if it would other‐
839 wise be considered ambiguous).
840 When completing pathnames (where the tag used is `paths') this
842 style accepts any number of patterns as the value in addition to
843 the boolean values. Pathnames matching one of these patterns
844 will be accepted immediately even if the command line contains
845 some more partially typed pathname components and these match no
846 file under the directory accepted.
847 This style is also used by the _expand completer to decide if
849 words beginning with a tilde or parameter expansion should be
850 expanded. For example, if there are parameters foo and foobar,
851 the string `$foo' will only be expanded if accept-exact is set
852 to `true'; otherwise the completion system will be allowed to
853 complete $foo to $foobar. If the style is set to `continue',
854 _expand will add the expansion as a match and the completion
855 system will also be allowed to continue.
856 add-space
858 This style is used by the _expand completer. If it is true (the
859 default), a space will be inserted after all words resulting
860 from the expansion, or a slash in the case of directory names.
861 If the value is `file', the completer will only add a space to
862 names of existing files. Either a boolean true or the value
863 `file' may be combined with `subst', in which case the completer
864 will not add a space to words generated from the expansion of a
865 substitution of the form `$(...)' or `${...}'.
866 The _prefix completer uses this style as a simple boolean value
868 to decide if a space should be inserted before the suffix.
869 ambiguous
871 This applies when completing non-final components of filename
872 paths, in other words those with a trailing slash. If it is
873 set, the cursor is left after the first ambiguous component,
874 even if menu completion is in use. The style is always tested
875 with the paths tag.
876 assign-list
878 When completing after an equals sign that is being treated as an
879 assignment, the completion system normally completes only one
880 filename. In some cases the value may be a list of filenames
881 separated by colons, as with PATH and similar parameters. This
882 style can be set to a list of patterns matching the names of
883 such parameters.
884 The default is to complete lists when the word on the line
886 already contains a colon.
887 auto-description
889 If set, this style's value will be used as the description for
890 options that are not described by the completion functions, but
891 that have exactly one argument. The sequence `%d' in the value
892 will be replaced by the description for this argument. Depend‐
893 ing on personal preferences, it may be useful to set this style
894 to something like `specify: %d'. Note that this may not work
895 for some commands.
896 avoid-completer
898 This is used by the _all_matches completer to decide if the
899 string consisting of all matches should be added to the list
900 currently being generated. Its value is a list of names of com‐
901 pleters. If any of these is the name of the completer that gen‐
902 erated the matches in this completion, the string will not be
903 added.
904 The default value for this style is `_expand _old_list _correct
906 _approximate', i.e. it contains the completers for which a
907 string with all matches will almost never be wanted.
908 cache-path
910 This style defines the path where any cache files containing
911 dumped completion data are stored. It defaults to `$ZDOT‐
912 DIR/.zcompcache', or `$HOME/.zcompcache' if $ZDOTDIR is not
913 defined. The completion cache will not be used unless the
914 use-cache style is set.
915 cache-policy
917 This style defines the function that will be used to determine
918 whether a cache needs rebuilding. See the section on the
919 _cache_invalid function below.
920 call-command
922 This style is used in the function for commands such as make and
923 ant where calling the command directly to generate matches suf‐
924 fers problems such as being slow or, as in the case of make can
925 potentially causes actions in the makefile to be executed. If it
926 is set to `true' the command is called to generate matches. The
927 default value of this style is `false'.
928 command
930 In many places, completion functions need to call external com‐
931 mands to generate the list of completions. This style can be
932 used to override the command that is called in some such cases.
933 The elements of the value are joined with spaces to form a com‐
934 mand line to execute. The value can also start with a hyphen,
935 in which case the usual command will be added to the end; this
936 is most useful for putting `builtin' or `command' in front to
937 make sure the appropriate version of a command is called, for
938 example to avoid calling a shell function with the same name as
939 an external command.
940 As an example, the completion function for process IDs uses this
942 style with the processes tag to generate the IDs to complete and
943 the list of processes to display (if the verbose style is
944 `true'). The list produced by the command should look like the
945 output of the ps command. The first line is not displayed, but
946 is searched for the string `PID' (or `pid') to find the position
947 of the process IDs in the following lines. If the line does not
948 contain `PID', the first numbers in each of the other lines are
949 taken as the process IDs to complete.
950 Note that the completion function generally has to call the
952 specified command for each attempt to generate the completion
953 list. Hence care should be taken to specify only commands that
954 take a short time to run, and in particular to avoid any that
955 may never terminate.
956 command-path
958 This is a list of directories to search for commands to com‐
959 plete. The default for this style is the value of the special
960 parameter path.
961 commands
963 This is used by the function completing sub-commands for the
964 system initialisation scripts (residing in /etc/init.d or some‐
965 where not too far away from that). Its values give the default
966 commands to complete for those commands for which the completion
967 function isn't able to find them out automatically. The default
968 for this style are the two strings `start' and `stop'.
969 complete
971 This is used by the _expand_alias function when invoked as a
972 bindable command. If it set to `true' and the word on the com‐
973 mand line is not the name of an alias, matching alias names will
974 be completed.
975 completer
977 The strings given as the value of this style provide the names
978 of the completer functions to use. The available completer func‐
979 tions are described in the section `Control Functions' below.
980 Each string may be either the name of a completer function or a
982 string of the form `function:name'. In the first case the com‐
983 pleter field of the context will contain the name of the com‐
984 pleter without the leading underscore and with all other under‐
985 scores replaced by hyphens. In the second case the function is
986 the name of the completer to call, but the context will contain
987 the user-defined name in the completer field of the context. If
988 the name starts with a hyphen, the string for the context will
989 be build from the name of the completer function as in the first
990 case with the name appended to it. For example:
991 zstyle ':completion:*' completer _complete _complete:-foo
993 Here, completion will call the _complete completer twice, once
995 using `complete' and once using `complete-foo' in the completer
996 field of the context. Normally, using the same completer more
997 than once only makes sense when used with the `functions:name'
998 form, because otherwise the context name will be the same in all
999 calls to the completer; possible exceptions to this rule are the
1000 _ignored and _prefix completers.
1001 The default value for this style is `_complete _ignored': only
1003 completion will be done, first using the ignored-patterns style
1004 and the $fignore array and then without ignoring matches.
1005 condition
1007 This style is used by the _list completer function to decide if
1008 insertion of matches should be delayed unconditionally. The
1009 default is `true'.
1010 disabled
1012 If this is set to `true', the _expand_alias completer and bind‐
1013 able command will try to expand disabled aliases, too. The
1014 default is `false'.
1015 disable-stat
1017 This is used with an empty tag by the _cvs function to decide
1018 whether the zsh/stat module should be used to generate names of
1019 modified files in the appropriate places (this is its only use).
1020 If the style is set, completion will use the ls command.
1021 domains
1023 A list of names of network domains for completion. If this is
1024 not set, domain names will be taken from the file
1025 /etc/resolv.conf.
1026 expand This style is used when completing strings consisting of multi‐
1028 ple parts, such as path names.
1029 If one of its values is the string `prefix', the partially typed
1031 word from the line will be expanded as far as possible even if
1032 trailing parts cannot be completed.
1033 If one of its values is the string `suffix', matching names for
1035 components after the first ambiguous one will also be added.
1036 This means that the resulting string is the longest unambiguous
1037 string possible. However, menu completion can be used to cycle
1038 through all matches.
1039 fake This style may be set for any completion context. It specifies
1041 additional strings that will always be completed in that con‐
1042 text. The form of each string is `value:description'; the colon
1043 and description may be omitted, but any literal colons in value
1044 must be quoted with a backslash. Any description provided is
1045 shown alongside the value in completion listings.
1046 It is important to use a sufficiently restrictive context when
1048 specifying fake strings. Note that the styles fake-files and
1049 fake-parameters provide additional features when completing
1050 files or parameters.
1051 fake-files
1053 This style is used when completing files and looked up without a
1054 tag. Its values are of the form `dir:names...'. This will add
1055 the names (strings separated by spaces) as possible matches when
1056 completing in the directory dir, even if no such files really
1057 exist.
1058 This can be useful on systems that support special filesystems
1060 whose top-level pathnames can not be listed or generated with
1061 glob patterns. It can also be used for directories for which
1062 one does not have read permission.
1063 fake-parameters
1065 This is used by the completion function for parameter names.
1066 Its values are names of parameters that might not yet be set but
1067 should be completed nonetheless. Each name may also be followed
1068 by a colon and a string specifying the type of the parameter
1069 (like `scalar', `array' or `integer'). If the type is given,
1070 the name will only be completed if parameters of that type are
1071 required in the particular context. Names for which no type is
1072 specified will always be completed.
1073 file-patterns
1075 This is used by the standard function for completing filenames,
1076 _files. If the style is unset up to three tags are offered,
1077 `globbed-files',`directories' and `all-files', depending on the
1078 types of files expected by the caller of _files. The first two
1079 (`globbed-files' and `directories') are normally offered
1080 together to make it easier to complete files in sub-directories.
1081 The file-patterns style provides alternatives to the default
1083 tags, which are not used. Its value consists of elements of the
1084 form `pattern:tag'; each string may contain any number of such
1085 specifications separated by spaces.
1086 The pattern is a pattern that is to be used to generate file‐
1088 names. Any occurrence of the sequence `%p' is replaced by any
1089 pattern(s) passed by the function calling _files. Colons in the
1090 pattern must be preceded by a backslash to make them distin‐
1091 guishable from the colon before the tag. If more than one pat‐
1092 tern is needed, the patterns can be given inside braces, sepa‐
1093 rated by commas.
1094 The tags of all strings in the value will be offered by _files
1096 and used when looking up other styles. Any tags in the same
1097 word will be offered at the same time and before later words.
1098 If no `:tag' is given the `files' tag will be used.
1099 The tag may also be followed by an optional second colon and a
1101 description, which will be used for the `%d' in the value of the
1102 format style (if that is set) instead of the default description
1103 supplied by the completion function. If the description given
1104 here contains itself a `%d', that is replaced with the descrip‐
1105 tion supplied by the completion function.
1106 For example, to make the rm command first complete only names of
1108 object files and then the names of all files if there is no
1109 matching object file:
1110 zstyle ':completion:*:*:rm:*' file-patterns \
1112 '*.o:object-files' '%p:all-files'
1113 To alter the default behaviour of file completion --- offer
1115 files matching a pattern and directories on the first attempt,
1116 then all files --- to offer only matching files on the first
1117 attempt, then directories, and finally all files:
1118 zstyle ':completion:*' file-patterns \
1120 '%p:globbed-files' '*(-/):directories' '*:all-files'
1121 This works even where there is no special pattern: _files
1123 matches all files using the pattern `*' at the first step and
1124 stops when it sees this pattern. Note also it will never try a
1125 pattern more than once for a single completion attempt.
1126 During the execution of completion functions, the EXTENDED_GLOB
1128 option is in effect, so the characters `#', `~' and `^' have
1129 special meanings in the patterns.
1130 file-sort
1132 The standard filename completion function uses this style with‐
1133 out a tag to determine in which order the names should be
1134 listed; menu completion will cycle through them in the same
1135 order. The possible values are: `size' to sort by the size of
1136 the file; `links' to sort by the number of links to the file;
1137 `modification' (or `time' or `date') to sort by the last modifi‐
1138 cation time; `access' to sort by the last access time; and
1139 `inode' (or `change') to sort by the last inode change time. If
1140 the style is set to any other value, or is unset, files will be
1141 sorted alphabetically by name. If the value contains the string
1142 `reverse', sorting is done in the opposite order.
1143 filter This is used by the LDAP plugin for e-mail address completion to
1145 specify the attributes to match against when filtering entries.
1146 So for example, if the style is set to `sn', matching is done
1147 against surnames. Standard LDAP filtering is used so normal
1148 completion matching is bypassed. If this style is not set, the
1149 LDAP plugin is skipped. You may also need to set the command
1150 style to specify how to connect to your LDAP server.
1151 force-list
1153 This forces a list of completions to be shown at any point where
1154 listing is done, even in cases where the list would usually be
1155 suppressed. For example, normally the list is only shown if
1156 there are at least two different matches. By setting this style
1157 to `always', the list will always be shown, even if there is
1158 only a single match that will immediately be accepted. The
1159 style may also be set to a number. In this case the list will
1160 be shown if there are at least that many matches, even if they
1161 would all insert the same string.
1162 This style is tested for the default tag as well as for each tag
1164 valid for the current completion. Hence the listing can be
1165 forced only for certain types of match.
1166 format If this is set for the descriptions tag, its value is used as a
1168 string to display above matches in completion lists. The
1169 sequence `%d' in this string will be replaced with a short
1170 description of what these matches are. This string may also
1171 contain the sequences to specify output attributes, such as
1172 `%B', `%S' and `%{...%}'.
1173 The style is tested with each tag valid for the current comple‐
1175 tion before it is tested for the descriptions tag. Hence dif‐
1176 ferent format strings can be defined for different types of
1177 match.
1178 Note also that some completer functions define additional
1180 `%'-sequences. These are described for the completer functions
1181 that make use of them.
1182 Some completion functions display messages that may be cus‐
1184 tomised by setting this style for the messages tag. Here, the
1185 `%d' is replaced with a message given by the completion func‐
1186 tion.
1187 Finally, the format string is looked up with the warnings tag,
1189 for use when no matches could be generated at all. In this case
1190 the `%d' is replaced with the descriptions for the matches that
1191 were expected separated by spaces. The sequence `%D' is
1192 replaced with the same descriptions separated by newlines.
1193 It is possible to use printf-style field width specifiers with
1195 `%d' and similar escape sequences. This is handled by the zfor‐
1196 mat builtin command from the zsh/zutil module, see zshmod‐
1197 ules(1).
1198 glob This is used by the _expand completer. If it is set to `true'
1200 (the default), globbing will be attempted on the words resulting
1201 from a previous substitution (see the substitute style) or else
1202 the original string from the line.
1203 global If this is set to `true' (the default), the _expand_alias com‐
1205 pleter and bindable command will try to expand global aliases.
1206 group-name
1208 The completion system can group different types of matches,
1209 which appear in separate lists. This style can be used to give
1210 the names of groups for particular tags. For example, in com‐
1211 mand position the completion system generates names of builtin
1212 and external commands, names of aliases, shell functions and
1213 parameters and reserved words as possible completions. To have
1214 the external commands and shell functions listed separately:
1215 zstyle ':completion:*:*:-command-:*:commands' group-name commands
1217 zstyle ':completion:*:*:-command-:*:functions' group-name functions
1218 As a consequence, any match with the same tag will be displayed
1220 in the same group.
1221 If the name given is the empty string the name of the tag for
1223 the matches will be used as the name of the group. So, to have
1224 all different types of matches displayed separately, one can
1225 just set:
1226 zstyle ':completion:*' group-name ''
1228 All matches for which no group name is defined will be put in a
1230 group named -default-.
1231 group-order
1233 This style is additional to the group-name style to specify the
1234 order for display of the groups defined by that style (compare
1235 tag-order, which determines which completions appear at all).
1236 The groups named are shown in the given order; any other groups
1237 are shown in the order defined by the completion function.
1238 For example, to have names of builtin commands, shell functions
1240 and external commands appear in that order when completing in
1241 command position:
1242 zstyle ':completion:*:*:-command-:*' group-order \
1244 builtins functions commands
1245 groups A list of names of UNIX groups. If this is not set, group names
1247 are taken from the YP database or the file `/etc/group'.
1248 hidden If this is set to true, matches for the given context will not
1250 be listed, although any description for the matches set with the
1251 format style will be shown. If it is set to `all', not even the
1252 description will be displayed.
1253 Note that the matches will still be completed; they are just not
1255 shown in the list. To avoid having matches considered as possi‐
1256 ble completions at all, the tag-order style can be modified as
1257 described below.
1258 hosts A list of names of hosts that should be completed. If this is
1260 not set, hostnames are taken from the file `/etc/hosts'.
1261 hosts-ports
1263 This style is used by commands that need or accept hostnames and
1264 network ports. The strings in the value should be of the form
1265 `host:port'. Valid ports are determined by the presence of
1266 hostnames; multiple ports for the same host may appear.
1267 ignore-line
1269 This is tested for each tag valid for the current completion.
1270 If it is set to `true', none of the words that are already on
1271 the line will be considered as possible completions. If it is
1272 set to `current', the word the cursor is on will not be consid‐
1273 ered as a possible completion. The value `current-shown' is
1274 similar but only applies if the list of completions is currently
1275 shown on the screen. Finally, if the style is set to `other',
1276 no word apart from the current one will be considered as a pos‐
1277 sible completion.
1278 The values `current' and `current-shown' are a bit like the
1280 opposite of the accept-exact style: only strings with missing
1281 characters will be completed.
1282 Note that you almost certainly don't want to set this to `true'
1284 or `other' for a general context such as `:completion:*'. This
1285 is because it would disallow completion of, for example, options
1286 multiple times even if the command in question accepts the
1287 option more than once.
1288 ignore-parents
1290 The style is tested without a tag by the function completing
1291 pathnames in order to determine whether to ignore the names of
1292 directories already mentioned in the current word, or the name
1293 of the current working directory. The value must include one or
1294 both of the following strings:
1295 parent The name of any directory whose path is already contained
1297 in the word on the line is ignored. For example, when
1298 completing after foo/../, the directory foo will not be
1299 considered a valid completion.
1300 pwd The name of the current working directory will not be
1302 completed; hence, for example, completion after ../ will
1303 not use the name of the current directory.
1304 In addition, the value may include one or both of:
1306 .. Ignore the specified directories only when the word on
1308 the line contains the substring `../'.
1309 directory
1311 Ignore the specified directories only when names of
1312 directories are completed, not when completing names of
1313 files.
1314 Excluded values act in a similar fashion to values of the
1316 ignored-patterns style, so they can be restored to consideration
1317 by the _ignored completer.
1318 ignored-patterns
1320 A list of patterns; any trial completion matching one of the
1321 patterns will be excluded from consideration. The _ignored com‐
1322 pleter can appear in the list of completers to restore the
1323 ignored matches. This is a more configurable version of the
1324 shell parameter $fignore.
1325 Note that the EXTENDED_GLOB option is set during the execution
1327 of completion functions, so the characters `#', `~' and `^' have
1328 special meanings in the patterns.
1329 insert This style is used by the _all_matches completer to decide
1331 whether to insert the list of all matches unconditionally
1332 instead of adding the list as another match.
1333 insert-ids
1335 When completing process IDs, for example as arguments to the
1336 kill and wait builtins the name of a command may be converted to
1337 the appropriate process ID. A problem arises when the process
1338 name typed is not unique. By default (or if this style is set
1339 explicitly to `menu') the name will be converted immediately to
1340 a set of possible IDs, and menu completion will be started to
1341 cycle through them.
1342 If the value of the style is `single', the shell will wait until
1344 the user has typed enough to make the command unique before con‐
1345 verting the name to an ID; attempts at completion will be unsuc‐
1346 cessful until that point. If the value is any other string,
1347 menu completion will be started when the string typed by the
1348 user is longer than the common prefix to the corresponding IDs.
1349 insert-tab
1351 If this is set to `true', the completion system will insert a
1352 TAB character (assuming that was used to start completion)
1353 instead of performing completion when there is no non-blank
1354 character to the left of the cursor. If it is set to `false',
1355 completion will be done even there.
1356 The value may also contain the substrings `pending' or `pend‐
1358 ing=val'. In this case, the typed character will be inserted
1359 instead of staring completion when there is unprocessed input
1360 pending. If a val is given, completion will not be done if
1361 there are at least that many characters of unprocessed input.
1362 This is often useful when pasting characters into a terminal.
1363 Note however, that it relies on the $PENDING special parameter
1364 from the zsh/zle module being set properly which is not guaran‐
1365 teed on all platforms.
1366 The default value of this style is `true' except for completion
1368 within vared builtin command where it is `false'.
1369 insert-unambiguous
1371 This is used by the _match and _approximate completers. These
1372 completers are often used with menu completion since the word
1373 typed may bear little resemblance to the final completion. How‐
1374 ever, if this style is `true', the completer will start menu
1375 completion only if it could find no unambiguous initial string
1376 at least as long as the original string typed by the user.
1377 In the case of the _approximate completer, the completer field
1379 in the context will already have been set to one of correct-num
1380 or approximate-num, where num is the number of errors that were
1381 accepted.
1382 In the case of the _match completer, the style may also be set
1384 to the string `pattern'. Then the pattern on the line is left
1385 unchanged if it does not match unambiguously.
1386 keep-prefix
1388 This style is used by the _expand completer. If it is `true',
1389 the completer will try to keep a prefix containing a tilde or
1390 parameter expansion. Hence, for example, the string `~/f*'
1391 would be expanded to `~/foo' instead of `/home/user/foo'. If
1392 the style is set to `changed' (the default), the prefix will
1393 only be left unchanged if there were other changes between the
1394 expanded words and the original word from the command line. Any
1395 other value forces the prefix to be expanded unconditionally.
1396 The behaviour of expand when this style is true is to cause
1398 _expand to give up when a single expansion with the restored
1399 prefix is the same as the original; hence any remaining com‐
1400 pleters may be called.
1401 last-prompt
1403 This is a more flexible form of the ALWAYS_LAST_PROMPT option.
1404 If it is true, the completion system will try to return the cur‐
1405 sor to the previous command line after displaying a completion
1406 list. It is tested for all tags valid for the current comple‐
1407 tion, then the default tag. The cursor will be moved back to
1408 the previous line if this style is `true' for all types of
1409 match. Note that unlike the ALWAYS_LAST_PROMPT option this is
1410 independent of the numeric prefix argument.
1411 list This style is used by the _history_complete_word bindable com‐
1413 mand. If it is set to `true' it has no effect. If it is set to
1414 `false' matches will not be listed. This overrides the setting
1415 of the options controlling listing behaviour, in particular
1416 AUTO_LIST. The context always starts with `:completion:his‐
1417 tory-words'.
1418 list-colors
1420 If the zsh/complist module is loaded, this style can be used to
1421 set color specifications. This mechanism replaces the use of
1422 the ZLS_COLORS and ZLS_COLOURS parameters described in the sec‐
1423 tion `The zsh/complist Module' in zshmodules(1), but the syntax
1424 is the same.
1425 If this style is set for the default tag, the strings in the
1427 value are taken as specifications that are to be used every‐
1428 where. If it is set for other tags, the specifications are used
1429 only for matches of the type described by the tag. For this to
1430 work best, the group-name style must be set to an empty string.
1431 In addition to setting styles for specific tags, it is also pos‐
1433 sible to use group names specified explicitly by the group-name
1434 tag together with the `(group)' syntax allowed by the ZLS_COLORS
1435 and ZLS_COLOURS parameters and simply using the default tag.
1436 It is possible to use any color specifications already set up
1438 for the GNU version of the ls command:
1439 zstyle ':completion:*:default' list-colors ${(s.:.)LS_COLORS}
1441 The default colors are the same as for the GNU ls command and
1443 can be obtained by setting the style to an empty string (i.e.
1444 '').
1445 list-grouped
1447 If this style is `true' (the default), the completion system
1448 will try to make certain completion listings more compact by
1449 grouping matches. For example, options for commands that have
1450 the same description (shown when the verbose style is set to
1451 `true') will appear as a single entry. However, menu selection
1452 can be used to cycle through all the matches.
1453 list-packed
1455 This is tested for each tag valid in the current context as well
1456 as the default tag. If it is set to `true', the corresponding
1457 matches appear in listings as if the LIST_PACKED option were
1458 set. If it is set to `false', they are listed normally.
1459 list-prompt
1461 If this style is set for the default tag, completion lists that
1462 don't fit on the screen can be scrolled (see the description of
1463 the zsh/complist module in zshmodules(1)). The value, if not
1464 the empty string, will be displayed after every screenful and
1465 the shell will prompt for a key press; if the style is set to
1466 the empty string, a default prompt will be used.
1467 The value may contain the escape sequences: `%l' or `%L', which
1469 will be replaced by the number of the last line displayed and
1470 the total number of lines; `%m' or `%M', the number of the last
1471 match shown and the total number of matches; and `%p' and `%P',
1472 `Top' when at the beginning of the list, `Bottom' when at the
1473 end and the position shown as a percentage of the total length
1474 otherwise. In each case the form with the uppercase letter will
1475 be replaced by a string of fixed width, padded to the right
1476 with spaces, while the lowercase form will be replaced by a
1477 variable width string. As in other prompt strings, the escape
1478 sequences `%S', `%s', `%B', `%b', `%U', `%u' for entering and
1479 leaving the display modes standout, bold and underline are also
1480 available, as is the form `%{...%}' for enclosing escape
1481 sequences which display with zero width.
1482 list-rows-first
1484 This style is tested in the same way as the list-packed style
1485 and determines whether matches are to be listed in a rows-first
1486 fashion as if the LIST_ROWS_FIRST option were set.
1487 list-suffixes
1489 This style is used by the function that completes filenames. If
1490 it is true, and completion is attempted on a string containing
1491 multiple partially typed pathname components, all ambiguous com‐
1492 ponents will be shown. Otherwise, completion stops at the first
1493 ambiguous component.
1494 list-separator
1496 The value of this style is used in completion listing to sepa‐
1497 rate the string to complete from a description when possible
1498 (e.g. when completing options). It defaults to `--' (two
1499 hyphens).
1500 local This is for use with functions that complete URLs for which the
1502 corresponding files are available directly from the filing sys‐
1503 tem. Its value should consist of three strings: a hostname, the
1504 path to the default web pages for the server, and the directory
1505 name used by a user placing web pages within their home area.
1506 For example:
1508 zstyle ':completion:*' local toast \
1510 /var/http/public/toast public_html
1511 Completion after `http://toast/stuff/' will look for files in
1513 the directory /var/http/public/toast/stuff, while completion
1514 after `http://toast/~yousir/' will look for files in the direc‐
1515 tory ~yousir/public_html.
1516 mail-directory
1518 If set, zsh will assume that mailbox files can be found in the
1519 directory specified. It defaults to `~/Mail'.
1520 match-original
1522 This is used by the _match completer. If it is set to only,
1523 _match will try to generate matches without inserting a `*' at
1524 the cursor position. If set to any other non-empty value, it
1525 will first try to generate matches without inserting the `*' and
1526 if that yields no matches, it will try again with the `*'
1527 inserted. If it is unset or set to the empty string, matching
1528 will only be performed with the `*' inserted.
1529 matcher
1531 This style is tested separately for each tag valid in the cur‐
1532 rent context. Its value is added to any match specifications
1533 given by the matcher-list style. It should be in the form
1534 described in the section `Matching Control' in zshcompwid(1).
1535 matcher-list
1537 This style can be set to a list of match specifications that are
1538 to be applied everywhere. Match specifications are described in
1539 the section `Matching Control' in zshcompwid(1). The completion
1540 system will try them one after another for each completer
1541 selected. For example, to try first simple completion and, if
1542 that generates no matches, case-insensitive completion:
1543 zstyle ':completion:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}'
1545 By default each specification replaces the previous one; how‐
1547 ever, if a specification is prefixed with +, it is added to the
1548 existing list. Hence it is possible to create increasingly gen‐
1549 eral specifications without repetition:
1550 zstyle ':completion:*' matcher-list '' '+m{a-Z}={A-Z}' '+m{A-Z}={a-z}'
1552 It is possible to create match specifications valid for particu‐
1554 lar completers by using the third field of the context. For
1555 example, to use the completers _complete and _prefix but only
1556 allow case-insensitive completion with _complete:
1557 zstyle ':completion:*' completer _complete _prefix
1559 zstyle ':completion:*:complete:*' matcher-list \
1560 '' 'm:{a-zA-Z}={A-Za-z}'
1561 User-defined names, as explained for the completer style, are
1563 available. This makes it possible to try the same completer
1564 more than once with different match specifications each time.
1565 For example, to try normal completion without a match specifica‐
1566 tion, then normal completion with case-insensitive matching,
1567 then correction, and finally partial-word completion:
1568 zstyle ':completion:*' completer _complete _correct _complete:foo
1570 zstyle ':completion:*:complete:*' matcher-list \
1571 '' 'm:{a-zA-Z}={A-Za-z}'
1572 zstyle ':completion:*:foo:*' matcher-list \
1573 'm:{a-zA-Z}={A-Za-z} r:|[-_./]=* r:|=*'
1574 If the style is unset in any context no match specification is
1576 applied. Note also that some completers such as _correct and
1577 _approximate do not use the match specifications at all, though
1578 these completers will only ever called once even if the
1579 matcher-list contains more than one element.
1580 Where multiple specifications are useful, note that the entire
1582 completion is done for each element of matcher-list, which can
1583 quickly reduce the shell's performance. As a rough rule of
1584 thumb, one to three strings will give acceptable performance.
1585 On the other hand, putting multiple space-separated values into
1586 the same string does not have an appreciable impact on perfor‐
1587 mance.
1588 max-errors
1590 This is used by the _approximate and _correct completer func‐
1591 tions to determine the maximum number of errors to allow. The
1592 completer will try to generate completions by first allowing one
1593 error, then two errors, and so on, until either a match or
1594 matches were found or the maximum number of errors given by this
1595 style has been reached.
1596 If the value for this style contains the string `numeric', the
1598 completer function will take any numeric argument as the maximum
1599 number of errors allowed. For example, with
1600 zstyle ':completion:*:approximate:::' max-errors 2 numeric
1602 two errors are allowed if no numeric argument is given, but with
1604 a numeric argument of six (as in `ESC-6 TAB'), up to six errors
1605 are accepted. Hence with a value of `0 numeric', no correcting
1606 completion will be attempted unless a numeric argument is given.
1607 If the value contains the string `not-numeric', the completer
1609 will not try to generate corrected completions when given a
1610 numeric argument, so in this case the number given should be
1611 greater than zero. For example, `2 not-numeric' specifies that
1612 correcting completion with two errors will usually be performed,
1613 but if a numeric argument is given, correcting completion will
1614 not be performed.
1615 The default value for this style is `2 numeric'.
1617 max-matches-width
1619 This style is used to determine the trade off between the width
1620 of the display used for matches and the width used for their
1621 descriptions when the verbose style is in effect. The value
1622 gives the number of display columns to reserve for the matches.
1623 The default is half the width of the screen.
1624 This has the most impact when several matches have the same
1626 description and so will be grouped together. Increasing the
1627 style will allow more matches to be grouped together; decreasing
1628 it will allow more of the description to be visible.
1629 menu If this is true in the context of any of the tags defined for
1631 the current completion menu completion will be used. The value
1632 for a specific tag will take precedence over that for the
1633 `default' tag.
1634 If none of the values found in this way is true but at least one
1636 is set to `auto', the shell behaves as if the AUTO_MENU option
1637 is set.
1638 If one of the values is explicitly set to false, menu completion
1640 will be explicitly turned off, overriding the MENU_COMPLETE
1641 option and other settings.
1642 In the form `yes=num', where `yes' may be any of the true values
1644 (`yes', `true', `on' and `1'), menu completion will be turned on
1645 if there are at least num matches. In the form `yes=long', menu
1646 completion will be turned on if the list does not fit on the
1647 screen. This does not activate menu completion if the widget
1648 normally only lists completions, but menu completion can be
1649 activated in that case with the value `yes=long-list' (Typi‐
1650 cally, the value `select=long-list' described later is more use‐
1651 ful as it provides control over scrolling.)
1652 Similarly, with any of the `false' values (as in `no=10'), menu
1654 completion will not be used if there are num or more matches.
1655 The value of this widget also controls menu selection, as imple‐
1657 mented by the zsh/complist module. The following values may
1658 appear either alongside or instead of the values above.
1659 If the value contains the string `select', menu selection will
1661 be started unconditionally.
1662 In the form `select=num', menu selection will only be started if
1664 there are at least num matches. If the values for more than one
1665 tag provide a number, the smallest number is taken.
1666 Menu selection can be turned off explicitly by defining a value
1668 containing the string`no-select'.
1669 It is also possible to start menu selection only if the list of
1671 matches does not fit on the screen by using the value
1672 `select=long'. To start menu selection even if the current wid‐
1673 get only performs listing, use the value `select=long-list'.
1674 To turn on menu completion or menu selection when a there are a
1676 certain number of matches or the list of matches does not fit on
1677 the screen, both of `yes=' and `select=' may be given twice,
1678 once with a number and once with `long' or `long-list'.
1679 Finally, it is possible to activate two special modes of menu
1681 selection. The word `interactive' in the value causes interac‐
1682 tive mode to be entered immediately when menu selection is
1683 started; see the description of the zsh/complist module in zsh‐
1684 modules(1).RE for a description of interactive mode. Including
1685 the string `search' does the same for incremental search mode.
1686 To select backward incremental search, include the string
1687 `search-backward'. )
1688 muttrc If set, gives the location of the mutt configuration
1690 file. It defaults to `~/.muttrc'.
1691 numbers
1693 This is used with the jobs tag. If it is `true', the
1694 shell will complete job numbers instead of the shortest
1695 unambiguous prefix of the job command text. If the value
1696 is a number, job numbers will only be used if that many
1697 words from the job descriptions are required to resolve
1698 ambiguities. For example, if the value is `1', strings
1699 will only be used if all jobs differ in the first word on
1700 their command lines.
1701 old-list
1703 This is used by the _oldlist completer. If it is set to
1704 `always', then standard widgets which perform listing
1705 will retain the current list of matches, however they
1706 were generated; this can be turned off explicitly with
1707 the value `never', giving the behaviour without the
1708 _oldlist completer. If the style is unset, or any other
1709 value, then the existing list of completions is displayed
1710 if it is not already; otherwise, the standard completion
1711 list is generated; this is the default behaviour of
1712 _oldlist. However, if there is an old list and this
1713 style contains the name of the completer function that
1714 generated the list, then the old list will be used even
1715 if it was generated by a widget which does not do list‐
1716 ing.
1717 For example, suppose you type ^Xc to use the _cor‐
1719 rect_word widget, which generates a list of corrections
1720 for the word under the cursor. Usually, typing ^D would
1721 generate a standard list of completions for the word on
1722 the command line, and show that. With _oldlist, it will
1723 instead show the list of corrections already generated.
1724 As another example consider the _match completer: with
1726 the insert-unambiguous style set to `true' it inserts
1727 only a common prefix string, if there is any. However,
1728 this may remove parts of the original pattern, so that
1729 further completion could produce more matches than on the
1730 first attempt. By using the _oldlist completer and set‐
1731 ting this style to _match, the list of matches generated
1732 on the first attempt will be used again.
1733 old-matches
1735 This is used by the _all_matches completer to decide if
1736 an old list of matches should be used if one exists.
1737 This is selected by one of the `true' values or by the
1738 string `only'. If the value is `only', _all_matches will
1739 only use an old list and won't have any effect on the
1740 list of matches currently being generated.
1741 If this style is set it is generally unwise to call the
1743 _all_matches completer unconditionally. One possible use
1744 is for either this style or the completer style to be
1745 defined with the -e option to zstyle to make the style
1746 conditional.
1747 old-menu
1749 This is used by the _oldlist completer. It controls how
1750 menu completion behaves when a completion has already
1751 been inserted and the user types a standard completion
1752 key such as TAB. The default behaviour of _oldlist is
1753 that menu completion always continues with the existing
1754 list of completions. If this style is set to `false',
1755 however, a new completion is started if the old list was
1756 generated by a different completion command; this is the
1757 behaviour without the _oldlist completer.
1758 For example, suppose you type ^Xc to generate a list of
1760 corrections, and menu completion is started in one of the
1761 usual ways. Usually, or with this style set to false,
1762 typing TAB at this point would start trying to complete
1763 the line as it now appears. With _oldlist, it instead
1764 continues to cycle through the list of corrections.
1765 original
1767 This is used by the _approximate and _correct completers
1768 to decide if the original string should be added as a
1769 possible completion. Normally, this is done only if
1770 there are at least two possible corrections, but if this
1771 style is set to `true', it is always added. Note that
1772 the style will be examined with the completer field in
1773 the context name set to correct-num or approximate-num,
1774 where num is the number of errors that were accepted.
1775 packageset
1777 This style is used when completing arguments of the
1778 Debian `dpkg' program. It contains an override for the
1779 default package set for a given context. For example,
1780 zstyle ':completion:*:complete:dpkg:option--status-1:*' \
1782 packageset avail
1783 causes available packages, rather than only installed
1785 packages, to be completed for `dpkg --status'.
1786 path The function that completes color names uses this style
1788 with the colors tag. The value should be the pathname of
1789 a file containing color names in the format of an X11
1790 rgb.txt file. If the style is not set but this file is
1791 found in one of various standard locations it will be
1792 used as the default.
1793 pine-directory
1795 If set, specifies the directory containing PINE mailbox
1796 files. It defaults to `~/mail'.
1797 ports A list of Internet service names (network ports) to com‐
1799 plete. If this is not set, service names are taken from
1800 the file `/etc/services'.
1801 prefix-hidden
1803 This is used for certain completions which share a common
1804 prefix, for example command options beginning with
1805 dashes. If it is `true', the prefix will not be shown in
1806 the list of matches.
1807 The default value for this style is `false'.
1809 prefix-needed
1811 This, too, is used for matches with a common prefix. If
1812 it is set to `true' this common prefix must be typed by
1813 the user to generate the matches. In the case of command
1814 options, this means that the initial `-', `+', or `--'
1815 must be typed explicitly before option names will be com‐
1816 pleted.
1817 The default value for this style is `true'.
1819 preserve-prefix
1821 This style is used when completing path names. Its value
1822 should be a pattern matching an initial prefix of the
1823 word to complete that should be left unchanged under all
1824 circumstances. For example, on some Unices an initial
1825 `//' (double slash) has a special meaning; setting this
1826 style to the string `//' will preserve it. As another
1827 example, setting this style to `?:/' under Cygwin would
1828 allow completion after `a:/...' and so on.
1829 range This is used by the _history completer and the _his‐
1831 tory_complete_word bindable command to decide which words
1832 should be completed.
1833 If it is a singe number, only the last N words from the
1835 history will be completed.
1836 If it is a range of the form `max:slice', the last slice
1838 words will be completed; then if that yields no matches,
1839 the slice words before those will be tried and so on.
1840 This process stops either when at least one match was
1841 been found, or max words have been tried.
1842 The default is to complete all words from the history at
1844 once.
1845 regular
1847 This style is used by the _expand_alias completer and
1848 bindable command. If set to `true' (the default), regu‐
1849 lar aliases will be expanded but only in command posi‐
1850 tion. If it is set to `false', regular aliases will
1851 never be expanded. If it is set to `always', regular
1852 aliases will be expanded even if not in command position.
1853 remote-access
1855 If set to false, certain commands will be prevented from
1856 making Internet connections to retrieve remote informa‐
1857 tion. This includes the completion for the CVS command.
1858 It is not always possible to know if connections are in
1860 fact to a remote site, so some may be prevented unneces‐
1861 sarily.
1862 remove-all-dups
1864 The _history_complete_word bindable command and the _his‐
1865 tory completer use this to decide if all duplicate
1866 matches should be removed, rather than just consecutive
1867 duplicates.
1868 select-prompt
1870 If this is set for the default tag, its value will be
1871 displayed during menu selection (see the menu style
1872 above) when the completion list does not fit on the
1873 screen as a whole. The same escapes as for the
1874 list-prompt style are understood, except that the numbers
1875 refer to the match or line the mark is on. A default
1876 prompt is used when the value is the empty string.
1877 select-scroll
1879 This style is tested for the default tag and determines
1880 how a completion list is scrolled during a menu selection
1881 (see the menu style above) when the completion list does
1882 not fit on the screen as a whole. If the value is `0'
1883 (zero), the list is scrolled by half-screenfuls; if it is
1884 a positive integer, the list is scrolled by the given
1885 number of lines; if it is a negative number, the list is
1886 scrolled by a screenful minus the absolute value of the
1887 given number of lines. The default is to scroll by sin‐
1888 gle lines.
1889 separate-sections
1891 This style is used with the manuals tag when completing
1892 names of manual pages. If it is `true', entries for dif‐
1893 ferent sections are added separately using tag names of
1894 the form `manual.X', where X is the section number. When
1895 the group-name style is also in effect, pages from dif‐
1896 ferent sections will appear separately. This style is
1897 also used similarly with the words style when completing
1898 words for the dict command. It allows words from differ‐
1899 ent dictionary databases to be added separately. The
1900 default for this style is `false'.
1901 show-completer
1903 Tested whenever a new completer is tried. If it is true,
1904 the completion system outputs a progress message in the
1905 listing area showing what completer is being tried. The
1906 message will be overwritten by any output when comple‐
1907 tions are found and is removed after completion is fin‐
1908 ished.
1909 single-ignored
1911 This is used by the _ignored completer when there is only
1912 one match. If its value is `show', the single match will
1913 be displayed but not inserted. If the value is `menu',
1914 then the single match and the original string are both
1915 added as matches and menu completion is started, making
1916 it easy to select either of them.
1917 sort Many completion widgets call _description at some point
1919 which decides whether the matches are added sorted or
1920 unsorted (often indirectly via _wanted or _requested).
1921 This style can be set explicitly to one of the usual true
1922 or false values as an override. If it is not set for the
1923 context, the standard behaviour of the calling widget is
1924 used.
1925 The style is tested first against the full context
1927 including the tag, and if that fails to produce a value
1928 against the context without the tag.
1929 If the calling widget explicitly requests unsorted
1931 matches, this is usually honoured. However, the default
1932 (unsorted) behaviour of completion for the command his‐
1933 tory may be overridden by setting the style to true.
1934 In the _expand completer, if it is set to `true', the
1936 expansions generated will always be sorted. If it is set
1937 to `menu', then the expansions are only sorted when they
1938 are offered as single strings but not in the string con‐
1939 taining all possible expansions.
1940 special-dirs
1942 Normally, the completion code will not produce the direc‐
1943 tory names `.' and `..' as possible completions. If this
1944 style is set to `true', it will add both `.' and `..' as
1945 possible completions; if it is set to `..', only `..'
1946 will be added.
1947 The following example sets special-dirs to `..' when the
1949 current prefix is empty, is a single `.', or consists
1950 only of a path beginning with `../'. Otherwise the value
1951 is `false'.
1952 zstyle -e ':completion:*' special-dirs \
1954 '[[ $PREFIX = (../)#(|.|..) ]] && reply=(..)'
1955 squeeze-slashes
1957 If set to `true', sequences of slashes in filename paths
1958 (for example in `foo//bar') will be treated as a single
1959 slash. This is the usual behaviour of UNIX paths. How‐
1960 ever, by default the file completion function behaves as
1961 if there were a `*' between the slashes.
1962 stop If set to `true', the _history_complete_word bindable
1964 command will stop once when reaching the beginning or end
1965 of the history. Invoking _history_complete_word will
1966 then wrap around to the opposite end of the history. If
1967 this style is set to `false' (the default), _history_com‐
1968 plete_word will loop immediately as in a menu completion.
1969 strip-comments
1971 If set to `true', this style causes non-essential comment
1972 text to be removed from completion matches. Currently it
1973 is only used when completing e-mail addresses where it
1974 removes any display name from the addresses, cutting them
1975 down to plain user@host form.
1976 subst-globs-only
1978 This is used by the _expand completer. If it is set to
1979 `true', the expansion will only be used if it resulted
1980 from globbing; hence, if expansions resulted from the use
1981 of the substitute style described below, but these were
1982 not further changed by globbing, the expansions will be
1983 rejected.
1984 The default for this style is `false'.
1986 substitute
1988 This boolean style controls whether the _expand completer
1989 will first try to expand all substitutions in the string
1990 (such as `$(...)' and `${...}').
1991 The default is `true'.
1993 suffix This is used by the _expand completer if the word starts
1995 with a tilde or contains a parameter expansion. If it is
1996 set to `true', the word will only be expanded if it
1997 doesn't have a suffix, i.e. if it is something like
1998 `~foo' or `$foo' rather than `~foo/' or `$foo/bar',
1999 unless that suffix itself contains characters eligible
2000 for expansion. The default for this style is `true'.
2001 tag-order
2003 This provides a mechanism for sorting how the tags avail‐
2004 able in a particular context will be used.
2005 The values for the style are sets of space-separated
2007 lists of tags. The tags in each value will be tried at
2008 the same time; if no match is found, the next value is
2009 used. (See the file-patterns style for an exception to
2010 this behavior.)
2011 For example:
2013 zstyle ':completion:*:complete:-command-:*' tag-order \
2015 'commands functions'
2016 specifies that completion in command position first
2018 offers external commands and shell functions. Remaining
2019 tags will be tried if no completions are found.
2020 In addition to tag names, each string in the value may
2022 take one of the following forms:
2023 - If any value consists of only a hyphen, then only
2025 the tags specified in the other values are gener‐
2026 ated. Normally all tags not explicitly selected
2027 are tried last if the specified tags fail to gen‐
2028 erate any matches. This means that a single value
2029 consisting only of a single hyphen turns off com‐
2030 pletion.
2031 ! tags...
2033 A string starting with an exclamation mark speci‐
2034 fies names of tags that are not to be used. The
2035 effect is the same as if all other possible tags
2036 for the context had been listed.
2037 tag:label ...
2039 Here, tag is one of the standard tags and label is
2040 an arbitrary name. Matches are generated as nor‐
2041 mal but the name label is used in contexts instead
2042 of tag. This is not useful in words starting with
2043 !.
2044 If the label starts with a hyphen, the tag is
2046 prepended to the label to form the name used for
2047 lookup. This can be used to make the completion
2048 system try a certain tag more than once, supplying
2049 different style settings for each attempt; see
2050 below for an example.
2051 tag:label:description
2053 As before, but description will replace the `%d'
2054 in the value of the format style instead of the
2055 default description supplied by the completion
2056 function. Spaces in the description must be
2057 quoted with a backslash. A `%d' appearing in
2058 description is replaced with the description given
2059 by the completion function.
2060 In any of the forms above the tag may be a pattern or
2062 several patterns in the form `{pat1,pat2...}'. In this
2063 case all matching tags will be used except for any given
2064 explicitly in the same string.
2065 One use of these features is to try one tag more than
2067 once, setting other styles differently on each attempt,
2068 but still to use all the other tags without having to
2069 repeat them all. For example, to make completion of
2070 function names in command position ignore all the comple‐
2071 tion functions starting with an underscore the first time
2072 completion is tried:
2073 zstyle ':completion:*:*:-command-:*' tag-order \
2075 'functions:-non-comp *' functions
2076 zstyle ':completion:*:functions-non-comp' ignored-patterns '_*'
2077 On the first attempt, all tags will be offered but the
2079 functions tag will be replaced by functions-non-comp.
2080 The ignored-patterns style is set for this tag to exclude
2081 functions starting with an underscore. If there are no
2082 matches, the second value of the tag-order style is used
2083 which completes functions using the default tag, this
2084 time presumably including all function names.
2085 The matches for one tag can be split into different
2087 groups. For example:
2088 zstyle ':completion:*' tag-order \
2090 'options:-long:long\ options
2091 options:-short:short\ options
2092 options:-single-letter:single\ letter\ options'
2093 zstyle ':completion:*:options-long' ignored-patterns '[-+](|-|[^-]*)'
2095 zstyle ':completion:*:options-short' ignored-patterns '--*' '[-+]?'
2096 zstyle ':completion:*:options-single-letter' ignored-patterns '???*'
2097 With the group-names style set, options beginning with
2099 `--', options beginning with a single `-' or `+' but con‐
2100 taining multiple characters, and single-letter options
2101 will be displayed in separate groups with different
2102 descriptions.
2103 Another use of patterns is to try multiple match specifi‐
2105 cations one after another. The matcher-list style offers
2106 something similar, but it is tested very early in the
2107 completion system and hence can't be set for single com‐
2108 mands nor for more specific contexts. Here is how to try
2109 normal completion without any match specification and, if
2110 that generates no matches, try again with case-insensi‐
2111 tive matching, restricting the effect to arguments of the
2112 command foo:
2113 zstyle ':completion:*:*:foo:*' tag-order '*' '*:-case'
2115 zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}'
2116 First, all the tags offered when completing after foo are
2118 tried using the normal tag name. If that generates no
2119 matches, the second value of tag-order is used, which
2120 tries all tags again except that this time each has -case
2121 appended to its name for lookup of styles. Hence this
2122 time the value for the matcher style from the second call
2123 to zstyle in the example is used to make completion
2124 case-insensitive.
2125 It is possible to use the -e option of the zstyle builtin
2127 command to specify conditions for the use of particular
2128 tags. For example:
2129 zstyle -e '*:-command-:*' tag-order '
2131 if [[ -n $PREFIX$SUFFIX ]]; then
2132 reply=( )
2133 else
2134 reply=( - )
2135 fi'
2136 Completion in command position will be attempted only if
2138 the string typed so far is not empty. This is tested
2139 using the PREFIX special parameter; see zshcompwid for a
2140 description of parameters which are special inside com‐
2141 pletion widgets. Setting reply to an empty array pro‐
2142 vides the default behaviour of trying all tags at once;
2143 setting it to an array containing only a hyphen disables
2144 the use of all tags and hence of all completions.
2145 If no tag-order style has been defined for a context, the
2147 strings `(|*-)argument-* (|*-)option-* values' and
2148 `options' plus all tags offered by the completion func‐
2149 tion will be used to provide a sensible default behavior
2150 that causes arguments (whether normal command arguments
2151 or arguments of options) to be completed before option
2152 names for most commands.
2153 urls This is used together with the the urls tag by functions
2155 completing URLs.
2156 If the value consists of more than one string, or if the
2158 only string does not name a file or directory, the
2159 strings are used as the URLs to complete.
2160 If the value contains only one string which is the name
2162 of a normal file the URLs are taken from that file (where
2163 the URLs may be separated by white space or newlines).
2164 Finally, if the only string in the value names a direc‐
2166 tory, the directory hierarchy rooted at this directory
2167 gives the completions. The top level directory should be
2168 the file access method, such as `http', `ftp', `bookmark'
2169 and so on. In many cases the next level of directories
2170 will be a filename. The directory hierarchy can descend
2171 as deep as necessary.
2172 For example,
2174 zstyle ':completion:*' urls ~/.urls
2176 mkdir -p ~/.urls/ftp/ftp.zsh.org/pub/development
2177 allows completion of all the components of the URL
2179 ftp://ftp.zsh.org/pub/development after suitable commands
2180 such as `netscape' or `lynx'. Note, however, that access
2181 methods and files are completed separately, so if the
2182 hosts style is set hosts can be completed without refer‐
2183 ence to the urls style.
2184 See the description in the function _urls itself for more
2186 information (e.g. `more $^fpath/_urls(N)').
2187 use-cache
2189 If this is set, the completion caching layer is activated
2190 for any completions which use it (via the _store_cache,
2191 _retrieve_cache, and _cache_invalid functions). The
2192 directory containing the cache files can be changed with
2193 the cache-path style.
2194 use-compctl
2196 If this style is set to a string not equal to false, 0,
2197 no, and off, the completion system may use any completion
2198 specifications defined with the compctl builtin command.
2199 If the style is unset, this is done only if the zsh/com‐
2200 pctl module is loaded. The string may also contain the
2201 substring `first' to use completions defined with `com‐
2202 pctl -T', and the substring `default' to use the comple‐
2203 tion defined with `compctl -D'.
2204 Note that this is only intended to smooth the transition
2206 from compctl to the new completion system and may disap‐
2207 pear in the future.
2208 Note also that the definitions from compctl will only be
2210 used if there is no specific completion function for the
2211 command in question. For example, if there is a function
2212 _foo to complete arguments to the command foo, compctl
2213 will never be invoked for foo. However, the compctl ver‐
2214 sion will be tried if foo only uses default completion.
2215 use-perl
2217 Various parts of the function system use awk to extract
2218 words from files or command output as this universally
2219 available. However, many versions of awk have arbitrary
2220 limits on the size of input. If this style is set, perl
2221 will be used instead. This is almost always preferable
2222 if perl is available on your system.
2223 Currently this is only used in completions for `make',
2225 but it may be extended depending on authorial frustra‐
2226 tion.
2227 users This may be set to a list of usernames to be completed.
2229 If it is not set or the string on the line doesn't match
2230 any of the strings in this list, all usernames will be
2231 completed.
2232 users-hosts
2234 The values of this style should be of the form
2235 `user@host' or `user:host'. It is used for commands that
2236 need pairs of user- and hostnames. These commands will
2237 complete usernames from this style (only), and will
2238 restrict subsequent hostname completion to hosts paired
2239 with that user in one of the values of the style.
2240 It is possible to group values for sets of commands which
2242 allow a remote login, such as rlogin and ssh, by using
2243 the my-accounts tag. Similarly, values for sets of com‐
2244 mands which usually refer to the accounts of other peo‐
2245 ple, such as talk and finger, can be grouped by using the
2246 other-accounts tag. More ambivalent commands may use the
2247 accounts tag.
2248 users-hosts-ports
2250 Like users-hosts but used for commands like telnet and
2251 containing strings of the form `user@host:port'.
2252 verbose
2254 If set, as it is by default, the completion listing is
2255 more verbose. In particular many commands show descrip‐
2256 tions for options if this style is `true'.
2257 word This is used by the _list completer, which prevents the
2259 insertion of completions until a second completion
2260 attempt when the line has not changed. The normal way of
2261 finding out if the line has changed is to compare its
2262 entire contents between the two occasions. If this style
2263 is true, the comparison is instead performed only on the
2264 current word. Hence if completion is performed on
2265 another word with the same contents, completion will not
2266 be delayed.
2267
2269 The initialization script compinit redefines all the widgets which per‐
2270 form completion to call the supplied widget function _main_complete.
2271 This function acts as a wrapper calling the so-called `completer' func‐
2272 tions that generate matches. If _main_complete is called with argu‐
2273 ments, these are taken as the names of completer functions to be called
2274 in the order given. If no arguments are given, the set of functions to
2275 try is taken from the completer style. For example, to use normal com‐
2276 pletion and correction if that doesn't generate any matches:
2277 zstyle ':completion:*' completer _complete _correct
2279 after calling compinit. The default value for this style is `_complete
2281 _ignored', i.e. normally only ordinary completion is tried, first with
2282 the effect of the ignored-patterns style and then without it. The
2283 _main_complete function uses the return value of the completer func‐
2284 tions to decide if other completers should be called. If the return
2285 value is zero, no other completers are tried and the _main_complete
2286 function returns.
2287 If the first argument to _main_complete is a single hyphen, the argu‐
2289 ments will not be taken as names of completers. Instead, the second
2290 argument gives a name to use in the completer field of the context and
2291 the other arguments give a command name and arguments to call to gener‐
2292 ate the matches.
2293 The following completer functions are contained in the distribution,
2295 although users may write their own. Note that in contexts the leading
2296 underscore is stripped, for example basic completion is performed in
2297 the context `:completion::complete:...'.
2298 _all_matches
2300 This completer can be used to add a string consisting of all
2301 other matches. As it influences later completers it must appear
2302 as the first completer in the list. The list of all matches is
2303 affected by the avoid-completer and old-matches styles described
2304 above.
2305 It may be useful to use the _generic function described below to
2307 bind _all_matches to its own keystroke, for example:
2308 zle -C all-matches complete-word _generic
2310 bindkey '^Xa' all-matches
2311 zstyle ':completion:all-matches:*' old-matches only
2312 zstyle ':completion:all-matches::::' completer _all_matches
2313 _approximate
2315 This is similar to the basic _complete completer but allows the
2316 completions to undergo corrections. The maximum number of
2317 errors can be specified by the max-errors style; see the
2318 description of approximate matching in zshexpn(1) for how errors
2319 are counted. Normally this completer will only be tried after
2320 the normal _complete completer:
2321 zstyle ':completion:*' completer _complete _approximate
2323 This will give correcting completion if and only if normal com‐
2325 pletion yields no possible completions. When corrected comple‐
2326 tions are found, the completer will normally start menu comple‐
2327 tion allowing you to cycle through these strings.
2328 This completer uses the tags corrections and original when gen‐
2330 erating the possible corrections and the original string. The
2331 format style for the former may contain the additional sequences
2332 `%e' and `%o' which will be replaced by the number of errors
2333 accepted to generate the corrections and the original string,
2334 respectively.
2335 The completer progressively increases the number of errors
2337 allowed up to the limit by the max-errors style, hence if a com‐
2338 pletion is found with one error, no completions with two errors
2339 will be shown, and so on. It modifies the completer name in the
2340 context to indicate the number of errors being tried: on the
2341 first try the completer field contains `approximate-1', on the
2342 second try `approximate-2', and so on.
2343 When _approximate is called from another function, the number of
2345 errors to accept may be passed with the -a option. The argument
2346 is in the same format as the max-errors style, all in one
2347 string.
2348 Note that this completer (and the _correct completer mentioned
2350 below) can be quite expensive to call, especially when a large
2351 number of errors are allowed. One way to avoid this is to set
2352 up the completer style using the -e option to zstyle so that
2353 some completers are only used when completion is attempted a
2354 second time on the same string, e.g.:
2355 zstyle -e ':completion:*' completer '
2357 if [[ $_last_try != "$HISTNO$BUFFER$CURSOR" ]]; then
2358 _last_try="$HISTNO$BUFFER$CURSOR"
2359 reply=(_complete _match _prefix)
2360 else
2361 reply=(_ignored _correct _approximate)
2362 fi'
2363 This uses the HISTNO parameter and the BUFFER and CURSOR special
2365 parameters that are available inside zle and completion widgets
2366 to find out if the command line hasn't changed since the last
2367 time completion was tried. Only then are the _ignored, _correct
2368 and _approximate completers called.
2369 _complete
2371 This completer generates all possible completions in a con‐
2372 text-sensitive manner, i.e. using the settings defined with the
2373 compdef function explained above and the current settings of all
2374 special parameters. This gives the normal completion behaviour.
2375 To complete arguments of commands, _complete uses the utility
2377 function _normal, which is in turn responsible for finding the
2378 particular function; it is described below. Various contexts of
2379 the form -context- are handled specifically. These are all men‐
2380 tioned above as possible arguments to the #compdef tag.
2381 Before trying to find a function for a specific context, _com‐
2383 plete checks if the parameter `compcontext' is set. Setting
2384 `compcontext' allows the usual completion dispatching to be
2385 overridden which is useful in places such as a function that
2386 uses vared for input. If it is set to an array, the elements are
2387 taken to be the possible matches which will be completed using
2388 the tag `values' and the description `value'. If it is set to an
2389 associative array, the keys are used as the possible completions
2390 and the values (if non-empty) are used as descriptions for the
2391 matches. If `compcontext' is set to a string containing colons,
2392 it should be of the form `tag:descr:action'. In this case the
2393 tag and descr give the tag and description to use and the action
2394 indicates what should be completed in one of the forms accepted
2395 by the _arguments utility function described below.
2396 Finally, if `compcontext' is set to a string without colons, the
2398 value is taken as the name of the context to use and the func‐
2399 tion defined for that context will be called. For this purpose,
2400 there is a special context named -command-line- that completes
2401 whole command lines (commands and their arguments). This is not
2402 used by the completion system itself but is nonetheless handled
2403 when explicitly called.
2404 _correct
2406 Generate corrections, but not completions, for the current word;
2407 this is similar to _approximate but will not allow any number of
2408 extra characters at the cursor as that completer does. The
2409 effect is similar to spell-checking. It is based on _approxi‐
2410 mate, but the completer field in the context name is correct.
2411 For example, with:
2413 zstyle ':completion:::::' completer _complete _correct _approximate
2415 zstyle ':completion:*:correct:::' max-errors 2 not-numeric
2416 zstyle ':completion:*:approximate:::' max-errors 3 numeric
2417 correction will accept up to two errors. If a numeric argument
2419 is given, correction will not be performed, but correcting com‐
2420 pletion will be, and will accept as many errors as given by the
2421 numeric argument. Without a numeric argument, first correction
2422 and then correcting completion will be tried, with the first one
2423 accepting two errors and the second one accepting three errors.
2424 When _correct is called as a function, the number of errors to
2426 accept may be given following the -a option. The argument is in
2427 the same form a values to the accept style, all in one string.
2428 This completer function is intended to be used without the
2430 _approximate completer or, as in the example, just before it.
2431 Using it after the _approximate completer is useless since
2432 _approximate will at least generate the corrected strings gener‐
2433 ated by the _correct completer -- and probably more.
2434 _expand
2436 This completer function does not really perform completion, but
2437 instead checks if the word on the command line is eligible for
2438 expansion and, if it is, gives detailed control over how this
2439 expansion is done. For this to happen, the completion system
2440 needs to be invoked with complete-word, not expand-or-complete
2441 (the default binding for TAB), as otherwise the string will be
2442 expanded by the shell's internal mechanism before the completion
2443 system is started. Note also this completer should be called
2444 before the _complete completer function.
2445 The tags used when generating expansions are all-expansions for
2447 the string containing all possible expansions, expansions when
2448 adding the possible expansions as single matches and original
2449 when adding the original string from the line. The order in
2450 which these strings are generated, if at all, can be controlled
2451 by the group-order and tag-order styles, as usual.
2452 The format string for all-expansions and for expansions may con‐
2454 tain the sequence `%o' which will be replaced by the original
2455 string from the line.
2456 The kind of expansion to be tried is controlled by the substi‐
2458 tute, glob and subst-globs-only styles.
2459 It is also possible to call _expand as a function, in which case
2461 the different modes may be selected with options: -s for substi‐
2462 tute, -g for glob and -o for subst-globs-only.
2463 _expand_alias
2465 If the word the cursor is on is an alias, it is expanded and no
2466 other completers are called. The types of aliases which are to
2467 be expanded can be controlled with the styles regular, global
2468 and disabled.
2469 This function is also a bindable command, see the section `Bind‐
2471 able Commands' below.
2472 _history
2474 Complete words from the shell's command history. This com‐
2475 pleter can be controlled by the remove-all-dups, and sort styles
2476 as for the _history_complete_word bindable command, see the sec‐
2477 tion `Bindable Commands' below and the section `Completion Sys‐
2478 tem Configuration' above.
2479 _ignored
2481 The ignored-patterns style can be set to a list of patterns
2482 which are compared against possible completions; matching ones
2483 are removed. With this completer those matches can be rein‐
2484 stated, as if no ignored-patterns style were set. The completer
2485 actually generates its own list of matches; which completers are
2486 invoked is determined in the same way as for the _prefix com‐
2487 pleter. The single-ignored style is also available as described
2488 above.
2489 _list This completer allows the insertion of matches to be delayed
2491 until completion is attempted a second time without the word on
2492 the line being changed. On the first attempt, only the list of
2493 matches will be shown. It is affected by the styles condition
2494 and word, see the section `Completion System Configuration'
2495 above.
2496 _match This completer is intended to be used after the _complete com‐
2498 pleter. It behaves similarly but the string on the command line
2499 may be a pattern to match against trial completions. This gives
2500 the effect of the GLOB_COMPLETE option.
2501 Normally completion will be performed by taking the pattern from
2503 the line, inserting a `*' at the cursor position and comparing
2504 the resulting pattern with the possible completions generated.
2505 This can be modified with the match-original style described
2506 above.
2507 The generated matches will be offered in a menu completion
2509 unless the insert-unambiguous style is set to `true'; see the
2510 description above for other options for this style.
2511 Note that matcher specifications defined globally or used by the
2513 completion functions (the styles matcher-list and matcher) will
2514 not be used.
2515 _menu This completer was written as simple example function to show
2517 how menu completion can be enabled in shell code. However, it
2518 has the notable effect of disabling menu selection which can be
2519 useful with _generic based widgets. It should be used as the
2520 first completer in the list. Note that this is independent of
2521 the setting of the MENU_COMPLETE option and does not work with
2522 the other menu completion widgets such as reverse-menu-complete,
2523 or accept-and-menu-complete.
2524 _oldlist
2526 This completer controls how the standard completion widgets
2527 behave when there is an existing list of completions which may
2528 have been generated by a special completion (i.e. a sepa‐
2529 rately-bound completion command). It allows the ordinary com‐
2530 pletion keys to continue to use the list of completions thus
2531 generated, instead of producing a new list of ordinary contex‐
2532 tual completions. It should appear in the list of completers
2533 before any of the widgets which generate matches. It uses two
2534 styles: old-list and old-menu, see the section `Completion Sys‐
2535 tem Configuration' above.
2536 _prefix
2538 This completer can be used to try completion with the suffix
2539 (everything after the cursor) ignored. In other words, the suf‐
2540 fix will not be considered to be part of the word to complete.
2541 The effect is similar to the expand-or-complete-prefix command.
2542 The completer style is used to decide which other completers are
2544 to be called to generate matches. If this style is unset, the
2545 list of completers set for the current context is used --
2546 except, of course, the _prefix completer itself. Furthermore,
2547 if this completer appears more than once in the list of com‐
2548 pleters only those completers not already tried by the last
2549 invocation of _prefix will be called.
2550 For example, consider this global completer style:
2552 zstyle ':completion:*' completer \
2554 _complete _prefix _correct _prefix:foo
2555 Here, the _prefix completer tries normal completion but ignoring
2557 the suffix. If that doesn't generate any matches, and neither
2558 does the call to the _correct completer after it, _prefix will
2559 be called a second time and, now only trying correction with the
2560 suffix ignored. On the second invocation the completer part of
2561 the context appears as `foo'.
2562 To use _prefix as the last resort and try only normal completion
2564 when it is invoked:
2565 zstyle ':completion:*' completer _complete ... _prefix
2567 zstyle ':completion::prefix:*' completer _complete
2568 The add-space style is also respected. If it is set to `true'
2570 then _prefix will insert a space between the matches generated
2571 (if any) and the suffix.
2572 Note that this completer is only useful if the COMPLETE_IN_WORD
2574 option is set; otherwise, the cursor will be moved to the end of
2575 the current word before the completion code is called and hence
2576 there will be no suffix.
2577 bashcompinit
2579 This function provides compatibility with bash's programmable
2580 completion system. When run it will define the functions, comp‐
2581 gen and complete which correspond to the bash builtins with the
2582 same names. It will then be possible to use completion specifi‐
2583 cations and functions written for bash.
2584
2586 In addition to the context-dependent completions provided, which are
2587 expected to work in an intuitively obvious way, there are a few widgets
2588 implementing special behaviour which can be bound separately to keys.
2589 The following is a list of these and their default bindings.
2590 _bash_completions
2592 This function is used by two widgets, _bash_complete-word and
2593 _bash_list-choices. It exists to provide compatibility with
2594 completion bindings in bash. The last character of the binding
2595 determines what is completed: `!', command names; `$', environ‐
2596 ment variables; `@', host names; `/', file names; `~' user
2597 names. In bash, the binding preceded by `\e' gives completion,
2598 and preceded by `^X' lists options. As some of these bindings
2599 clash with standard zsh bindings, only `\e~' and `^X~' are bound
2600 by default. To add the rest, the following should be added to
2601 .zshrc after compinit has been run:
2602 for key in '!' '$' '@' '/' '~'; do
2604 bindkey "\e$key" _bash_complete-word
2605 bindkey "^X$key" _bash_list-choices
2606 done
2607 This includes the bindings for `~' in case they were already
2609 bound to something else; the completion code does not override
2610 user bindings.
2611 _correct_filename (^XC)
2613 Correct the filename path at the cursor position. Allows up to
2614 six errors in the name. Can also be called with an argument to
2615 correct a filename path, independently of zle; the correction is
2616 printed on standard output.
2617 _correct_word (^Xc)
2619 Performs correction of the current argument using the usual con‐
2620 textual completions as possible choices. This stores the string
2621 `correct-word' in the function field of the context name and
2622 then calls the _correct completer.
2623 _expand_alias (^Xa)
2625 This function can be used as a completer and as a bindable com‐
2626 mand. It expands the word the cursor is on if it is an alias.
2627 The types of alias expanded can be controlled with the styles
2628 regular, global and disabled.
2629 When used as a bindable command there is one additional feature
2631 that can be selected by setting the complete style to `true'.
2632 In this case, if the word is not the name of an alias,
2633 _expand_alias tries to complete the word to a full alias name
2634 without expanding it. It leaves the cursor directly after the
2635 completed word so that invoking _expand_alias once more will
2636 expand the now-complete alias name.
2637 _expand_word (^Xe)
2639 Performs expansion on the current word: equivalent to the stan‐
2640 dard expand-word command, but using the _expand completer.
2641 Before calling it, the function field of the context is set to
2642 `expand-word'.
2643 _generic
2645 This function is not defined as a widget and not bound by
2646 default. However, it can be used to define a widget and will
2647 then store the name of the widget in the function field of the
2648 context and call the completion system. This allows custom com‐
2649 pletion widgets with their own set of style settings to be
2650 defined easily. For example, to define a widget that performs
2651 normal completion and starts menu selection:
2652 zle -C foo complete-word _generic
2654 bindkey '...' foo
2655 zstyle ':completion:foo:*' menu yes select=1
2656 _history_complete_word (\e/)
2658 Complete words from the shell's command history. This uses the
2659 list, remove-all-dups, sort, and stop styles.
2660 _most_recent_file (^Xm)
2662 Complete the name of the most recently modified file matching
2663 the pattern on the command line (which may be blank). If given
2664 a numeric argument N, complete the Nth most recently modified
2665 file. Note the completion, if any, is always unique.
2666 _next_tags (^Xn)
2668 This command alters the set of matches used to that for the next
2669 tag, or set of tags, either as given by the tag-order style or
2670 as set by default; these matches would otherwise not be avail‐
2671 able. Successive invocations of the command cycle through all
2672 possible sets of tags.
2673 _read_comp (^X^R)
2675 Prompt the user for a string, and use that to perform completion
2676 on the current word. There are two possibilities for the
2677 string. First, it can be a set of words beginning `_', for
2678 example `_files -/', in which case the function with any argu‐
2679 ments will be called to generate the completions. Unambiguous
2680 parts of the function name will be completed automatically (nor‐
2681 mal completion is not available at this point) until a space is
2682 typed.
2683 Second, any other string will be passed as a set of arguments to
2685 compadd and should hence be an expression specifying what should
2686 be completed.
2687 A very restricted set of editing commands is available when
2689 reading the string: `DEL' and `^H' delete the last character;
2690 `^U' deletes the line, and `^C' and `^G' abort the function,
2691 while `RET' accepts the completion. Note the string is used
2692 verbatim as a command line, so arguments must be quoted in
2693 accordance with standard shell rules.
2694 Once a string has been read, the next call to _read_comp will
2696 use the existing string instead of reading a new one. To force
2697 a new string to be read, call _read_comp with a numeric argu‐
2698 ment.
2699 _complete_debug (^X?)
2701 This widget performs ordinary completion, but captures in a tem‐
2702 porary file a trace of the shell commands executed by the com‐
2703 pletion system. Each completion attempt gets its own file. A
2704 command to view each of these files is pushed onto the editor
2705 buffer stack.
2706 _complete_help (^Xh)
2708 This widget displays information about the context names, the
2709 tags, and the completion functions used when completing at the
2710 current cursor position. If given a numeric argument other than
2711 1 (as in `ESC-2 ^Xh'), then the styles used and the contexts for
2712 which they are used will be shown, too.
2713 Note that the information about styles may be incomplete; it
2715 depends on the information available from the completion func‐
2716 tions called, which in turn is determined by the user's own
2717 styles and other settings.
2718 _complete_tag (^Xt)
2720 This widget completes symbol tags created by the etags or ctags
2721 programmes (note there is no connection with the completion sys‐
2722 tem's tags) stored in a file TAGS, in the format used by etags,
2723 or tags, in the format created by ctags. It will look back up
2724 the path hierarchy for the first occurrence of either file; if
2725 both exist, the file TAGS is preferred. You can specify the
2726 full path to a TAGS or tags file by setting the parameter $TAGS‐
2727 FILE or $tagsfile respectively. The corresponding completion
2728 tags used are etags and vtags, after emacs and vi respectively.
2729
2731 Descriptions follow for utility functions that may be useful when writ‐
2732 ing completion functions. If functions are installed in subdirecto‐
2733 ries, most of these reside in the Base subdirectory. Like the example
2734 functions for commands in the distribution, the utility functions gen‐
2735 erating matches all follow the convention of returning zero if they
2736 generated completions and non-zero if no matching completions could be
2737 added.
2738 Two more features are offered by the _main_complete function. The
2740 arrays compprefuncs and comppostfuncs may contain names of functions
2741 that are to be called immediately before or after completion has been
2742 tried. A function will only be called once unless it explicitly rein‐
2743 serts itself into the array.
2744 _all_labels [ -x ] [ -12VJ ] tag name descr [ command args ... ]
2746 This is a convenient interface to the _next_label function
2747 below, implementing the loop shown in the _next_label example.
2748 The command and its arguments are called to generate the
2749 matches. The options stored in the parameter name will automat‐
2750 ically be inserted into the args passed to the command. Nor‐
2751 mally, they are put directly after the command, but if one of
2752 the args is a single hyphen, they are inserted directly before
2753 that. If the hyphen is the last argument, it will be removed
2754 from the argument list before the command is called. This
2755 allows _all_labels to be used in almost all cases where the
2756 matches can be generated by a single call to the compadd builtin
2757 command or by a call to one of the utility functions.
2758 For example:
2760 local expl
2762 ...
2763 if _requested foo; then
2764 ...
2765 _all_labels foo expl '...' compadd ... - $matches
2766 fi
2767 Will complete the strings from the matches parameter, using com‐
2769 padd with additional options which will take precedence over
2770 those generated by _all_labels.
2771 _alternative [ -C name ] spec ...
2773 This function is useful in simple cases where multiple tags are
2774 available. Essentially it implements a loop like the one
2775 described for the _tags function below.
2776 The tags to use and the action to perform if a tag is requested
2778 are described using the specs which are of the form:
2779 `tag:descr:action'. The tags are offered using _tags and if the
2780 tag is requested, the action is executed with the given descrip‐
2781 tion descr. The actions are those accepted by the _arguments
2782 function (described below), excluding the `->state' and `=...'
2783 forms.
2784 For example, the action may be a simple function call:
2786 _alternative \
2788 'users:user:_users' \
2789 'hosts:host:_hosts'
2790 offers usernames and hostnames as possible matches, generated by
2792 the _users and _hosts functions respectively.
2793 Like _arguments, this functions uses _all_labels to execute the
2795 actions, which will loop over all sets of tags. Special han‐
2796 dling is only required if there is an additional valid tag, for
2797 example inside a function called from _alternative.
2798 Like _tags this function supports the -C option to give a dif‐
2800 ferent name for the argument context field.
2801 _arguments [ -swWACRS ] [ -O name ] [ -M matchspec ] [ : ] spec ...
2803 This function can be used to give a complete specification for
2804 completion for a command whose arguments follow standard UNIX
2805 option and argument conventions. The following forms specify
2806 individual sets of options and arguments; to avoid ambiguity,
2807 these may be separated from the options to _arguments itself by
2808 a single colon.
2809 n:message:action
2811 n::message:action
2812 This describes the n'th normal argument. The message
2813 will be printed above the matches generated and the
2814 action indicates what can be completed in this position
2815 (see below). If there are two colons before the message
2816 the argument is optional. If the message contains only
2817 white space, nothing will be printed above the matches
2818 unless the action adds an explanation string itself.
2819 :message:action
2821 ::message:action
2822 Similar, but describes the next argument, whatever number
2823 that happens to be. If all arguments are specified in
2824 this form in the correct order the numbers are unneces‐
2825 sary.
2826 *:message:action
2828 *::message:action
2829 *:::message:action
2830 This describes how arguments (usually non-option argu‐
2831 ments, those not beginning with - or +) are to be com‐
2832 pleted when neither of the first two forms was provided.
2833 Any number of arguments can be completed in this fashion.
2834 With two colons before the message, the words special
2836 array and the CURRENT special parameter are modified to
2837 refer only to the normal arguments when the action is
2838 executed or evaluated. With three colons before the mes‐
2839 sage they are modified to refer only to the normal argu‐
2840 ments covered by this description.
2841 optspec
2843 optspec:...
2844 This describes an option. The colon indicates handling
2845 for one or more arguments to the option; if it is not
2846 present, the option is assumed to take no arguments.
2847 By default, options are multi-character name, one `-word'
2849 per option. With -s, options may be single characters,
2850 with more than one option per word, although words start‐
2851 ing with two hyphens, such as `--prefix', are still con‐
2852 sidered complete option names. This is suitable for
2853 standard GNU options.
2854 The combination of -s with -w allows single-letter
2856 options to be combined in a single word even if one or
2857 more of the options take arguments. For example, if -a
2858 takes an argument, with no -s `-ab' is considered as a
2859 single (unhandled) option; with -s -ab is an option with
2860 the argument `b'; with both -s and -w, -ab may be the
2861 option -a and the option(-b) with arguments still to
2862 come.
2863 The option -W takes this a stage further: it is possible
2865 to complete single-letter options even after an argument
2866 that occurs in the same word. However, it depends on the
2867 action performed whether options will really be completed
2868 at this point. For more control, use a utility function
2869 like _guard as part of the action.
2870 The following forms are available for the initial opt‐
2872 spec, whether or not the option has arguments.
2873 *optspec
2875 Here optspec is one of the remaining forms below.
2876 This indicates the following optspec may be
2877 repeated. Otherwise if the corresponding option
2878 is already present on the command line to the left
2879 of the cursor it will not be offered again.
2880 -optname
2882 +optname
2883 In the simplest form the optspec is just the
2884 option name beginning with a minus or a plus sign,
2885 such as `-foo'. The first argument for the option
2886 (if any) must follow as a separate word directly
2887 after the option.
2888 Either of `-+optname' and `+-optname' can be used
2890 to specify that -optname and +optname are both
2891 valid.
2892 In all the remaining forms, the leading `-' may be
2894 replaced by or paired with `+' in this way.
2895 -optname-
2897 The first argument of the option must come
2898 directly after the option name in the same word.
2899 For example, `-foo-:...' specifies that the com‐
2900 pleted option and argument will look like
2901 `-fooarg'.
2902 -optname+
2904 The first argument may appear immediately after
2905 optname in the same word, or may appear as a sepa‐
2906 rate word after the option. For example,
2907 `-foo+:...' specifies that the completed option
2908 and argument will look like either `-fooarg' or
2909 `-foo arg'.
2910 -optname=
2912 The argument may appear as the next word, or in
2913 same word as the option name provided that it is
2914 separated from it by an equals sign, for example
2915 `-foo=arg' or `-foo arg'.
2916 -optname=-
2918 The argument to the option must appear after an
2919 equals sign in the same word, and may not be given
2920 in the next argument.
2921 optspec[explanation]
2923 An explanation string may be appended to any of
2924 the preceding forms of optspec by enclosing it in
2925 brackets, as in `-q[query operation]'.
2926 The verbose style is used to decide whether the
2928 explanation strings are displayed with the option
2929 in a completion listing.
2930 If no bracketed explanation string is given but
2932 the auto-description style is set and only one
2933 argument is described for this optspec, the value
2934 of the style is displayed, with any appearance of
2935 the sequence `%d' in it replaced by the message of
2936 the first optarg that follows the optspec; see
2937 below.
2938 It is possible for options with a literal `+' or `=' to appear,
2940 but that character must be quoted, for example `-\+'.
2941 Each optarg following an optspec must take one of the following
2943 forms:
2944 :message:action
2946 ::message:action
2947 An argument to the option; message and action are treated
2948 as for ordinary arguments. In the first form, the argu‐
2949 ment is mandatory, and in the second form it is optional.
2950 This group may be repeated for options which take multi‐
2952 ple arguments. In other words, :message1:action1:mes‐
2953 sage2:action2 specifies that the option takes two argu‐
2954 ments.
2955 :*pattern:message:action
2957 :*pattern::message:action
2958 :*pattern:::message:action
2959 This describes multiple arguments. Only the last optarg
2960 for an option taking multiple arguments may be given in
2961 this form. If the pattern is empty (i.e., :*:), all the
2962 remaining words on the line are to be completed as
2963 described by the action; otherwise, all the words up to a
2964 word matching the pattern are to be completed using the
2965 action.
2966 Multiple colons are treated as for the `*:...' forms for
2968 ordinary arguments: when the message is preceded by two
2969 colons, the words special array and the CURRENT special
2970 parameter are modified during the execution or evaluation
2971 of the action to refer only to the words after the
2972 option. When preceded by three colons, they are modified
2973 to refer only to the words covered by this description.
2974 Any literal colon in an optname, message, or action must be preceded by
2976 a backslash, `\:'.
2977 Each of the forms above may be preceded by a list in parentheses of
2979 option names and argument numbers. If the given option is on the com‐
2980 mand line, the options and arguments indicated in parentheses will not
2981 be offered. For example, `(-two -three 1)-one:...' completes the
2982 option `-one'; if this appears on the command line, the options -two
2983 and -three and the first ordinary argument will not be completed after
2984 it. `(-foo):...' specifies an ordinary argument completion; -foo will
2985 not be completed if that argument is already present.
2986 Other items may appear in the list of excluded options to indicate var‐
2988 ious other items that should not be applied when the current specifica‐
2989 tion is matched: a single star (*) for the rest arguments (i.e. a spec‐
2990 ification of the form `*:...'); a colon (:) for all normal
2991 (non-option-) arguments; and a hyphen (-) for all options. For exam‐
2992 ple, if `(*)' appears before an option and the option appears on the
2993 command line, the list of remaining arguments (those shown in the above
2994 table beginning with `*:') will not be completed.
2995 To aid in reuse of specifications, it is possible to precede any of the
2997 forms above with `!'; then the form will no longer be completed,
2998 although if the option or argument appears on the command line they
2999 will be skipped as normal. The main use for this is when the arguments
3000 are given by an array, and _arguments is called repeatedly for more
3001 specific contexts: on the first call `_arguments $global_options' is
3002 used, and on subsequent calls `_arguments !$^global_options'.
3003 In each of the forms above the action determines how completions should
3005 be generated. Except for the `->string' form below, the action will be
3006 executed by calling the _all_labels function to process all tag labels.
3007 No special handling of tags is needed unless a function call introduces
3008 a new one.
3009 The forms for action are as follows.
3011 (single unquoted space)
3013 This is useful where an argument is required but it is not pos‐
3014 sible or desirable to generate matches for it. The message will
3015 be displayed but no completions listed. Note that even in this
3016 case the colon at the end of the message is needed; it may only
3017 be omitted when neither a message nor an action is given.
3018 (item1 item2 ...)
3020 One of a list of possible matches, for example:
3021 :foo:(foo bar baz)
3023 ((item1\:desc1 ...))
3025 Similar to the above, but with descriptions for each possible
3026 match. Note the backslash before the colon. For example,
3027 :foo:((a\:bar b\:baz))
3029 The matches will be listed together with their descriptions if
3031 the description style is set with the values tag in the context.
3032 ->string
3034 In this form, _arguments processes the arguments and options and
3035 then returns control to the calling function with parameters set
3036 to indicate the state of processing; the calling function then
3037 makes its own arrangements for generating completions. For
3038 example, functions that implement a state machine can use this
3039 type of action.
3040 Where _arguments encounters a `->string', it will strip all
3042 leading and trailing whitespace from string and set the array
3043 state to the set of all stringss for which an action is to be
3044 performed.
3045 By default and in common with all other well behaved completion
3047 functions, _arguments returns zero if it was able to add matches
3048 and non-zero otherwise. However, if the -R option is given,
3049 _arguments will instead return a status of 300 to indicate that
3050 $state is to be handled.
3051 In addition to $state, _arguments also sets the global parame‐
3053 ters `context', `line' and `opt_args' as described below, and
3054 does not reset any changes made to the special parameters such
3055 as PREFIX and words. This gives the calling function the choice
3056 of resetting these parameters or propagating changes in them.
3057 A function calling _arguments with at least one action contain‐
3059 ing a `->string' therefore must declare appropriate local param‐
3060 eters:
3061 local context state line
3063 typeset -A opt_args
3064 to avoid _arguments from altering the global environment.
3066 {eval-string}
3068 A string in braces is evaluated as shell code to generate
3069 matches. If the eval-string itself does not begin with an open‐
3070 ing parenthesis or brace it is split into separate words before
3071 execution.
3072 = action
3074 If the action starts with `= ' (an equals sign followed by a
3075 space), _arguments will insert the contents of the argument
3076 field of the current context as the new first element in the
3077 words special array and increment the value of the CURRENT spe‐
3078 cial parameter. This has the effect of inserting a dummy word
3079 onto the completion command line while not changing the point at
3080 which completion is taking place.
3081 This is most useful with one of the specifiers that restrict the
3083 words on the command line on which the action is to operate (the
3084 two- and three-colon forms above). One particular use is when
3085 an action itself causes _arguments on a restricted range; it is
3086 necessary to use this trick to insert an appropriate command
3087 name into the range for the second call to _arguments to be able
3088 to parse the line.
3089 word...
3091 word...
3092 This covers all forms other than those above. If the action
3093 starts with a space, the remaining list of words will be invoked
3094 unchanged.
3095 Otherwise it will be invoked with some extra strings placed
3097 after the first word; these are to be passed down as options to
3098 the compadd builtin. They ensure that the state specified by
3099 _arguments, in particular the descriptions of options and argu‐
3100 ments, is correctly passed to the completion command. These
3101 additional arguments are taken from the array parameter `expl';
3102 this will be set up before executing the action and hence may be
3103 referred to inside it, typically in an expansion of the form
3104 `$expl[@]' which preserves empty elements of the array.
3105 During the performance of the action the array `line' will be set to
3107 the command name and normal arguments from the command line, i.e. the
3108 words from the command line excluding all options and their arguments.
3109 Options are stored in the associative array `opt_args' with option
3110 names as keys and their arguments as the values. For options that have
3111 more than one argument these are given as one string, separated by
3112 colons. All colons in the original arguments are preceded with back‐
3113 slashes.
3114 The parameter `context' is set when returning to the calling function
3116 to perform an action of the form `->string'. It is set to an array of
3117 elements corresponding to the elements of $state. Each element is a
3118 suitable name for the argument field of the context: either a string of
3119 the form `option-opt-n' for the n'th argument of the option -opt, or a
3120 string of the form `argument-n' for the n'th argument. For `rest'
3121 arguments, that is those in the list at the end not handled by posi‐
3122 tion, n is the string `rest'. For example, when completing the argu‐
3123 ment of the -o option, the name is `option-o-1', while for the second
3124 normal (non-option-) argument it is `argument-2'.
3125 Furthermore, during the evaluation of the action the context name in
3127 the curcontext parameter is altered to append the same string that is
3128 stored in the context parameter.
3129 It is possible to specify multiple sets of options and arguments with
3131 the sets separated by single hyphens. The specifications before the
3132 first hyphen (if any) are shared by all the remaining sets. The first
3133 word in every other set provides a name for the set which may appear in
3134 exclusion lists in specifications, either alone or before one of the
3135 possible values described above. In the second case a `-' should
3136 appear between this name and the remainder.
3137 For example:
3139 _arguments \
3141 -a \
3142 - set1 \
3143 -c \
3144 - set2 \
3145 -d \
3146 ':arg:(x2 y2)'
3147 This defines two sets. When the command line contains the option `-c',
3149 the `-d' option and the argument will not be considered possible com‐
3150 pletions. When it contains `-d' or an argument, the option `-c' will
3151 not be considered. However, after `-a' both sets will still be consid‐
3152 ered valid.
3153 If the name given for one of the mutually exclusive sets is of the form
3155 `(name)' then only one value from each set will ever be completed; more
3156 formally, all specifications are mutually exclusive to all other speci‐
3157 fications in the same set. This is useful for defining multiple sets
3158 of options which are mutually exclusive and in which the options are
3159 aliases for each other. For example:
3160 _arguments \
3162 -a -b \
3163 - '(compress)' \
3164 {-c,--compress}'[compress]' \
3165 - '(uncompress)' \
3166 {-d,--decompress}'[decompress]'
3167 As the completion code has to parse the command line separately for
3169 each set this form of argument is slow and should only be used when
3170 necessary. A useful alternative is often an option specification with
3171 rest-arguments (as in `-foo:*:...'); here the option -foo swallows up
3172 all remaining arguments as described by the optarg definitions.
3173 The options -S and -A are available to simplify the specifications for
3175 commands with standard option parsing. With -S, no option will be com‐
3176 pleted after a `--' appearing on its own on the line; this argument
3177 will otherwise be ignored; hence in the line
3178 foobar -a -- -b
3180 the `-a' is considered an option but the `-b' is considered an argu‐
3182 ment, while the `--' is considered to be neither.
3183 With -A, no options will be completed after the first non-option argu‐
3185 ment on the line. The -A must be followed by a pattern matching all
3186 strings which are not to be taken as arguments. For example, to make
3187 _arguments stop completing options after the first normal argument, but
3188 ignoring all strings starting with a hyphen even if they are not
3189 described by one of the optspecs, the form is `-A "-*"'.
3190 The option `-O name' specifies the name of an array whose elements will
3192 be passed as arguments to functions called to execute actions. For
3193 example, this can be used to pass the same set of options for the com‐
3194 padd builtin to all actions.
3195 The option `-M spec' sets a match specification to use to completion
3197 option names and values. It must appear before the first argument
3198 specification. The default is `r:|[_-]=* r:|=*': this allows partial
3199 word completion after `_' and `-', for example `-f-b' can be completed
3200 to `-foo-bar'.
3201 The option -C tells _arguments to modify the curcontext parameter for
3203 an action of the form `->state'. This is the standard parameter used
3204 to keep track of the current context. Here it (and not the context
3205 array) should be made local to the calling function to avoid passing
3206 back the modified value and should be initialised to the current value
3207 at the start of the function:
3208 local curcontext="$curcontext"
3210 This is useful where it is not possible for multiple states to be valid
3212 together.
3213 The option `--' allows _arguments to work out the names of long options
3215 that support the `--help' option which is standard in many GNU com‐
3216 mands. The command word is called with the argument `--help' and the
3217 output examined for option names. Clearly, it can be dangerous to pass
3218 this to commands which may not support this option as the behaviour of
3219 the command is unspecified.
3220 In addition to options, `_arguments --' will try to deduce the types of
3222 arguments available for options when the form `--opt=val' is valid. It
3223 is also possible to provide hints by examining the help text of the
3224 command and adding specifiers of the form `pattern:message:action';
3225 note that normal _arguments specifiers are not used. The pattern is
3226 matched against the help text for an option, and if it matches the mes‐
3227 sage and action are used as for other argument specifiers. For exam‐
3228 ple:
3229 _arguments -- '*\*:toggle:(yes no)' \
3231 '*=FILE*:file:_files' \
3232 '*=DIR*:directory:_files -/' \
3233 '*=PATH*:directory:_files -/'
3234 Here, `yes' and `no' will be completed as the argument of options whose
3236 description ends in a star; file names will be completed for options
3237 that contain the substring `=FILE' in the description; and directories
3238 will be completed for options whose description contains `=DIR' or
3239 `=PATH'. The last three are in fact the default and so need not be
3240 given explicitly, although it is possible to override the use of these
3241 patterns. A typical help text which uses this feature is:
3242 -C, --directory=DIR change to directory DIR
3244 so that the above specifications will cause directories to be completed
3246 after `--directory', though not after `-C'.
3247 Note also that _arguments tries to find out automatically if the argu‐
3249 ment for an option is optional. This can be specified explicitly by
3250 doubling the colon before the message.
3251 If the pattern ends in `(-)', this will removed from the pattern and
3253 the action will be used only directly after the `=', not in the next
3254 word. This is the behaviour of a normal specification defined with the
3255 form `=-'.
3256 The `_arguments --' can be followed by the option `-i patterns' to give
3258 patterns for options which are not to be completed. The patterns can
3259 be given as the name of an array parameter or as a literal list in
3260 parentheses. For example,
3261 _arguments -- -i \
3263 "(--(en|dis)able-FEATURE*)"
3264 will cause completion to ignore the options `--enable-FEATURE' and
3266 `--disable-FEATURE' (this example is useful with GNU configure).
3267 The `_arguments --' form can also be followed by the option `-s pair'
3269 to describe option aliases. Each pair consists of a pattern and a
3270 replacement. For example, some configure-scripts describe options only
3271 as `--enable-foo', but also accept `--disable-foo'. To allow comple‐
3272 tion of the second form:
3273 _arguments -- -s "(#--enable- --disable-)"
3275 Here is a more general example of the use of _arguments:
3277 _arguments '-l+:left border:' \
3279 '-format:paper size:(letter A4)' \
3280 '*-copy:output file:_files::resolution:(300 600)' \
3281 ':postscript file:_files -g \*.\(ps\|eps\)' \
3282 '*:page number:'
3283 This describes three options: `-l', `-format', and `-copy'. The first
3285 takes one argument described as `left border' for which no completion
3286 will be offered because of the empty action. Its argument may come
3287 directly after the `-l' or it may be given as the next word on the
3288 line.
3289 The `-format' option takes one argument in the next word, described as
3291 `paper size' for which only the strings `letter' and `A4' will be com‐
3292 pleted.
3293 The `-copy' option may appear more than once on the command line and
3295 takes two arguments. The first is mandatory and will be completed as a
3296 filename. The second is optional (because of the second colon before
3297 the description `resolution') and will be completed from the strings
3298 `300' and `600'.
3299 The last two descriptions say what should be completed as arguments.
3301 The first describes the first argument as a `postscript file' and makes
3302 files ending in `ps' or `eps' be completed. The last description gives
3303 all other arguments the description `page numbers' but does not offer
3304 completions.
3305 _cache_invalid cache_identifier
3307 This function returns status zero if the completions cache cor‐
3308 responding to the given cache identifier needs rebuilding. It
3309 determines this by looking up the cache-policy style for the
3310 current context. This should provide a function name which is
3311 run with the full path to the relevant cache file as the only
3312 argument.
3313 Example:
3315 _example_caching_policy () {
3317 # rebuild if cache is more than a week old
3318 oldp=( "$1"(Nmw+1) )
3319 (( $#oldp ))
3320 }
3321 _call_function return name [ args ... ]
3323 If a function name exists, it is called with the arguments args.
3324 The return argument gives the name of a parameter in which the
3325 return status from the function name; if return is empty or a
3326 single hyphen it is ignored.
3327 The return value of _call_function itself is zero if the func‐
3329 tion name exists and was called and non-zero otherwise.
3330 _call_program tag string ...
3332 This function provides a mechanism for the user to override the
3333 use of an external command. It looks up the command style with
3334 the supplied tag. If the style is set, its value is used as the
3335 command to execute. The strings from the call to _call_program,
3336 or from the style if set, are concatenated with spaces between
3337 them and the resulting string is evaluated. The return value is
3338 the return value of the command called.
3339 _combination [ -s pattern ] tag style spec ... field opts ...
3341 This function is used to complete combinations of values, for
3342 example pairs of hostnames and usernames. The style argument
3343 gives the style which defines the pairs; it is looked up in a
3344 context with the tag specified.
3345 The style name consists of field names separated by hyphens, for
3347 example `users-hosts-ports'. For each field for a value is
3348 already known, a spec of the form `field=pattern' is given. For
3349 example, if the command line so far specifies a user `pws', the
3350 argument `users=pws' should appear.
3351 The next argument with no equals sign is taken as the name of
3353 the field for which completions should be generated (presumably
3354 not one of the fields for which the value is known).
3355 The matches generated will be taken from the value of the style.
3357 These should contain the possible values for the combinations in
3358 the appropriate order (users, hosts, ports in the example
3359 above). The different fields the values for the different
3360 fields are separated by colons. This can be altered with the
3361 option -s to _combination which specifies a pattern. Typically
3362 this is a character class, as for example `-s "[:@]"' in the
3363 case of the users-hosts style. Each `field=pattern' specifi‐
3364 cation restricts the completions which apply to elements of the
3365 style with appropriately matching fields.
3366 If no style with the given name is defined for the given tag, or
3368 if none of the strings in style's value match, but a function
3369 name of the required field preceded by an underscore is defined,
3370 that function will be called to generate the matches. For exam‐
3371 ple, if there is no `users-hosts-ports' or no matching hostname
3372 when a host is required, the function `_hosts' will automati‐
3373 cally be called.
3374 If the same name is used for more than one field, in both the
3376 `field=pattern' and the argument that gives the name of the
3377 field to be completed, the number of the field (starting with
3378 one) may be given after the fieldname, separated from it by a
3379 colon.
3380 All arguments after the required field name are passed to com‐
3382 padd when generating matches from the style value, or to the
3383 functions for the fields if they are called.
3384 _describe [ -oO | -t tag ] descr name1 [ name2 ] opts ... -- ...
3386 This function associates completions with descriptions. Multi‐
3387 ple groups separated by -- can be supplied, potentially with
3388 different completion options opts.
3389 The descr is taken as a string to display above the matches if
3391 the format style for the descriptions tag is set. This is fol‐
3392 lowed by one or two names of arrays followed by options to pass
3393 to compadd. The first array contains the possible completions
3394 with their descriptions in the form `completion:description'.
3395 If a second array is given, it should have the same number of
3396 elements as the first; in this case the corresponding elements
3397 are added as possible completions instead of the completion
3398 strings from the first array. The completion list will retain
3399 the descriptions from the first array. Finally, a set of com‐
3400 pletion options can appear.
3401 If the option `-o' appears before the first argument, the
3403 matches added will be treated as names of command options (N.B.
3404 not shell options), typically following a `-', `--' or `+' on
3405 the command line. In this case _describe uses the prefix-hid‐
3406 den, prefix-needed and verbose styles to find out if the strings
3407 should be added as completions and if the descriptions should be
3408 shown. Without the `-o' option, only the verbose style is used
3409 to decide how descriptions are shown. If `-O' is used instead
3410 of `-O', command options are completed as above but _describe
3411 will not handle the prefix-needed style.
3412 With the -t option a tag can be specified. The default is `val‐
3414 ues' or, if the -o option is given, `options'.
3415 If selected by the list-grouped style, strings with the same
3417 description will appear together in the list.
3418 _describe uses the _all_labels function to generate the matches,
3420 so it does not need to appear inside a loop over tag labels.
3421 _description [ -x ] [ -12VJ ] tag name descr [ spec ... ]
3423 This function is not to be confused with the previous one; it is
3424 used as a helper function for creating options to compadd. It
3425 is buried inside many of the higher level completion functions
3426 and so often does not need to be called directly.
3427 The styles listed below are tested in the current context using
3429 the given tag. The resulting options for compadd are put into
3430 the array named name (this is traditionally `expl', but this
3431 convention is not enforced). The description for the corre‐
3432 sponding set of matches is passed to the function in descr.
3433 The styles tested are: format, hidden, matcher, ignored-patterns
3435 and group-name. The format style is first tested for the given
3436 tag and then for the descriptions tag if no value was found,
3437 while the remainder are only tested for the tag given as the
3438 first argument. The function also calls _setup which tests some
3439 more styles.
3440 The string returned by the format style (if any) will be modi‐
3442 fied so that the sequence `%d' is replaced by the descr given as
3443 the third argument without any leading or trailing white space.
3444 If, after removing the white space, the descr is the empty
3445 string, the format style will not be used and the options put
3446 into the name array will not contain an explanation string to be
3447 displayed above the matches.
3448 If _description is called with more than three arguments, the
3450 additional specs should be of the form `char:str'. These supply
3451 escape sequence replacements for the format style: every appear‐
3452 ance of `%char' will be replaced by string.
3453 If the -x option is given, the description will be passed to
3455 compadd using the -x option instead of the default -X. This
3456 means that the description will be displayed even if there are
3457 no corresponding matches.
3458 The options placed in the array name take account of the
3460 group-name style, so matches are placed in a separate group
3461 where necessary. The group normally has its elements sorted (by
3462 passing the option -J to compadd), but if an option starting
3463 with `-V', `-J', `-1', or `-2' is passed to _description, that
3464 option will be included in the array. Hence it is possible for
3465 the completion group to be unsorted by giving the option `-V',
3466 `-1V', or `-2V'.
3467 In most cases, the function will be used like this:
3469 local expl
3471 _description files expl file
3472 compadd "$expl[@]" - "$files[@]"
3473 Note the use of the parameter expl, the hyphen, and the list of
3475 matches. Almost all calls to compadd within the completion sys‐
3476 tem use a similar format; this ensures that user-specified
3477 styles are correctly passed down to the builtins which implement
3478 the internals of completion.
3479 _dispatch context string ...
3481 This sets the current context to context and looks for comple‐
3482 tion functions to handle this context by hunting through the
3483 list of command names or special contexts (as described above
3484 for compdef) given as string .... The first completion function
3485 to be defined for one of the contexts in the list is used to
3486 generate matches. Typically, the last string is -default- to
3487 cause the function for default completion to be used as a fall‐
3488 back.
3489 The function sets the parameter $service to the string being
3491 tried, and sets the context/command field (the fourth) of the
3492 $curcontext parameter to the context given as the first argu‐
3493 ment.
3494 _files The function _files calls _path_files with all the arguments it
3496 was passed except for -g and -/. The use of these two options
3497 depends on the setting of the file-patterns style.
3498 This function accepts the full set of options allowed by
3500 _path_files, described below.
3501 _gnu_generic
3503 This function is a simple wrapper around the _arguments function
3504 described above. It can be used to determine automatically the
3505 long options understood by commands that produce a list when
3506 passed the option `--help'. It is intended to be used as a
3507 top-level completion function in its own right. For example, to
3508 enable option completion for the commands foo and bar, use
3509 compdef _gnu_generic foo bar
3511 after the call to compinit.
3513 The completion system as supplied is conservative in its use of
3515 this function, since it is important to be sure the command
3516 understands the option `-'-help'.
3517 _guard [ options ] pattern descr
3519 This function is intended to be used in the action for the spec‐
3520 ifications passed to _arguments and similar functions. It
3521 returns immediately with a non-zero return value if the string
3522 to be completed does not match the pattern. If the pattern
3523 matches, the descr is displayed; the function then returns zero
3524 if the word to complete is not empty, non-zero otherwise.
3525 The pattern may be preceded by any of the options understood by
3527 compadd that are passed down from _description, namely -M, -J,
3528 -V, -1, -2, -n, -F and -X. All of these options will be
3529 ignored. This fits in conveniently with the argument-passing
3530 conventions of actions for _arguments.
3531 As an example, consider a command taking the options -n and
3533 -none, where -n must be followed by a numeric value in the same
3534 word. By using:
3535 _arguments '-n-: :_guard "[0-9]#" "numeric value"' '-none'
3537 _arguments can be made to both display the message `numeric
3539 value' and complete options after `-n<TAB>'. If the `-n' is
3540 already followed by one or more digits (the pattern passed to
3541 _guard) only the message will be displayed; if the `-n' is fol‐
3542 lowed by another character, only options are completed.
3543 _message [ -r12 ] [ -VJ group ] descr
3545 _message -e [ tag ] descr
3546 The descr is used in the same way as the third argument to the
3547 _description function, except that the resulting string will
3548 always be shown whether or not matches were generated. This is
3549 useful for displaying a help message in places where no comple‐
3550 tions can be generated.
3551 The format style is examined with the messages tag to find a
3553 message; the usual tag, descriptions, is used only if the style
3554 is not set with the former.
3555 If the -r option is given, no style is used; the descr is taken
3557 literally as the string to display. This is most useful when
3558 the descr comes from a pre-processed argument list which already
3559 contains an expanded description.
3560 The -12VJ options and the group are passed to compadd and hence
3562 determine the group the message string is added to.
3563 The second form gives a description for completions with the tag
3565 tag to be shown even if there are no matches for that tag. The
3566 tag can be omitted and if so the tag is taken from the parameter
3567 $curtag; this is maintained by the completion system and so is
3568 usually correct.
3569 _multi_parts sep array
3571 The argument sep is a separator character. The array may be
3572 either the name of an array parameter or a literal array in the
3573 form `(foo bar)', a parenthesised list of words separated by
3574 whitespace. The possible completions are the strings from the
3575 array. However, each chunk delimited by sep will be completed
3576 separately. For example, the _tar function uses `_multi_parts /
3577 patharray' to complete partial file paths from the given array
3578 of complete file paths.
3579 The -i option causes _multi_parts to insert a unique match even
3581 if that requires multiple separators to be inserted. This is
3582 not usually the expected behaviour with filenames, but certain
3583 other types of completion, for example those with a fixed set of
3584 possibilities, may be more suited to this form.
3585 Like other utility functions, this function accepts the `-V',
3587 `-J', `-1', `-2', `-n', `-f', `-X', `-M', `-P', `-S', `-r',
3588 `-R', and `-q' options and passes them to the compadd builtin.
3589 _next_label [ -x ] [ -12VJ ] tag name descr [ options ... ]
3591 This function is used to implement the loop over different tag
3592 labels for a particular tag as described above for the tag-order
3593 style. On each call it checks to see if there are any more tag
3594 labels; if there is it returns status zero, otherwise non-zero.
3595 As this function requires a current tag to be set, it must
3596 always follow a call to _tags or _requested.
3597 The -x12VJ options and the first three arguments are passed to
3599 the _description function. Where appropriate the tag will be
3600 replaced by a tag label in this call. Any description given in
3601 the tag-order style is preferred to the descr passed to
3602 _next_label.
3603 The options given after the descr are set in the parameter given
3605 by name, and hence are to be passed to compadd or whatever func‐
3606 tion is called to add the matches.
3607 Here is a typical use of this function for the tag foo. The
3609 call to _requested determines if tag foo is required at all; the
3610 loop over _next_label handles any labels defined for the tag in
3611 the tag-order style.
3612 local expl ret=1
3614 ...
3615 if _requested foo; then
3616 ...
3617 while _next_label foo expl '...'; do
3618 compadd "$expl[@]" ... && ret=0
3619 done
3620 ...
3621 fi
3622 return ret
3623 _normal
3625 This is the standard function called to handle completion out‐
3626 side any special -context-. It is called both to complete the
3627 command word and also the arguments for a command. In the sec‐
3628 ond case, _normal looks for a special completion for that com‐
3629 mand, and if there is none it uses the completion for the
3630 -default- context.
3631 A second use is to reexamine the command line specified by the
3633 $words array and the $CURRENT parameter after those have been
3634 modified. For example, the function _precommand, which com‐
3635 pletes after pre-command specifiers such as nohup, removes the
3636 first word from the words array, decrements the CURRENT parame‐
3637 ter, then calls _normal again. The effect is that `nohup cmd
3638 ...' is treated in the same way as `cmd ...'.
3639 If the command name matches one of the patterns given by one of
3641 the options -p or -P to compdef, the corresponding completion
3642 function is called and then the parameter _compskip is checked.
3643 If it is set completion is terminated at that point even if no
3644 matches have been found. This is the same effect as in the
3645 -first- context.
3646 _options
3648 This can be used to complete the names of shell options. It
3649 provides a matcher specification that ignores a leading `no',
3650 ignores underscores and allows upper-case letters to match their
3651 lower-case counterparts (for example, `glob', `noglob',
3652 `NO_GLOB' are all completed). Any arguments are propagated to
3653 the compadd builtin.
3654 _options_set and _options_unset
3656 These functions complete only set or unset options, with the
3657 same matching specification used in the _options function.
3658 Note that you need to uncomment a few lines in the _main_com‐
3660 plete function for these functions to work properly. The lines
3661 in question are used to store the option settings in effect
3662 before the completion widget locally sets the options it needs.
3663 Hence these functions are not generally used by the completion
3664 system.
3665 _parameters
3667 This is used to complete the names of shell parameters.
3668 The option `-g pattern' limits the completion to parameters
3670 whose type matches the pattern. The type of a parameter is that
3671 shown by `print ${(t)param}', hence judicious use of `*' in pat‐
3672 tern is probably necessary.
3673 All other arguments are passed to the compadd builtin.
3675 _path_files
3677 This function is used throughout the completion system to com‐
3678 plete filenames. It allows completion of partial paths. For
3679 example, the string `/u/i/s/sig' may be completed to
3680 `/usr/include/sys/signal.h'.
3681 The options accepted by both _path_files and _files are:
3683 -f Complete all filenames. This is the default.
3685 -/ Specifies that only directories should be completed.
3687 -g pattern
3689 Specifies that only files matching the pattern should be
3690 completed.
3691 -W paths
3693 Specifies path prefixes that are to be prepended to the
3694 string from the command line to generate the filenames
3695 but that should not be inserted as completions nor shown
3696 in completion listings. Here, paths may be the name of
3697 an array parameter, a literal list of paths enclosed in
3698 parentheses or an absolute pathname.
3699 -F ignored-files
3701 This behaves as for the corresponding option to the com‐
3702 padd builtin. It gives direct control over which file‐
3703 names should be ignored. If the option is not present,
3704 the ignored-patterns style is used.
3705 Both _path_files and _files also accept the following options
3707 which are passed to compadd: `-J', `-V', `-1', `-2', `-n', `-X',
3708 `-M', `-P', `-S', `-q', `-r', and `-R'.
3709 Finally, the _path_files function uses the styles expand,
3711 ambiguous, special-dirs, list-suffixes and file-sort described
3712 above.
3713 _pick_variant [ -c command ] [ -r name ] label=pattern ... label [ args
3715 ... ]
3716 This function is used to resolve situations where a single com‐
3717 mand name requires more than one type of handling, either
3718 because it has more than one variant or because there is a name
3719 clash between two different commands.
3720 The command to run is taken from the first element of the array
3722 words unless this is overridden by the option -c. This command
3723 is run and its output is compared with a series of patterns.
3724 Arguments to be passed to the command can be specified at the
3725 end after all the other arguments. The patterns to try in order
3726 are given by the arguments label=pattern; if the output of `com‐
3727 mand args ...' contains pattern, then label is selected as the
3728 label for the command variant. If none of the patterns match,
3729 the final command label is selected and status 1 is returned.
3730 If the `-r name' is given, the label picked is stored in the
3732 parameter named name.
3733 The results are also cached in the _cmd_variant associative
3735 array indexed by the name of the command run.
3736 _regex_arguments name spec ...
3738 This function generates a completion function name which matches
3739 the specifications spec ..., a set of regular expressions as
3740 described below. After running _regex_arguments, the function
3741 name should be called at the appropriate point. The pattern to
3742 be matched is given by the contents of the words array up to the
3743 current cursor position joined together with null characters; no
3744 quotation is applied.
3745 The arguments are grouped as sets of alternatives separated by
3747 `|', which are tried one after the other until one matches.
3748 Each alternative consists of a one or more specifications which
3749 are tried left to right, with each pattern matched being
3750 stripped in turn from the command line being tested, until all
3751 of the group succeeds or until one fails; in the latter case,
3752 the next alternative is tried. This structure can be repeated
3753 to arbitrary depth by using parentheses; matching proceeds from
3754 inside to outside.
3755 A special procedure is applied if no test succeeds but the
3757 remaining command line string contains no null character (imply‐
3758 ing the remaining word is the one for which completions are to
3759 be generated). The completion target is restricted to the
3760 remaining word and any actions for the corresponding patterns
3761 are executed. In this case, nothing is stripped from the com‐
3762 mand line string. The order of evaluation of the actions can be
3763 determined by the tag-order style; the various formats supported
3764 by _alternative can be used in action. The descr is used for
3765 setting up the array parameter expl.
3766 Specification arguments take one of following forms, in which
3768 metacharacters such as `(', `)', `#' and `|' should be quoted.
3769 /pattern/ [%lookahead%] [-guard] [:tag:descr:action]
3771 This is a single primitive component. The function tests
3772 whether the combined pattern `(#b)((#B)pattern)looka‐
3773 head*' matches the command line string. If so, `guard'
3774 is evaluated and its return status is examined to deter‐
3775 mine if the test has succeeded. The pattern string `[]'
3776 is guaranteed never to match. The lookahead is not
3777 stripped from the command line before the next pattern is
3778 examined.
3779 /pattern/+ [%lookahead%] [-guard] [:tag:descr:action]
3781 This is similar to `/pattern/ ...' but the left part of
3782 the command line string (i.e. the part already matched by
3783 previous patterns) is also considered part of the comple‐
3784 tion target.
3785 /pattern/- [%lookahead%] [-guard] [:tag:descr:action]
3787 This is similar to `/pattern/ ...' but the actions of the
3788 current and previously matched patterns are ignored even
3789 if the following `pattern' matches the empty string.
3790 ( spec )
3792 Parentheses may be used to groups specs; note each paren‐
3793 thesis is a single argument to _regex_arguments.
3794 spec # This allows any number of repetitions of spec.
3796 spec spec
3798 The two specs are to be matched one after the other as
3799 described above.
3800 spec | spec
3802 Either of the two specs can be matched.
3803 _requested [ -x ] [ -12VJ ] tag [ name descr [ command args ... ] ]
3805 This function is called to decide whether a tag already regis‐
3806 tered by a call to _tags (see below) has been requested by the
3807 user and hence completion should be performed for it. It
3808 returns status zero if the tag is requested and non-zero other‐
3809 wise. The function is typically used as part of a loop over
3810 different tags as follows:
3811 _tags foo bar baz
3813 while _tags; do
3814 if _requested foo; then
3815 ... # perform completion for foo
3816 fi
3817 ... # test the tags bar and baz in the same way
3818 ... # exit loop if matches were generated
3819 done
3820 Note that the test for whether matches were generated is not
3822 performed until the end of the _tags loop. This is so that the
3823 user can set the tag-order style to specify a set of tags to be
3824 completed at the same time.
3825 If name and descr are given, _requested calls the _description
3827 function with these arguments together with the options passed
3828 to _requested.
3829 If command is given, the _all_labels function will be called
3831 immediately with the same arguments. In simple cases this makes
3832 it possible to perform the test for the tag and the matching in
3833 one go. For example:
3834 local expl ret=1
3836 _tags foo bar baz
3837 while _tags; do
3838 _requested foo expl 'description' \
3839 compadd foobar foobaz && ret=0
3840 ...
3841 (( ret )) || break
3842 done
3843 If the command is not compadd, it must nevertheless be prepared
3845 to handle the same options.
3846 _retrieve_cache cache_identifier
3848 This function retrieves completion information from the file
3849 given by cache_identifier, stored in a directory specified by
3850 the cache-path style which defaults to ~/.zcompcache. The
3851 return value is zero if retrieval was successful. It will only
3852 attempt retrieval if the use-cache style is set, so you can call
3853 this function without worrying about whether the user wanted to
3854 use the caching layer.
3855 See _store_cache below for more details.
3857 _sep_parts
3859 This function is passed alternating arrays and separators as
3860 arguments. The arrays specify completions for parts of strings
3861 to be separated by the separators. The arrays may be the names
3862 of array parameters or a quoted list of words in parentheses.
3863 For example, with the array `hosts=(ftp news)' the call
3864 `_sep_parts '(foo bar)' @ hosts' will complete the string `f'
3865 to `foo' and the string `b@n' to `bar@news'.
3866 This function accepts the compadd options `-V', `-J', `-1',
3868 `-2', `-n', `-X', `-M', `-P', `-S', `-r', `-R', and `-q' and
3869 passes them on to the compadd builtin used to add the matches.
3870 _setup tag [ group ]
3872 This function sets up the special parameters used by the comple‐
3873 tion system appropriately for the tag given as the first argu‐
3874 ment. It uses the styles list-colors, list-packed,
3875 list-rows-first, last-prompt, accept-exact, menu and force-list.
3876 The optional group supplies the name of the group in which the
3878 matches will be placed. If it is not given, the tag is used as
3879 the group name.
3880 This function is called automatically from _description and
3882 hence is not normally called explicitly.
3883 _store_cache cache_identifier params ...
3885 This function, together with _retrieve_cache and _cache_invalid,
3886 implements a caching layer which can be used in any completion
3887 function. Data obtained by costly operations are stored in
3888 parameters; this function then dumps the values of those parame‐
3889 ters to a file. The data can then be retrieved quickly from
3890 that file via _retrieve_cache, even in different instances of
3891 the shell.
3892 The cache_identifier specifies the file which the data should be
3894 dumped to. The file is stored in a directory specified by the
3895 cache-path style which defaults to ~/.zcompcache. The remaining
3896 params arguments are the parameters to dump to the file.
3897 The return value is zero if storage was successful. The func‐
3899 tion will only attempt storage if the use-cache style is set, so
3900 you can call this function without worrying about whether the
3901 user wanted to use the caching layer.
3902 The completion function may avoid calling _retrieve_cache when
3904 it already has the completion data available as parameters.
3905 However, in that case it should call _cache_invalid to check
3906 whether the data in the parameters and in the cache are still
3907 valid.
3908 See the _perl_modules completion function for a simple example
3910 of the usage of the caching layer.
3911 _tags [ [ -C name ] tags ... ]
3913 If called with arguments, these are taken to be the names of
3914 tags valid for completions in the current context. These tags
3915 are stored internally and sorted by using the tag-order style.
3916 Next, _tags is called repeatedly without arguments from the same
3918 completion function. This successively selects the first, sec‐
3919 ond, etc. set of tags requested by the user. The return value
3920 is zero if at least one of the tags is requested and non-zero
3921 otherwise. To test if a particular tag is to be tried, the
3922 _requested function should be called (see above).
3923 If `-C name' is given, name is temporarily stored in the argu‐
3925 ment field (the fifth) of the context in the curcontext parame‐
3926 ter during the call to _tags; the field is restored on exit.
3927 This allows _tags to use a more specific context without having
3928 to change and reset the curcontext parameter (which has the same
3929 effect).
3930 _values [ -O name ] [ -s sep ] [ -S sep ] [ -wC ] desc spec ...
3932 This is used to complete arbitrary keywords (values) and their
3933 arguments, or lists of such combinations.
3934 If the first argument is the option `-O name', it will be used
3936 in the same way as by the _arguments function. In other words,
3937 the elements of the name array will be passed to compadd when
3938 executing an action.
3939 If the first argument (or the first argument after `-O name') is
3941 `-s', the next argument is used as the character that separates
3942 multiple values. This character is automatically added after
3943 each value in an auto-removable fashion (see below); all values
3944 completed by `_values -s' appear in the same word on the command
3945 line, unlike completion using _arguments. If this option is not
3946 present, only a single value will be completed per word.
3947 Normally, _values will only use the current word to determine
3949 which values are already present on the command line and hence
3950 are not to be completed again. If the -w option is given, other
3951 arguments are examined as well.
3952 The first non-option argument is used as a string to print as a
3954 description before listing the values.
3955 All other arguments describe the possible values and their argu‐
3957 ments in the same format used for the description of options by
3958 the _arguments function (see above). The only differences are
3959 that no minus or plus sign is required at the beginning, values
3960 can have only one argument, and the forms of action beginning
3961 with an equal sign are not supported.
3962 The character separating a value from its argument can be set
3964 using the option -S (like -s, followed by the character to use
3965 as the separator in the next argument). By default the equals
3966 sign will be used as the separator between values and arguments.
3967 Example:
3969 _values -s , 'description' \
3971 '*foo[bar]' \
3972 '(two)*one[number]:first count:' \
3973 'two[another number]::second count:(1 2 3)'
3974 This describes three possible values: `foo', `one', and `two'.
3976 The first is described as `bar', takes no argument and may
3977 appear more than once. The second is described as `number', may
3978 appear more than once, and takes one mandatory argument
3979 described as `first count'; no action is specified, so it will
3980 not be completed. The `(two)' at the beginning says that if the
3981 value `one' is on the line, the value `two' will no longer be
3982 considered a possible completion. Finally, the last value
3983 (`two') is described as `another number' and takes an optional
3984 argument described as `second count' for which the completions
3985 (to appear after an `=') are `1', `2', and `3'. The _values
3986 function will complete lists of these values separated by com‐
3987 mas.
3988 Like _arguments, this function temporarily adds another context
3990 name component to the arguments element (the fifth) of the cur‐
3991 rent context while executing the action. Here this name is just
3992 the name of the value for which the argument is completed.
3993 The style verbose is used to decide if the descriptions for the
3995 values (but not those for the arguments) should be printed.
3996 The associative array val_args is used to report values and
3998 their arguments; this works similarly to the opt_args associa‐
3999 tive array used by _arguments. Hence the function calling _val‐
4000 ues should declare the local parameters state, line, context and
4001 val_args:
4002 local context state line
4004 typeset -A val_args
4005 when using an action of the form `->string'. With this function
4007 the context parameter will be set to the name of the value whose
4008 argument is to be completed.
4009 Note also that _values normally adds the character used as the
4011 separator between values as an auto-removable suffix (similar to
4012 a `/' after a directory). However, this is not possible for a
4013 `->string' action as the matches for the argument are generated
4014 by the calling function. To get the usual behaviour, the the
4015 calling function can add the separator x as a suffix by passing
4016 the options `-qS x' either directly or indirectly to compadd.
4017 The option -C is treated in the same way as it is by _arguments.
4019 In that case the parameter curcontext should be made local
4020 instead of context (as described above).
4021 _wanted [ -x ] [ -C name ] [ -12VJ ] tag name descr command args ...
4023 In many contexts, completion can only generate one particular
4024 set of matches, usually corresponding to a single tag. However,
4025 it is still necessary to decide whether the user requires
4026 matches of this type. This function is useful in such a case.
4027 The arguments to _wanted are the same as those to _requested,
4029 i.e. arguments to be passed to _description. However, in this
4030 case the command is not optional; all the processing of tags,
4031 including the loop over both tags and tag labels and the genera‐
4032 tion of matches, is carried out automatically by _wanted.
4033 Hence to offer only one tag and immediately add the correspond‐
4035 ing matches with the given description:
4036 _wanted tag expl 'description' \
4038 compadd matches...
4039 Note that, as for _requested, the command must be able to accept
4041 options to be passed down to compadd.
4042 Like _tags this function supports the -C option to give a dif‐
4044 ferent name for the argument context field. The -x option has
4045 the same meaning as for _description.
4046
4048 In the source distribution, the files are contained in various subdi‐
4049 rectories of the Completion directory. They may have been installed in
4050 the same structure, or into one single function directory. The follow‐
4051 ing is a description of the files found in the original directory
4052 structure. If you wish to alter an installed file, you will need to
4053 copy it to some directory which appears earlier in your fpath than the
4054 standard directory where it appears.
4055 Base The core functions and special completion widgets automatically
4057 bound to keys. You will certainly need most of these, though
4058 will probably not need to alter them. Many of these are docu‐
4059 mented above.
4060 Zsh Functions for completing arguments of shell builtin commands and
4062 utility functions for this. Some of these are also used by
4063 functions from the Unix directory.
4064 Unix Functions for completing arguments of external commands and
4066 suites of commands. They may need modifying for your system,
4067 although in many cases some attempt is made to decide which ver‐
4068 sion of a command is present. For example, completion for the
4069 mount command tries to determine the system it is running on,
4070 while completion for many other utilities try to decide whether
4071 the GNU version of the command is in use, and hence whether the
4072 --help option is supported.
4073 X, AIX, BSD, ...
4075 Completion and utility function for commands available only on
4076 some systems. These are not arranged hierarchically, so, for
4077 example, both the Linux and Debian directories, as well as the X
4078 directory, may be useful on your system.
4079zsh 4.2.6 November 28, 2005 ZSHCOMPSYS(1)