1ZSHCOMPSYS(1)               General Commands Manual              ZSHCOMPSYS(1)
2
3
4

NAME

6       zshcompsys - zsh completion system
7

DESCRIPTION

9       This describes the shell code for the `new' completion system, referred
10       to as compsys.  It is written in shell functions based on the  features
11       described in zshcompwid(1).
12
13       The features are contextual, sensitive to the point at which completion
14       is started.  Many completions are already provided.  For this reason, a
15       user  can perform a great many tasks without knowing any details beyond
16       how to initialize the system, which is described below  in  INITIALIZA‐
17       TION.
18
19       The context that decides what completion is to be performed may be
20       ·      an  argument  or option position: these describe the position on
21              the command line at which completion is requested.  For  example
22              `first  argument  to  rmdir,  the  word  being completed names a
23              directory';
24
25
26       ·      a special context, denoting an element in  the  shell's  syntax.
27              For  example  `a  word  in  command  position' or `an array sub‐
28              script'.
29
30
31       A full context specification  contains  other  elements,  as  we  shall
32       describe.
33
34       Besides  commands  names and contexts, the system employs two more con‐
35       cepts, styles and tags.  These provide ways for the user  to  configure
36       the system's behaviour.
37
38       Tags  play  a dual role.  They serve as a classification system for the
39       matches, typically indicating a class of object that the user may  need
40       to  distinguish.  For example, when completing arguments of the ls com‐
41       mand the user may prefer to try files before directories,  so  both  of
42       these are tags.  They also appear as the rightmost element in a context
43       specification.
44
45       Styles modify various operations of the completion system, such as out‐
46       put formatting, but also what kinds of completers are used (and in what
47       order), or which tags are examined.  Styles may  accept  arguments  and
48       are  manipulated  using  the  zstyle  command  described in see zshmod‐
49       ules(1).
50
51       In summary, tags describe what the completion objects  are,  and  style
52       how they are to be completed.  At various points of execution, the com‐
53       pletion system checks what styles and/or tags are defined for the  cur‐
54       rent  context, and uses that to modify its behavior.  The full descrip‐
55       tion of context handling, which determines how tags and other  elements
56       of the context influence the behaviour of styles, is described below in
57       COMPLETION SYSTEM CONFIGURATION.
58
59       When a completion is requested, a dispatcher function  is  called;  see
60       the  description  of  _main_complete  in  the list of control functions
61       below. This dispatcher decides which function should be called to  pro‐
62       duce the completions, and calls it. The result is passed to one or more
63       completers, functions that implement individual completion  strategies:
64       simple  completion, error correction, completion with error correction,
65       menu selection, etc.
66
67       More generally, the shell functions contained in the completion  system
68       are of two types:
69       ·      those beginning `comp' are to be called directly; there are only
70              a few of these;
71
72
73       ·      those beginning `_' are called  by  the  completion  code.   The
74              shell  functions  of this set, which implement completion behav‐
75              iour and may be bound to keystrokes, are referred  to  as  `wid‐
76              gets'.  These proliferate as new completions are required.
77
78

INITIALIZATION

80       If the system was installed completely, it should be enough to call the
81       shell function compinit from your initialization  file;  see  the  next
82       section.   However,  the  function  compinstall can be run by a user to
83       configure various aspects of the completion system.
84
85       Usually, compinstall will insert code into .zshrc, although if that  is
86       not  writable  it will save it in another file and tell you that file's
87       location.  Note that it is up to you to make sure that the lines  added
88       to  .zshrc are actually run; you may, for example, need to move them to
89       an earlier place in the file if .zshrc usually returns early.  So  long
90       as you keep them all together (including the comment lines at the start
91       and finish), you can rerun compinstall and it will correctly locate and
92       modify  these lines.  Note, however, that any code you add to this sec‐
93       tion by hand is likely to be lost if you  rerun  compinstall,  although
94       lines using the command `zstyle' should be gracefully handled.
95
96       The  new  code  will  take effect next time you start the shell, or run
97       .zshrc by hand; there is also an option to make them take effect  imme‐
98       diately.   However,  if  compinstall  has removed definitions, you will
99       need to restart the shell to see the changes.
100
101       To run compinstall you will need to make sure it is in a directory men‐
102       tioned in your fpath parameter, which should already be the case if zsh
103       was properly configured as long as your startup files do not remove the
104       appropriate  directories  from  fpath.   Then  it  must  be  autoloaded
105       (`autoload -U compinstall' is recommended).  You can abort the  instal‐
106       lation any time you are being prompted for information, and your .zshrc
107       will not be altered at all; changes only take place right at  the  end,
108       where you are specifically asked for confirmation.
109
110   Use of compinit
111       This section describes the use of compinit to initialize completion for
112       the current session when called directly; if you have  run  compinstall
113       it will be called automatically from your .zshrc.
114
115       To  initialize  the system, the function compinit should be in a direc‐
116       tory mentioned  in  the  fpath  parameter,  and  should  be  autoloaded
117       (`autoload  -U  compinit'  is  recommended),  and  then  run  simply as
118       `compinit'.  This will define a few utility functions, arrange for  all
119       the necessary shell functions to be autoloaded, and will then re-define
120       all widgets that do completion to use the new system.  If you  use  the
121       menu-select  widget,  which  is  part  of  the zsh/complist module, you
122       should make sure that that module is loaded before the call to compinit
123       so  that  that  widget  is  also re-defined.  If completion styles (see
124       below) are set up  to  perform  expansion  as  well  as  completion  by
125       default,  and the TAB key is bound to expand-or-complete, compinit will
126       rebind it to complete-word; this is necessary to use the  correct  form
127       of expansion.
128
129       Should  you need to use the original completion commands, you can still
130       bind keys to the old widgets by putting a `.' in front  of  the  widget
131       name, e.g. `.expand-or-complete'.
132
133       To speed up the running of compinit, it can be made to produce a dumped
134       configuration that will be read in on future invocations; this  is  the
135       default,  but can be turned off by calling compinit with the option -D.
136       The dumped file is .zcompdump in the  same  directory  as  the  startup
137       files  (i.e.  $ZDOTDIR  or $HOME); alternatively, an explicit file name
138       can be given  by  `compinit  -d  dumpfile'.   The  next  invocation  of
139       compinit  will  read  the dumped file instead of performing a full ini‐
140       tialization.
141
142       If the number of completion files changes, compinit will recognise this
143       and produce a new dump file.  However, if the name of a function or the
144       arguments in the first line of a #compdef function (as described below)
145       change,  it is easiest to delete the dump file by hand so that compinit
146       will re-create it the next time it is run.  The check performed to  see
147       if  there are new functions can be omitted by giving the option -C.  In
148       this case the dump file  will  only  be  created  if  there  isn't  one
149       already.
150
151       The  dumping  is  actually  done by another function, compdump, but you
152       will only need to run this yourself if  you  change  the  configuration
153       (e.g.  using  compdef)  and then want to dump the new one.  The name of
154       the old dumped file will be remembered for this purpose.
155
156       If the parameter _compdir is set, compinit uses it as a directory where
157       completion  functions  can be found; this is only necessary if they are
158       not already in the function search path.
159
160       For security reasons compinit also  checks  if  the  completion  system
161       would  use  files not owned by root or by the current user, or files in
162       directories that are world- or group-writable or that are not owned  by
163       root  or  by the current user.  If such files or directories are found,
164       compinit will ask if the completion system should really be  used.   To
165       avoid  these tests and make all files found be used without asking, use
166       the option -u, and to make compinit silently ignore all insecure  files
167       and  directories  use  the  option  -i.  This security check is skipped
168       entirely when the -C option is given.
169
170       The security check can be retried at any time by running  the  function
171       compaudit.   This  is  the  same check used by compinit, but when it is
172       executed directly any changes to fpath are made local to  the  function
173       so they do not persist.  The directories to be checked may be passed as
174       arguments; if none are given, compaudit uses fpath and _compdir to find
175       completion  system  directories, adding missing ones to fpath as neces‐
176       sary.  To force a check of exactly the directories currently  named  in
177       fpath,  set  _compdir  to  an  empty string before calling compaudit or
178       compinit.
179
180       The function bashcompinit provides compatibility with  bash's  program‐
181       mable  completion system.  When run it will define the functions, comp‐
182       gen and complete which correspond to the bash builtins  with  the  same
183       names.   It  will then be possible to use completion specifications and
184       functions written for bash.
185
186   Autoloaded files
187       The convention for autoloaded functions used in completion is that they
188       start with an underscore; as already mentioned, the fpath/FPATH parame‐
189       ter must contain the directory in which they are stored.   If  zsh  was
190       properly  installed on your system, then fpath/FPATH automatically con‐
191       tains the required directories for the standard functions.
192
193       For incomplete installations, if compinit does not  find  enough  files
194       beginning with an underscore (fewer than twenty) in the search path, it
195       will try to find more by adding the directory _compdir  to  the  search
196       path.  If that directory has a subdirectory named Base, all subdirecto‐
197       ries will be added to the path.  Furthermore, if the subdirectory  Base
198       has  a subdirectory named Core, compinit will add all subdirectories of
199       the subdirectories to the path: this allows the functions to be in  the
200       same format as in the zsh source distribution.
201
202       When  compinit  is  run,  it  searches  all  such  files accessible via
203       fpath/FPATH and reads the first line of each of them.  This line should
204       contain  one  of the tags described below.  Files whose first line does
205       not start with one of these tags are not considered to be part  of  the
206       completion system and will not be treated specially.
207
208       The tags are:
209
210       #compdef name ... [ -{p|P} pattern ... [ -N name ... ] ]
211              The  file  will be made autoloadable and the function defined in
212              it will be called when completing names, each of which is either
213              the name of a command whose arguments are to be completed or one
214              of a number of special contexts in the form -context-  described
215              below.
216
217              Each  name may also be of the form `cmd=service'.  When complet‐
218              ing the command cmd, the function typically behaves  as  if  the
219              command   (or  special  context)  service  was  being  completed
220              instead.  This provides a way of altering the behaviour of func‐
221              tions that can perform many different completions.  It is imple‐
222              mented by setting the parameter $service when calling the  func‐
223              tion;  the  function may choose to interpret this how it wishes,
224              and simpler functions will probably ignore it.
225
226              If the #compdef line contains one of the options -p or  -P,  the
227              words  following are taken to be patterns.  The function will be
228              called when completion is attempted for  a  command  or  context
229              that  matches  one  of  the patterns.  The options -p and -P are
230              used to specify patterns to be tried before or after other  com‐
231              pletions  respectively.  Hence -P may be used to specify default
232              actions.
233
234              The option -N is used after a list following -p or -P; it speci‐
235              fies that remaining words no longer define patterns.  It is pos‐
236              sible to toggle between the three options as many times as  nec‐
237              essary.
238
239       #compdef -k style key-sequence ...
240              This  option  creates  a widget behaving like the builtin widget
241              style and binds it to the  given  key-sequences,  if  any.   The
242              style  must  be  one of the builtin widgets that perform comple‐
243              tion, namely complete-word, delete-char-or-list,  expand-or-com‐
244              plete,  expand-or-complete-prefix,  list-choices, menu-complete,
245              menu-expand-or-complete,  or  reverse-menu-complete.    If   the
246              zsh/complist  module  is  loaded  (see zshmodules(1)) the widget
247              menu-select is also available.
248
249              When one of the key-sequences is typed, the function in the file
250              will  be  invoked to generate the matches.  Note that a key will
251              not be re-bound if it already was (that is, was bound  to  some‐
252              thing  other  than  undefined-key).   The widget created has the
253              same name as the file and can be bound to any other  keys  using
254              bindkey as usual.
255
256       #compdef -K widget-name style key-sequence [ name style seq ... ]
257              This is similar to -k except that only one key-sequence argument
258              may be given for each  widget-name  style  pair.   However,  the
259              entire  set  of three arguments may be repeated with a different
260              set of arguments.  Note in particular that the widget-name  must
261              be  distinct  in  each  set.  If it does not begin with `_' this
262              will be added.  The widget-name should not clash with  the  name
263              of  any existing widget: names based on the name of the function
264              are most useful.  For example,
265
266                     #compdef -K _foo_complete complete-word "^X^C" \
267                       _foo_list list-choices "^X^D"
268
269              (all on one line) defines a widget _foo_complete for completion,
270              bound  to  `^X^C',  and a widget _foo_list for listing, bound to
271              `^X^D'.
272
273       #autoload [ options ]
274              Functions with the #autoload tag are marked for autoloading  but
275              are  not  otherwise treated specially.  Typically they are to be
276              called from within one of the completion functions.  Any options
277              supplied  will  be passed to the autoload builtin; a typical use
278              is +X to force the function to be loaded immediately.  Note that
279              the -U and -z flags are always added implicitly.
280
281       The  #  is part of the tag name and no white space is allowed after it.
282       The #compdef tags use the compdef function described  below;  the  main
283       difference is that the name of the function is supplied implicitly.
284
285       The special contexts for which completion functions can be defined are:
286
287       -array-value-
288              The right hand side of an array-assignment (`name=(...)')
289
290       -brace-parameter-
291              The name of a parameter expansion within braces (`${...}')
292
293       -assign-parameter-
294              The  name of a parameter in an assignment, i.e. on the left hand
295              side of an `='
296
297       -command-
298              A word in command position
299
300       -condition-
301              A word inside a condition (`[[...]]')
302
303       -default-
304              Any word for which no other completion is defined
305
306       -equal-
307              A word beginning with an equals sign
308
309       -first-
310              This is tried before any other completion function.   The  func‐
311              tion  called  may  set the _compskip parameter to one of various
312              values: all: no further completion is attempted; a  string  con‐
313              taining  the substring patterns: no pattern completion functions
314              will be called; a string containing default:  the  function  for
315              the  `-default-'  context  will  not  be  called,  but functions
316              defined for commands will be.
317
318       -math- Inside mathematical contexts, such as `((...))'
319
320       -parameter-
321              The name of a parameter expansion (`$...')
322
323       -redirect-
324              The word after a redirection operator.
325
326       -subscript-
327              The contents of a parameter subscript.
328
329       -tilde-
330              After an initial tilde (`~'), but before the first slash in  the
331              word.
332
333       -value-
334              On the right hand side of an assignment.
335
336       Default  implementations  are  supplied for each of these contexts.  In
337       most cases the context -context-  is  implemented  by  a  corresponding
338       function  _context,  for example the context `-tilde-' and the function
339       `_tilde').
340
341       The contexts -redirect- and -value- allow extra context-specific infor‐
342       mation.  (Internally, this is handled by the functions for each context
343       calling the function _dispatch.)  The extra information is added  sepa‐
344       rated by commas.
345
346       For  the -redirect- context, the extra information is in the form `-re‐
347       direct-,op,command', where op is the redirection operator  and  command
348       is  the name of the command on the line.  If there is no command on the
349       line yet, the command field will be empty.
350
351       For the -value- context, the form is `-value-,name,command', where name
352       is  the  name of the parameter on the left hand side of the assignment.
353       In  the  case  of  elements  of  an  associative  array,  for   example
354       `assoc=(key <TAB>', name is expanded to `name-key'.  In certain special
355       contexts, such as completing after `make  CFLAGS=',  the  command  part
356       gives the name of the command, here make; otherwise it is empty.
357
358       It  is  not necessary to define fully specific completions as the func‐
359       tions provided  will  try  to  generate  completions  by  progressively
360       replacing  the elements with `-default-'.  For example, when completing
361       after `foo=<TAB>', _value will try the names `-value-,foo,'  (note  the
362       empty          command          part),          `-value-,foo,-default-'
363       and`-value-,-default-,-default-', in that order, until it finds a func‐
364       tion to handle the context.
365
366       As an example:
367
368              compdef '_files -g "*.log"' '-redirect-,2>,-default-'
369
370       completes  files matching `*.log' after `2> <TAB>' for any command with
371       no more specific handler defined.
372
373       Also:
374
375              compdef _foo -value-,-default-,-default-
376
377       specifies that _foo provides completions for the values  of  parameters
378       for  which  no special function has been defined.  This is usually han‐
379       dled by the function _value itself.
380
381       The same lookup rules are used when looking  up  styles  (as  described
382       below); for example
383
384              zstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log'
385
386       is  another  way  to  make  completion  after `2> <TAB>' complete files
387       matching `*.log'.
388
389   Functions
390       The following function  is  defined  by  compinit  and  may  be  called
391       directly.
392
393       compdef [ -ane ] function name ... [ -{p|P} pattern ... [ -N name ...]]
394       compdef -d name ...
395       compdef -k [ -an ] function style key-sequence [ key-sequence ... ]
396       compdef -K [ -an ] function name style key-seq [ name style seq ... ]
397              The  first  form  defines the function to call for completion in
398              the given contexts as described for the #compdef tag above.
399
400              Alternatively, all the arguments may  have  the  form  `cmd=ser‐
401              vice'.   Here  service  should  already  have  been  defined  by
402              `cmd1=service' lines in #compdef files, as described above.  The
403              argument for cmd will be completed in the same way as service.
404
405              The  function  argument may alternatively be a string containing
406              almost any shell code.  If the string contains  an  equal  sign,
407              the  above  will  take precedence.  The option -e may be used to
408              specify the first argument is to be evaluated as shell code even
409              if it contains an equal sign.  The string will be executed using
410              the eval builtin command to generate completions.  This provides
411              a  way  of  avoiding having to define a new completion function.
412              For example, to complete files ending in `.h'  as  arguments  to
413              the command foo:
414
415                     compdef '_files -g "*.h"' foo
416
417              The  option  -n prevents any completions already defined for the
418              command or context from being overwritten.
419
420              The option -d deletes any completion defined for the command  or
421              contexts listed.
422
423              The  names  may  also contain -p, -P and -N options as described
424              for the #compdef tag.  The effect on the argument list is  iden‐
425              tical,  switching  between  definitions  of  patterns tried ini‐
426              tially, patterns tried finally, and  normal  commands  and  con‐
427              texts.
428
429              The  parameter $_compskip may be set by any function defined for
430              a pattern context.  If it is set to a value containing the  sub‐
431              string  `patterns' none of the pattern-functions will be called;
432              if it is set to a value containing the substring `all', no other
433              function will be called.
434
435              The  form  with  -k  defines  a widget with the same name as the
436              function that will be called for each of the key-sequences; this
437              is  like  the #compdef -k tag.  The function should generate the
438              completions needed and will otherwise behave  like  the  builtin
439              widget  whose  name is given as the style argument.  The widgets
440              usable  for  this   are:   complete-word,   delete-char-or-list,
441              expand-or-complete,   expand-or-complete-prefix,   list-choices,
442              menu-complete,  menu-expand-or-complete,  and  reverse-menu-com‐
443              plete,  as  well  as  menu-select  if the zsh/complist module is
444              loaded.  The option -n prevents the key being  bound  if  it  is
445              already to bound to something other than undefined-key.
446
447              The  form  with -K is similar and defines multiple widgets based
448              on the same function, each of which requires the  set  of  three
449              arguments name, style and key-sequence, where the latter two are
450              as for -k and the first must be a unique widget  name  beginning
451              with an underscore.
452
453              Wherever  applicable, the -a option makes the function autoload‐
454              able, equivalent to autoload -U function.
455
456       The function compdef can be used to associate existing completion func‐
457       tions with new commands.  For example,
458
459              compdef _pids foo
460
461       uses the function _pids to complete process IDs for the command foo.
462
463       Note  also the _gnu_generic function described below, which can be used
464       to complete options for commands that understand the `--help' option.
465

COMPLETION SYSTEM CONFIGURATION

467       This section gives a short overview of how the completion system works,
468       and  then  more  detail on how users can configure how and when matches
469       are generated.
470
471   Overview
472       When completion is attempted somewhere on the command line the  comple‐
473       tion system begins building the context.  The context represents every‐
474       thing that the shell knows about the meaning of the  command  line  and
475       the  significance of the cursor position.  This takes account of a num‐
476       ber of things including the command word (such as `grep' or `zsh')  and
477       options  to which the current word may be an argument (such as the `-o'
478       option to zsh which takes a shell option as an argument).
479
480       The context starts out very generic ("we are beginning  a  completion")
481       and becomes more specific as more is learned ("the current word is in a
482       position that is usually a command name" or "the current word might  be
483       a  variable  name"  and so on).  Therefore the context will vary during
484       the same call to the completion system.
485
486       This context information is condensed into a string consisting of  mul‐
487       tiple  fields  separated by colons, referred to simply as `the context'
488       in the remainder of the documentation.  Note that a user of the comple‐
489       tion  system rarely needs to compose a context string, unless for exam‐
490       ple a new function is being written to perform  completion  for  a  new
491       command.   What a user may need to do is compose a style pattern, which
492       is matched against a context when needed to look  up  context-sensitive
493       options that configure the completion system.
494
495       The  next  few  paragraphs explain how a context is composed within the
496       completion function suite.  Following that is discussion of how  styles
497       are  defined.  Styles determine such things as how the matches are gen‐
498       erated, similarly to shell options but with much  more  control.   They
499       are defined with the zstyle builtin command (see zshmodules(1)).
500
501       The  context string always consists of a fixed set of fields, separated
502       by colons and with a leading colon before the first.  Fields which  are
503       not yet known are left empty, but the surrounding colons appear anyway.
504       The fields are always in the order  :completion:function:completer:com‐
505       mand:argument:tag.  These have the following meaning:
506
507       ·      The literal string completion, saying that this style is used by
508              the completion system.   This  distinguishes  the  context  from
509              those used by, for example, zle widgets and ZFTP functions.
510
511
512       ·      The function, if completion is called from a named widget rather
513              than through the normal completion system.   Typically  this  is
514              blank,  but  it is set by special widgets such as predict-on and
515              the various functions in the Widget directory of  the  distribu‐
516              tion to the name of that function, often in an abbreviated form.
517
518
519       ·      The completer currently active, the name of the function without
520              the leading underscore and with other underscores  converted  to
521              hyphens.   A `completer' is in overall control of how completion
522              is to be performed; `complete' is the simplest, but  other  com‐
523              pleters exist to perform related tasks such as correction, or to
524              modify the behaviour of a  later  completer.   See  the  section
525              `Control Functions' below for more information.
526
527
528       ·      The command or a special -context-, just at it appears following
529              the #compdef tag or the compdef function.  Completion  functions
530              for commands that have sub-commands usually modify this field to
531              contain the name of the command followed by a minus sign and the
532              sub-command.   For  example, the completion function for the cvs
533              command sets this field to cvs-add when completing arguments  to
534              the add subcommand.
535
536
537       ·      The  argument; this indicates which command line or option argu‐
538              ment we are completing.  For command  arguments  this  generally
539              takes  the  form  argument-n, where n is the number of the argu‐
540              ment, and for arguments to options the form option-opt-n where n
541              is  the  number of the argument to option opt.  However, this is
542              only the case if  the  command  line  is  parsed  with  standard
543              UNIX-style options and arguments, so many completions do not set
544              this.
545
546
547       ·      The tag.  As described previously, tags are used to discriminate
548              between  the types of matches a completion function can generate
549              in a certain context.  Any completion function may use  any  tag
550              name  it  likes,  but  a  list  of the more common ones is given
551              below.
552
553
554       The context is gradually put together as the  functions  are  executed,
555       starting  with  the  main  entry point, which adds :completion: and the
556       function element if necessary.  The completer then adds  the  completer
557       element.   The  contextual  completion  adds  the  command and argument
558       options.  Finally, the tag is added when the types  of  completion  are
559       known.  For example, the context name
560
561              :completion::complete:dvips:option-o-1:files
562
563       says  that normal completion was attempted as the first argument to the
564       option -o of the command dvips:
565
566              dvips -o ...
567
568       and the completion function will generate filenames.
569
570       Usually completion will be tried for all  possible  tags  in  an  order
571       given  by  the  completion  function.   However, this can be altered by
572       using the tag-order style.  Completion is then restricted to  the  list
573       of given tags in the given order.
574
575       The  _complete_help  bindable  command  shows all the contexts and tags
576       available for completion at a particular point.  This provides an  easy
577       way  of  finding  information  for  tag-order  and other styles.  It is
578       described in the section `Bindable Commands' below.
579
580       When looking up styles the completion system uses full  context  names,
581       including  the tag.  Looking up the value of a style therefore consists
582       of two things: the context, which is matched to the most specific (best
583       fitting) style pattern, and the name of the style itself, which must be
584       matched exactly.  The following examples demonstrate  that  style  pat‐
585       terns  may  be  loosely  defined  for  styles that apply broadly, or as
586       tightly defined as desired for styles that apply  in  narrower  circum‐
587       stances.
588
589       For example, many completion functions can generate matches in a simple
590       and a verbose form and use the  verbose  style  to  decide  which  form
591       should be used.  To make all such functions use the verbose form, put
592
593              zstyle ':completion:*' verbose yes
594
595       in  a startup file (probably .zshrc).  This gives the verbose style the
596       value yes in every context inside the completion  system,  unless  that
597       context has a more specific definition.  It is best to avoid giving the
598       context as `*' in case the style has some meaning outside  the  comple‐
599       tion system.
600
601       Many  such general purpose styles can be configured simply by using the
602       compinstall function.
603
604       A more specific example of the use of the verbose style is by the  com‐
605       pletion  for  the kill builtin.  If the style is set, the builtin lists
606       full job texts and process command lines; otherwise it shows  the  bare
607       job numbers and PIDs.  To turn the style off for this use only:
608
609              zstyle ':completion:*:*:kill:*:*' verbose no
610
611       For  even  more  control,  the  style can use one of the tags `jobs' or
612       `processes'.  To turn off verbose display only for jobs:
613
614              zstyle ':completion:*:*:kill:*:jobs' verbose no
615
616       The -e option to zstyle even allows completion function code to  appear
617       as  the  argument  to  a style; this requires some understanding of the
618       internals of completion functions (see see zshcompwid(1))).  For  exam‐
619       ple,
620
621              zstyle -e ':completion:*' hosts 'reply=($myhosts)'
622
623       This  forces  the value of the hosts style to be read from the variable
624       myhosts each time a host name is needed; this is useful if the value of
625       myhosts  can  change  dynamically.  For another useful example, see the
626       example in the description of the file-list style below.  This form can
627       be slow and should be avoided for commonly examined styles such as menu
628       and list-rows-first.
629
630       Note that the order in which styles are defined does  not  matter;  the
631       style  mechanism uses the most specific possible match for a particular
632       style to determine the set of values.  More precisely, strings are pre‐
633       ferred  over  patterns  (for  example, `:completion::complete:::foo' is
634       more specific than `:completion::complete:::*'),  and  longer  patterns
635       are preferred over shorter patterns.
636
637       A good rule of thumb is that any completion style pattern that needs to
638       include more than one wildcard (*) and that does not end in a tag name,
639       should  include  all  six  colons  (:), possibly surrounding additional
640       wildcards.
641
642       Style names like those of tags are arbitrary and depend on the  comple‐
643       tion  function.   However,  the following two sections list some of the
644       most common tags and styles.
645
646   Standard Tags
647       Some of the following are only used when looking up  particular  styles
648       and do not refer to a type of match.
649
650       accounts
651              used to look up the users-hosts style
652
653       all-expansions
654              used by the _expand completer when adding the single string con‐
655              taining all possible expansions
656
657       all-files
658              for the names of all files (as distinct from a  particular  sub‐
659              set, see the globbed-files tag).
660
661       arguments
662              for arguments to a command
663
664       arrays for names of array parameters
665
666       association-keys
667              for  keys  of  associative arrays; used when completing inside a
668              subscript to a parameter of this type
669
670       bookmarks
671              when completing bookmarks (e.g. for URLs and the  zftp  function
672              suite)
673
674       builtins
675              for names of builtin commands
676
677       characters
678              for  single  characters  in  arguments of commands such as stty.
679              Also used when completing character  classes  after  an  opening
680              bracket
681
682       colormapids
683              for X colormap ids
684
685       colors for color names
686
687       commands
688              for  names  of external commands.  Also used by complex commands
689              such as cvs when completing names subcommands.
690
691       contexts
692              for contexts in arguments to the zstyle builtin command
693
694       corrections
695              used by the _approximate and _correct  completers  for  possible
696              corrections
697
698       cursors
699              for cursor names used by X programs
700
701       default
702              used  in  some  contexts to provide a way of supplying a default
703              when more specific tags are also valid.  Note that this  tag  is
704              used when only the function field of the context name is set
705
706       descriptions
707              used  when  looking up the value of the format style to generate
708              descriptions for types of matches
709
710       devices
711              for names of device special files
712
713       directories
714              for names of directories -- local-directories  is  used  instead
715              when  completing  arguments  of  cd and related builtin commands
716              when the cdpath array is set
717
718       directory-stack
719              for entries in the directory stack
720
721       displays
722              for X display names
723
724       domains
725              for network domains
726
727       email-plugin
728              for  email  addresses  from  the  `_email-plugin'   backend   of
729              _email_addresses
730
731       expansions
732              used  by  the _expand completer for individual words (as opposed
733              to the complete set of expansions) resulting from the  expansion
734              of a word on the command line
735
736       extensions
737              for X server extensions
738
739       file-descriptors
740              for numbers of open file descriptors
741
742       files  the generic file-matching tag used by functions completing file‐
743              names
744
745       fonts  for X font names
746
747       fstypes
748              for file system types (e.g. for the mount command)
749
750       functions
751              names of functions -- normally shell functions, although certain
752              commands may understand other kinds of function
753
754       globbed-files
755              for filenames when the name has been generated by pattern match‐
756              ing
757
758       groups for names of user groups
759
760       history-words
761              for words from the history
762
763       hosts  for hostnames
764
765       indexes
766              for array indexes
767
768       jobs   for jobs (as listed by the `jobs' builtin)
769
770       interfaces
771              for network interfaces
772
773       keymaps
774              for names of zsh keymaps
775
776       keysyms
777              for names of X keysyms
778
779       libraries
780              for names of system libraries
781
782       limits for system limits
783
784       local-directories
785              for names of directories that are subdirectories of the  current
786              working  directory  when  completing arguments of cd and related
787              builtin commands (compare path-directories) -- when  the  cdpath
788              array is unset, directories is used instead
789
790       manuals
791              for names of manual pages
792
793       mailboxes
794              for e-mail folders
795
796       maps   for map names (e.g. NIS maps)
797
798       messages
799              used to look up the format style for messages
800
801       modifiers
802              for names of X modifiers
803
804       modules
805              for modules (e.g. zsh modules)
806
807       my-accounts
808              used to look up the users-hosts style
809
810       named-directories
811              for  named  directories  (you  wouldn't have guessed that, would
812              you?)
813
814       names  for all kinds of names
815
816       newsgroups
817              for USENET groups
818
819       nicknames
820              for nicknames of NIS maps
821
822       options
823              for command options
824
825       original
826              used by the _approximate, _correct and _expand  completers  when
827              offering the original string as a match
828
829       other-accounts
830              used to look up the users-hosts style
831
832       other-files
833              for  the names of any non-directory files.  This is used instead
834              of all-files when the list-dirs-first style is in effect.
835
836       packages
837              for packages (e.g. rpm or installed Debian packages)
838
839       parameters
840              for names of parameters
841
842       path-directories
843              for names of directories found by  searching  the  cdpath  array
844              when  completing  arguments  of  cd and related builtin commands
845              (compare local-directories)
846
847       paths  used to look up the values of the  expand,  ambiguous  and  spe‐
848              cial-dirs styles
849
850       pods   for perl pods (documentation files)
851
852       ports  for communication ports
853
854       prefixes
855              for prefixes (like those of a URL)
856
857       printers
858              for print queue names
859
860       processes
861              for process identifiers
862
863       processes-names
864              used  to  look up the command style when generating the names of
865              processes for killall
866
867       sequences
868              for sequences (e.g. mh sequences)
869
870       sessions
871              for sessions in the zftp function suite
872
873       signals
874              for signal names
875
876       strings
877              for strings (e.g. the replacement strings  for  the  cd  builtin
878              command)
879
880       styles for styles used by the zstyle builtin command
881
882       suffixes
883              for filename extensions
884
885       tags   for tags (e.g. rpm tags)
886
887       targets
888              for makefile targets
889
890       time-zones
891              for time zones (e.g. when setting the TZ parameter)
892
893       types  for types of whatever (e.g. address types for the xhost command)
894
895       urls   used to look up the urls and local styles when completing URLs
896
897       users  for usernames
898
899       values for one of a set of values in certain lists
900
901       variant
902              used  by _pick_variant to look up the command to run when deter‐
903              mining what program is installed for a particular command name.
904
905       visuals
906              for X visuals
907
908       warnings
909              used to look up the format style for warnings
910
911       widgets
912              for zsh widget names
913
914       windows
915              for IDs of X windows
916
917       zsh-options
918              for shell options
919
920   Standard Styles
921       Note that the values of several of these styles represent boolean  val‐
922       ues.   Any  of the strings `true', `on', `yes', and `1' can be used for
923       the value `true' and any of the strings `false', `off', `no',  and  `0'
924       for  the  value `false'.  The behavior for any other value is undefined
925       except where explicitly mentioned.  The default  value  may  be  either
926       `true' or `false' if the style is not set.
927
928       Some  of  these  styles  are tested first for every possible tag corre‐
929       sponding to a type of match, and if no style was found, for the default
930       tag.   The  most  notable styles of this type are menu, list-colors and
931       styles  controlling  completion  listing  such   as   list-packed   and
932       last-prompt.   When tested for the default tag, only the function field
933       of the context will be set so that a style using the default  tag  will
934       normally be defined along the lines of:
935
936              zstyle ':completion:*:default' menu ...
937
938       accept-exact
939              This is tested for the default tag in addition to the tags valid
940              for the current context.  If it is set to `true' and any of  the
941              trial  matches  is  the  same as the string on the command line,
942              this match will immediately be accepted (even if it would other‐
943              wise be considered ambiguous).
944
945              When  completing  pathnames (where the tag used is `paths') this
946              style accepts any number of patterns as the value in addition to
947              the  boolean  values.   Pathnames matching one of these patterns
948              will be accepted immediately even if the command  line  contains
949              some more partially typed pathname components and these match no
950              file under the directory accepted.
951
952              This style is also used by the _expand completer  to  decide  if
953              words  beginning  with  a tilde or parameter expansion should be
954              expanded.  For example, if there are parameters foo and  foobar,
955              the  string  `$foo' will only be expanded if accept-exact is set
956              to `true'; otherwise the completion system will  be  allowed  to
957              complete  $foo  to  $foobar.  If the style is set to `continue',
958              _expand will add the expansion as a  match  and  the  completion
959              system will also be allowed to continue.
960
961       accept-exact-dirs
962              This  is used by filename completion.  Unlike accept-exact it is
963              a boolean.  By default, filename completion examines all  compo‐
964              nents  of  a path to see if there are completions of that compo‐
965              nent, even if the component matches an existing directory.   For
966              example,  when completion after /usr/bin/, the function examines
967              possible completions to /usr.
968
969              When this style is `true', any prefix of a path that matches  an
970              existing  directory  is accepted without any attempt to complete
971              it further.  Hence, in the given example, the path /usr/bin/  is
972              accepted immediately and completion tried in that directory.
973
974              This style is also useful when completing after directories that
975              magically appear when referenced, such as ZFS  .zfs  directories
976              or  NetApp  .snapshot  directories.   When  the style is set the
977              shell does not check for the existence of the  directory  within
978              the parent directory.
979
980              If  you  wish  to  inhibit  this  behaviour  entirely,  set  the
981              path-completion style (see below) to `false'.
982
983       add-space
984              This style is used by the _expand completer.  If  it  is  `true'
985              (the  default), a space will be inserted after all words result‐
986              ing from the expansion, or a slash  in  the  case  of  directory
987              names.   If  the  value is `file', the completer will only add a
988              space to names of existing files.  Either a  boolean  `true'  or
989              the value `file' may be combined with `subst', in which case the
990              completer will not add a  space  to  words  generated  from  the
991              expansion of a substitution of the form `$(...)' or `${...}'.
992
993              The  _prefix completer uses this style as a simple boolean value
994              to decide if a space should be inserted before the suffix.
995
996       ambiguous
997              This applies when completing non-final  components  of  filename
998              paths,  in  other  words  those with a trailing slash.  If it is
999              set, the cursor is left after  the  first  ambiguous  component,
1000              even  if  menu completion is in use.  The style is always tested
1001              with the paths tag.
1002
1003       assign-list
1004              When completing after an equals sign that is being treated as an
1005              assignment,  the  completion  system normally completes only one
1006              filename.  In some cases the value  may be a list  of  filenames
1007              separated  by colons, as with PATH and similar parameters.  This
1008              style can be set to a list of patterns  matching  the  names  of
1009              such parameters.
1010
1011              The  default  is  to  complete  lists  when the word on the line
1012              already contains a colon.
1013
1014       auto-description
1015              If set, this style's value will be used as the  description  for
1016              options  that are not described by the completion functions, but
1017              that have exactly one argument.  The sequence `%d' in the  value
1018              will  be replaced by the description for this argument.  Depend‐
1019              ing on personal preferences, it may be useful to set this  style
1020              to  something  like  `specify: %d'.  Note that this may not work
1021              for some commands.
1022
1023       avoid-completer
1024              This is used by the _all_matches  completer  to  decide  if  the
1025              string  consisting  of  all  matches should be added to the list
1026              currently being generated.  Its value is a list of names of com‐
1027              pleters.  If any of these is the name of the completer that gen‐
1028              erated the matches in this completion, the string  will  not  be
1029              added.
1030
1031              The  default value for this style is `_expand _old_list _correct
1032              _approximate', i.e. it  contains  the  completers  for  which  a
1033              string with all matches will almost never be wanted.
1034
1035       cache-path
1036              This  style  defines  the  path where any cache files containing
1037              dumped completion data  are  stored.   It  defaults  to  `$ZDOT‐
1038              DIR/.zcompcache',  or  `$HOME/.zcompcache'  if  $ZDOTDIR  is not
1039              defined.  The completion cache  will  not  be  used  unless  the
1040              use-cache style is set.
1041
1042       cache-policy
1043              This  style  defines the function that will be used to determine
1044              whether a cache  needs  rebuilding.   See  the  section  on  the
1045              _cache_invalid function below.
1046
1047       call-command
1048              This style is used in the function for commands such as make and
1049              ant where calling the command directly to generate matches  suf‐
1050              fers  problems such as being slow or, as in the case of make can
1051              potentially cause actions in the makefile to be executed. If  it
1052              is  set to `true' the command is called to generate matches. The
1053              default value of this style is `false'.
1054
1055       command
1056              In many places, completion functions need to call external  com‐
1057              mands  to  generate  the list of completions.  This style can be
1058              used to override the command that is called in some such  cases.
1059              The  elements of the value are joined with spaces to form a com‐
1060              mand line to execute.  The value can also start with  a  hyphen,
1061              in  which  case the usual command will be added to the end; this
1062              is most useful for putting `builtin' or `command'  in  front  to
1063              make  sure  the  appropriate version of a command is called, for
1064              example to avoid calling a shell function with the same name  as
1065              an external command.
1066
1067              As an example, the completion function for process IDs uses this
1068              style with the processes tag to generate the IDs to complete and
1069              the  list  of  processes  to  display  (if  the verbose style is
1070              `true').  The list produced by the command should look like  the
1071              output  of the ps command.  The first line is not displayed, but
1072              is searched for the string `PID' (or `pid') to find the position
1073              of the process IDs in the following lines.  If the line does not
1074              contain `PID', the first numbers in each of the other lines  are
1075              taken as the process IDs to complete.
1076
1077              Note  that  the  completion  function  generally has to call the
1078              specified command for each attempt to  generate  the  completion
1079              list.   Hence care should be taken to specify only commands that
1080              take a short time to run, and in particular to  avoid  any  that
1081              may never terminate.
1082
1083       command-path
1084              This  is  a  list  of directories to search for commands to com‐
1085              plete.  The default for this style is the value of  the  special
1086              parameter path.
1087
1088       commands
1089              This  is  used  by  the function completing sub-commands for the
1090              system initialisation scripts (residing in /etc/init.d or  some‐
1091              where  not too far away from that).  Its values give the default
1092              commands to complete for those commands for which the completion
1093              function isn't able to find them out automatically.  The default
1094              for this style are the two strings `start' and `stop'.
1095
1096       complete
1097              This is used by the _expand_alias function  when  invoked  as  a
1098              bindable  command.  If set to `true' and the word on the command
1099              line is not the name of an alias, matching alias names  will  be
1100              completed.
1101
1102       complete-options
1103              This  is  used  by  the  completer for cd, chdir and pushd.  For
1104              these commands a - is used to introduce a directory stack  entry
1105              and  completion  of  these  is  far  more common than completing
1106              options.  Hence unless the value of this style is `true' options
1107              will  not  be  completed,  even  after  an  initial -.  If it is
1108              `true', options will be completed  after  an  initial  -  unless
1109              there is a preceding -- on the command line.
1110
1111       completer
1112              The  strings  given as the value of this style provide the names
1113              of the completer functions to use. The available completer func‐
1114              tions are described in the section `Control Functions' below.
1115
1116              Each  string may be either the name of a completer function or a
1117              string of the form `function:name'.  In the first case the  com‐
1118              pleter  field  of  the context will contain the name of the com‐
1119              pleter without the leading underscore and with all other  under‐
1120              scores  replaced by hyphens.  In the second case the function is
1121              the name of the completer to call, but the context will  contain
1122              the user-defined name in the completer field of the context.  If
1123              the name starts with a hyphen, the string for the  context  will
1124              be build from the name of the completer function as in the first
1125              case with the name appended to it.  For example:
1126
1127                     zstyle ':completion:*' completer _complete _complete:-foo
1128
1129              Here, completion will call the _complete completer  twice,  once
1130              using  `complete' and once using `complete-foo' in the completer
1131              field of the context.  Normally, using the same  completer  more
1132              than  once  only makes sense when used with the `functions:name'
1133              form, because otherwise the context name will be the same in all
1134              calls to the completer; possible exceptions to this rule are the
1135              _ignored and _prefix completers.
1136
1137              The default value for this style is `_complete  _ignored':  only
1138              completion  will be done, first using the ignored-patterns style
1139              and the $fignore array and then without ignoring matches.
1140
1141       condition
1142              This style is used by the _list completer function to decide  if
1143              insertion  of  matches  should  be  delayed unconditionally. The
1144              default is `true'.
1145
1146       delimiters
1147              This style is used when adding a delimiter for use with  history
1148              modifiers  or glob qualifiers that have delimited arguments.  It
1149              is an array of preferred delimiters to add.  Non-special charac‐
1150              ters are preferred as the completion system may otherwise become
1151              confused.  The default list is :, +, /, -, %.  The list  may  be
1152              empty to force a delimiter to be typed.
1153
1154       disabled
1155              If  this is set to `true', the _expand_alias completer and bind‐
1156              able command will try to  expand  disabled  aliases,  too.   The
1157              default is `false'.
1158
1159       domains
1160              A  list  of names of network domains for completion.  If this is
1161              not  set,  domain  names   will   be   taken   from   the   file
1162              /etc/resolv.conf.
1163
1164       environ
1165              The environ style is used when completing for `sudo'.  It is set
1166              to an array of `VAR=value' assignments to be exported  into  the
1167              local  environment  before the completion for the target command
1168              is invoked.
1169              zstyle ':completion:*:sudo::' environ \
1170                PATH="/sbin:/usr/sbin:$PATH" HOME="/root"
1171
1172       expand This style is used when completing strings consisting of  multi‐
1173              ple parts, such as path names.
1174
1175              If one of its values is the string `prefix', the partially typed
1176              word from the line will be expanded as far as possible  even  if
1177              trailing parts cannot be completed.
1178
1179              If  one of its values is the string `suffix', matching names for
1180              components after the first ambiguous one  will  also  be  added.
1181              This  means that the resulting string is the longest unambiguous
1182              string possible.  However, menu completion can be used to  cycle
1183              through all matches.
1184
1185       fake   This  style may be set for any completion context.  It specifies
1186              additional strings that will always be completed  in  that  con‐
1187              text.  The form of each string is `value:description'; the colon
1188              and description may be omitted, but any literal colons in  value
1189              must  be  quoted  with a backslash.  Any description provided is
1190              shown alongside the value in completion listings.
1191
1192              It is important to use a sufficiently restrictive  context  when
1193              specifying  fake  strings.   Note that the styles fake-files and
1194              fake-parameters  provide  additional  features  when  completing
1195              files or parameters.
1196
1197       fake-always
1198              This  works  identically  to  the  fake  style  except  that the
1199              ignored-patterns style is not applied to it.  This makes it pos‐
1200              sible  to  override  a  set of matches completely by setting the
1201              ignored patterns to `*'.
1202
1203              The following shows a way of supplementing any  tag  with  arbi‐
1204              trary  data,  but  having  it behave for display purposes like a
1205              separate tag.  In this  example  we  use  the  features  of  the
1206              tag-order  style  to  divide  the named-directories tag into two
1207              when performing completion with the standard completer  complete
1208              for  arguments  of cd.  The tag named-directories-normal behaves
1209              as normal, but the tag named-directories-mine contains  a  fixed
1210              set  of  directories.   This  has the effect of adding the match
1211              group `extra directories' with the given completions.
1212
1213                     zstyle ':completion::complete:cd:*' tag-order \
1214                       'named-directories:-mine:extra\ directories
1215                       named-directories:-normal:named\ directories *'
1216                     zstyle ':completion::complete:cd:*:named-directories-mine' \
1217                       fake-always mydir1 mydir2
1218                     zstyle ':completion::complete:cd:*:named-directories-mine' \
1219                       ignored-patterns '*'
1220
1221       fake-files
1222              This style is used when completing files and looked up without a
1223              tag.   Its values are of the form `dir:names...'.  This will add
1224              the names (strings separated by spaces) as possible matches when
1225              completing  in  the  directory dir, even if no such files really
1226              exist.  The dir may be a pattern; pattern characters  or  colons
1227              in  dir  should  be quoted with a backslash to be treated liter‐
1228              ally.
1229
1230              This can be useful on systems that support special file  systems
1231              whose  top-level  pathnames  can not be listed or generated with
1232              glob patterns (but see accept-exact-dirs for a more general  way
1233              of dealing with this problem).  It can also be used for directo‐
1234              ries for which one does not have read permission.
1235
1236              The pattern form can be used to add a certain `magic'  entry  to
1237              all directories on a particular file system.
1238
1239       fake-parameters
1240              This  is  used  by  the completion function for parameter names.
1241              Its values are names of parameters that might not yet be set but
1242              should be completed nonetheless.  Each name may also be followed
1243              by a colon and a string specifying the  type  of  the  parameter
1244              (like  `scalar',  `array'  or `integer').  If the type is given,
1245              the name will only be completed if parameters of that  type  are
1246              required  in the particular context.  Names for which no type is
1247              specified will always be completed.
1248
1249       file-list
1250              This style controls whether files completed using  the  standard
1251              builtin  mechanism  are to be listed with a long list similar to
1252              ls -l.  Note that this feature uses the  shell  module  zsh/stat
1253              for  file  information;  this  loads the builtin stat which will
1254              replace any external stat executable.  To avoid this the follow‐
1255              ing code can be included in an initialization file:
1256
1257                     zmodload -i zsh/stat
1258                     disable stat
1259
1260              The style may either be set to a `true' value (or `all'), or one
1261              of the values `insert' or `list', indicating that files  are  to
1262              be  listed in long format in all circumstances, or when attempt‐
1263              ing to insert a file name, or when listing  file  names  without
1264              attempting to insert one.
1265
1266              More  generally,  the  value may be an array of any of the above
1267              values, optionally followed by =num.  If num is present it gives
1268              the  maximum number of matches for which long listing style will
1269              be used.  For example,
1270
1271                     zstyle ':completion:*' file-list list=20 insert=10
1272
1273              specifies that long format will be used when listing  up  to  20
1274              files  or  inserting  a  file  with up to 10 matches (assuming a
1275              listing is to be shown at all, for example on an ambiguous  com‐
1276              pletion), else short format will be used.
1277
1278                     zstyle -e ':completion:*' file-list \
1279                            '(( ${+NUMERIC} )) && reply=(true)'
1280
1281              specifies that long format will be used any time a numeric argu‐
1282              ment is supplied, else short format.
1283
1284       file-patterns
1285              This is used by the standard function for completing  filenames,
1286              _files.   If  the  style  is unset up to three tags are offered,
1287              `globbed-files',`directories' and `all-files', depending on  the
1288              types of files  expected by the caller of _files.  The first two
1289              (`globbed-files'  and  `directories')   are   normally   offered
1290              together to make it easier to complete files in sub-directories.
1291
1292              The  file-patterns  style  provides  alternatives to the default
1293              tags, which are not used.  Its value consists of elements of the
1294              form  `pattern:tag';  each string may contain any number of such
1295              specifications separated by spaces.
1296
1297              The pattern is a pattern that is to be used  to  generate  file‐
1298              names.   Any  occurrence of the sequence `%p' is replaced by any
1299              pattern(s) passed by the function calling _files.  Colons in the
1300              pattern  must  be  preceded  by a backslash to make them distin‐
1301              guishable from the colon before the tag.  If more than one  pat‐
1302              tern  is  needed, the patterns can be given inside braces, sepa‐
1303              rated by commas.
1304
1305              The tags of all strings in the value will be offered  by  _files
1306              and  used  when  looking  up other styles.  Any tags in the same
1307              word will be offered at the same time and  before  later  words.
1308              If no `:tag' is given the `files' tag will be used.
1309
1310              The  tag  may also be followed by an optional second colon and a
1311              description, which will be used for the `%d' in the value of the
1312              format style (if that is set) instead of the default description
1313              supplied by the completion function.  If the  description  given
1314              here  contains itself a `%d', that is replaced with the descrip‐
1315              tion supplied by the completion function.
1316
1317              For example, to make the rm command first complete only names of
1318              object  files  and  then  the  names of all files if there is no
1319              matching object file:
1320
1321                     zstyle ':completion:*:*:rm:*:*' file-patterns \
1322                         '*.o:object-files' '%p:all-files'
1323
1324              To alter the default behaviour of file completion -- offer files
1325              matching  a  pattern  and directories on the first attempt, then
1326              all files -- to offer only matching files on the first  attempt,
1327              then directories, and finally all files:
1328
1329                     zstyle ':completion:*' file-patterns \
1330                         '%p:globbed-files' '*(-/):directories' '*:all-files'
1331
1332              This  works  even  where  there  is  no  special pattern: _files
1333              matches all files using the pattern `*' at the  first  step  and
1334              stops  when it sees this pattern.  Note also it will never try a
1335              pattern more than once for a single completion attempt.
1336
1337              During the execution of completion functions, the  EXTENDED_GLOB
1338              option  is  in  effect,  so the characters `#', `~' and `^' have
1339              special meanings in the patterns.
1340
1341       file-sort
1342              The standard filename completion function uses this style  with‐
1343              out  a  tag  to  determine  in  which  order the names should be
1344              listed; menu completion will cycle  through  them  in  the  same
1345              order.   The  possible values are: `size' to sort by the size of
1346              the file; `links' to sort by the number of links  to  the  file;
1347              `modification' (or `time' or `date') to sort by the last modifi‐
1348              cation time; `access' to sort  by  the  last  access  time;  and
1349              `inode' (or `change') to sort by the last inode change time.  If
1350              the style is set to any other value, or is unset, files will  be
1351              sorted alphabetically by name.  If the value contains the string
1352              `reverse', sorting is done in the opposite order.  If the  value
1353              contains the string `follow', timestamps are associated with the
1354              targets of symbolic links; the default is to use the  timestamps
1355              of the links themselves.
1356
1357       filter The    ldap    plugin   of   email   address   completion   (see
1358              _email_addresses) uses this style to specify the  attributes  to
1359              match  against  when  filtering entries.  So for example, if the
1360              style is set to `sn', matching is done against surnames.   Stan‐
1361              dard  LDAP  filtering  is  used so normal completion matching is
1362              bypassed.  If this style is not set, the LDAP plugin is skipped.
1363              You  may  also  need  to set the command style to specify how to
1364              connect to your LDAP server.
1365
1366       force-list
1367              This forces a list of completions to be shown at any point where
1368              listing  is  done, even in cases where the list would usually be
1369              suppressed.  For example, normally the list  is  only  shown  if
1370              there are at least two different matches.  By setting this style
1371              to `always', the list will always be shown,  even  if  there  is
1372              only  a  single  match  that  will immediately be accepted.  The
1373              style may also be set to a number.  In this case the  list  will
1374              be  shown  if there are at least that many matches, even if they
1375              would all insert the same string.
1376
1377              This style is tested for the default tag as well as for each tag
1378              valid  for  the  current  completion.   Hence the listing can be
1379              forced only for certain types of match.
1380
1381       format If this is set for the descriptions tag, its value is used as  a
1382              string  to  display  above  matches  in  completion  lists.  The
1383              sequence `%d' in this string  will  be  replaced  with  a  short
1384              description  of  what  these  matches are.  This string may also
1385              contain the following sequences to specify output attributes  as
1386              described  in  the section EXPANSION OF PROMPT SEQUENCES in zsh‐
1387              misc(1): `%B', `%S', `%U', `%F', `%K' and their lower case coun‐
1388              terparts,  as  well as `%{...%}'.  `%F', `%K' and `%{...%}' take
1389              arguments in the same form as prompt expansion.  Note  that  the
1390              sequence  `%G'  is  not available; an argument to `%{' should be
1391              used instead.
1392
1393              The style is tested with each tag valid for the current  comple‐
1394              tion  before  it is tested for the descriptions tag.  Hence dif‐
1395              ferent format strings can be  defined  for  different  types  of
1396              match.
1397
1398              Note  also  that  some  completer  functions  define  additional
1399              `%'-sequences.  These are described for the completer  functions
1400              that make use of them.
1401
1402              Some  completion  functions  display  messages  that may be cus‐
1403              tomised by setting this style for the messages tag.   Here,  the
1404              `%d'  is  replaced  with a message given by the completion func‐
1405              tion.
1406
1407              Finally, the format string is looked up with the  warnings  tag,
1408              for use when no matches could be generated at all.  In this case
1409              the `%d' is replaced with the descriptions for the matches  that
1410              were  expected  separated  by  spaces.   The  sequence  `%D'  is
1411              replaced with the same descriptions separated by newlines.
1412
1413              It is possible to use printf-style field width  specifiers  with
1414              `%d' and similar escape sequences.  This is handled by the zfor‐
1415              mat builtin command  from  the  zsh/zutil  module,  see  zshmod‐
1416              ules(1).
1417
1418       glob   This  is  used by the _expand completer.  If it is set to `true'
1419              (the default), globbing will be attempted on the words resulting
1420              from  a previous substitution (see the substitute style) or else
1421              the original string from the line.
1422
1423       global If this is set to `true' (the default), the  _expand_alias  com‐
1424              pleter and bindable command will try to expand global aliases.
1425
1426       group-name
1427              The  completion  system  can  group  different types of matches,
1428              which appear in separate lists.  This style can be used to  give
1429              the  names  of groups for particular tags.  For example, in com‐
1430              mand position the completion system generates names  of  builtin
1431              and  external  commands,  names  of aliases, shell functions and
1432              parameters and reserved words as possible completions.  To  have
1433              the external commands and shell functions listed separately:
1434
1435                     zstyle ':completion:*:*:-command-:*:commands' \
1436                            group-name commands
1437                     zstyle ':completion:*:*:-command-:*:functions' \
1438                            group-name functions
1439
1440              As  a consequence, any match with the same tag will be displayed
1441              in the same group.
1442
1443              If the name given is the empty string the name of  the  tag  for
1444              the  matches will be used as the name of the group.  So, to have
1445              all different types of matches  displayed  separately,  one  can
1446              just set:
1447
1448                     zstyle ':completion:*' group-name ''
1449
1450              All  matches for which no group name is defined will be put in a
1451              group named -default-.
1452
1453       group-order
1454              This style is additional to the group-name style to specify  the
1455              order  for  display of the groups defined by that style (compare
1456              tag-order, which determines which completions  appear  at  all).
1457              The  groups named are shown in the given order; any other groups
1458              are shown in the order defined by the completion function.
1459
1460              For example, to have names of builtin commands, shell  functions
1461              and  external  commands  appear in that order when completing in
1462              command position:
1463
1464                     zstyle ':completion:*:*:-command-:*:*' group-order \
1465                            builtins functions commands
1466
1467       groups A list of names of UNIX groups.  If this is not set, group names
1468              are taken from the YP database or the file `/etc/group'.
1469
1470       hidden If this is set to `true', matches for the given context will not
1471              be listed, although any description for the matches set with the
1472              format style will be shown.  If it is set to `all', not even the
1473              description will be displayed.
1474
1475              Note that the matches will still be completed; they are just not
1476              shown in the list.  To avoid having matches considered as possi‐
1477              ble completions at all, the tag-order style can be  modified  as
1478              described below.
1479
1480       hosts  A  list  of names of hosts that should be completed.  If this is
1481              not set, hostnames are taken from the file `/etc/hosts'.
1482
1483       hosts-ports
1484              This style is used by commands that need or accept hostnames and
1485              network  ports.   The strings in the value should be of the form
1486              `host:port'.  Valid ports are  determined  by  the  presence  of
1487              hostnames; multiple ports for the same host may appear.
1488
1489       ignore-line
1490              This  is  tested  for each tag valid for the current completion.
1491              If it is set to `true', none of the words that  are  already  on
1492              the  line  will be considered as possible completions.  If it is
1493              set to `current', the word the cursor is on will not be  consid‐
1494              ered  as  a  possible  completion.  The value `current-shown' is
1495              similar but only applies if the list of completions is currently
1496              shown  on  the screen.  Finally, if the style is set to `other',
1497              all words on the  line  except  for  the  current  one  will  be
1498              excluded from the possible completions.
1499
1500              The  values  `current'  and  `current-shown'  are a bit like the
1501              opposite of the accept-exact style:  only strings  with  missing
1502              characters will be completed.
1503
1504              Note  that you almost certainly don't want to set this to `true'
1505              or `other' for a general context such as `:completion:*'.   This
1506              is because it would disallow completion of, for example, options
1507              multiple times even if  the  command  in  question  accepts  the
1508              option more than once.
1509
1510       ignore-parents
1511              The  style  is  tested  without a tag by the function completing
1512              pathnames in order to determine whether to ignore the  names  of
1513              directories  already  mentioned in the current word, or the name
1514              of the current working directory.  The value must include one or
1515              both of the following strings:
1516
1517              parent The name of any directory whose path is already contained
1518                     in the word on the line is ignored.   For  example,  when
1519                     completing  after  foo/../, the directory foo will not be
1520                     considered a valid completion.
1521
1522              pwd    The name of the current working  directory  will  not  be
1523                     completed;  hence, for example, completion after ../ will
1524                     not use the name of the current directory.
1525
1526              In addition, the value may include one or both of:
1527
1528              ..     Ignore the specified directories only when  the  word  on
1529                     the line contains the substring `../'.
1530
1531              directory
1532                     Ignore  the  specified  directories  only  when  names of
1533                     directories are completed, not when completing  names  of
1534                     files.
1535
1536              Excluded  values  act  in  a  similar  fashion  to values of the
1537              ignored-patterns style, so they can be restored to consideration
1538              by the _ignored completer.
1539
1540       extra-verbose
1541              If  set, the completion listing is more verbose at the cost of a
1542              probable decrease in completion speed.   Completion  performance
1543              will suffer if this style is set to `true'.
1544
1545       ignored-patterns
1546              A  list  of  patterns;  any trial completion matching one of the
1547              patterns will be excluded from consideration.  The _ignored com‐
1548              pleter  can  appear  in  the  list  of completers to restore the
1549              ignored matches.  This is a more  configurable  version  of  the
1550              shell parameter $fignore.
1551
1552              Note  that  the EXTENDED_GLOB option is set during the execution
1553              of completion functions, so the characters `#', `~' and `^' have
1554              special meanings in the patterns.
1555
1556       insert This  style  is  used  by  the  _all_matches completer to decide
1557              whether to  insert  the  list  of  all  matches  unconditionally
1558              instead of adding the list as another match.
1559
1560       insert-ids
1561              When  completing  process  IDs,  for example as arguments to the
1562              kill and wait builtins the name of a command may be converted to
1563              the  appropriate  process ID.  A problem arises when the process
1564              name typed is not unique.  By default (or if this style  is  set
1565              explicitly  to `menu') the name will be converted immediately to
1566              a set of possible IDs, and menu completion will  be  started  to
1567              cycle through them.
1568
1569              If the value of the style is `single', the shell will wait until
1570              the user has typed enough to make the command unique before con‐
1571              verting the name to an ID; attempts at completion will be unsuc‐
1572              cessful until that point.  If the value  is  any  other  string,
1573              menu  completion  will  be  started when the string typed by the
1574              user is longer than the common prefix to the corresponding IDs.
1575
1576       insert-tab
1577              If this is set to `true', the completion system  will  insert  a
1578              TAB  character  (assuming  that  was  used  to start completion)
1579              instead of performing completion  when  there  is  no  non-blank
1580              character  to  the left of the cursor.  If it is set to `false',
1581              completion will be done even there.
1582
1583              The value may also contain the substrings  `pending'  or  `pend‐
1584              ing=val'.   In  this  case, the typed character will be inserted
1585              instead of starting completion when there is  unprocessed  input
1586              pending.   If  a  val  is  given, completion will not be done if
1587              there are at least that many characters  of  unprocessed  input.
1588              This  is  often  useful when pasting characters into a terminal.
1589              Note however, that it relies on the $PENDING  special  parameter
1590              from  the zsh/zle module being set properly which is not guaran‐
1591              teed on all platforms.
1592
1593              The default value of this style is `true' except for  completion
1594              within vared builtin command where it is `false'.
1595
1596       insert-unambiguous
1597              This  is  used by the _match and _approximate completers.  These
1598              completers are often used with menu completion  since  the  word
1599              typed may bear little resemblance to the final completion.  How‐
1600              ever, if this style is `true', the  completer  will  start  menu
1601              completion  only  if it could find no unambiguous initial string
1602              at least as long as the original string typed by the user.
1603
1604              In the case of the _approximate completer, the  completer  field
1605              in  the context will already have been set to one of correct-num
1606              or approximate-num, where num is the number of errors that  were
1607              accepted.
1608
1609              In  the  case of the _match completer, the style may also be set
1610              to the string `pattern'.  Then the pattern on the line  is  left
1611              unchanged if it does not match unambiguously.
1612
1613       gain-privileges
1614              If set to true, this style enables the use of commands like sudo
1615              or doas to gain extra privileges when retrieving information for
1616              completion.  This  is  only  done  when  a  command such as sudo
1617              appears on the command-line. To force the use of, e.g.  sudo  or
1618              to  override  any  prefix that might be added due to gain-privi‐
1619              leges, the command style can be used with a  value  that  begins
1620              with a hyphen.
1621
1622       keep-prefix
1623              This  style  is used by the _expand completer.  If it is `true',
1624              the completer will try to keep a prefix containing  a  tilde  or
1625              parameter  expansion.   Hence,  for  example,  the string `~/f*'
1626              would be expanded to `~/foo' instead  of  `/home/user/foo'.   If
1627              the  style  is  set  to `changed' (the default), the prefix will
1628              only be left unchanged if there were other changes  between  the
1629              expanded words and the original word from the command line.  Any
1630              other value forces the prefix to be expanded unconditionally.
1631
1632              The behaviour of _expand when this style is `true' is  to  cause
1633              _expand  to  give  up  when a single expansion with the restored
1634              prefix is the same as the original;  hence  any  remaining  com‐
1635              pleters may be called.
1636
1637       last-prompt
1638              This  is  a more flexible form of the ALWAYS_LAST_PROMPT option.
1639              If it is `true', the completion system will try  to  return  the
1640              cursor  to  the previous command line after displaying a comple‐
1641              tion list.  It is tested for all tags valid for the current com‐
1642              pletion, then the default tag.  The cursor will be moved back to
1643              the previous line if this style  is  `true'  for  all  types  of
1644              match.   Note  that unlike the ALWAYS_LAST_PROMPT option this is
1645              independent of the numeric argument.
1646
1647       known-hosts-files
1648              This style should contain a list of files  to  search  for  host
1649              names  and (if the use-ip style is set) IP addresses in a format
1650              compatible with ssh known_hosts files.  If it is  not  set,  the
1651              files /etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts are used.
1652
1653       list   This  style  is used by the _history_complete_word bindable com‐
1654              mand.  If it is set to `true' it has no effect.  If it is set to
1655              `false'  matches will not be listed.  This overrides the setting
1656              of the options  controlling  listing  behaviour,  in  particular
1657              AUTO_LIST.   The  context  always  starts with `:completion:his‐
1658              tory-words'.
1659
1660       list-colors
1661              If the zsh/complist module is loaded, this style can be used  to
1662              set  color  specifications.   This mechanism replaces the use of
1663              the ZLS_COLORS and ZLS_COLOURS parameters described in the  sec‐
1664              tion  `The zsh/complist Module' in zshmodules(1), but the syntax
1665              is the same.
1666
1667              If this style is set for the default tag,  the  strings  in  the
1668              value  are  taken  as  specifications that are to be used every‐
1669              where.  If it is set for other tags, the specifications are used
1670              only  for matches of the type described by the tag.  For this to
1671              work best, the group-name style must be set to an empty string.
1672
1673              In addition to setting styles for specific tags, it is also pos‐
1674              sible  to use group names specified explicitly by the group-name
1675              tag together with the `(group)' syntax allowed by the ZLS_COLORS
1676              and ZLS_COLOURS parameters and simply using the default tag.
1677
1678              It  is  possible  to use any color specifications already set up
1679              for the GNU version of the ls command:
1680
1681                     zstyle ':completion:*:default' list-colors \
1682                            ${(s.:.)LS_COLORS}
1683
1684              The default colors are the same as for the GNU  ls  command  and
1685              can  be  obtained  by setting the style to an empty string (i.e.
1686              '').
1687
1688       list-dirs-first
1689              This is used by file completion.  If set, directories to be com‐
1690              pleted  are  listed  separately  from  and before completion for
1691              other files, regardless of tag ordering.  In addition,  the  tag
1692              other-files  is  used  in  place  of all-files for the remaining
1693              files, to indicate that no directories are presented  with  that
1694              tag.
1695
1696       list-grouped
1697              If  this  style  is  `true' (the default), the completion system
1698              will try to make certain completion  listings  more  compact  by
1699              grouping  matches.   For example, options for commands that have
1700              the same description (shown when the verbose  style  is  set  to
1701              `true')  will appear as a single entry.  However, menu selection
1702              can be used to cycle through all the matches.
1703
1704       list-packed
1705              This is tested for each tag valid in the current context as well
1706              as  the  default tag.  If it is set to `true', the corresponding
1707              matches appear in listings as if  the  LIST_PACKED  option  were
1708              set.  If it is set to `false', they are listed normally.
1709
1710       list-prompt
1711              If  this style is set for the default tag, completion lists that
1712              don't fit on the screen can be scrolled (see the description  of
1713              the  zsh/complist  module  in zshmodules(1)).  The value, if not
1714              the empty string, will be displayed after  every  screenful  and
1715              the  shell  will  prompt for a key press; if the style is set to
1716              the empty string, a default prompt will be used.
1717
1718              The value may contain the escape sequences: `%l' or `%L',  which
1719              will  be  replaced  by the number of the last line displayed and
1720              the total number of lines; `%m' or `%M', the number of the  last
1721              match  shown and the total number of matches; and `%p' and `%P',
1722              `Top' when at the beginning of the list, `Bottom'  when  at  the
1723              end  and  the position shown as a percentage of the total length
1724              otherwise.  In each case the form with the uppercase letter will
1725              be  replaced  by  a  string of fixed width, padded to the  right
1726              with spaces, while the lowercase form  will  be  replaced  by  a
1727              variable  width  string.  As in other prompt strings, the escape
1728              sequences `%S', `%s', `%B', `%b', `%U', `%u'  for  entering  and
1729              leaving  the  display  modes  standout,  bold and underline, and
1730              `%F', `%f', `%K', `%k' for changing  the  foreground  background
1731              colour, are also available, as is the form `%{...%}' for enclos‐
1732              ing escape sequences which display with zero (or, with a numeric
1733              argument, some other) width.
1734
1735              After  deleting  this  prompt  the variable LISTPROMPT should be
1736              unset for the removal to take effect.
1737
1738       list-rows-first
1739              This style is tested in the same way as  the  list-packed  style
1740              and  determines whether matches are to be listed in a rows-first
1741              fashion as if the LIST_ROWS_FIRST option were set.
1742
1743       list-suffixes
1744              This style is used by the function that completes filenames.  If
1745              it is `true', and completion is attempted on a string containing
1746              multiple partially typed pathname components, all ambiguous com‐
1747              ponents will be shown.  Otherwise, completion stops at the first
1748              ambiguous component.
1749
1750       list-separator
1751              The value of this style is used in completion listing  to  sepa‐
1752              rate  the  string  to  complete from a description when possible
1753              (e.g. when  completing  options).   It  defaults  to  `--'  (two
1754              hyphens).
1755
1756       local  This  is for use with functions that complete URLs for which the
1757              corresponding files are available directly from the file system.
1758              Its  value should consist of three strings: a hostname, the path
1759              to the default web pages for the server, and the directory  name
1760              used by a user placing web pages within their home area.
1761
1762              For example:
1763
1764                     zstyle ':completion:*' local toast \
1765                         /var/http/public/toast public_html
1766
1767              Completion  after  `http://toast/stuff/'  will look for files in
1768              the directory  /var/http/public/toast/stuff,   while  completion
1769              after  `http://toast/~yousir/' will look for files in the direc‐
1770              tory ~yousir/public_html.
1771
1772       mail-directory
1773              If set, zsh will assume that mailbox files can be found  in  the
1774              directory specified.  It defaults to `~/Mail'.
1775
1776       match-original
1777              This  is  used  by  the _match completer.  If it is set to only,
1778              _match will try to generate matches without inserting a  `*'  at
1779              the  cursor  position.   If set to any other non-empty value, it
1780              will first try to generate matches without inserting the `*' and
1781              if  that  yields  no  matches,  it  will  try again with the `*'
1782              inserted.  If it is unset or set to the empty  string,  matching
1783              will only be performed with the `*' inserted.
1784
1785       matcher
1786              This  style  is tested separately for each tag valid in the cur‐
1787              rent context.  Its value is placed before any  match  specifica‐
1788              tions  given  by the matcher-list style so can override them via
1789              the use of an x: specification.  The value should be in the form
1790              described  in  the section `Completion Matching Control' in zsh‐
1791              compwid(1).  For examples of this, see the  description  of  the
1792              tag-order style.
1793
1794       matcher-list
1795              This style can be set to a list of match specifications that are
1796              to be applied everywhere. Match specifications are described  in
1797              the section `Completion Matching Control' in zshcompwid(1).  The
1798              completion system will try them one after another for each  com‐
1799              pleter  selected.   For  example, to try first simple completion
1800              and, if that generates no matches, case-insensitive completion:
1801
1802                     zstyle ':completion:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}'
1803
1804              By default each specification replaces the  previous  one;  how‐
1805              ever,  if a specification is prefixed with +, it is added to the
1806              existing list.  Hence it is possible to create increasingly gen‐
1807              eral specifications without repetition:
1808
1809                     zstyle ':completion:*' matcher-list \
1810                            '' '+m:{a-z}={A-Z}' '+m:{A-Z}={a-z}'
1811
1812              It is possible to create match specifications valid for particu‐
1813              lar completers by using the third field of  the  context.   This
1814              applies   only   to   completers   that   override   the  global
1815              matcher-list, which as of this writing includes only _prefix and
1816              _ignored.   For  example,  to  use  the completers _complete and
1817              _prefix but allow case-insensitive completion  only  with  _com‐
1818              plete:
1819
1820                     zstyle ':completion:*' completer _complete _prefix
1821                     zstyle ':completion:*:complete:*:*:*' matcher-list \
1822                            '' 'm:{a-zA-Z}={A-Za-z}'
1823
1824              User-defined  names,  as  explained for the completer style, are
1825              available.  This makes it possible to  try  the  same  completer
1826              more  than  once  with different match specifications each time.
1827              For example, to try normal completion without a match specifica‐
1828              tion,  then  normal  completion  with case-insensitive matching,
1829              then correction, and finally partial-word completion:
1830
1831                     zstyle ':completion:*' completer \
1832                         _complete _correct _complete:foo
1833                     zstyle ':completion:*:complete:*:*:*' matcher-list \
1834                         '' 'm:{a-zA-Z}={A-Za-z}'
1835                     zstyle ':completion:*:foo:*:*:*' matcher-list \
1836                         'm:{a-zA-Z}={A-Za-z} r:|[-_./]=* r:|=*'
1837
1838              If the style is unset in any context no match  specification  is
1839              applied.   Note  also  that some completers such as _correct and
1840              _approximate do not use the match specifications at all,  though
1841              these  completers  will  only  ever  be  called once even if the
1842              matcher-list contains more than one element.
1843
1844              Where multiple specifications are useful, note that  the  entire
1845              completion  is  done for each element of matcher-list, which can
1846              quickly reduce the shell's performance.   As  a  rough  rule  of
1847              thumb,  one  to  three strings will give acceptable performance.
1848              On the other hand, putting multiple space-separated values  into
1849              the  same  string does not have an appreciable impact on perfor‐
1850              mance.
1851
1852              If there is no current matcher or it is empty,  and  the  option
1853              NO_CASE_GLOB  is  in effect, the matching for files is performed
1854              case-insensitively in  any  case.   However,  any  matcher  must
1855              explicitly   specify   case-insensitive   matching  if  that  is
1856              required.
1857
1858       max-errors
1859              This is used by the _approximate and  _correct  completer  func‐
1860              tions  to  determine the maximum number of errors to allow.  The
1861              completer will try to generate completions by first allowing one
1862              error,  then  two  errors,  and  so  on, until either a match or
1863              matches were found or the maximum number of errors given by this
1864              style has been reached.
1865
1866              If  the  value for this style contains the string `numeric', the
1867              completer function will take any numeric argument as the maximum
1868              number of errors allowed. For example, with
1869
1870                     zstyle ':completion:*:approximate:::' max-errors 2 numeric
1871
1872              two errors are allowed if no numeric argument is given, but with
1873              a numeric argument of six (as in `ESC-6 TAB'), up to six  errors
1874              are  accepted.  Hence with a value of `0 numeric', no correcting
1875              completion will be attempted unless a numeric argument is given.
1876
1877              If the value contains the string  `not-numeric',  the  completer
1878              will  not  try  to  generate  corrected completions when given a
1879              numeric argument, so in this case the  number  given  should  be
1880              greater  than zero.  For example, `2 not-numeric' specifies that
1881              correcting completion with two errors will usually be performed,
1882              but  if  a numeric argument is given, correcting completion will
1883              not be performed.
1884
1885              The default value for this style is `2 numeric'.
1886
1887       max-matches-width
1888              This style is used to determine the trade off between the  width
1889              of  the  display  used  for matches and the width used for their
1890              descriptions when the verbose style is  in  effect.   The  value
1891              gives  the number of display columns to reserve for the matches.
1892              The default is half the width of the screen.
1893
1894              This has the most impact when  several  matches  have  the  same
1895              description  and  so  will  be grouped together.  Increasing the
1896              style will allow more matches to be grouped together; decreasing
1897              it will allow more of the description to be visible.
1898
1899       menu   If  this is `true' in the context of any of the tags defined for
1900              the current completion menu completion will be used.  The  value
1901              for  a  specific  tag  will  take  precedence  over that for the
1902              `default' tag.
1903
1904              If none of the values found in this way is `true' but  at  least
1905              one  is  set  to  `auto',  the shell behaves as if the AUTO_MENU
1906              option is set.
1907
1908              If one of the values is explicitly set to `false', menu  comple‐
1909              tion will be explicitly turned off, overriding the MENU_COMPLETE
1910              option and other settings.
1911
1912              In the form `yes=num', where `yes' may be any of the `true' val‐
1913              ues  (`yes',  `true',  `on'  and  `1'),  menu completion will be
1914              turned on if there are  at  least  num  matches.   In  the  form
1915              `yes=long',  menu  completion will be turned on if the list does
1916              not fit on the screen.  This does not activate  menu  completion
1917              if  the widget normally only lists completions, but menu comple‐
1918              tion  can  be  activated   in   that   case   with   the   value
1919              `yes=long-list'   (Typically,   the   value   `select=long-list'
1920              described later is more  useful  as  it  provides  control  over
1921              scrolling.)
1922
1923              Similarly,  with any of the `false' values (as in `no=10'), menu
1924              completion will not be used if there are num or more matches.
1925
1926              The value of this widget also controls menu selection, as imple‐
1927              mented  by  the  zsh/complist  module.  The following values may
1928              appear either alongside or instead of the values above.
1929
1930              If the value contains the string `select', menu  selection  will
1931              be started unconditionally.
1932
1933              In the form `select=num', menu selection will only be started if
1934              there are at least num matches.  If the values for more than one
1935              tag provide a number, the smallest number is taken.
1936
1937              Menu  selection can be turned off explicitly by defining a value
1938              containing the string`no-select'.
1939
1940              It is also possible to start menu selection only if the list  of
1941              matches   does  not  fit  on  the  screen  by  using  the  value
1942              `select=long'.  To start menu selection even if the current wid‐
1943              get only performs listing, use the value `select=long-list'.
1944
1945              To  turn  on  menu completion or menu selection when there are a
1946              certain number of matches or the list of matches does not fit on
1947              the  screen,  both  of  `yes=' and `select=' may be given twice,
1948              once with a number and once with `long' or `long-list'.
1949
1950              Finally, it is possible to activate two special  modes  of  menu
1951              selection.   The word `interactive' in the value causes interac‐
1952              tive mode to be  entered  immediately  when  menu  selection  is
1953              started;  see the description of the zsh/complist module in zsh‐
1954              modules(1) for a description of interactive mode.  Including the
1955              string  `search'  does the same for incremental search mode.  To
1956              select  backward  incremental   search,   include   the   string
1957              `search-backward'.
1958
1959       muttrc If  set,  gives the location of the mutt configuration file.  It
1960              defaults to `~/.muttrc'.
1961
1962       numbers
1963              This is used with the jobs tag.  If it is `true', the shell will
1964              complete  job numbers instead of the shortest unambiguous prefix
1965              of the job command text.  If the value is a number, job  numbers
1966              will  only  be used if that many words from the job descriptions
1967              are required to resolve ambiguities.  For example, if the  value
1968              is  `1',  strings  will  only  be used if all jobs differ in the
1969              first word on their command lines.
1970
1971       old-list
1972              This is used by  the  _oldlist  completer.   If  it  is  set  to
1973              `always',  then  standard  widgets  which  perform  listing will
1974              retain the current list of matches, however they were generated;
1975              this can be turned off explicitly with the value `never', giving
1976              the behaviour without the _oldlist completer.  If the  style  is
1977              unset, or any other value, then the existing list of completions
1978              is displayed if it is not already; otherwise, the standard  com‐
1979              pletion  list  is  generated;  this  is the default behaviour of
1980              _oldlist.  However, if there is an old list and this style  con‐
1981              tains  the  name  of  the  completer function that generated the
1982              list, then the old list will be used even if it was generated by
1983              a widget which does not do listing.
1984
1985              For  example, suppose you type ^Xc to use the _correct_word wid‐
1986              get, which generates a list of corrections for  the  word  under
1987              the  cursor.   Usually, typing ^D would generate a standard list
1988              of completions for the word on the command line, and show  that.
1989              With  _oldlist,  it  will  instead  show the list of corrections
1990              already generated.
1991
1992              As another example  consider  the  _match  completer:  with  the
1993              insert-unambiguous  style set to `true' it inserts only a common
1994              prefix string, if there is any.  However, this may remove  parts
1995              of  the  original pattern, so that further completion could pro‐
1996              duce more matches than on  the  first  attempt.   By  using  the
1997              _oldlist completer and setting this style to _match, the list of
1998              matches generated on the first attempt will be used again.
1999
2000       old-matches
2001              This is used by the _all_matches completer to decide if  an  old
2002              list  of matches should be used if one exists.  This is selected
2003              by one of the `true' values or by the  string  `only'.   If  the
2004              value  is  `only',  _all_matches  will  only use an old list and
2005              won't have any effect on the list  of  matches  currently  being
2006              generated.
2007
2008              If  this  style  is  set  it  is  generally  unwise  to call the
2009              _all_matches completer unconditionally.  One possible use is for
2010              either  this style or the completer style to be defined with the
2011              -e option to zstyle to make the style conditional.
2012
2013       old-menu
2014              This is used by the _oldlist completer.  It  controls  how  menu
2015              completion  behaves  when a completion has already been inserted
2016              and the user types a standard completion key such as  TAB.   The
2017              default  behaviour  of  _oldlist  is that menu completion always
2018              continues with the existing list of completions.  If this  style
2019              is  set  to `false', however, a new completion is started if the
2020              old list was generated by a different completion  command;  this
2021              is the behaviour without the _oldlist completer.
2022
2023              For  example, suppose you type ^Xc to generate a list of correc‐
2024              tions, and menu completion is started in one of the usual  ways.
2025              Usually,  or  with this style set to `false', typing TAB at this
2026              point would start trying to complete the line as it now appears.
2027              With _oldlist, it instead continues to cycle through the list of
2028              corrections.
2029
2030       original
2031              This is used by the  _approximate  and  _correct  completers  to
2032              decide if the original string should be added as a possible com‐
2033              pletion.  Normally, this is done only if there are at least  two
2034              possible  corrections, but if this style is set to `true', it is
2035              always added.  Note that the style will  be  examined  with  the
2036              completer  field  in  the  context  name  set  to correct-num or
2037              approximate-num, where num is the number  of  errors  that  were
2038              accepted.
2039
2040       packageset
2041              This  style  is  used  when  completing  arguments of the Debian
2042              `dpkg' program.  It contains an override for the default package
2043              set for a given context.  For example,
2044
2045                     zstyle ':completion:*:complete:dpkg:option--status-1:*' \
2046                                    packageset avail
2047
2048              causes  available packages, rather than only installed packages,
2049              to be completed for `dpkg --status'.
2050
2051       path   The function that completes color names uses this style with the
2052              colors tag.  The value should be the pathname of a file contain‐
2053              ing color names in the format of an X11 rgb.txt  file.   If  the
2054              style  is not set but this file is found in one of various stan‐
2055              dard locations it will be used as the default.
2056
2057       path-completion
2058              This is used by filename completion.  By default, filename  com‐
2059              pletion  examines  all  components of a path to see if there are
2060              completions of that component.  For example, /u/b/z can be  com‐
2061              pleted  to  /usr/bin/zsh.   Explicitly  setting  this  style  to
2062              `false' inhibits this behaviour for path components up to the  /
2063              before    the    cursor;   this   overrides   the   setting   of
2064              accept-exact-dirs.
2065
2066              Even with the style set to `false', it is still possible to com‐
2067              plete  multiple paths by setting the option COMPLETE_IN_WORD and
2068              moving the cursor back to the first component in the path to  be
2069              completed.  For example, /u/b/z can be completed to /usr/bin/zsh
2070              if the cursor is after the /u.
2071
2072       pine-directory
2073              If set, specifies the directory containing PINE  mailbox  files.
2074              There  is no default, since recursively searching this directory
2075              is inconvenient for anyone who doesn't use PINE.
2076
2077       ports  A list of Internet service names (network  ports)  to  complete.
2078              If  this  is  not  set,  service  names  are taken from the file
2079              `/etc/services'.
2080
2081       prefix-hidden
2082              This is used for certain completions which share a  common  pre‐
2083              fix,  for  example command options beginning with dashes.  If it
2084              is `true', the prefix will not be shown in the list of matches.
2085
2086              The default value for this style is `false'.
2087
2088       prefix-needed
2089              This style is also relevant for matches with  a  common  prefix.
2090              If  it  is set to `true' this common prefix must be typed by the
2091              user to generate the matches.
2092
2093              The style is applicable to the  options,  signals,  jobs,  func‐
2094              tions, and parameters completion tags.
2095
2096              For  command  options,  this means that the initial `-', `+', or
2097              `--' must be typed explicitly before option names will  be  com‐
2098              pleted.
2099
2100              For signals, an initial `-' is required before signal names will
2101              be completed.
2102
2103              For jobs, an initial `%' is required before job  names  will  be
2104              completed.
2105
2106              For  function  and  parameter  names,  an  initial `_' or `.' is
2107              required before function or parameter names starting with  those
2108              characters will be completed.
2109
2110              The  default  value  for  this style is `false' for function and
2111              parameter completions, and  `true' otherwise.
2112
2113       preserve-prefix
2114              This style is used when completing path names.  Its value should
2115              be  a pattern matching an initial prefix of the word to complete
2116              that should be left  unchanged  under  all  circumstances.   For
2117              example,  on  some  Unices  an initial `//' (double slash) has a
2118              special meaning; setting this style to the string `//' will pre‐
2119              serve it.  As another example, setting this style to `?:/' under
2120              Cygwin would allow completion after `a:/...' and so on.
2121
2122       range  This is used by the _history  completer  and  the  _history_com‐
2123              plete_word bindable command to decide which words should be com‐
2124              pleted.
2125
2126              If it is a single number, only the last N words from the history
2127              will be completed.
2128
2129              If  it  is a range of the form `max:slice', the last slice words
2130              will be completed; then if that yields  no  matches,  the  slice
2131              words  before those will be tried and so on.  This process stops
2132              either when at least one match has been found, or max words have
2133              been tried.
2134
2135              The default is to complete all words from the history at once.
2136
2137       recursive-files
2138              If  this  style  is set, its value is an array of patterns to be
2139              tested against `$PWD/': note the trailing  slash,  which  allows
2140              directories  in  the  pattern  to  be delimited unambiguously by
2141              including slashes on both sides.  If an ordinary file completion
2142              fails  and  the  word  on  the  command line does not yet have a
2143              directory part to its name, the style  is  retrieved  using  the
2144              same tag as for the completion just attempted, then the elements
2145              tested against $PWD/ in turn.  If one matches,  then  the  shell
2146              reattempts completion by prepending the word on the command line
2147              with each directory in the expansion of **/*(/) in turn.   Typi‐
2148              cally the elements of the style will be set to restrict the num‐
2149              ber of directories beneath the current one to a manageable  num‐
2150              ber, for example `*/.git/*'.
2151
2152              For example,
2153
2154                     zstyle ':completion:*' recursive-files '*/zsh/*'
2155
2156              If  the  current  directory is /home/pws/zsh/Src, then zle_trTAB
2157              can be completed to Zle/zle_tricky.c.
2158
2159       regular
2160              This style is used by the _expand_alias completer  and  bindable
2161              command.   If  set to `true' (the default), regular aliases will
2162              be expanded but only in command  position.   If  it  is  set  to
2163              `false',  regular aliases will never be expanded.   If it is set
2164              to `always', regular aliases will be expanded  even  if  not  in
2165              command position.
2166
2167       rehash If  this  is set when completing external commands, the internal
2168              list (hash) of commands will be updated for each search by issu‐
2169              ing the rehash command.  There is a speed penalty for this which
2170              is only likely to be noticeable when  directories  in  the  path
2171              have slow file access.
2172
2173       remote-access
2174              If  set to `false', certain commands will be prevented from mak‐
2175              ing Internet connections to retrieve remote  information.   This
2176              includes the completion for the CVS command.
2177
2178              It  is not always possible to know if connections are in fact to
2179              a remote site, so some may be prevented unnecessarily.
2180
2181       remove-all-dups
2182              The _history_complete_word bindable  command  and  the  _history
2183              completer  use this to decide if all duplicate matches should be
2184              removed, rather than just consecutive duplicates.
2185
2186       select-prompt
2187              If this is set for the default tag, its value will be  displayed
2188              during  menu  selection (see the menu style above) when the com‐
2189              pletion list does not fit on the screen as a  whole.   The  same
2190              escapes as for the list-prompt style are understood, except that
2191              the numbers refer to the match  or  line  the  mark  is  on.   A
2192              default prompt is used when the value is the empty string.
2193
2194       select-scroll
2195              This  style  is  tested for the default tag and determines how a
2196              completion list is scrolled during a  menu  selection  (see  the
2197              menu  style  above) when the completion list does not fit on the
2198              screen as a whole.  If the value is  `0'  (zero),  the  list  is
2199              scrolled  by  half-screenfuls;  if it is a positive integer, the
2200              list is scrolled by the given number of lines; if it is a  nega‐
2201              tive number, the list is scrolled by a screenful minus the abso‐
2202              lute value of the given number of  lines.   The  default  is  to
2203              scroll by single lines.
2204
2205       separate-sections
2206              This style is used with the manuals tag when completing names of
2207              manual pages.  If it is `true', entries for  different  sections
2208              are  added  separately  using  tag names of the form `manual.X',
2209              where X is the section number.  When  the  group-name  style  is
2210              also  in effect, pages from different sections will appear sepa‐
2211              rately.  This style is also used similarly with the words  style
2212              when completing words for the dict command. It allows words from
2213              different dictionary databases  to  be  added  separately.   The
2214              default for this style is `false'.
2215
2216       show-ambiguity
2217              If  the zsh/complist module is loaded, this style can be used to
2218              highlight the first ambiguous character in completion lists. The
2219              value  is  either  a color indication such as those supported by
2220              the list-colors style or, with a value of `true', a  default  of
2221              underlining is selected. The highlighting is only applied if the
2222              completion display strings correspond to the actual matches.
2223
2224       show-completer
2225              Tested whenever a new completer is tried.  If it is `true',  the
2226              completion system outputs a progress message in the listing area
2227              showing what completer is being  tried.   The  message  will  be
2228              overwritten  by  any  output  when  completions are found and is
2229              removed after completion is finished.
2230
2231       single-ignored
2232              This is used by the _ignored completer when there  is  only  one
2233              match.   If  its  value is `show', the single match will be dis‐
2234              played but not inserted.  If the value is `menu', then the  sin‐
2235              gle  match and the original string are both added as matches and
2236              menu completion is started, making it easy to select  either  of
2237              them.
2238
2239       sort   Many  completion  widgets  call _description at some point which
2240              decides whether the matches are added sorted or unsorted  (often
2241              indirectly  via  _wanted  or _requested).  This style can be set
2242              explicitly to one of the usual `true' or `false'  values  as  an
2243              override.  If it is not set for the context, the standard behav‐
2244              iour of the calling widget is used.
2245
2246              The style is tested first against the full context including the
2247              tag,  and  if  that fails to produce a value against the context
2248              without the tag.
2249
2250              If the calling widget explicitly requests unsorted matches, this
2251              is  usually honoured.  However, the default (unsorted) behaviour
2252              of completion for the command history may be overridden by  set‐
2253              ting the style to `true'.
2254
2255              In the _expand completer, if it is set to `true', the expansions
2256              generated will always be sorted.  If it is set to  `menu',  then
2257              the  expansions  are only sorted when they are offered as single
2258              strings but not in the string  containing  all  possible  expan‐
2259              sions.
2260
2261       special-dirs
2262              Normally,  the  completion  code  will not produce the directory
2263              names `.' and `..' as possible completions.  If  this  style  is
2264              set to `true', it will add both `.' and `..' as possible comple‐
2265              tions; if it is set to `..', only `..' will be added.
2266
2267              The following example sets special-dirs to `..' when the current
2268              prefix  is  empty,  is  a single `.', or consists only of a path
2269              beginning with `../'.  Otherwise the value is `false'.
2270
2271                     zstyle -e ':completion:*' special-dirs \
2272                        '[[ $PREFIX = (../)#(|.|..) ]] && reply=(..)'
2273
2274       squeeze-slashes
2275              If set to `true', sequences of slashes in  filename  paths  (for
2276              example  in `foo//bar') will be treated as a single slash.  This
2277              is the usual behaviour of UNIX paths.  However, by  default  the
2278              file  completion function behaves as if there were a `*' between
2279              the slashes.
2280
2281       stop   If set to `true', the  _history_complete_word  bindable  command
2282              will  stop  once  when reaching the beginning or end of the his‐
2283              tory.  Invoking _history_complete_word will then wrap around  to
2284              the  opposite  end  of  the  history.   If  this style is set to
2285              `false' (the default), _history_complete_word will loop  immedi‐
2286              ately as in a menu completion.
2287
2288       strip-comments
2289              If  set  to `true', this style causes non-essential comment text
2290              to be removed from completion matches.   Currently  it  is  only
2291              used  when completing e-mail addresses where it removes any dis‐
2292              play name  from  the  addresses,  cutting  them  down  to  plain
2293              user@host form.
2294
2295       subst-globs-only
2296              This  is used by the _expand completer.  If it is set to `true',
2297              the expansion will only be used if it  resulted  from  globbing;
2298              hence,  if  expansions  resulted  from the use of the substitute
2299              style described below, but these were  not  further  changed  by
2300              globbing, the expansions will be rejected.
2301
2302              The default for this style is `false'.
2303
2304       substitute
2305              This  boolean  style controls whether the _expand completer will
2306              first try to expand all substitutions in  the  string  (such  as
2307              `$(...)' and `${...}').
2308
2309              The default is `true'.
2310
2311       suffix This  is used by the _expand completer if the word starts with a
2312              tilde or contains a  parameter  expansion.   If  it  is  set  to
2313              `true', the word will only be expanded if it doesn't have a suf‐
2314              fix, i.e. if it is something like `~foo' or `$foo'  rather  than
2315              `~foo/'  or `$foo/bar', unless that suffix itself contains char‐
2316              acters eligible for expansion.  The default for  this  style  is
2317              `true'.
2318
2319       tag-order
2320              This  provides a mechanism for sorting how the tags available in
2321              a particular context will be used.
2322
2323              The values for the style are sets of  space-separated  lists  of
2324              tags.  The tags in each value will be tried at the same time; if
2325              no match is found, the next value is used.  (See  the  file-pat‐
2326              terns style for an exception to this behavior.)
2327
2328              For example:
2329
2330                     zstyle ':completion:*:complete:-command-:*:*' tag-order \
2331                         'commands functions'
2332
2333              specifies  that  completion  in  command  position  first offers
2334              external commands and shell functions.  Remaining tags  will  be
2335              tried if no completions are found.
2336
2337              In  addition to tag names, each string in the value may take one
2338              of the following forms:
2339
2340              -      If any value consists of only a  hyphen,  then  only  the
2341                     tags  specified  in the other values are generated.  Nor‐
2342                     mally all tags not explicitly selected are tried last  if
2343                     the  specified  tags  fail to generate any matches.  This
2344                     means that a single value consisting  only  of  a  single
2345                     hyphen turns off completion.
2346
2347              ! tags...
2348                     A  string  starting  with  an  exclamation mark specifies
2349                     names of tags that are not to be used.  The effect is the
2350                     same  as  if  all other possible tags for the context had
2351                     been listed.
2352
2353              tag:label ...
2354                     Here, tag is one of the standard tags  and  label  is  an
2355                     arbitrary  name.  Matches are generated as normal but the
2356                     name label is used in contexts instead of tag.   This  is
2357                     not useful in words starting with !.
2358
2359                     If  the  label starts with a hyphen, the tag is prepended
2360                     to the label to form the name used for lookup.  This  can
2361                     be  used  to make the completion system try a certain tag
2362                     more than once, supplying different  style  settings  for
2363                     each attempt; see below for an example.
2364
2365              tag:label:description
2366                     As  before,  but description will replace the `%d' in the
2367                     value of the format style instead of the default descrip‐
2368                     tion  supplied by the completion function.  Spaces in the
2369                     description must be quoted  with  a  backslash.   A  `%d'
2370                     appearing in description is replaced with the description
2371                     given by the completion function.
2372
2373              In any of the forms above the tag may be a  pattern  or  several
2374              patterns  in the form `{pat1,pat2...}'.  In this case all match‐
2375              ing tags will be used except for any  given  explicitly  in  the
2376              same string.
2377
2378              One use of these features is to try one tag more than once, set‐
2379              ting other styles differently on each attempt, but still to  use
2380              all the other tags without having to repeat them all.  For exam‐
2381              ple, to make completion of function names  in  command  position
2382              ignore  all the completion functions starting with an underscore
2383              the first time completion is tried:
2384
2385                     zstyle ':completion:*:*:-command-:*:*' tag-order \
2386                         'functions:-non-comp *' functions
2387                     zstyle ':completion:*:functions-non-comp' \
2388                         ignored-patterns '_*'
2389
2390              On the first attempt, all tags will be offered but the functions
2391              tag  will  be  replaced by functions-non-comp.  The ignored-pat‐
2392              terns style is set for this tag to  exclude  functions  starting
2393              with  an  underscore.  If there are no matches, the second value
2394              of the tag-order style is used which completes  functions  using
2395              the  default  tag,  this  time presumably including all function
2396              names.
2397
2398              The matches for one tag can be split into different groups.  For
2399              example:
2400
2401                     zstyle ':completion:*' tag-order \
2402                         'options:-long:long\ options
2403                          options:-short:short\ options
2404                          options:-single-letter:single\ letter\ options'
2405                     zstyle ':completion:*:options-long' \
2406                          ignored-patterns '[-+](|-|[^-]*)'
2407                     zstyle ':completion:*:options-short' \
2408                          ignored-patterns '--*' '[-+]?'
2409                     zstyle ':completion:*:options-single-letter' \
2410                          ignored-patterns '???*'
2411
2412              With  the  group-names  style  set, options beginning with `--',
2413              options beginning with a single `-' or `+' but containing multi‐
2414              ple  characters,  and single-letter options will be displayed in
2415              separate groups with different descriptions.
2416
2417              Another use of patterns is to try multiple match  specifications
2418              one after another.  The matcher-list style offers something sim‐
2419              ilar, but it is tested very early in the completion  system  and
2420              hence  can't  be  set  for single commands nor for more specific
2421              contexts.  Here is how to  try  normal  completion  without  any
2422              match specification and, if that generates no matches, try again
2423              with case-insensitive matching, restricting the effect to  argu‐
2424              ments of the command foo:
2425
2426                     zstyle ':completion:*:*:foo:*:*' tag-order '*' '*:-case'
2427                     zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}'
2428
2429              First,  all the tags offered when completing after foo are tried
2430              using the normal tag name.  If that generates  no  matches,  the
2431              second  value  of  tag-order is used, which tries all tags again
2432              except that this time each has -case appended to  its  name  for
2433              lookup  of  styles.   Hence  this time the value for the matcher
2434              style from the second call to zstyle in the example is  used  to
2435              make completion case-insensitive.
2436
2437              It  is  possible to use the -e option of the zstyle builtin com‐
2438              mand to specify conditions for the use of particular tags.   For
2439              example:
2440
2441                     zstyle -e '*:-command-:*' tag-order '
2442                         if [[ -n $PREFIX$SUFFIX ]]; then
2443                           reply=( )
2444                         else
2445                           reply=( - )
2446                         fi'
2447
2448              Completion  in  command  position  will be attempted only if the
2449              string typed so far is not empty.  This is tested using the PRE‐
2450              FIX  special  parameter;  see  zshcompwid  for  a description of
2451              parameters which are special inside completion widgets.  Setting
2452              reply to an empty array provides the default behaviour of trying
2453              all tags at once; setting it  to  an  array  containing  only  a
2454              hyphen  disables  the  use  of all tags and hence of all comple‐
2455              tions.
2456
2457              If no tag-order style  has  been  defined  for  a  context,  the
2458              strings  `(|*-)argument-*  (|*-)option-*  values'  and `options'
2459              plus all tags offered by the completion function will be used to
2460              provide  a  sensible  default  behavior  that  causes  arguments
2461              (whether normal command arguments or arguments of options) to be
2462              completed before option names for most commands.
2463
2464       urls   This  is used together with the urls tag by functions completing
2465              URLs.
2466
2467              If the value consists of more than one string, or  if  the  only
2468              string  does  not name a file or directory, the strings are used
2469              as the URLs to complete.
2470
2471              If the value contains only one string which is  the  name  of  a
2472              normal  file  the  URLs are taken from that file (where the URLs
2473              may be separated by white space or newlines).
2474
2475              Finally, if the only string in the value names a directory,  the
2476              directory  hierarchy  rooted at this directory gives the comple‐
2477              tions.  The top  level  directory  should  be  the  file  access
2478              method,  such  as  `http', `ftp', `bookmark' and so on.  In many
2479              cases the next level of directories will  be  a  filename.   The
2480              directory hierarchy can descend as deep as necessary.
2481
2482              For example,
2483
2484                     zstyle ':completion:*' urls ~/.urls
2485                     mkdir -p ~/.urls/ftp/ftp.zsh.org/pub
2486
2487              allows   completion   of   all   the   components   of  the  URL
2488              ftp://ftp.zsh.org/pub after suitable commands such as `netscape'
2489              or  `lynx'.   Note,  however,  that access methods and files are
2490              completed separately, so if the hosts style is set hosts can  be
2491              completed without reference to the urls style.
2492
2493              See the description in the function _urls itself for more infor‐
2494              mation (e.g. `more $^fpath/_urls(N)').
2495
2496       use-cache
2497              If this is set, the completion caching layer  is  activated  for
2498              any   completions   which   use   it   (via   the  _store_cache,
2499              _retrieve_cache, and _cache_invalid functions).   The  directory
2500              containing  the  cache  files can be changed with the cache-path
2501              style.
2502
2503       use-compctl
2504              If this style is set to a string not equal to false, 0, no,  and
2505              off, the completion system may use any completion specifications
2506              defined with the compctl  builtin  command.   If  the  style  is
2507              unset,  this  is  done only if the zsh/compctl module is loaded.
2508              The string may also contain the substring `first' to use comple‐
2509              tions  defined with `compctl -T', and the substring `default' to
2510              use the completion defined with `compctl -D'.
2511
2512              Note that this is only intended to smooth  the  transition  from
2513              compctl  to  the  new completion system and may disappear in the
2514              future.
2515
2516              Note also that the definitions from compctl will only be used if
2517              there  is  no  specific  completion  function for the command in
2518              question.  For example, if there is a function _foo to  complete
2519              arguments  to the command foo, compctl will never be invoked for
2520              foo.  However, the compctl version will be  tried  if  foo  only
2521              uses default completion.
2522
2523       use-ip By default, the function _hosts that completes host names strips
2524              IP addresses from entries read from host databases such  as  NIS
2525              and  ssh  files.   If this style is `true', the corresponding IP
2526              addresses can be completed as well.  This style is  not  use  in
2527              any  context  where the hosts style is set; note also it must be
2528              set before the cache of host names is generated  (typically  the
2529              first completion attempt).
2530
2531       users  This  may  be set to a list of usernames to be completed.  If it
2532              is not set all usernames will be completed.  Note that if it  is
2533              set  only  that list of users will be completed; this is because
2534              on some systems querying all users can take a prohibitive amount
2535              of time.
2536
2537       users-hosts
2538              The  values  of  this style should be of the form `user@host' or
2539              `user:host'. It is used for commands that need  pairs  of  user-
2540              and hostnames.  These commands will complete usernames from this
2541              style (only), and will restrict subsequent  hostname  completion
2542              to  hosts  paired  with  that  user  in one of the values of the
2543              style.
2544
2545              It is possible to group values for sets of commands which  allow
2546              a remote login, such as rlogin and ssh, by using the my-accounts
2547              tag.  Similarly, values for sets of commands which usually refer
2548              to the accounts of other people, such as talk and finger, can be
2549              grouped by using the other-accounts tag.  More  ambivalent  com‐
2550              mands may use the accounts tag.
2551
2552       users-hosts-ports
2553              Like  users-hosts but used for commands like telnet and contain‐
2554              ing strings of the form `user@host:port'.
2555
2556       verbose
2557              If set, as it is by default, the completion listing is more ver‐
2558              bose.  In particular many commands show descriptions for options
2559              if this style is `true'.
2560
2561       word   This is used by the _list completer, which prevents  the  inser‐
2562              tion  of  completions until a second completion attempt when the
2563              line has not changed.  The normal way of finding out if the line
2564              has  changed  is  to compare its entire contents between the two
2565              occasions.  If this style is `true', the comparison  is  instead
2566              performed only on the current word.  Hence if completion is per‐
2567              formed on another word with the same contents,  completion  will
2568              not be delayed.
2569

CONTROL FUNCTIONS

2571       The initialization script compinit redefines all the widgets which per‐
2572       form completion to call the supplied  widget  function  _main_complete.
2573       This function acts as a wrapper calling the so-called `completer' func‐
2574       tions that generate matches.  If _main_complete is  called  with  argu‐
2575       ments, these are taken as the names of completer functions to be called
2576       in the order given.  If no arguments are given, the set of functions to
2577       try is taken from the completer style.  For example, to use normal com‐
2578       pletion and correction if that doesn't generate any matches:
2579
2580              zstyle ':completion:*' completer _complete _correct
2581
2582       after calling compinit. The default value for this style is  `_complete
2583       _ignored',  i.e. normally only ordinary completion is tried, first with
2584       the effect of the ignored-patterns style  and  then  without  it.   The
2585       _main_complete  function  uses the return status of the completer func‐
2586       tions to decide if other completers should be called.   If  the  return
2587       status  is  zero,  no other completers are tried and the _main_complete
2588       function returns.
2589
2590       If the first argument to _main_complete is a single hyphen,  the  argu‐
2591       ments  will  not  be taken as names of completers.  Instead, the second
2592       argument gives a name to use in the completer field of the context  and
2593       the other arguments give a command name and arguments to call to gener‐
2594       ate the matches.
2595
2596       The following completer functions are contained  in  the  distribution,
2597       although  users may write their own.  Note that in contexts the leading
2598       underscore is stripped, for example basic completion  is  performed  in
2599       the context `:completion::complete:...'.
2600
2601       _all_matches
2602              This  completer  can  be  used to add a string consisting of all
2603              other matches.  As it influences later completers it must appear
2604              as  the first completer in the list.  The list of all matches is
2605              affected by the avoid-completer and old-matches styles described
2606              above.
2607
2608              It may be useful to use the _generic function described below to
2609              bind _all_matches to its own keystroke, for example:
2610
2611                     zle -C all-matches complete-word _generic
2612                     bindkey '^Xa' all-matches
2613                     zstyle ':completion:all-matches:*' old-matches only
2614                     zstyle ':completion:all-matches::::' completer _all_matches
2615
2616              Note that this does not generate completions by  itself:   first
2617              use  any  of  the  standard ways of generating a list of comple‐
2618              tions, then use ^Xa to show all matches.  It is possible instead
2619              to  add  a  standard  completer to the list and request that the
2620              list of all matches should be directly inserted:
2621
2622                     zstyle ':completion:all-matches::::' completer \
2623                            _all_matches _complete
2624                     zstyle ':completion:all-matches:*' insert true
2625
2626              In this case the old-matches style should not be set.
2627
2628       _approximate
2629              This is similar to the basic _complete completer but allows  the
2630              completions  to  undergo  corrections.   The  maximum  number of
2631              errors can  be  specified  by  the  max-errors  style;  see  the
2632              description of approximate matching in zshexpn(1) for how errors
2633              are counted.  Normally this completer will only be  tried  after
2634              the normal _complete completer:
2635
2636                     zstyle ':completion:*' completer _complete _approximate
2637
2638              This  will give correcting completion if and only if normal com‐
2639              pletion yields no possible completions.  When corrected  comple‐
2640              tions  are found, the completer will normally start menu comple‐
2641              tion allowing you to cycle through these strings.
2642
2643              This completer uses the tags corrections and original when  gen‐
2644              erating  the  possible corrections and the original string.  The
2645              format style for the former may contain the additional sequences
2646              `%e'  and  `%o'  which  will be replaced by the number of errors
2647              accepted to generate the corrections and  the  original  string,
2648              respectively.
2649
2650              The  completer  progressively  increases  the  number  of errors
2651              allowed up to the limit by the max-errors style, hence if a com‐
2652              pletion  is found with one error, no completions with two errors
2653              will be shown, and so on.  It modifies the completer name in the
2654              context  to  indicate  the  number of errors being tried: on the
2655              first try the completer field contains `approximate-1',  on  the
2656              second try `approximate-2', and so on.
2657
2658              When _approximate is called from another function, the number of
2659              errors to accept may be passed with the -a option.  The argument
2660              is  in  the  same  format  as  the  max-errors style, all in one
2661              string.
2662
2663              Note that this completer (and the _correct  completer  mentioned
2664              below)  can  be quite expensive to call, especially when a large
2665              number of errors are allowed.  One way to avoid this is  to  set
2666              up  the  completer  style  using the -e option to zstyle so that
2667              some completers are only used when  completion  is  attempted  a
2668              second time on the same string, e.g.:
2669
2670                     zstyle -e ':completion:*' completer '
2671                       if [[ $_last_try != "$HISTNO$BUFFER$CURSOR" ]]; then
2672                         _last_try="$HISTNO$BUFFER$CURSOR"
2673                         reply=(_complete _match _prefix)
2674                       else
2675                         reply=(_ignored _correct _approximate)
2676                       fi'
2677
2678              This uses the HISTNO parameter and the BUFFER and CURSOR special
2679              parameters that are available inside zle and completion  widgets
2680              to  find  out  if the command line hasn't changed since the last
2681              time completion was tried.  Only then are the _ignored, _correct
2682              and _approximate completers called.
2683
2684       _canonical_paths  [ -A var ] [ -N ] [ -MJV12nfX ] tag descr [ paths ...
2685       ]
2686              This completion function completes all paths given  to  it,  and
2687              also  tries to offer completions which point to the same file as
2688              one of the paths given (relative path when an absolute  path  is
2689              given,  and  vice versa; when ..'s are present in the word to be
2690              completed; and some paths got from symlinks).
2691
2692              -A, if specified, takes the paths from the array variable speci‐
2693              fied.  Paths  can also be specified on the command line as shown
2694              above.  -N, if  specified,  prevents  canonicalizing  the  paths
2695              given before using them for completion, in case they are already
2696              so. The options -M, -J, -V, -1, -2, -n, -F,  -X  are  passed  to
2697              compadd.
2698
2699              See _description for a description of tag and descr.
2700
2701       _cmdambivalent
2702              Completes the remaining positional arguments as an external com‐
2703              mand.  The external command and its arguments are  completed  as
2704              separate  arguments  (in  a  manner  appropriate  for completing
2705              /usr/bin/env) if there are  two  or  more  remaining  positional
2706              arguments  on  the  command line, and as a quoted command string
2707              (in the manner of system(...)) otherwise.  See  also  _cmdstring
2708              and _precommand.
2709
2710              This function takes no arguments.
2711
2712       _cmdstring
2713              Completes  an external command as a single argument, as for sys‐
2714              tem(...).
2715
2716       _complete
2717              This completer generates all  possible  completions  in  a  con‐
2718              text-sensitive  manner, i.e. using the settings defined with the
2719              compdef function explained above and the current settings of all
2720              special parameters.  This gives the normal completion behaviour.
2721
2722              To  complete  arguments  of commands, _complete uses the utility
2723              function _normal, which is in turn responsible for  finding  the
2724              particular function; it is described below.  Various contexts of
2725              the form -context- are handled specifically. These are all  men‐
2726              tioned above as possible arguments to the #compdef tag.
2727
2728              Before  trying  to find a function for a specific context, _com‐
2729              plete checks if the  parameter  `compcontext'  is  set.  Setting
2730              `compcontext'  allows  the  usual  completion  dispatching to be
2731              overridden which is useful in places such  as  a  function  that
2732              uses vared for input. If it is set to an array, the elements are
2733              taken to be the possible matches which will be  completed  using
2734              the tag `values' and the description `value'. If it is set to an
2735              associative array, the keys are used as the possible completions
2736              and  the  values (if non-empty) are used as descriptions for the
2737              matches.  If `compcontext' is set to a string containing colons,
2738              it  should  be of the form `tag:descr:action'.  In this case the
2739              tag and descr give the tag and description to use and the action
2740              indicates  what should be completed in one of the forms accepted
2741              by the _arguments utility function described below.
2742
2743              Finally, if `compcontext' is set to a string without colons, the
2744              value  is  taken as the name of the context to use and the func‐
2745              tion defined for that context will be called.  For this purpose,
2746              there  is  a special context named -command-line- that completes
2747              whole command lines (commands and their arguments).  This is not
2748              used  by the completion system itself but is nonetheless handled
2749              when explicitly called.
2750
2751       _correct
2752              Generate corrections, but not completions, for the current word;
2753              this is similar to _approximate but will not allow any number of
2754              extra characters at the cursor  as  that  completer  does.   The
2755              effect  is  similar to spell-checking.  It is based on _approxi‐
2756              mate, but the completer field in the context name is correct.
2757
2758              For example, with:
2759
2760                     zstyle ':completion:::::' completer \
2761                            _complete _correct _approximate
2762                     zstyle ':completion:*:correct:::' max-errors 2 not-numeric
2763                     zstyle ':completion:*:approximate:::' max-errors 3 numeric
2764
2765              correction will accept up to two errors.  If a numeric  argument
2766              is  given, correction will not be performed, but correcting com‐
2767              pletion will be, and will accept as many errors as given by  the
2768              numeric  argument.  Without a numeric argument, first correction
2769              and then correcting completion will be tried, with the first one
2770              accepting two errors and the second one accepting three errors.
2771
2772              When  _correct  is called as a function, the number of errors to
2773              accept may be given following the -a option.  The argument is in
2774              the same form a values to the accept style, all in one string.
2775
2776              This  completer  function  is  intended  to  be used without the
2777              _approximate completer or, as in the example,  just  before  it.
2778              Using  it  after  the  _approximate  completer  is useless since
2779              _approximate will at least generate the corrected strings gener‐
2780              ated by the _correct completer -- and probably more.
2781
2782       _expand
2783              This  completer function does not really perform completion, but
2784              instead checks if the word on the command line is  eligible  for
2785              expansion  and,  if  it is, gives detailed control over how this
2786              expansion is done.  For this to happen,  the  completion  system
2787              needs  to  be invoked with complete-word, not expand-or-complete
2788              (the default binding for TAB), as otherwise the string  will  be
2789              expanded by the shell's internal mechanism before the completion
2790              system is started.  Note also this completer  should  be  called
2791              before the _complete completer function.
2792
2793              The  tags used when generating expansions are all-expansions for
2794              the string containing all possible expansions,  expansions  when
2795              adding  the  possible  expansions as single matches and original
2796              when adding the original string from the  line.   The  order  in
2797              which  these strings are generated, if at all, can be controlled
2798              by the group-order and tag-order styles, as usual.
2799
2800              The format string for all-expansions and for expansions may con‐
2801              tain  the  sequence  `%o' which will be replaced by the original
2802              string from the line.
2803
2804              The kind of expansion to be tried is controlled by  the  substi‐
2805              tute, glob and subst-globs-only styles.
2806
2807              It is also possible to call _expand as a function, in which case
2808              the different modes may be selected with options: -s for substi‐
2809              tute, -g for glob and -o for subst-globs-only.
2810
2811       _expand_alias
2812              If  the word the cursor is on is an alias, it is expanded and no
2813              other completers are called.  The types of aliases which are  to
2814              be  expanded  can  be controlled with the styles regular, global
2815              and disabled.
2816
2817              This function is also a bindable command, see the section `Bind‐
2818              able Commands' below.
2819
2820       _extensions
2821              If  the  cursor follows the string `*.', filename extensions are
2822              completed. The extensions are taken from files in current direc‐
2823              tory  or  a  directory specified at the beginning of the current
2824              word. For exact matches, completion  continues  to  allow  other
2825              completers  such  as _expand to expand the pattern. The standard
2826              add-space and prefix-hidden styles are observed.
2827
2828       _external_pwds
2829              Completes current directories of other zsh  processes  belonging
2830              to the current user.
2831
2832              This  is intended to be used via _generic, bound to a custom key
2833              combination. Note that pattern matching is enabled  so  matching
2834              is performed similar to how it works with the _match completer.
2835
2836       _history
2837              Complete  words  from  the  shell's command  history.  This com‐
2838              pleter can be controlled by the remove-all-dups, and sort styles
2839              as for the _history_complete_word bindable command, see the sec‐
2840              tion `Bindable Commands' below and the section `Completion  Sys‐
2841              tem Configuration' above.
2842
2843       _ignored
2844              The  ignored-patterns  style  can  be  set to a list of patterns
2845              which are compared against possible completions;  matching  ones
2846              are  removed.   With  this  completer those matches can be rein‐
2847              stated, as if no ignored-patterns style were set.  The completer
2848              actually generates its own list of matches; which completers are
2849              invoked is determined in the same way as for  the  _prefix  com‐
2850              pleter.  The single-ignored style is also available as described
2851              above.
2852
2853       _list  This completer allows the insertion of  matches  to  be  delayed
2854              until  completion is attempted a second time without the word on
2855              the line being changed.  On the first attempt, only the list  of
2856              matches  will  be shown.  It is affected by the styles condition
2857              and word, see  the  section  `Completion  System  Configuration'
2858              above.
2859
2860       _match This  completer  is intended to be used after the _complete com‐
2861              pleter.  It behaves similarly but the string on the command line
2862              may be a pattern to match against trial completions.  This gives
2863              the effect of the GLOB_COMPLETE option.
2864
2865              Normally completion will be performed by taking the pattern from
2866              the  line,  inserting a `*' at the cursor position and comparing
2867              the resulting pattern with the possible  completions  generated.
2868              This  can  be  modified  with the match-original style described
2869              above.
2870
2871              The generated matches will  be  offered  in  a  menu  completion
2872              unless  the  insert-unambiguous  style is set to `true'; see the
2873              description above for other options for this style.
2874
2875              Note that matcher specifications defined globally or used by the
2876              completion  functions (the styles matcher-list and matcher) will
2877              not be used.
2878
2879       _menu  This completer was written as simple example  function  to  show
2880              how  menu  completion  can be enabled in shell code. However, it
2881              has the notable effect of disabling menu selection which can  be
2882              useful  with  _generic  based  widgets. It should be used as the
2883              first completer in the list.  Note that this is  independent  of
2884              the  setting  of the MENU_COMPLETE option and does not work with
2885              the other menu completion widgets such as reverse-menu-complete,
2886              or accept-and-menu-complete.
2887
2888       _oldlist
2889              This  completer  controls  how  the  standard completion widgets
2890              behave when there is an existing list of completions  which  may
2891              have  been  generated  by  a  special  completion  (i.e. a sepa‐
2892              rately-bound completion command).  It allows the  ordinary  com‐
2893              pletion  keys  to  continue  to use the list of completions thus
2894              generated, instead of producing a new list of  ordinary  contex‐
2895              tual  completions.   It  should appear in the list of completers
2896              before any of the widgets which generate matches.  It  uses  two
2897              styles:  old-list and old-menu, see the section `Completion Sys‐
2898              tem Configuration' above.
2899
2900       _precommand
2901              Complete an external command in word-separated arguments, as for
2902              exec and /usr/bin/env.
2903
2904       _prefix
2905              This  completer  can  be  used to try completion with the suffix
2906              (everything after the cursor) ignored.  In other words, the suf‐
2907              fix  will  not be considered to be part of the word to complete.
2908              The effect is similar to the expand-or-complete-prefix command.
2909
2910              The completer style is used to decide which other completers are
2911              to  be  called to generate matches.  If this style is unset, the
2912              list of completers set  for  the  current  context  is  used  --
2913              except,  of  course, the _prefix completer itself.  Furthermore,
2914              if this completer appears more than once in  the  list  of  com‐
2915              pleters  only  those  completers  not  already tried by the last
2916              invocation of _prefix will be called.
2917
2918              For example, consider this global completer style:
2919
2920                     zstyle ':completion:*' completer \
2921                         _complete _prefix _correct _prefix:foo
2922
2923              Here, the _prefix completer tries normal completion but ignoring
2924              the  suffix.   If that doesn't generate any matches, and neither
2925              does the call to the _correct completer after it,  _prefix  will
2926              be called a second time and, now only trying correction with the
2927              suffix ignored.  On the second invocation the completer part  of
2928              the context appears as `foo'.
2929
2930              To use _prefix as the last resort and try only normal completion
2931              when it is invoked:
2932
2933                     zstyle ':completion:*' completer _complete ... _prefix
2934                     zstyle ':completion::prefix:*' completer _complete
2935
2936              The add-space style is also respected.  If it is set  to  `true'
2937              then  _prefix  will insert a space between the matches generated
2938              (if any) and the suffix.
2939
2940              Note that this completer is only useful if the  COMPLETE_IN_WORD
2941              option is set; otherwise, the cursor will be moved to the end of
2942              the current word before the completion code is called and  hence
2943              there will be no suffix.
2944
2945       _user_expand
2946              This  completer  behaves  similarly to the _expand completer but
2947              instead  performs  expansions  defined  by  users.   The  styles
2948              add-space  and sort styles specific to the _expand completer are
2949              usable with _user_expand in addition  to  other  styles  handled
2950              more generally by the completion system.  The tag all-expansions
2951              is also available.
2952
2953              The expansion depends  on  the  array  style  user-expand  being
2954              defined  for  the current context; remember that the context for
2955              completers is less specific than that for contextual  completion
2956              as  the  full  context has not yet been determined.  Elements of
2957              the array may have one of the following forms:
2958
2959              $hash
2960
2961                     hash is the name of an associative array.  Note  this  is
2962                     not  a  full  parameter  expression, merely a $, suitably
2963                     quoted to prevent immediate expansion,  followed  by  the
2964                     name  of  an  associative  array.  If the trial expansion
2965                     word matches a key in hash, the  resulting  expansion  is
2966                     the corresponding value.
2967              _func
2968
2969                     _func  is  the  name  of a shell function whose name must
2970                     begin with _ but is not otherwise special to the  comple‐
2971                     tion  system.  The function is called with the trial word
2972                     as an argument.  If the word is to be expanded, the func‐
2973                     tion  should set the array reply to a list of expansions.
2974                     Optionally, it can set REPLY to a word that will be  used
2975                     as  a  description for the set of expansions.  The return
2976                     status of the function is irrelevant.

BINDABLE COMMANDS

2978       In addition to the context-dependent completions  provided,  which  are
2979       expected to work in an intuitively obvious way, there are a few widgets
2980       implementing special behaviour which can be bound separately  to  keys.
2981       The following is a list of these and their default bindings.
2982
2983       _bash_completions
2984              This  function  is  used by two widgets, _bash_complete-word and
2985              _bash_list-choices.  It exists  to  provide  compatibility  with
2986              completion  bindings in bash.  The last character of the binding
2987              determines what is completed: `!', command names; `$',  environ‐
2988              ment  variables;  `@',  host  names;  `/',  file names; `~' user
2989              names.  In bash, the binding preceded by `\e' gives  completion,
2990              and  preceded  by `^X' lists options.  As some of these bindings
2991              clash with standard zsh bindings, only `\e~' and `^X~' are bound
2992              by  default.   To add the rest, the following should be added to
2993              .zshrc after compinit has been run:
2994
2995                     for key in '!' '$' '@' '/' '~'; do
2996                       bindkey "\e$key" _bash_complete-word
2997                       bindkey "^X$key" _bash_list-choices
2998                     done
2999
3000              This includes the bindings for `~' in  case  they  were  already
3001              bound  to  something else; the completion code does not override
3002              user bindings.
3003
3004       _correct_filename (^XC)
3005              Correct the filename path at the cursor position.  Allows up  to
3006              six  errors in the name.  Can also be called with an argument to
3007              correct a filename path, independently of zle; the correction is
3008              printed on standard output.
3009
3010       _correct_word (^Xc)
3011              Performs correction of the current argument using the usual con‐
3012              textual completions as possible choices. This stores the  string
3013              `correct-word'  in  the  function  field of the context name and
3014              then calls the _correct completer.
3015
3016       _expand_alias (^Xa)
3017              This function can be used as a completer and as a bindable  com‐
3018              mand.   It  expands the word the cursor is on if it is an alias.
3019              The types of alias expanded can be controlled  with  the  styles
3020              regular, global and disabled.
3021
3022              When  used as a bindable command there is one additional feature
3023              that can be selected by setting the complete  style  to  `true'.
3024              In  this  case,  if  the  word  is  not  the  name  of an alias,
3025              _expand_alias tries to complete the word to a  full  alias  name
3026              without  expanding  it.  It leaves the cursor directly after the
3027              completed word so that invoking  _expand_alias  once  more  will
3028              expand the now-complete alias name.
3029
3030       _expand_word (^Xe)
3031              Performs expansion on the current word:  equivalent to the stan‐
3032              dard expand-word  command,  but  using  the  _expand  completer.
3033              Before  calling  it, the function field of the context is set to
3034              `expand-word'.
3035
3036       _generic
3037              This function is not defined  as  a  widget  and  not  bound  by
3038              default.   However,  it  can be used to define a widget and will
3039              then store the name of the widget in the function field  of  the
3040              context and call the completion system.  This allows custom com‐
3041              pletion widgets with their own  set  of  style  settings  to  be
3042              defined  easily.   For example, to define a widget that performs
3043              normal completion and starts menu selection:
3044
3045                     zle -C foo complete-word _generic
3046                     bindkey '...' foo
3047                     zstyle ':completion:foo:*' menu yes select=1
3048
3049              Note in particular that the completer style may be set  for  the
3050              context in order to change the set of functions used to generate
3051              possible matches.  If _generic is called with  arguments,  those
3052              are  passed  through to _main_complete as the list of completers
3053              in place of those defined by the completer style.
3054
3055       _history_complete_word (\e/)
3056              Complete words from the shell's command history. This  uses  the
3057              list, remove-all-dups, sort, and stop styles.
3058
3059       _most_recent_file (^Xm)
3060              Complete  the  name  of the most recently modified file matching
3061              the pattern on the command line (which may be blank).  If  given
3062              a  numeric  argument  N, complete the Nth most recently modified
3063              file.  Note the completion, if any, is always unique.
3064
3065       _next_tags (^Xn)
3066              This command alters the set of matches used to that for the next
3067              tag,  or  set of tags, either as given by the tag-order style or
3068              as set by default; these matches would otherwise not  be  avail‐
3069              able.   Successive  invocations of the command cycle through all
3070              possible sets of tags.
3071
3072       _read_comp (^X^R)
3073              Prompt the user for a string, and use that to perform completion
3074              on  the  current  word.   There  are  two  possibilities for the
3075              string.  First, it can be a set  of  words  beginning  `_',  for
3076              example  `_files  -/', in which case the function with any argu‐
3077              ments will be called to generate the  completions.   Unambiguous
3078              parts of the function name will be completed automatically (nor‐
3079              mal completion is not available at this point) until a space  is
3080              typed.
3081
3082              Second, any other string will be passed as a set of arguments to
3083              compadd and should hence be an expression specifying what should
3084              be completed.
3085
3086              A  very  restricted  set  of  editing commands is available when
3087              reading the string:  `DEL' and `^H' delete the  last  character;
3088              `^U'  deletes  the  line,  and `^C' and `^G' abort the function,
3089              while `RET' accepts the completion.  Note  the  string  is  used
3090              verbatim  as  a  command  line,  so  arguments must be quoted in
3091              accordance with standard shell rules.
3092
3093              Once a string has been read, the next call  to  _read_comp  will
3094              use  the existing string instead of reading a new one.  To force
3095              a new string to be read, call _read_comp with  a  numeric  argu‐
3096              ment.
3097
3098       _complete_debug (^X?)
3099              This widget performs ordinary completion, but captures in a tem‐
3100              porary file a trace of the shell commands executed by  the  com‐
3101              pletion  system.   Each completion attempt gets its own file.  A
3102              command to view each of these files is pushed  onto  the  editor
3103              buffer stack.
3104
3105       _complete_help (^Xh)
3106              This  widget  displays  information about the context names, the
3107              tags, and the completion functions used when completing  at  the
3108              current  cursor position. If given a numeric argument other than
3109              1 (as in `ESC-2 ^Xh'), then the styles used and the contexts for
3110              which they are used will be shown, too.
3111
3112              Note  that  the  information  about styles may be incomplete; it
3113              depends on the information available from the  completion  func‐
3114              tions  called,  which  in  turn  is determined by the user's own
3115              styles and other settings.
3116
3117       _complete_help_generic
3118              Unlike other commands listed here, this must  be  created  as  a
3119              normal ZLE widget rather than a completion widget (i.e. with zle
3120              -N).  It is used for generating help with a widget bound to  the
3121              _generic widget that is described above.
3122
3123              If  this widget is created using the name of the function, as it
3124              is by default, then when executed it will read a  key  sequence.
3125              This  is expected to be bound to a call to a completion function
3126              that uses the _generic widget.  That widget  will  be  executed,
3127              and  information  provided  in  the  same  format that the _com‐
3128              plete_help widget displays for contextual completion.
3129
3130              If the widget's name contains debug, for example if it  is  cre‐
3131              ated as `zle -N _complete_debug_generic _complete_help_generic',
3132              it will read and execute the keystring for a generic  widget  as
3133              before, but then generate debugging information as done by _com‐
3134              plete_debug for contextual completion.
3135
3136              If the widget's  name  contains  noread,  it  will  not  read  a
3137              keystring  but  instead  arrange  that the next use of a generic
3138              widget run in the same shell will have the effect  as  described
3139              above.
3140
3141              The    widget    works    by   setting   the   shell   parameter
3142              ZSH_TRACE_GENERIC_WIDGET which is read by  _generic.   Unsetting
3143              the parameter cancels any pending effect of the noread form.
3144
3145              For example, after executing the following:
3146
3147                     zle -N _complete_debug_generic _complete_help_generic
3148                     bindkey '^x:' _complete_debug_generic
3149
3150              typing `C-x :' followed by the key sequence for a generic widget
3151              will cause trace output for that widget to be saved to a file.
3152
3153       _complete_tag (^Xt)
3154              This widget completes symbol tags created by the etags or  ctags
3155              programmes (note there is no connection with the completion sys‐
3156              tem's tags) stored in a file TAGS, in the format used by  etags,
3157              or  tags,  in the format created by ctags.  It will look back up
3158              the path hierarchy for the first occurrence of either  file;  if
3159              both  exist,  the  file  TAGS is preferred.  You can specify the
3160              full path to a TAGS or tags file by setting the parameter $TAGS‐
3161              FILE  or  $tagsfile  respectively.  The corresponding completion
3162              tags used are etags and vtags, after emacs and vi respectively.
3163

UTILITY FUNCTIONS

3165       Descriptions follow for utility functions that may be useful when writ‐
3166       ing  completion  functions.   If functions are installed in subdirecto‐
3167       ries, most of these reside in the Base subdirectory.  Like the  example
3168       functions  for commands in the distribution, the utility functions gen‐
3169       erating matches all follow the convention of returning status  zero  if
3170       they  generated  completions  and  non-zero  if no matching completions
3171       could be added.
3172
3173       _absolute_command_paths
3174              This function completes  external  commands  as  absolute  paths
3175              (unlike  _command_names -e which completes their basenames).  It
3176              takes no arguments.
3177
3178       _all_labels [ -x ] [ -12VJ ] tag name descr [ command arg ... ]
3179              This is a  convenient  interface  to  the  _next_label  function
3180              below,  implementing  the loop shown in the _next_label example.
3181              The command  and  its  arguments  are  called  to  generate  the
3182              matches.  The options stored in the parameter name will automat‐
3183              ically be inserted into the args passed to  the  command.   Nor‐
3184              mally,  they  are  put directly after the command, but if one of
3185              the args is a single hyphen, they are inserted  directly  before
3186              that.   If  the  hyphen is the last argument, it will be removed
3187              from the argument list  before  the  command  is  called.   This
3188              allows  _all_labels  to  be  used  in almost all cases where the
3189              matches can be generated by a single call to the compadd builtin
3190              command or by a call to one of the utility functions.
3191
3192              For example:
3193
3194                     local expl
3195                     ...
3196                     if _requested foo; then
3197                       ...
3198                       _all_labels foo expl '...' compadd ... - $matches
3199                     fi
3200
3201              Will complete the strings from the matches parameter, using com‐
3202              padd with additional options which  will  take  precedence  over
3203              those generated by _all_labels.
3204
3205       _alternative [ -O name ] [ -C name ] spec ...
3206              This  function is useful in simple cases where multiple tags are
3207              available.  Essentially  it  implements  a  loop  like  the  one
3208              described for the _tags function below.
3209
3210              The  tags to use and the action to perform if a tag is requested
3211              are  described  using  the  specs  which  are   of   the   form:
3212              `tag:descr:action'.  The tags are offered using _tags and if the
3213              tag is requested, the action is executed with the given descrip‐
3214              tion  descr.   The  actions are those accepted by the _arguments
3215              function (described below), excluding the `->state'  and  `=...'
3216              forms.
3217
3218              For example, the action may be a simple function call:
3219
3220                     _alternative \
3221                         'users:user:_users' \
3222                         'hosts:host:_hosts'
3223
3224              offers usernames and hostnames as possible matches, generated by
3225              the _users and _hosts functions respectively.
3226
3227              Like _arguments, this function uses _all_labels to  execute  the
3228              actions,  which  will  loop over all sets of tags.  Special han‐
3229              dling is only required if there is an additional valid tag,  for
3230              example inside a function called from _alternative.
3231
3232              The  option  `-O  name' is used in the same way as by the _argu‐
3233              ments function.  In other words, the elements of the name  array
3234              will be passed to compadd when executing an action.
3235
3236              Like  _tags  this function supports the -C option to give a dif‐
3237              ferent name for the argument context field.
3238
3239
3240       _arguments [ -nswWCRS ] [ -A pat ] [ -O name ] [ -M matchspec ]
3241                  [ : ] spec ...
3242       _arguments [ opt ... ] -- [ -l ] [ -i pats ] [ -s pair ]
3243                  [ helpspec ...]
3244              This function can be used to give a complete  specification  for
3245              completion  for  a  command whose arguments follow standard UNIX
3246              option and argument conventions.
3247
3248              Options Overview
3249
3250              Options to _arguments itself must be in separate words, i.e.  -s
3251              -w,  not  -sw.   The options are followed by specs that describe
3252              options and arguments of the analyzed command.  To avoid ambigu‐
3253              ity,  all options to _arguments itself may be separated from the
3254              spec forms by a single colon.
3255
3256              The `--' form is used to intuit spec forms from the help  output
3257              of the command being analyzed, and is described in detail below.
3258              The opts for the `--' form are otherwise the same options as the
3259              first  form.  Note that `-s' following `--' has a distinct mean‐
3260              ing from `-s' preceding `--', and both may appear.
3261
3262              The option switches -s, -S, -A, -w, and -W affect how _arguments
3263              parses  the analyzed command line's options.  These switches are
3264              useful for commands with standard argument parsing.
3265
3266              The options of _arguments have the following meanings:
3267
3268              -n     With this option, _arguments sets the  parameter  NORMARG
3269                     to  the  position  of  the  first  normal argument in the
3270                     $words array, i.e. the position  after  the  end  of  the
3271                     options.   If that argument has not been reached, NORMARG
3272                     is set to -1.  The caller should  declare  `integer  NOR‐
3273                     MARG' if the -n option is passed; otherwise the parameter
3274                     is not used.
3275
3276              -s     Enable option stacking for single-letter options, whereby
3277                     multiple  single-letter  options  may  be combined into a
3278                     single word.  For example, the two options `-x' and  `-y'
3279                     may  be  combined  into a single word `-xy'.  By default,
3280                     every word corresponds to a single option name (`-xy'  is
3281                     a single option named `xy').
3282
3283                     Options  beginning  with a single hyphen or plus sign are
3284                     eligible for stacking; words beginning with  two  hyphens
3285                     are not.
3286
3287                     Note  that  -s after -- has a different meaning, which is
3288                     documented in the segment entitled `Deriving  spec  forms
3289                     from the help output'.
3290
3291              -w     In combination with -s, allow option stacking even if one
3292                     or more of the options take arguments.  For  example,  if
3293                     -x  takes an argument, with no -s, `-xy' is considered as
3294                     a single (unhandled) option; with -s, -xy  is  an  option
3295                     with  the  argument  `y'; with both -s and -w, -xy is the
3296                     option -x and the option -y with arguments to -x (and  to
3297                     -y,  if  it  takes arguments) still to come in subsequent
3298                     words.
3299
3300              -W     This option takes -w a stage further:  it is possible  to
3301                     complete  single-letter  options  even  after an argument
3302                     that occurs in the same word.  However, it depends on the
3303                     action performed whether options will really be completed
3304                     at this point.  For more control, use a utility  function
3305                     like _guard as part of the action.
3306
3307              -C     Modify the curcontext parameter for an action of the form
3308                     `->state'.  This is discussed in detail below.
3309
3310              -R     Return status 300 instead of zero when a $state is to  be
3311                     handled, in the `->string' syntax.
3312
3313              -S     Do  not  complete  options  after a `--' appearing on the
3314                     line, and ignore the `--'.  For example, with -S, in  the
3315                     line
3316
3317                            foobar -x -- -y
3318
3319                     the  `-x' is considered an option, the `-y' is considered
3320                     an argument, and the `--' is considered to be neither.
3321
3322              -A pat Do not complete options after the first non-option  argu‐
3323                     ment  on the line.  pat is a pattern matching all strings
3324                     which are not to be taken as arguments.  For example,  to
3325                     make  _arguments  stop completing options after the first
3326                     normal argument, but ignoring all strings starting with a
3327                     hyphen  even if they are not described by one of the opt‐
3328                     specs, the form is `-A "-*"'.
3329
3330              -O name
3331                     Pass the elements of the array name as arguments to func‐
3332                     tions  called  to  execute actions.  This is discussed in
3333                     detail below.
3334
3335              -M matchspec
3336                     Use the  match  specification  matchspec  for  completing
3337                     option  names  and  values.  The default matchspec allows
3338                     partial word completion after `_' and `-', such  as  com‐
3339                     pleting `-f-b' to `-foo-bar'.  The default matchspec is:
3340                     r:|[_-]=* r:|=*
3341
3342              specs: overview
3343
3344              Each of the following forms is a spec describing individual sets
3345              of options or arguments on the command line being analyzed.
3346
3347              n:message:action
3348              n::message:action
3349                     This describes the n'th  normal  argument.   The  message
3350                     will  be  printed  above  the  matches  generated and the
3351                     action indicates what can be completed in  this  position
3352                     (see  below).  If there are two colons before the message
3353                     the argument is optional.  If the message  contains  only
3354                     white  space,  nothing  will be printed above the matches
3355                     unless the action adds an explanation string itself.
3356
3357              :message:action
3358              ::message:action
3359                     Similar, but describes the next argument, whatever number
3360                     that  happens  to  be.  If all arguments are specified in
3361                     this form in the correct order the numbers  are  unneces‐
3362                     sary.
3363
3364              *:message:action
3365              *::message:action
3366              *:::message:action
3367                     This  describes  how  arguments (usually non-option argu‐
3368                     ments, those not beginning with - or +) are  to  be  com‐
3369                     pleted  when neither of the first two forms was provided.
3370                     Any number of arguments can be completed in this fashion.
3371
3372                     With two colons before the  message,  the  words  special
3373                     array  and  the CURRENT special parameter are modified to
3374                     refer only to the normal arguments  when  the  action  is
3375                     executed or evaluated.  With three colons before the mes‐
3376                     sage they are modified to refer only to the normal  argu‐
3377                     ments covered by this description.
3378
3379              optspec
3380              optspec:...
3381                     This  describes  an option.  The colon indicates handling
3382                     for one or more arguments to the option;  if  it  is  not
3383                     present, the option is assumed to take no arguments.
3384
3385                     The  following  forms  are available for the initial opt‐
3386                     spec, whether or not the option has arguments.
3387
3388                     *optspec
3389                            Here optspec is one of the remaining forms  below.
3390                            This   indicates  the  following  optspec  may  be
3391                            repeated.  Otherwise if the  corresponding  option
3392                            is already present on the command line to the left
3393                            of the cursor it will not be offered again.
3394
3395                     -optname
3396                     +optname
3397                            In the simplest  form  the  optspec  is  just  the
3398                            option name beginning with a minus or a plus sign,
3399                            such as `-foo'.  The first argument for the option
3400                            (if  any)  must follow as a separate word directly
3401                            after the option.
3402
3403                            Either of `-+optname' and `+-optname' can be  used
3404                            to  specify  that  -optname  and +optname are both
3405                            valid.
3406
3407                            In all the remaining forms, the leading `-' may be
3408                            replaced by or paired with `+' in this way.
3409
3410                     -optname-
3411                            The   first  argument  of  the  option  must  come
3412                            directly after the option name in the  same  word.
3413                            For  example,  `-foo-:...' specifies that the com‐
3414                            pleted  option  and  argument   will   look   like
3415                            `-fooarg'.
3416
3417                     -optname+
3418                            The  first  argument  may appear immediately after
3419                            optname in the same word, or may appear as a sepa‐
3420                            rate   word   after   the  option.   For  example,
3421                            `-foo+:...' specifies that  the  completed  option
3422                            and  argument  will  look like either `-fooarg' or
3423                            `-foo arg'.
3424
3425                     -optname=
3426                            The argument may appear as the next  word,  or  in
3427                            same  word  as the option name provided that it is
3428                            separated from it by an equals sign,  for  example
3429                            `-foo=arg' or `-foo arg'.
3430
3431                     -optname=-
3432                            The  argument  to  the option must appear after an
3433                            equals sign in the same word, and may not be given
3434                            in the next argument.
3435
3436                     optspec[explanation]
3437                            An  explanation  string  may be appended to any of
3438                            the preceding forms of optspec by enclosing it  in
3439                            brackets, as in `-q[query operation]'.
3440
3441                            The  verbose  style  is used to decide whether the
3442                            explanation strings are displayed with the  option
3443                            in a completion listing.
3444
3445                            If  no  bracketed  explanation string is given but
3446                            the auto-description style is  set  and  only  one
3447                            argument  is described for this optspec, the value
3448                            of the style is displayed, with any appearance  of
3449                            the sequence `%d' in it replaced by the message of
3450                            the first optarg that  follows  the  optspec;  see
3451                            below.
3452
3453                     It  is  possible for options with a literal `+' or `=' to
3454                     appear, but that character must be  quoted,  for  example
3455                     `-\+'.
3456
3457                     Each  optarg  following  an  optspec must take one of the
3458                     following forms:
3459
3460                     :message:action
3461                     ::message:action
3462                            An argument to the option; message and action  are
3463                            treated  as  for ordinary arguments.  In the first
3464                            form, the argument is mandatory, and in the second
3465                            form it is optional.
3466
3467                            This  group may be repeated for options which take
3468                            multiple  arguments.   In   other   words,   :mes‐
3469                            sage1:action1:message2:action2  specifies that the
3470                            option takes two arguments.
3471
3472                     :*pattern:message:action
3473                     :*pattern::message:action
3474                     :*pattern:::message:action
3475                            This describes multiple arguments.  Only the  last
3476                            optarg for an option taking multiple arguments may
3477                            be given in this form.  If the  pattern  is  empty
3478                            (i.e.  :*:),  all  the remaining words on the line
3479                            are to be completed as described  by  the  action;
3480                            otherwise,  all  the  words  up to and including a
3481                            word matching the  pattern  are  to  be  completed
3482                            using the action.
3483
3484                            Multiple  colons  are  treated  as for the `*:...'
3485                            forms for ordinary arguments:  when the message is
3486                            preceded  by  two  colons, the words special array
3487                            and the CURRENT  special  parameter  are  modified
3488                            during  the  execution or evaluation of the action
3489                            to refer only to the words after the option.  When
3490                            preceded  by  three  colons,  they are modified to
3491                            refer only to the words covered by  this  descrip‐
3492                            tion.
3493
3494              Any literal colon in an optname, message, or action must be pre‐
3495              ceded by a backslash, `\:'.
3496
3497              Each of the forms above may be preceded by a list in parentheses
3498              of option names and argument numbers.  If the given option is on
3499              the command line, the options and arguments indicated in  paren‐
3500              theses   will  not  be  offered.   For  example,  `(-two  -three
3501              1)-one:...' completes the option `-one'; if this appears on  the
3502              command line, the options -two and -three and the first ordinary
3503              argument will not be completed after it.  `(-foo):...' specifies
3504              an  ordinary  argument completion; -foo will not be completed if
3505              that argument is already present.
3506
3507              Other items may appear in the list of excluded options to  indi‐
3508              cate  various  other  items  that should not be applied when the
3509              current specification is matched: a single star (*) for the rest
3510              arguments  (i.e.  a  specification of the form `*:...'); a colon
3511              (:) for all normal (non-option-) arguments; and a hyphen (-) for
3512              all options.  For example, if `(*)' appears before an option and
3513              the option appears on the command line, the  list  of  remaining
3514              arguments  (those  shown in the above table beginning with `*:')
3515              will not be completed.
3516
3517              To aid in reuse of specifications, it is possible to precede any
3518              of  the  forms  above  with `!'; then the form will no longer be
3519              completed, although if the option or  argument  appears  on  the
3520              command  line  they will be skipped as normal.  The main use for
3521              this is when the arguments are given by an array, and _arguments
3522              is  called  repeatedly  for more specific contexts: on the first
3523              call `_arguments $global_options' is  used,  and  on  subsequent
3524              calls `_arguments !$^global_options'.
3525
3526              specs: actions
3527
3528              In each of the forms above the action determines how completions
3529              should be generated.  Except for the `->string' form below,  the
3530              action  will  be executed by calling the _all_labels function to
3531              process all tag labels.  No special handling of tags  is  needed
3532              unless a function call introduces a new one.
3533
3534              The  functions called to execute actions will be called with the
3535              elements of the array named by the `-O  name'  option  as  argu‐
3536              ments.   This  can be used, for example, to pass the same set of
3537              options for the compadd builtin to all actions.
3538
3539              The forms for action are as follows.
3540
3541               (single unquoted space)
3542                     This is useful where an argument is required  but  it  is
3543                     not  possible  or  desirable  to generate matches for it.
3544                     The message will be displayed but no completions  listed.
3545                     Note  that  even in this case the colon at the end of the
3546                     message is needed; it may only be omitted when neither  a
3547                     message nor an action is given.
3548
3549              (item1 item2 ...)
3550                     One of a list of possible matches, for example:
3551
3552                            :foo:(foo bar baz)
3553
3554              ((item1\:desc1 ...))
3555                     Similar to the above, but with descriptions for each pos‐
3556                     sible match.  Note the backslash before the  colon.   For
3557                     example,
3558
3559                            :foo:((a\:bar b\:baz))
3560
3561                     The  matches  will be listed together with their descrip‐
3562                     tions if the description style is set with the values tag
3563                     in the context.
3564
3565              ->string
3566                     In  this  form,  _arguments  processes  the arguments and
3567                     options and then returns control to the calling  function
3568                     with  parameters set to indicate the state of processing;
3569                     the calling function then makes its own arrangements  for
3570                     generating  completions.   For  example,  functions  that
3571                     implement a state machine can use this type of action.
3572
3573                     Where _arguments encounters action in the `->string' for‐
3574                     mat,  it  will  strip all leading and trailing whitespace
3575                     from string and set the array state to  the  set  of  all
3576                     strings for which an action is to be performed.  The ele‐
3577                     ments of the array state_descr are  assigned  the  corre‐
3578                     sponding  message  field from each optarg containing such
3579                     an action.
3580
3581                     By default and in common with all other well behaved com‐
3582                     pletion  functions,  _arguments returns status zero if it
3583                     was able to add matches and non-zero otherwise.  However,
3584                     if the -R option is given, _arguments will instead return
3585                     a status of 300 to indicate that $state is to be handled.
3586
3587                     In addition to $state and $state_descr,  _arguments  also
3588                     sets   the   global   parameters  `context',  `line'  and
3589                     `opt_args' as described below, and  does  not  reset  any
3590                     changes made to the special parameters such as PREFIX and
3591                     words.  This gives the calling  function  the  choice  of
3592                     resetting  these  parameters  or  propagating  changes in
3593                     them.
3594
3595                     A function calling _arguments with at  least  one  action
3596                     containing  a `->string' must therefore declare appropri‐
3597                     ate local parameters:
3598
3599                            local context state state_descr line
3600                            typeset -A opt_args
3601
3602                     to prevent _arguments from altering the  global  environ‐
3603                     ment.
3604
3605              {eval-string}
3606                     A string in braces is evaluated as shell code to generate
3607                     matches.  If the eval-string itself does not  begin  with
3608                     an opening parenthesis or brace it is split into separate
3609                     words before execution.
3610
3611              = action
3612                     If the action starts with `= ' (an equals  sign  followed
3613                     by  a  space), _arguments will insert the contents of the
3614                     argument field of the current context as  the  new  first
3615                     element  in  the  words  special  array and increment the
3616                     value of the CURRENT special  parameter.   This  has  the
3617                     effect of inserting a dummy word onto the completion com‐
3618                     mand line while not changing the point at  which  comple‐
3619                     tion is taking place.
3620
3621                     This  is  most  useful  with  one  of the specifiers that
3622                     restrict the words on  the  command  line  on  which  the
3623                     action  is  to  operate  (the  two- and three-colon forms
3624                     above).  One particular use  is  when  an  action  itself
3625                     causes  _arguments on a restricted range; it is necessary
3626                     to use this trick to insert an appropriate  command  name
3627                     into  the  range  for the second call to _arguments to be
3628                     able to parse the line.
3629
3630               word...
3631              word...
3632                     This covers all forms other than  those  above.   If  the
3633                     action  starts  with a space, the remaining list of words
3634                     will be invoked unchanged.
3635
3636                     Otherwise it will be  invoked  with  some  extra  strings
3637                     placed  after the first word; these are to be passed down
3638                     as options to the compadd builtin.  They ensure that  the
3639                     state specified by _arguments, in particular the descrip‐
3640                     tions of options and arguments, is  correctly  passed  to
3641                     the  completion  command.  These additional arguments are
3642                     taken from the array parameter `expl'; this will  be  set
3643                     up  before executing the action and hence may be referred
3644                     to inside it, typically  in  an  expansion  of  the  form
3645                     `$expl[@]' which preserves empty elements of the array.
3646
3647              During  the  performance  of the action the array `line' will be
3648              set to the normal arguments from  the  command  line,  i.e.  the
3649              words from the command line after the command name excluding all
3650              options and their arguments.  Options are stored in the associa‐
3651              tive  array `opt_args' with option names as keys and their argu‐
3652              ments as the values.  For options that have more than one  argu‐
3653              ment  these  are  given as one string, separated by colons.  All
3654              colons and backslashes in the original  arguments  are  preceded
3655              with backslashes.
3656
3657              The  parameter  `context'  is  set when returning to the calling
3658              function to perform an action of the form `->string'.  It is set
3659              to an array of elements corresponding to the elements of $state.
3660              Each element is a suitable name for the argument  field  of  the
3661              context: either a string of the form `option-opt-n' for the n'th
3662              argument of the option -opt, or a  string  of  the  form  `argu‐
3663              ment-n'  for  the  n'th argument.  For `rest' arguments, that is
3664              those in the list at the end not handled by position, n  is  the
3665              string `rest'.  For example, when completing the argument of the
3666              -o option, the name is `option-o-1', while for the second normal
3667              (non-option-) argument it is `argument-2'.
3668
3669              Furthermore,  during  the  evaluation  of the action the context
3670              name in the curcontext parameter is altered to append  the  same
3671              string that is stored in the context parameter.
3672
3673              The  option -C tells _arguments to modify the curcontext parame‐
3674              ter for an action of the form `->state'.  This is  the  standard
3675              parameter  used  to  keep track of the current context.  Here it
3676              (and not the context array) should be made local to the  calling
3677              function  to avoid passing back the modified value and should be
3678              initialised to the current value at the start of the function:
3679
3680                     local curcontext="$curcontext"
3681
3682              This is useful where it is not possible for multiple  states  to
3683              be valid together.
3684
3685              Grouping Options
3686
3687              Options  can  be grouped to simplify exclusion lists. A group is
3688              introduced with `+' followed by a name for the group in the sub‐
3689              sequent  word.  Whole groups can then be referenced in an exclu‐
3690              sion list or a group name can be used  to  disambiguate  between
3691              two forms of the same option. For example:
3692
3693                     _arguments \
3694                         '(group2--x)-a' \
3695                       + group1 \
3696                         -m \
3697                         '(group2)-n' \
3698                       + group2 \
3699                         -x -y
3700
3701              If  the  name  of a group is specified in the form `(name)' then
3702              only one value from that group will ever be completed; more for‐
3703              mally,  all  specifications  are mutually exclusive to all other
3704              specifications in  that  group.  This  is  useful  for  defining
3705              options that are aliases for each other. For example:
3706
3707                     _arguments \
3708                         -a -b \
3709                       + '(operation)' \
3710                         {-c,--compress}'[compress]' \
3711                         {-d,--decompress}'[decompress]' \
3712                         {-l,--list}'[list]'
3713
3714              If  an  option  in  a  group  appears on the command line, it is
3715              stored in the associative array `opt_args'  with  'group-option'
3716              as a key.  In the example above, a key `operation--c' is used if
3717              the option `-c' is present on the command line.
3718
3719              Specifying Multiple Sets of Arguments
3720
3721              It is possible to specify multiple sets of options and arguments
3722              with  the  sets  separated  by single hyphens. This differs from
3723              groups in that sets are considered to be mutually  exclusive  of
3724              each other.
3725
3726              Specifications  before the first set and from any group are com‐
3727              mon to all sets. For example:
3728
3729                     _arguments \
3730                         -a \
3731                       - set1 \
3732                         -c \
3733                       - set2 \
3734                         -d \
3735                         ':arg:(x2 y2)'
3736
3737              This defines two sets.   When  the  command  line  contains  the
3738              option  `-c',  the `-d' option and the argument will not be con‐
3739              sidered possible completions.  When it contains `-d' or an argu‐
3740              ment,  the  option  `-c' will not be considered.  However, after
3741              `-a' both sets will still be considered valid.
3742
3743              As for groups, the name of a set may appear in exclusion  lists,
3744              either alone or preceding a normal option or argument specifica‐
3745              tion.
3746
3747              The completion code has to parse the command line separately for
3748              each set. This can be slow so sets should only be used when nec‐
3749              essary.  A useful alternative is often an  option  specification
3750              with  rest-arguments  (as in `-foo:*:...'); here the option -foo
3751              swallows up all remaining arguments as described by  the  optarg
3752              definitions.
3753
3754              Deriving spec forms from the help output
3755
3756              The  option `--' allows _arguments to work out the names of long
3757              options that support the `--help' option which  is  standard  in
3758              many GNU commands.  The command word is called with the argument
3759              `--help' and the output examined for option names.  Clearly,  it
3760              can  be dangerous to pass this to commands which may not support
3761              this option as the behaviour of the command is unspecified.
3762
3763              In addition to options, `_arguments --' will try to  deduce  the
3764              types   of   arguments  available  for  options  when  the  form
3765              `--opt=val' is valid.  It is also possible to provide  hints  by
3766              examining  the  help  text of the command and adding helpspec of
3767              the form `pattern:message:action'; note  that  other  _arguments
3768              spec  forms  are  not  used.  The pattern is matched against the
3769              help text for an option, and  if  it  matches  the  message  and
3770              action  are  used as for other argument specifiers.  The special
3771              case of `*:' means both message and action are empty, which  has
3772              the  effect of causing options having no description in the help
3773              output to be ordered in listings ahead of options  that  have  a
3774              description.
3775
3776              For example:
3777
3778                     _arguments -- '*\*:toggle:(yes no)' \
3779                                   '*=FILE*:file:_files' \
3780                                   '*=DIR*:directory:_files -/' \
3781                                   '*=PATH*:directory:_files -/'
3782
3783              Here,  `yes'  and  `no'  will  be  completed  as the argument of
3784              options whose description ends in a star;  file  names  will  be
3785              completed  for options that contain the substring `=FILE' in the
3786              description; and directories will be completed for options whose
3787              description  contains  `=DIR' or `=PATH'.  The last three are in
3788              fact the default and so need not be given  explicitly,  although
3789              it is possible to override the use of these patterns.  A typical
3790              help text which uses this feature is:
3791
3792                       -C, --directory=DIR          change to directory DIR
3793
3794              so that the above specifications will cause  directories  to  be
3795              completed after `--directory', though not after `-C'.
3796
3797              Note also that _arguments tries to find out automatically if the
3798              argument for an option  is  optional.   This  can  be  specified
3799              explicitly by doubling the colon before the message.
3800
3801              If the pattern ends in `(-)', this will be removed from the pat‐
3802              tern and the action will be used only directly  after  the  `=',
3803              not  in the next word.  This is the behaviour of a normal speci‐
3804              fication defined with the form `=-'.
3805
3806              By default, the command (with the option `--help') is run  after
3807              resetting  all  the  locale  categories (except for LC_CTYPE) to
3808              `C'.  If the localized help output is known to work, the  option
3809              `-l' can be specified after the `_arguments --' so that the com‐
3810              mand is run in the current locale.
3811
3812              The `_arguments --' can be followed by the option `-i  patterns'
3813              to give patterns for options which are not to be completed.  The
3814              patterns can be given as the name of an array parameter or as  a
3815              literal list in parentheses.  For example,
3816
3817                     _arguments -- -i \
3818                         "(--(en|dis)able-FEATURE*)"
3819
3820              will  cause  completion to ignore the options `--enable-FEATURE'
3821              and `--disable-FEATURE' (this example is useful with GNU config‐
3822              ure).
3823
3824              The  `_arguments --' form can also be followed by the option `-s
3825              pair' to describe option aliases.  The pair consists of  a  list
3826              of alternating patterns and corresponding replacements, enclosed
3827              in parens and quoted so that it forms a single argument word  in
3828              the _arguments call.
3829
3830              For example, some configure-script help output describes options
3831              only as `--enable-foo', but the script also accepts the  negated
3832              form `--disable-foo'.  To allow completion of the second form:
3833
3834                     _arguments -- -s "((#s)--enable- --disable-)"
3835
3836              Miscellaneous notes
3837
3838              Finally,  note  that _arguments generally expects to be the pri‐
3839              mary function handling any completion for which it is used.   It
3840              may  have side effects which change the treatment of any matches
3841              added by other functions called after it.  To combine _arguments
3842              with  other  functions,  those functions should be called either
3843              before _arguments, as an action within a spec,  or  in  handlers
3844              for `->state' actions.
3845
3846              Here is a more general example of the use of _arguments:
3847
3848                     _arguments '-l+:left border:' \
3849                                '-format:paper size:(letter A4)' \
3850                                '*-copy:output file:_files::resolution:(300 600)' \
3851                                ':postscript file:_files -g \*.\(ps\|eps\)' \
3852                                '*:page number:'
3853
3854              This describes three options: `-l', `-format', and `-copy'.  The
3855              first takes one argument described as `left border' for which no
3856              completion  will  be  offered  because of the empty action.  Its
3857              argument may come directly after the `-l' or it may be given  as
3858              the next word on the line.
3859
3860              The  `-format'  option  takes  one  argument  in  the next word,
3861              described as `paper size' for which only  the  strings  `letter'
3862              and `A4' will be completed.
3863
3864              The `-copy' option may appear more than once on the command line
3865              and takes two arguments.  The first is  mandatory  and  will  be
3866              completed as a filename.  The second is optional (because of the
3867              second colon before the description `resolution')  and  will  be
3868              completed from the strings `300' and `600'.
3869
3870              The  last two descriptions say what should be completed as argu‐
3871              ments.  The first describes the first argument as a  `postscript
3872              file' and makes files ending in `ps' or `eps' be completed.  The
3873              last description gives all other arguments the description `page
3874              numbers' but does not offer completions.
3875
3876       _cache_invalid cache_identifier
3877              This  function returns status zero if the completions cache cor‐
3878              responding to the given cache identifier needs  rebuilding.   It
3879              determines  this  by  looking  up the cache-policy style for the
3880              current context.  This should provide a function name  which  is
3881              run  with  the  full path to the relevant cache file as the only
3882              argument.
3883
3884              Example:
3885
3886                     _example_caching_policy () {
3887                         # rebuild if cache is more than a week old
3888                         local -a oldp
3889                         oldp=( "$1"(Nm+7) )
3890                         (( $#oldp ))
3891                     }
3892
3893       _call_function return name [ arg ... ]
3894              If a function name exists, it is called with the arguments args.
3895              The  return  argument gives the name of a parameter in which the
3896              return status from the function name should be stored; if return
3897              is empty or a single hyphen it is ignored.
3898
3899              The  return status of _call_function itself is zero if the func‐
3900              tion name exists and was called and non-zero otherwise.
3901
3902       _call_program [ -l ] [ -p ] tag string ...
3903              This function provides a mechanism for the user to override  the
3904              use  of an external command.  It looks up the command style with
3905              the supplied tag.  If the style is set, its value is used as the
3906              command to execute.  The strings from the call to _call_program,
3907              or from the style if set, are concatenated with  spaces  between
3908              them  and  the resulting string is evaluated.  The return status
3909              is the return status of the command called.
3910
3911              By default, the command is run in an environment where  all  the
3912              locale  categories  (except  for  LC_CTYPE)  are reset to `C' by
3913              calling the utility function _comp_locale (see  below).  If  the
3914              option  `-l'  is  given,  the  command  is  run with the current
3915              locale.
3916
3917              If the option `-p' is supplied it  indicates  that  the  command
3918              output  is  influenced by the permissions it is run with. If the
3919              gain-privileges style is set to true,  _call_program  will  make
3920              use of commands such as sudo, if present on the command-line, to
3921              match the permissions to whatever the final command is likely to
3922              run  under.  When  looking  up  the  gain-privileges and command
3923              styles, the command component of the  zstyle  context  will  end
3924              with a slash (`/') followed by the command that would be used to
3925              gain privileges.
3926
3927       _combination [ -s pattern ] tag style spec ... field opts ...
3928              This function is used to complete combinations of  values,   for
3929              example  pairs  of  hostnames and usernames.  The style argument
3930              gives the style which defines the pairs; it is looked  up  in  a
3931              context with the tag specified.
3932
3933              The style name consists of field names separated by hyphens, for
3934              example `users-hosts-ports'.  For each  field  for  a  value  is
3935              already known, a spec of the form `field=pattern' is given.  For
3936              example, if the command line so far specifies a user `pws',  the
3937              argument `users=pws' should appear.
3938
3939              The  next  argument  with no equals sign is taken as the name of
3940              the field for which completions should be generated  (presumably
3941              not one of the fields for which the value is known).
3942
3943              The matches generated will be taken from the value of the style.
3944              These should contain the possible values for the combinations in
3945              the  appropriate  order  (users,  hosts,  ports  in  the example
3946              above).  The values for the different fields  are  separated  by
3947              colons.   This can be altered with the option -s to _combination
3948              which specifies a pattern.  Typically this is a character class,
3949              as for example `-s "[:@]"' in the case of the users-hosts style.
3950              Each `field=pattern'  specification  restricts  the  completions
3951              which apply to elements of the style with appropriately matching
3952              fields.
3953
3954              If no style with the given name is defined for the given tag, or
3955              if  none  of  the strings in style's value match, but a function
3956              name of the required field preceded by an underscore is defined,
3957              that function will be called to generate the matches.  For exam‐
3958              ple, if there is no `users-hosts-ports' or no matching  hostname
3959              when  a  host  is required, the function `_hosts' will automati‐
3960              cally be called.
3961
3962              If the same name is used for more than one field,  in  both  the
3963              `field=pattern'  and  the  argument  that  gives the name of the
3964              field to be completed, the number of the  field  (starting  with
3965              one)  may  be  given after the fieldname, separated from it by a
3966              colon.
3967
3968              All arguments after the required field name are passed  to  com‐
3969              padd  when  generating  matches  from the style value, or to the
3970              functions for the fields if they are called.
3971
3972       _command_names [ -e | - ]
3973              This function completes words that are valid  at  command  posi‐
3974              tion:  names  of  aliases, builtins, hashed commands, functions,
3975              and so on.  With the -e flag,  only  hashed  commands  are  com‐
3976              pleted.  The - flag is ignored.
3977
3978       _comp_locale
3979              This  function  resets  all  the  locale  categories  other than
3980              LC_CTYPE to `C' so that the output from external commands can be
3981              easily  analyzed  by the completion system. LC_CTYPE retains the
3982              current value (taking LC_ALL and LANG  into  account),  ensuring
3983              that  non-ASCII characters in file names are still handled prop‐
3984              erly.
3985
3986              This function should normally be run only in a subshell, because
3987              the  new  locale  is  exported to the environment. Typical usage
3988              would be `$(_comp_locale; command ...)'.
3989
3990       _completers [ -p ]
3991              This function completes names of completers.
3992
3993              -p     Include the leading underscore (`_') in the matches.
3994
3995
3996       _describe [-12JVx] [ -oO | -t tag ] descr name1 [ name2 ] [ opt ... ]
3997                 [ -- name1 [ name2 ] [ opt ... ] ... ]
3998              This function associates completions with descriptions.   Multi‐
3999              ple  groups  separated  by  -- can be supplied, potentially with
4000              different completion options opts.
4001
4002              The descr is taken as a string to display above the  matches  if
4003              the  format style for the descriptions tag is set.  This is fol‐
4004              lowed by one or two names of arrays followed by options to  pass
4005              to  compadd.   The array name1 contains the possible completions
4006              with their descriptions in  the  form  `completion:description'.
4007              Any  literal  colons  in  completion must be quoted with a back‐
4008              slash.  If a name2 is given, it should have the same  number  of
4009              elements  as  name1; in this case the corresponding elements are
4010              added as possible completions instead of the completion  strings
4011              from  name1.   The  completion list will retain the descriptions
4012              from name1.  Finally, a set of completion options can appear.
4013
4014              If the option  `-o'  appears  before  the  first  argument,  the
4015              matches  added will be treated as names of command options (N.B.
4016              not shell options), typically following a `-', `--'  or  `+'  on
4017              the  command  line.  In this case _describe uses the prefix-hid‐
4018              den, prefix-needed and verbose styles to find out if the strings
4019              should be added as completions and if the descriptions should be
4020              shown.  Without the `-o' option, only the verbose style is  used
4021              to  decide  how descriptions are shown.  If `-O' is used instead
4022              of `-o', command options are completed as  above  but  _describe
4023              will not handle the prefix-needed style.
4024
4025              With the -t option a tag can be specified.  The default is `val‐
4026              ues' or, if the -o option is given, `options'.
4027
4028              The options -1, -2, -J, -V, -x are passed to _next_label.
4029
4030              If selected by the list-grouped style,  strings  with  the  same
4031              description will appear together in the list.
4032
4033              _describe uses the _all_labels function to generate the matches,
4034              so it does not need to appear inside a loop over tag labels.
4035
4036       _description [ -x ] [ -12VJ ] tag name descr [ spec ... ]
4037              This function is not to be confused with the previous one; it is
4038              used  as  a helper function for creating options to compadd.  It
4039              is buried inside many of the higher level  completion  functions
4040              and so often does not need to be called directly.
4041
4042              The  styles listed below are tested in the current context using
4043              the given tag.  The resulting options for compadd are  put  into
4044              the  array  named  name  (this is traditionally `expl', but this
4045              convention is not enforced).  The  description  for  the  corre‐
4046              sponding set of matches is passed to the function in descr.
4047
4048              The styles tested are: format, hidden, matcher, ignored-patterns
4049              and group-name.  The format style is first tested for the  given
4050              tag  and  then  for  the descriptions tag if no value was found,
4051              while the remainder are only tested for the  tag  given  as  the
4052              first argument.  The function also calls _setup which tests some
4053              more styles.
4054
4055              The string returned by the format style (if any) will  be  modi‐
4056              fied so that the sequence `%d' is replaced by the descr given as
4057              the third argument without any leading or trailing white  space.
4058              If,  after  removing  the  white  space,  the descr is the empty
4059              string, the format style will not be used and  the  options  put
4060              into the name array will not contain an explanation string to be
4061              displayed above the matches.
4062
4063              If _description is called with more than  three  arguments,  the
4064              additional specs should be of the form `char:str'.  These supply
4065              escape sequence replacements for the format style: every appear‐
4066              ance of `%char' will be replaced by string.
4067
4068              If  the  -x  option  is given, the description will be passed to
4069              compadd using the -x option instead of  the  default  -X.   This
4070              means  that  the description will be displayed even if there are
4071              no corresponding matches.
4072
4073              The options placed  in  the  array  name  take  account  of  the
4074              group-name  style,  so  matches  are  placed in a separate group
4075              where necessary.  The group normally has its elements sorted (by
4076              passing  the  option  -J  to compadd), but if an option starting
4077              with `-V', `-J', `-1', or `-2' is passed to  _description,  that
4078              option  will be included in the array.  Hence it is possible for
4079              the completion group to be unsorted by giving the  option  `-V',
4080              `-1V', or `-2V'.
4081
4082              In most cases, the function will be used like this:
4083
4084                     local expl
4085                     _description files expl file
4086                     compadd "$expl[@]" - "$files[@]"
4087
4088              Note  the use of the parameter expl, the hyphen, and the list of
4089              matches.  Almost all calls to compadd within the completion sys‐
4090              tem  use  a  similar  format;  this  ensures that user-specified
4091              styles are correctly passed down to the builtins which implement
4092              the internals of completion.
4093
4094       _dir_list [ -s sep ] [ -S ]
4095              Complete a list of directory names separated by colons (the same
4096              format as $PATH).
4097
4098              -s sep Use sep as separator between items.  sep  defaults  to  a
4099                     colon (`:').
4100
4101              -S     Add  sep instead of slash (`/') as an autoremoveable suf‐
4102                     fix.
4103
4104       _dispatch context string ...
4105              This sets the current context to context and looks  for  comple‐
4106              tion  functions  to  handle  this context by hunting through the
4107              list of command names or special contexts  (as  described  above
4108              for compdef) given as strings.  The first completion function to
4109              be defined for one of the contexts in the list is used to gener‐
4110              ate  matches.   Typically, the last string is -default- to cause
4111              the function for default completion to be used as a fallback.
4112
4113              The function sets the parameter $service  to  the  string  being
4114              tried,  and  sets  the context/command field (the fourth) of the
4115              $curcontext parameter to the context given as  the  first  argu‐
4116              ment.
4117
4118       _email_addresses [ -c ] [ -n plugin ]
4119              Complete email addresses.  Addresses are provided by plugins.
4120
4121              -c     Complete  bare  localhost@domain.tld addresses, without a
4122                     name part or a  comment.   Without  this  option,  RFC822
4123                     `Firstname Lastname <address>' strings are completed.
4124
4125              -n plugin
4126                     Complete aliases from plugin.
4127
4128              The following plugins are available by default: _email-ldap (see
4129              the filter style), _email-local  (completes  user@hostname  Unix
4130              addresses),  _email-mail  (completes  aliases  from  ~/.mailrc),
4131              _email-mush, _email-mutt, and _email-pine.
4132
4133              Addresses from the _email-foo plugin are  added  under  the  tag
4134              `email-foo'.
4135
4136              Writing plugins
4137
4138              Plugins  are  written  as separate functions with names starting
4139              with `_email-'.  They are invoked with the -c option and compadd
4140              options.   They should either do their own completion or set the
4141              $reply array to a list of `alias:address'  elements  and  return
4142              300.  New plugins will be picked up and run automatically.
4143
4144       _files The  function _files calls _path_files with all the arguments it
4145              was passed except for -g and -/.  The use of these  two  options
4146              depends on the setting of the  file-patterns style.
4147
4148              This  function  accepts  the  full  set  of  options  allowed by
4149              _path_files, described below.
4150
4151       _gnu_generic
4152              This function is a simple wrapper around the _arguments function
4153              described  above.  It can be used to determine automatically the
4154              long options understood by commands that  produce  a  list  when
4155              passed  the  option  `--help'.   It  is intended to be used as a
4156              top-level completion function in its own right.  For example, to
4157              enable option completion for the commands foo and bar, use
4158
4159                     compdef _gnu_generic foo bar
4160
4161              after the call to compinit.
4162
4163              The  completion system as supplied is conservative in its use of
4164              this function, since it is important  to  be  sure  the  command
4165              understands the option `--help'.
4166
4167       _guard [ options ] pattern descr
4168              This function displays descr if pattern matches the string to be
4169              completed.  It is intended to be used  in  the  action  for  the
4170              specifications passed to _arguments and similar functions.
4171
4172              The  return  status is zero if the message was displayed and the
4173              word to complete is not empty, and non-zero otherwise.
4174
4175              The pattern may be preceded by any of the options understood  by
4176              compadd  that  are passed down from _description, namely -M, -J,
4177              -V, -1, -2, -n, -F  and  -X.   All  of  these  options  will  be
4178              ignored.   This  fits  in conveniently with the argument-passing
4179              conventions of actions for _arguments.
4180
4181              As an example, consider a command  taking  the  options  -n  and
4182              -none,  where -n must be followed by a numeric value in the same
4183              word.  By using:
4184
4185                     _arguments '-n-: :_guard "[0-9]#" "numeric value"' '-none'
4186
4187              _arguments can be made to  both  display  the  message  `numeric
4188              value'  and  complete  options  after `-n<TAB>'.  If the `-n' is
4189              already followed by one or more digits (the  pattern  passed  to
4190              _guard)  only the message will be displayed; if the `-n' is fol‐
4191              lowed by another character, only options are completed.
4192
4193       _message [ -r12 ] [ -VJ group ] descr
4194       _message -e [ tag ] descr
4195              The descr is used in the same way as the third argument  to  the
4196              _description  function,  except  that  the resulting string will
4197              always be shown whether or not matches were generated.  This  is
4198              useful  for displaying a help message in places where no comple‐
4199              tions can be generated.
4200
4201              The format style is examined with the messages  tag  to  find  a
4202              message;  the usual tag, descriptions, is used only if the style
4203              is not set with the former.
4204
4205              If the -r option is given, no style is used; the descr is  taken
4206              literally  as  the  string to display.  This is most useful when
4207              the descr comes from a pre-processed argument list which already
4208              contains an expanded description.
4209
4210              The  -12VJ options and the group are passed to compadd and hence
4211              determine the group the message string is added to.
4212
4213              The second -e form gives a description for completions with  the
4214              tag  tag  to be shown even if there are no matches for that tag.
4215              This form is called by _arguments in the event that there is  no
4216              action  for an option specification.  The tag can be omitted and
4217              if so the tag is taken from the parameter $curtag; this is main‐
4218              tained by the completion system and so is usually correct.  Note
4219              that if there are no  matches  at  the  time  this  function  is
4220              called, compstate[insert] is cleared, so additional matches gen‐
4221              erated later are not inserted on the command line.
4222
4223       _multi_parts [ -i ] sep array
4224              The argument sep is a separator character.   The  array  may  be
4225              either  the name of an array parameter or a literal array in the
4226              form `(foo bar)', a parenthesised list  of  words  separated  by
4227              whitespace.   The  possible completions are the strings from the
4228              array.  However, each chunk delimited by sep will  be  completed
4229              separately.  For example, the _tar function uses `_multi_parts /
4230              patharray' to complete partial file paths from the  given  array
4231              of complete file paths.
4232
4233              The  -i option causes _multi_parts to insert a unique match even
4234              if that requires multiple separators to be  inserted.   This  is
4235              not  usually  the expected behaviour with filenames, but certain
4236              other types of completion, for example those with a fixed set of
4237              possibilities, may be more suited to this form.
4238
4239              Like  other  utility  functions, this function accepts the `-V',
4240              `-J', `-1', `-2', `-n', `-f',  `-X',  `-M',  `-P',  `-S',  `-r',
4241              `-R', and `-q' options and passes them to the compadd builtin.
4242
4243       _next_label [ -x ] [ -12VJ ] tag name descr [ option ... ]
4244              This  function  is used to implement the loop over different tag
4245              labels for a particular tag as described above for the tag-order
4246              style.   On each call it checks to see if there are any more tag
4247              labels; if there is it returns status zero, otherwise  non-zero.
4248              As  this  function  requires  a  current  tag to be set, it must
4249              always follow a call to _tags or _requested.
4250
4251              The -x12VJ options and the first three arguments are  passed  to
4252              the  _description  function.   Where appropriate the tag will be
4253              replaced by a tag label in this call.  Any description given  in
4254              the  tag-order  style  is  preferred  to  the  descr  passed  to
4255              _next_label.
4256
4257              The options given after the descr are set in the parameter given
4258              by name, and hence are to be passed to compadd or whatever func‐
4259              tion is called to add the matches.
4260
4261              Here is a typical use of this function for  the  tag  foo.   The
4262              call to _requested determines if tag foo is required at all; the
4263              loop over _next_label handles any labels defined for the tag  in
4264              the tag-order style.
4265
4266                     local expl ret=1
4267                     ...
4268                     if _requested foo; then
4269                       ...
4270                       while _next_label foo expl '...'; do
4271                         compadd "$expl[@]" ... && ret=0
4272                       done
4273                       ...
4274                     fi
4275                     return ret
4276
4277       _normal
4278              This  is  the standard function called to handle completion out‐
4279              side any special -context-.  It is called both to  complete  the
4280              command  word and also the arguments for a command.  In the sec‐
4281              ond case, _normal looks for a special completion for  that  com‐
4282              mand,  and  if  there  is  none  it  uses the completion for the
4283              -default- context.
4284
4285              A second use is to reexamine the command line specified  by  the
4286              $words  array  and  the $CURRENT parameter after those have been
4287              modified.  For example, the  function  _precommand,  which  com‐
4288              pletes  after  pre-command specifiers such as nohup, removes the
4289              first word from the words array, decrements the CURRENT  parame‐
4290              ter,  then  calls  _normal again.  The effect is that `nohup cmd
4291              ...' is treated in the same way as `cmd ...'.
4292
4293              If the command name matches one of the patterns given by one  of
4294              the  options  -p  or -P to compdef, the corresponding completion
4295              function is called and then the parameter _compskip is  checked.
4296              If  it  is set completion is terminated at that point even if no
4297              matches have been found.  This is the  same  effect  as  in  the
4298              -first- context.
4299
4300       _options
4301              This  can  be  used  to complete the names of shell options.  It
4302              provides a matcher specification that ignores  a  leading  `no',
4303              ignores underscores and allows upper-case letters to match their
4304              lower-case  counterparts   (for   example,   `glob',   `noglob',
4305              `NO_GLOB'  are  all completed).  Any arguments are propagated to
4306              the compadd builtin.
4307
4308       _options_set and _options_unset
4309              These functions complete only set or  unset  options,  with  the
4310              same matching specification used in the _options function.
4311
4312              Note  that  you  need to uncomment a few lines in the _main_com‐
4313              plete function for these functions to work properly.  The  lines
4314              in  question  are  used  to  store the option settings in effect
4315              before the completion widget locally sets the options it  needs.
4316              Hence  these  functions are not generally used by the completion
4317              system.
4318
4319       _parameters
4320              This is used to complete the names of shell parameters.
4321
4322              The option `-g pattern'  limits  the  completion  to  parameters
4323              whose type matches the pattern.  The type of a parameter is that
4324              shown by `print ${(t)param}', hence judicious use of `*' in pat‐
4325              tern is probably necessary.
4326
4327              All other arguments are passed to the compadd builtin.
4328
4329       _path_files
4330              This  function  is used throughout the completion system to com‐
4331              plete filenames.  It allows completion of  partial  paths.   For
4332              example,   the   string   `/u/i/s/sig'   may   be  completed  to
4333              `/usr/include/sys/signal.h'.
4334
4335              The options accepted by both _path_files and _files are:
4336
4337              -f     Complete all filenames.  This is the default.
4338
4339              -/     Specifies that only directories should be completed.
4340
4341              -g pattern
4342                     Specifies that only files matching the pattern should  be
4343                     completed.
4344
4345              -W paths
4346                     Specifies  path  prefixes that are to be prepended to the
4347                     string from the command line to  generate  the  filenames
4348                     but  that should not be inserted as completions nor shown
4349                     in completion listings.  Here, paths may be the  name  of
4350                     an  array  parameter, a literal list of paths enclosed in
4351                     parentheses or an absolute pathname.
4352
4353              -F ignored-files
4354                     This behaves as for the corresponding option to the  com‐
4355                     padd  builtin.   It gives direct control over which file‐
4356                     names should be ignored.  If the option is  not  present,
4357                     the ignored-patterns style is used.
4358
4359              Both  _path_files  and  _files also accept the following options
4360              which are passed to compadd: `-J', `-V', `-1', `-2', `-n', `-X',
4361              `-M', `-P', `-S', `-q', `-r', and `-R'.
4362
4363              Finally,  the  _path_files  function   uses  the  styles expand,
4364              ambiguous, special-dirs, list-suffixes and  file-sort  described
4365              above.
4366
4367
4368       _pick_variant [ -b builtin-label ] [ -c command ] [ -r name ]
4369                     label=pattern ... label [ arg ... ]
4370              This  function is used to resolve situations where a single com‐
4371              mand name requires  more  than  one  type  of  handling,  either
4372              because  it has more than one variant or because there is a name
4373              clash between two different commands.
4374
4375              The command to run is taken from the first element of the  array
4376              words  unless this is overridden by the option -c.  This command
4377              is run and its output is compared with  a  series  of  patterns.
4378              Arguments  to  be  passed to the command can be specified at the
4379              end after all the other arguments.  The patterns to try in order
4380              are given by the arguments label=pattern; if the output of `com‐
4381              mand arg ...' contains pattern, then label is  selected  as  the
4382              label  for  the command variant.  If none of the patterns match,
4383              the final command label is selected and status 1 is returned.
4384
4385              If the `-b builtin-label' is given, the command is tested to see
4386              if  it  is  provided as a shell builtin, possibly autoloaded; if
4387              so, the label builtin-label is selected as  the  label  for  the
4388              variant.
4389
4390              If  the  `-r  name'  is given, the label picked is stored in the
4391              parameter named name.
4392
4393              The results are also  cached  in  the  _cmd_variant  associative
4394              array indexed by the name of the command run.
4395
4396       _regex_arguments name spec ...
4397              This function generates a completion function name which matches
4398              the specifications  specs,  a  set  of  regular  expressions  as
4399              described  below.   After running _regex_arguments, the function
4400              name should be called as a normal completion function.  The pat‐
4401              tern  to  be matched is given by the contents of the words array
4402              up to the current cursor  position  joined  together  with  null
4403              characters; no quotation is applied.
4404
4405              The  arguments  are grouped as sets of alternatives separated by
4406              `|', which are tried one after  the  other  until  one  matches.
4407              Each  alternative consists of a one or more specifications which
4408              are tried  left  to  right,  with  each  pattern  matched  being
4409              stripped  in  turn from the command line being tested, until all
4410              of the group succeeds or until one fails; in  the  latter  case,
4411              the  next  alternative is tried.  This structure can be repeated
4412              to arbitrary depth by using parentheses; matching proceeds  from
4413              inside to outside.
4414
4415              A  special  procedure  is  applied  if  no test succeeds but the
4416              remaining command line string contains no null character (imply‐
4417              ing  the  remaining word is the one for which completions are to
4418              be generated).  The  completion  target  is  restricted  to  the
4419              remaining  word  and  any actions for the corresponding patterns
4420              are executed.  In this case, nothing is stripped from  the  com‐
4421              mand line string.  The order of evaluation of the actions can be
4422              determined by the tag-order style; the various formats supported
4423              by  _alternative  can  be used in action.  The descr is used for
4424              setting up the array parameter expl.
4425
4426              Specification arguments take one of following  forms,  in  which
4427              metacharacters such as `(', `)', `#' and `|' should be quoted.
4428
4429              /pattern/ [%lookahead%] [-guard] [:tag:descr:action]
4430                     This is a single primitive component.  The function tests
4431                     whether  the  combined  pattern  `(#b)((#B)pattern)looka‐
4432                     head*'  matches  the command line string.  If so, `guard'
4433                     is evaluated and its return status is examined to  deter‐
4434                     mine  if the test has succeeded.  The pattern string `[]'
4435                     is guaranteed never  to  match.   The  lookahead  is  not
4436                     stripped from the command line before the next pattern is
4437                     examined.
4438
4439                     The argument starting with : is used in the  same  manner
4440                     as an argument to _alternative.
4441
4442                     A  component is used as follows: pattern is tested to see
4443                     if the component already exists on the command line.   If
4444                     it  does,  any  following  specifications are examined to
4445                     find something to complete.  If a  component  is  reached
4446                     but  no  such pattern exists yet on the command line, the
4447                     string containing the action is used to generate  matches
4448                     to insert at that point.
4449
4450              /pattern/+ [%lookahead%] [-guard] [:tag:descr:action]
4451                     This  is  similar to `/pattern/ ...' but the left part of
4452                     the command line string (i.e. the part already matched by
4453                     previous patterns) is also considered part of the comple‐
4454                     tion target.
4455
4456              /pattern/- [%lookahead%] [-guard] [:tag:descr:action]
4457                     This is similar to `/pattern/ ...' but the actions of the
4458                     current  and previously matched patterns are ignored even
4459                     if the following `pattern' matches the empty string.
4460
4461              ( spec )
4462                     Parentheses may be used to groups specs; note each paren‐
4463                     thesis is a single argument to _regex_arguments.
4464
4465              spec # This allows any number of repetitions of spec.
4466
4467              spec spec
4468                     The  two  specs  are to be matched one after the other as
4469                     described above.
4470
4471              spec | spec
4472                     Either of the two specs can be matched.
4473
4474              The function _regex_words can be used as a  helper  function  to
4475              generate  matches  for  a set of alternative words possibly with
4476              their own arguments as a command line argument.
4477
4478              Examples:
4479
4480                     _regex_arguments _tst /$'[^\0]#\0'/ \
4481                         /$'[^\0]#\0'/ :'compadd aaa'
4482
4483              This generates a function _tst that completes aaa  as  its  only
4484              argument.   The  tag  and  description  for the action have been
4485              omitted for brevity (this works but is not recommended in normal
4486              use).   The  first  component matches the command word, which is
4487              arbitrary; the second matches  any argument.  As the argument is
4488              also  arbitrary, any following component would not depend on aaa
4489              being present.
4490
4491                     _regex_arguments _tst /$'[^\0]#\0'/ \
4492                         /$'aaa\0'/ :'compadd aaa'
4493
4494              This is a more typical use; it is  similar,  but  any  following
4495              patterns  would only match if aaa was present as the first argu‐
4496              ment.
4497
4498                     _regex_arguments _tst /$'[^\0]#\0'/ \( \
4499                         /$'aaa\0'/ :'compadd aaa' \
4500                         /$'bbb\0'/ :'compadd bbb' \) \#
4501
4502              In this example, an indefinite number of command  arguments  may
4503              be completed.  Odd arguments are completed as aaa and even argu‐
4504              ments as bbb.  Completion fails unless the set of  aaa  and  bbb
4505              arguments before the current one is matched correctly.
4506
4507                     _regex_arguments _tst /$'[^\0]#\0'/ \
4508                         \( /$'aaa\0'/ :'compadd aaa' \| \
4509                         /$'bbb\0'/ :'compadd bbb' \) \#
4510
4511              This  is similar, but either aaa or bbb may be completed for any
4512              argument.  In this case _regex_words could be used to generate a
4513              suitable expression for the arguments.
4514
4515       _regex_words tag description spec ...
4516              This  function  can  be  used  to  generate  arguments  for  the
4517              _regex_arguments command which may  be  inserted  at  any  point
4518              where  a set of rules is expected.  The tag and description give
4519              a standard tag and description pertaining to  the  current  con‐
4520              text.   Each spec contains two or three arguments separated by a
4521              colon: note that there is no leading colon in this case.
4522
4523              Each spec gives one of a set of words that may be  completed  at
4524              this point, together with arguments.  It is thus roughly equiva‐
4525              lent to the _arguments function when used in normal  (non-regex)
4526              completion.
4527
4528              The  part  of  the spec before the first colon is the word to be
4529              completed.  This may contain a *; the entire  word,  before  and
4530              after  the  *  is  completed,  but only the text before the * is
4531              required for the context to be matched, so  that  further  argu‐
4532              ments may be completed after the abbreviated form.
4533
4534              The second part of spec is a description for the word being com‐
4535              pleted.
4536
4537              The optional third part of the spec describes how words  follow‐
4538              ing  the one being completed are themselves to be completed.  It
4539              will be evaluated in order to avoid problems with quoting.  This
4540              means  that  typically  it contains a reference to an array con‐
4541              taining previously generated regex arguments.
4542
4543              The option -t term specifies a terminator for the  word  instead
4544              of the usual space.  This is handled as an auto-removable suffix
4545              in the manner of the option -s sep to _values.
4546
4547              The result of the processing by _regex_words is  placed  in  the
4548              array reply, which should be made local to the calling function.
4549              If the set of words and arguments may be matched repeatedly, a #
4550              should be appended to the generated array at that point.
4551
4552              For example:
4553
4554                     local -a reply
4555                     _regex_words mydb-commands 'mydb commands' \
4556                       'add:add an entry to mydb:$mydb_add_cmds' \
4557                       'show:show entries in mydb'
4558                     _regex_arguments _mydb "$reply[@]"
4559                     _mydb "$@"
4560
4561              This  shows a completion function for a command mydb which takes
4562              two command arguments, add and show.  show takes  no  arguments,
4563              while  the  arguments  for  add have already been prepared in an
4564              array mydb_add_cmds,  quite  possibly  by  a  previous  call  to
4565              _regex_words.
4566
4567       _requested [ -x ] [ -12VJ ] tag [ name descr [ command [ arg ... ] ]
4568              This  function  is called to decide whether a tag already regis‐
4569              tered by a call to _tags (see below) has been requested  by  the
4570              user  and  hence  completion  should  be  performed  for it.  It
4571              returns status zero if the tag is requested and non-zero  other‐
4572              wise.   The  function  is  typically used as part of a loop over
4573              different tags as follows:
4574
4575                     _tags foo bar baz
4576                     while _tags; do
4577                       if _requested foo; then
4578                         ... # perform completion for foo
4579                       fi
4580                       ... # test the tags bar and baz in the same way
4581                       ... # exit loop if matches were generated
4582                     done
4583
4584              Note that the test for whether matches  were  generated  is  not
4585              performed  until the end of the _tags loop.  This is so that the
4586              user can set the tag-order style to specify a set of tags to  be
4587              completed at the same time.
4588
4589              If  name  and descr are given, _requested calls the _description
4590              function with these arguments together with the  options  passed
4591              to _requested.
4592
4593              If  command  is  given,  the _all_labels function will be called
4594              immediately with the same arguments.  In simple cases this makes
4595              it  possible to perform the test for the tag and the matching in
4596              one go.  For example:
4597
4598                     local expl ret=1
4599                     _tags foo bar baz
4600                     while _tags; do
4601                       _requested foo expl 'description' \
4602                           compadd foobar foobaz && ret=0
4603                       ...
4604                       (( ret )) || break
4605                     done
4606
4607              If the command is not compadd, it must nevertheless be  prepared
4608              to handle the same options.
4609
4610       _retrieve_cache cache_identifier
4611              This  function  retrieves  completion  information from the file
4612              given by cache_identifier, stored in a  directory  specified  by
4613              the  cache-path  style  which  defaults  to  ~/.zcompcache.  The
4614              return status is zero if retrieval was successful.  It will only
4615              attempt retrieval if the use-cache style is set, so you can call
4616              this function without worrying about whether the user wanted  to
4617              use the caching layer.
4618
4619              See _store_cache below for more details.
4620
4621       _sep_parts
4622              This  function  is  passed  alternating arrays and separators as
4623              arguments.  The arrays specify completions for parts of  strings
4624              to  be separated by the separators.  The arrays may be the names
4625              of array parameters or a quoted list of  words  in  parentheses.
4626              For   example,  with  the  array  `hosts=(ftp  news)'  the  call
4627              `_sep_parts '(foo bar)' @ hosts' will complete the  string   `f'
4628              to `foo' and the string `b@n' to `bar@news'.
4629
4630              This  function  accepts  the  compadd  options `-V', `-J', `-1',
4631              `-2', `-n', `-X', `-M', `-P', `-S', `-r',  `-R',  and  `-q'  and
4632              passes them on to the compadd builtin used to add the matches.
4633
4634       _sequence [ -s sep ] [ -n max ] [ -d ] function [ - ] ...
4635              This  function  is  a  wrapper to other functions for completing
4636              items in a separated list. The same function is used to complete
4637              each  item  in  the list. The separator is specified with the -s
4638              option. If -s is omitted it will use `,'. Duplicate  values  are
4639              not matched unless -d is specified. If there is a fixed or maxi‐
4640              mum number of items in the list, this can be specified with  the
4641              -n option.
4642
4643              Common compadd options are passed on to the function. It is pos‐
4644              sible to use compadd directly with _sequence, though _values may
4645              be more appropriate in this situation.
4646
4647       _setup tag [ group ]
4648              This function sets up the special parameters used by the comple‐
4649              tion system appropriately for the tag given as the  first  argu‐
4650              ment.     It   uses   the   styles   list-colors,   list-packed,
4651              list-rows-first, last-prompt, accept-exact, menu and force-list.
4652
4653              The optional group supplies the name of the group in  which  the
4654              matches  will be placed.  If it is not given, the tag is used as
4655              the group name.
4656
4657              This function is  called  automatically  from  _description  and
4658              hence is not normally called explicitly.
4659
4660       _store_cache cache_identifier param ...
4661              This function, together with _retrieve_cache and _cache_invalid,
4662              implements a caching layer which can be used in  any  completion
4663              function.   Data  obtained  by  costly  operations are stored in
4664              parameters; this function then dumps the values of those parame‐
4665              ters  to  a  file.   The data can then be retrieved quickly from
4666              that file via _retrieve_cache, even in  different  instances  of
4667              the shell.
4668
4669              The cache_identifier specifies the file which the data should be
4670              dumped to.  The file is stored in a directory specified  by  the
4671              cache-path style which defaults to ~/.zcompcache.  The remaining
4672              params arguments are the parameters to dump to the file.
4673
4674              The return status is zero if storage was successful.  The  func‐
4675              tion will only attempt storage if the use-cache style is set, so
4676              you can call this function without worrying  about  whether  the
4677              user wanted to use the caching layer.
4678
4679              The  completion  function may avoid calling _retrieve_cache when
4680              it already has the  completion  data  available  as  parameters.
4681              However,  in  that  case  it should call _cache_invalid to check
4682              whether the data in the parameters and in the  cache  are  still
4683              valid.
4684
4685              See  the  _perl_modules completion function for a simple example
4686              of the usage of the caching layer.
4687
4688       _tags [ [ -C name ] tag ... ]
4689              If called with arguments, these are taken to  be  the  names  of
4690              tags  valid  for completions in the current context.  These tags
4691              are stored internally and sorted by using the tag-order style.
4692
4693              Next, _tags is called repeatedly without arguments from the same
4694              completion  function.  This successively selects the first, sec‐
4695              ond, etc. set of tags requested by the user.  The return  status
4696              is  zero  if  at least one of the tags is requested and non-zero
4697              otherwise.  To test if a particular tag  is  to  be  tried,  the
4698              _requested function should be called (see above).
4699
4700              If  `-C  name' is given, name is temporarily stored in the argu‐
4701              ment field (the fifth) of the context in the curcontext  parame‐
4702              ter  during  the  call  to _tags; the field is restored on exit.
4703              This allows _tags to use a more specific context without  having
4704              to change and reset the curcontext parameter (which has the same
4705              effect).
4706
4707       _tilde_files
4708              Like _files, but resolve leading tildes according to  the  rules
4709              of  filename expansion, so the suggested completions don't start
4710              with a `~' even if the filename on the command-line does.
4711
4712       _values [ -O name ] [ -s sep ] [ -S sep ] [ -wC ] desc spec ...
4713              This is used to complete arbitrary keywords (values)  and  their
4714              arguments, or lists of such combinations.
4715
4716              If  the  first argument is the option `-O name', it will be used
4717              in the same way as by the _arguments function.  In other  words,
4718              the  elements  of  the name array will be passed to compadd when
4719              executing an action.
4720
4721              If the first argument (or the first argument after `-O name') is
4722              `-s',  the next argument is used as the character that separates
4723              multiple values.  This character is  automatically  added  after
4724              each  value in an auto-removable fashion (see below); all values
4725              completed by `_values -s' appear in the same word on the command
4726              line, unlike completion using _arguments.  If this option is not
4727              present, only a single value will be completed per word.
4728
4729              Normally, _values will only use the current  word  to  determine
4730              which  values  are already present on the command line and hence
4731              are not to be completed again.  If the -w option is given, other
4732              arguments are examined as well.
4733
4734              The  first non-option argument is used as a string to print as a
4735              description before listing the values.
4736
4737              All other arguments describe the possible values and their argu‐
4738              ments  in the same format used for the description of options by
4739              the _arguments function (see above).  The only  differences  are
4740              that  no minus or plus sign is required at the beginning, values
4741              can have only one argument, and the forms  of  action  beginning
4742              with an equal sign are not supported.
4743
4744              The  character  separating  a value from its argument can be set
4745              using the option -S (like -s, followed by the character  to  use
4746              as  the  separator in the next argument).  By default the equals
4747              sign will be used as the separator between values and arguments.
4748
4749              Example:
4750
4751                     _values -s , 'description' \
4752                             '*foo[bar]' \
4753                             '(two)*one[number]:first count:' \
4754                             'two[another number]::second count:(1 2 3)'
4755
4756              This describes three possible values: `foo', `one',  and  `two'.
4757              The  first  is  described  as  `bar',  takes no argument and may
4758              appear more than once.  The second is described as `number', may
4759              appear   more  than  once,  and  takes  one  mandatory  argument
4760              described as `first count'; no action is specified, so  it  will
4761              not be completed.  The `(two)' at the beginning says that if the
4762              value `one' is on the line, the value `two' will  no  longer  be
4763              considered  a  possible  completion.   Finally,  the  last value
4764              (`two') is described as `another number' and takes  an  optional
4765              argument  described  as `second count' for which the completions
4766              (to appear after an `=') are `1', `2',  and  `3'.   The  _values
4767              function  will  complete lists of these values separated by com‐
4768              mas.
4769
4770              Like _arguments, this function temporarily adds another  context
4771              name  component to the arguments element (the fifth) of the cur‐
4772              rent context while executing the action.  Here this name is just
4773              the name of the value for which the argument is completed.
4774
4775              The  style verbose is used to decide if the descriptions for the
4776              values (but not those for the arguments) should be printed.
4777
4778              The associative array val_args is  used  to  report  values  and
4779              their  arguments;  this works similarly to the opt_args associa‐
4780              tive array used by _arguments.  Hence the function calling _val‐
4781              ues  should  declare  the  local  parameters state, state_descr,
4782              line, context and val_args:
4783
4784                     local context state state_descr line
4785                     typeset -A val_args
4786
4787              when using an action of the form `->string'.  With this function
4788              the context parameter will be set to the name of the value whose
4789              argument is to be completed.  Note that for _values,  the  state
4790              and  state_descr  are scalars rather than arrays.  Only a single
4791              matching state is returned.
4792
4793              Note also that _values normally adds the character used  as  the
4794              separator between values as an auto-removable suffix (similar to
4795              a `/' after a directory).  However, this is not possible  for  a
4796              `->string'  action as the matches for the argument are generated
4797              by the calling function.  To get the usual behaviour, the  call‐
4798              ing  function can add the separator x as a suffix by passing the
4799              options `-qS x' either directly or indirectly to compadd.
4800
4801              The option -C is treated in the same way as it is by _arguments.
4802              In  that  case  the  parameter  curcontext  should be made local
4803              instead of context (as described above).
4804
4805       _wanted [ -x ] [ -C name ]  [ -12VJ ] tag name descr command [ arg ...]
4806              In many contexts, completion can only  generate  one  particular
4807              set of matches, usually corresponding to a single tag.  However,
4808              it is still  necessary  to  decide  whether  the  user  requires
4809              matches of this type.  This function is useful in such a case.
4810
4811              The  arguments  to  _wanted are the same as those to _requested,
4812              i.e. arguments to be passed to _description.  However,  in  this
4813              case  the  command is not optional;  all the processing of tags,
4814              including the loop over both tags and tag labels and the genera‐
4815              tion of matches, is carried out automatically by _wanted.
4816
4817              Hence  to offer only one tag and immediately add the correspond‐
4818              ing matches with the given description:
4819
4820                     local expl
4821                     _wanted tag expl 'description' \
4822                         compadd matches...
4823
4824              Note that, as for _requested, the command must be able to accept
4825              options to be passed down to compadd.
4826
4827              Like  _tags  this function supports the -C option to give a dif‐
4828              ferent name for the argument context field.  The -x  option  has
4829              the same meaning as for _description.
4830
4831       _widgets [ -g pattern ]
4832              This  function  completes  names of zle widgets (see the section
4833              `Widgets' in zshzle(1)).  The pattern, if  present,  is  matched
4834              against  values of the $widgets special parameter, documented in
4835              the section `The zsh/zleparameter Module' in zshmodules(1).
4836

COMPLETION SYSTEM VARIABLES

4838       There are some standard variables, initialised  by  the  _main_complete
4839       function and then used from other functions.
4840
4841       The standard variables are:
4842
4843       _comp_caller_options
4844              The  completion  system  uses setopt to set a number of options.
4845              This allows functions to be written without concern for compati‐
4846              bility with every possible combination of user options. However,
4847              sometimes completion needs to know what the user's option  pref‐
4848              erences  are.  These are saved in the _comp_caller_options asso‐
4849              ciative array. Option names, spelled in lowercase without under‐
4850              scores,  are  mapped  to  one  or  other of the strings `on' and
4851              `off'.
4852
4853              _comp_priv_prefix
4854                     Completion  functions  such  as   _sudo   can   set   the
4855                     _comp_priv_prefix array to a command prefix that may then
4856                     be used by _call_program to  match  the  privileges  when
4857                     calling programs to generate matches.
4858
4859              Two  more  features  are offered by the _main_complete function.
4860              The arrays compprefuncs and comppostfuncs may contain  names  of
4861              functions that are to be called immediately before or after com‐
4862              pletion has been tried.  A function will  only  be  called  once
4863              unless it explicitly reinserts itself into the array.
4864

COMPLETION DIRECTORIES

4866       In  the  source distribution, the files are contained in various subdi‐
4867       rectories of the Completion directory.  They may have been installed in
4868       the same structure, or into one single function directory.  The follow‐
4869       ing is a description of the  files  found  in  the  original  directory
4870       structure.   If  you  wish to alter an installed file, you will need to
4871       copy it to some directory which appears earlier in your fpath than  the
4872       standard directory where it appears.
4873
4874       Base   The  core functions and special completion widgets automatically
4875              bound to keys.  You will certainly need most  of  these,  though
4876              will  probably  not need to alter them.  Many of these are docu‐
4877              mented above.
4878
4879       Zsh    Functions for completing arguments of shell builtin commands and
4880              utility  functions  for  this.   Some  of these are also used by
4881              functions from the Unix directory.
4882
4883       Unix   Functions for completing  arguments  of  external  commands  and
4884              suites  of  commands.   They may need modifying for your system,
4885              although in many cases some attempt is made to decide which ver‐
4886              sion  of  a command is present.  For example, completion for the
4887              mount command tries to determine the system it  is  running  on,
4888              while  completion for many other utilities try to decide whether
4889              the GNU version of the command is in use, and hence whether  the
4890              --help option is supported.
4891
4892       X, AIX, BSD, ...
4893              Completion  and  utility function for commands available only on
4894              some systems.  These are not arranged  hierarchically,  so,  for
4895              example, both the Linux and Debian directories, as well as the X
4896              directory, may be useful on your system.
4897
4898
4899
4900zsh 5.6.2                     September 14, 2018                 ZSHCOMPSYS(1)
Impressum