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 is to the path: this allows the functions to  be  in
200       the 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 names... [ -[pP] patterns... [ -N names... ] ]
211              The  file  will be made autoloadable and the function defined in
212              it will be called when completing names, each of which is either
213              the name of a command whose arguments are to be completed or one
214              of a number of special contexts in the form -context-  described
215              below.
216
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-sequences...
240              This  option  creates  a widget behaving like the builtin widget
241              style and binds it to the  given  key-sequences,  if  any.   The
242              style  must  be  one of the builtin widgets that perform comple‐
243              tion, namely complete-word, delete-char-or-list,  expand-or-com‐
244              plete,  expand-or-complete-prefix,  list-choices, menu-complete,
245              menu-expand-or-complete,  or  reverse-menu-complete.    If   the
246              zsh/complist  module  is  loaded  (see zshmodules(1)) the widget
247              menu-select is also available.
248
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-sequences ...
257              This  is  similar to -k except that only one key-sequences argu‐
258              ment may be given for each widget-name style pair.  However, the
259              entire  set  of three arguments may be repeated with a different
260              set of arguments.  Note in particular that the widget-name  must
261              be  distinct  in  each  set.  If it does not begin with `_' this
262              will be added.  The widget-name should not clash with  the  name
263              of  any existing widget: names based on the name of the function
264              are most useful.  For example,
265
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 (`foo=(...)')
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
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.  In the case of elements of an associa‐
353       tive array,  for  example  `assoc=(key  <TAB>',  name  is  expanded  to
354       `name-key'.   In  certain  special  contexts,  such as completing after
355       `make CFLAGS=', the command part gives the name of  the  command,  here
356       make; otherwise it is empty.
357
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 names... [ -[pP] patterns... [ -N names... ]
394       ]
395       compdef -d names...
396       compdef -k [ -an ] function style key-sequences...
397       compdef -K [ -an ] function name style key-sequences ...
398              The first form defines the function to call  for  completion  in
399              the given contexts as described for the #compdef tag above.
400
401              Alternatively,  all  the  arguments  may have the form `cmd=ser‐
402              vice'.   Here  service  should  already  have  been  defined  by
403              `cmd1=service' lines in #compdef files, as described above.  The
404              argument for cmd will be completed in the same way as service.
405
406              The function argument may alternatively be a  string  containing
407              almost  any  shell  code.  If the string contains an equal sign,
408              the above will take precedence.  The option -e may  be  used  to
409              specify the first argument is to be evaluated as shell code even
410              if it contains an equal sign.  The string will be executed using
411              the eval builtin command to generate completions.  This provides
412              a way of avoiding having to define a  new  completion  function.
413              For  example,  to  complete files ending in `.h' as arguments to
414              the command foo:
415
416                     compdef '_files -g "*.h"' foo
417
418              The option -n prevents any completions already defined  for  the
419              command or context from being overwritten.
420
421              The  option -d deletes any completion defined for the command or
422              contexts listed.
423
424              The names may also contain -p, -P and -N  options  as  described
425              for  the #compdef tag.  The effect on the argument list is iden‐
426              tical, switching between  definitions  of  patterns  tried  ini‐
427              tially,  patterns  tried  finally,  and normal commands and con‐
428              texts.
429
430              The parameter $_compskip may be set by any function defined  for
431              a  pattern context.  If it is set to a value containing the sub‐
432              string `patterns' none of the pattern-functions will be  called;
433              if it is set to a value containing the substring `all', no other
434              function will be called.
435
436              The form with -k defines a widget with  the  same  name  as  the
437              function that will be called for each of the key-sequences; this
438              is like the #compdef -k tag.  The function should  generate  the
439              completions  needed  and  will otherwise behave like the builtin
440              widget whose name is given as the style argument.   The  widgets
441              usable   for   this   are:  complete-word,  delete-char-or-list,
442              expand-or-complete,   expand-or-complete-prefix,   list-choices,
443              menu-complete,  menu-expand-or-complete,  and  reverse-menu-com‐
444              plete, as well as menu-select  if  the  zsh/complist  module  is
445              loaded.   The  option  -n  prevents the key being bound if it is
446              already to bound to something other than undefined-key.
447
448              The form with -K is similar and defines multiple  widgets  based
449              on  the  same  function, each of which requires the set of three
450              arguments name, style and key-sequences, where  the  latter  two
451              are  as for -k and the first must be a unique widget name begin‐
452              ning with an underscore.
453
454              Wherever applicable, the -a option makes the function  autoload‐
455              able, equivalent to autoload -U function.
456
457       The function compdef can be used to associate existing completion func‐
458       tions with new commands.  For example,
459
460              compdef _pids foo
461
462       uses the function _pids to complete process IDs for the command foo.
463
464       Note also the _gnu_generic function described below, which can be  used
465       to complete options for commands that understand the `--help' option.
466

COMPLETION SYSTEM CONFIGURATION

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

CONTROL FUNCTIONS

2506       The initialization script compinit redefines all the widgets which per‐
2507       form  completion  to  call the supplied widget function _main_complete.
2508       This function acts as a wrapper calling the so-called `completer' func‐
2509       tions  that  generate  matches.  If _main_complete is called with argu‐
2510       ments, these are taken as the names of completer functions to be called
2511       in the order given.  If no arguments are given, the set of functions to
2512       try is taken from the completer style.  For example, to use normal com‐
2513       pletion and correction if that doesn't generate any matches:
2514
2515              zstyle ':completion:*' completer _complete _correct
2516
2517       after  calling compinit. The default value for this style is `_complete
2518       _ignored', i.e. normally only ordinary completion is tried, first  with
2519       the  effect  of  the  ignored-patterns  style and then without it.  The
2520       _main_complete function uses the return status of the  completer  func‐
2521       tions  to  decide  if other completers should be called.  If the return
2522       status is zero, no other completers are tried  and  the  _main_complete
2523       function returns.
2524
2525       If  the  first argument to _main_complete is a single hyphen, the argu‐
2526       ments will not be taken as names of completers.   Instead,  the  second
2527       argument  gives a name to use in the completer field of the context and
2528       the other arguments give a command name and arguments to call to gener‐
2529       ate the matches.
2530
2531       The  following  completer  functions are contained in the distribution,
2532       although users may write their own.  Note that in contexts the  leading
2533       underscore  is  stripped,  for example basic completion is performed in
2534       the context `:completion::complete:...'.
2535
2536       _all_matches
2537              This completer can be used to add a  string  consisting  of  all
2538              other matches.  As it influences later completers it must appear
2539              as the first completer in the list.  The list of all matches  is
2540              affected by the avoid-completer and old-matches styles described
2541              above.
2542
2543              It may be useful to use the _generic function described below to
2544              bind _all_matches to its own keystroke, for example:
2545
2546                     zle -C all-matches complete-word _generic
2547                     bindkey '^Xa' all-matches
2548                     zstyle ':completion:all-matches:*' old-matches only
2549                     zstyle ':completion:all-matches::::' completer _all_matches
2550
2551              Note  that  this does not generate completions by itself:  first
2552              use any of the standard ways of generating  a  list  of  comple‐
2553              tions, then use ^Xa to show all matches.  It is possible instead
2554              to add a standard completer to the list  and  request  that  the
2555              list of all matches should be directly inserted:
2556
2557                     zstyle ':completion:all-matches::::' completer _all_matches _complete
2558                     zstyle ':completion:all-matches:*' insert true
2559
2560              In this case the old-matches style should not be set.
2561
2562       _approximate
2563              This  is similar to the basic _complete completer but allows the
2564              completions to  undergo  corrections.   The  maximum  number  of
2565              errors  can  be  specified  by  the  max-errors  style;  see the
2566              description of approximate matching in zshexpn(1) for how errors
2567              are  counted.   Normally this completer will only be tried after
2568              the normal _complete completer:
2569
2570                     zstyle ':completion:*' completer _complete _approximate
2571
2572              This will give correcting completion if and only if normal  com‐
2573              pletion  yields no possible completions.  When corrected comple‐
2574              tions are found, the completer will normally start menu  comple‐
2575              tion allowing you to cycle through these strings.
2576
2577              This  completer uses the tags corrections and original when gen‐
2578              erating the possible corrections and the original  string.   The
2579              format style for the former may contain the additional sequences
2580              `%e' and `%o' which will be replaced by  the  number  of  errors
2581              accepted  to  generate  the corrections and the original string,
2582              respectively.
2583
2584              The completer  progressively  increases  the  number  of  errors
2585              allowed up to the limit by the max-errors style, hence if a com‐
2586              pletion is found with one error, no completions with two  errors
2587              will be shown, and so on.  It modifies the completer name in the
2588              context to indicate the number of errors  being  tried:  on  the
2589              first  try  the completer field contains `approximate-1', on the
2590              second try `approximate-2', and so on.
2591
2592              When _approximate is called from another function, the number of
2593              errors to accept may be passed with the -a option.  The argument
2594              is in the same format  as  the  max-errors  style,  all  in  one
2595              string.
2596
2597              Note  that  this completer (and the _correct completer mentioned
2598              below) can be quite expensive to call, especially when  a  large
2599              number  of  errors are allowed.  One way to avoid this is to set
2600              up the completer style using the -e option  to  zstyle  so  that
2601              some  completers  are  only  used when completion is attempted a
2602              second time on the same string, e.g.:
2603
2604                     zstyle -e ':completion:*' completer '
2605                       if [[ $_last_try != "$HISTNO$BUFFER$CURSOR" ]]; then
2606                         _last_try="$HISTNO$BUFFER$CURSOR"
2607                         reply=(_complete _match _prefix)
2608                       else
2609                         reply=(_ignored _correct _approximate)
2610                       fi'
2611
2612              This uses the HISTNO parameter and the BUFFER and CURSOR special
2613              parameters  that are available inside zle and completion widgets
2614              to find out if the command line hasn't changed  since  the  last
2615              time completion was tried.  Only then are the _ignored, _correct
2616              and _approximate completers called.
2617
2618       _complete
2619              This completer generates all  possible  completions  in  a  con‐
2620              text-sensitive  manner, i.e. using the settings defined with the
2621              compdef function explained above and the current settings of all
2622              special parameters.  This gives the normal completion behaviour.
2623
2624              To  complete  arguments  of commands, _complete uses the utility
2625              function _normal, which is in turn responsible for  finding  the
2626              particular function; it is described below.  Various contexts of
2627              the form -context- are handled specifically. These are all  men‐
2628              tioned above as possible arguments to the #compdef tag.
2629
2630              Before  trying  to find a function for a specific context, _com‐
2631              plete checks if the  parameter  `compcontext'  is  set.  Setting
2632              `compcontext'  allows  the  usual  completion  dispatching to be
2633              overridden which is useful in places such  as  a  function  that
2634              uses vared for input. If it is set to an array, the elements are
2635              taken to be the possible matches which will be  completed  using
2636              the tag `values' and the description `value'. If it is set to an
2637              associative array, the keys are used as the possible completions
2638              and  the  values (if non-empty) are used as descriptions for the
2639              matches.  If `compcontext' is set to a string containing colons,
2640              it  should  be of the form `tag:descr:action'.  In this case the
2641              tag and descr give the tag and description to use and the action
2642              indicates  what should be completed in one of the forms accepted
2643              by the _arguments utility function described below.
2644
2645              Finally, if `compcontext' is set to a string without colons, the
2646              value  is  taken as the name of the context to use and the func‐
2647              tion defined for that context will be called.  For this purpose,
2648              there  is  a special context named -command-line- that completes
2649              whole command lines (commands and their arguments).  This is not
2650              used  by the completion system itself but is nonetheless handled
2651              when explicitly called.
2652
2653       _correct
2654              Generate corrections, but not completions, for the current word;
2655              this is similar to _approximate but will not allow any number of
2656              extra characters at the cursor  as  that  completer  does.   The
2657              effect  is  similar to spell-checking.  It is based on _approxi‐
2658              mate, but the completer field in the context name is correct.
2659
2660              For example, with:
2661
2662                     zstyle ':completion:::::' completer _complete _correct _approximate
2663                     zstyle ':completion:*:correct:::' max-errors 2 not-numeric
2664                     zstyle ':completion:*:approximate:::' max-errors 3 numeric
2665
2666              correction will accept up to two errors.  If a numeric  argument
2667              is  given, correction will not be performed, but correcting com‐
2668              pletion will be, and will accept as many errors as given by  the
2669              numeric  argument.  Without a numeric argument, first correction
2670              and then correcting completion will be tried, with the first one
2671              accepting two errors and the second one accepting three errors.
2672
2673              When  _correct  is called as a function, the number of errors to
2674              accept may be given following the -a option.  The argument is in
2675              the same form a values to the accept style, all in one string.
2676
2677              This  completer  function  is  intended  to  be used without the
2678              _approximate completer or, as in the example,  just  before  it.
2679              Using  it  after  the  _approximate  completer  is useless since
2680              _approximate will at least generate the corrected strings gener‐
2681              ated by the _correct completer -- and probably more.
2682
2683       _expand
2684              This  completer function does not really perform completion, but
2685              instead checks if the word on the command line is  eligible  for
2686              expansion  and,  if  it is, gives detailed control over how this
2687              expansion is done.  For this to happen,  the  completion  system
2688              needs  to  be invoked with complete-word, not expand-or-complete
2689              (the default binding for TAB), as otherwise the string  will  be
2690              expanded by the shell's internal mechanism before the completion
2691              system is started.  Note also this completer  should  be  called
2692              before the _complete completer function.
2693
2694              The  tags used when generating expansions are all-expansions for
2695              the string containing all possible expansions,  expansions  when
2696              adding  the  possible  expansions as single matches and original
2697              when adding the original string from the  line.   The  order  in
2698              which  these strings are generated, if at all, can be controlled
2699              by the group-order and tag-order styles, as usual.
2700
2701              The format string for all-expansions and for expansions may con‐
2702              tain  the  sequence  `%o' which will be replaced by the original
2703              string from the line.
2704
2705              The kind of expansion to be tried is controlled by  the  substi‐
2706              tute, glob and subst-globs-only styles.
2707
2708              It is also possible to call _expand as a function, in which case
2709              the different modes may be selected with options: -s for substi‐
2710              tute, -g for glob and -o for subst-globs-only.
2711
2712       _expand_alias
2713              If  the word the cursor is on is an alias, it is expanded and no
2714              other completers are called.  The types of aliases which are  to
2715              be  expanded  can  be controlled with the styles regular, global
2716              and disabled.
2717
2718              This function is also a bindable command, see the section `Bind‐
2719              able Commands' below.
2720
2721       _history
2722              Complete  words  from  the  shell's command  history.  This com‐
2723              pleter can be controlled by the remove-all-dups, and sort styles
2724              as for the _history_complete_word bindable command, see the sec‐
2725              tion `Bindable Commands' below and the section `Completion  Sys‐
2726              tem Configuration' above.
2727
2728       _ignored
2729              The  ignored-patterns  style  can  be  set to a list of patterns
2730              which are compared against possible completions;  matching  ones
2731              are  removed.   With  this  completer those matches can be rein‐
2732              stated, as if no ignored-patterns style were set.  The completer
2733              actually generates its own list of matches; which completers are
2734              invoked is determined in the same way as for  the  _prefix  com‐
2735              pleter.  The single-ignored style is also available as described
2736              above.
2737
2738       _list  This completer allows the insertion of  matches  to  be  delayed
2739              until  completion is attempted a second time without the word on
2740              the line being changed.  On the first attempt, only the list  of
2741              matches  will  be shown.  It is affected by the styles condition
2742              and word, see  the  section  `Completion  System  Configuration'
2743              above.
2744
2745       _match This  completer  is intended to be used after the _complete com‐
2746              pleter.  It behaves similarly but the string on the command line
2747              may be a pattern to match against trial completions.  This gives
2748              the effect of the GLOB_COMPLETE option.
2749
2750              Normally completion will be performed by taking the pattern from
2751              the  line,  inserting a `*' at the cursor position and comparing
2752              the resulting pattern with the possible  completions  generated.
2753              This  can  be  modified  with the match-original style described
2754              above.
2755
2756              The generated matches will  be  offered  in  a  menu  completion
2757              unless  the  insert-unambiguous  style is set to `true'; see the
2758              description above for other options for this style.
2759
2760              Note that matcher specifications defined globally or used by the
2761              completion  functions (the styles matcher-list and matcher) will
2762              not be used.
2763
2764       _menu  This completer was written as simple example  function  to  show
2765              how  menu  completion  can be enabled in shell code. However, it
2766              has the notable effect of disabling menu selection which can  be
2767              useful  with  _generic  based  widgets. It should be used as the
2768              first completer in the list.  Note that this is  independent  of
2769              the  setting  of the MENU_COMPLETE option and does not work with
2770              the other menu completion widgets such as reverse-menu-complete,
2771              or accept-and-menu-complete.
2772
2773       _oldlist
2774              This  completer  controls  how  the  standard completion widgets
2775              behave when there is an existing list of completions  which  may
2776              have  been  generated  by  a  special  completion  (i.e. a sepa‐
2777              rately-bound completion command).  It allows the  ordinary  com‐
2778              pletion  keys  to  continue  to use the list of completions thus
2779              generated, instead of producing a new list of  ordinary  contex‐
2780              tual  completions.   It  should appear in the list of completers
2781              before any of the widgets which generate matches.  It  uses  two
2782              styles:  old-list and old-menu, see the section `Completion Sys‐
2783              tem Configuration' above.
2784
2785       _prefix
2786              This completer can be used to try  completion  with  the  suffix
2787              (everything after the cursor) ignored.  In other words, the suf‐
2788              fix will not be considered to be part of the word  to  complete.
2789              The effect is similar to the expand-or-complete-prefix command.
2790
2791              The completer style is used to decide which other completers are
2792              to be called to generate matches.  If this style is  unset,  the
2793              list  of  completers  set  for  the  current  context is used --
2794              except, of course, the _prefix completer  itself.   Furthermore,
2795              if  this  completer  appears  more than once in the list of com‐
2796              pleters only those completers not  already  tried  by  the  last
2797              invocation of _prefix will be called.
2798
2799              For example, consider this global completer style:
2800
2801                     zstyle ':completion:*' completer \
2802                         _complete _prefix _correct _prefix:foo
2803
2804              Here, the _prefix completer tries normal completion but ignoring
2805              the suffix.  If that doesn't generate any matches,  and  neither
2806              does  the  call to the _correct completer after it, _prefix will
2807              be called a second time and, now only trying correction with the
2808              suffix  ignored.  On the second invocation the completer part of
2809              the context appears as `foo'.
2810
2811              To use _prefix as the last resort and try only normal completion
2812              when it is invoked:
2813
2814                     zstyle ':completion:*' completer _complete ... _prefix
2815                     zstyle ':completion::prefix:*' completer _complete
2816
2817              The  add-space  style is also respected.  If it is set to `true'
2818              then _prefix will insert a space between the  matches  generated
2819              (if any) and the suffix.
2820
2821              Note  that this completer is only useful if the COMPLETE_IN_WORD
2822              option is set; otherwise, the cursor will be moved to the end of
2823              the  current word before the completion code is called and hence
2824              there will be no suffix.
2825
2826       _user_expand
2827              This completer behaves similarly to the  _expand  completer  but
2828              instead  performs  expansions  defined  by  users.   The  styles
2829              add-space and sort styles specific to the _expand completer  are
2830              usable  with  _user_expand  in  addition to other styles handled
2831              more generally by the completion system.  The tag all-expansions
2832              is also available.
2833
2834              The  expansion  depends  on  the  array  style user-expand being
2835              defined for the current context; remember that the  context  for
2836              completers  is less specific than that for contextual completion
2837              as the full context has not yet been  determined.   Elements  of
2838              the array may have one of the following forms:
2839              $hash
2840
2841                     hash  is  the name of an associative array.  Note this is
2842                     not a full parameter expression,  merely  a  $,  suitably
2843                     quoted  to  prevent  immediate expansion, followed by the
2844                     name of an associative array.   If  the  trial  expansion
2845                     word  matches  a  key in hash, the resulting expansion is
2846                     the corresponding value.
2847              _func
2848
2849                     _func is the name of a shell  function  whose  name  must
2850                     begin  with _ but is not otherwise special to the comple‐
2851                     tion system.  The function is called with the trial  word
2852                     as an argument.  If the word is to be expanded, the func‐
2853                     tion should set the array reply to a list of  expansions.
2854                     Optionally,  it can set REPLY to a word that will be used
2855                     as a description for the set of expansions.   The  return
2856                     status of the function is irrelevant.

BINDABLE COMMANDS

2858       In  addition  to  the context-dependent completions provided, which are
2859       expected to work in an intuitively obvious way, there are a few widgets
2860       implementing  special  behaviour which can be bound separately to keys.
2861       The following is a list of these and their default bindings.
2862
2863       _bash_completions
2864              This function is used by two  widgets,  _bash_complete-word  and
2865              _bash_list-choices.   It  exists  to  provide compatibility with
2866              completion bindings in bash.  The last character of the  binding
2867              determines  what is completed: `!', command names; `$', environ‐
2868              ment variables; `@', host  names;  `/',  file  names;  `~'  user
2869              names.   In bash, the binding preceded by `\e' gives completion,
2870              and preceded by `^X' lists options.  As some of  these  bindings
2871              clash with standard zsh bindings, only `\e~' and `^X~' are bound
2872              by default.  To add the rest, the following should be  added  to
2873              .zshrc after compinit has been run:
2874
2875                     for key in '!' '$' '@' '/' '~'; do
2876                       bindkey "\e$key" _bash_complete-word
2877                       bindkey "^X$key" _bash_list-choices
2878                     done
2879
2880              This  includes  the  bindings  for `~' in case they were already
2881              bound to something else; the completion code does  not  override
2882              user bindings.
2883
2884       _correct_filename (^XC)
2885              Correct  the filename path at the cursor position.  Allows up to
2886              six errors in the name.  Can also be called with an argument  to
2887              correct a filename path, independently of zle; the correction is
2888              printed on standard output.
2889
2890       _correct_word (^Xc)
2891              Performs correction of the current argument using the usual con‐
2892              textual  completions as possible choices. This stores the string
2893              `correct-word' in the function field of  the  context  name  and
2894              then calls the _correct completer.
2895
2896       _expand_alias (^Xa)
2897              This  function can be used as a completer and as a bindable com‐
2898              mand.  It expands the word the cursor is on if it is  an  alias.
2899              The  types  of  alias expanded can be controlled with the styles
2900              regular, global and disabled.
2901
2902              When used as a bindable command there is one additional  feature
2903              that  can  be  selected by setting the complete style to `true'.
2904              In this case,  if  the  word  is  not  the  name  of  an  alias,
2905              _expand_alias  tries  to  complete the word to a full alias name
2906              without expanding it.  It leaves the cursor directly  after  the
2907              completed  word  so  that  invoking _expand_alias once more will
2908              expand the now-complete alias name.
2909
2910       _expand_word (^Xe)
2911              Performs expansion on the current word:  equivalent to the stan‐
2912              dard  expand-word  command,  but  using  the  _expand completer.
2913              Before calling it, the function field of the context is  set  to
2914              `expand-word'.
2915
2916       _generic
2917              This  function  is  not  defined  as  a  widget and not bound by
2918              default.  However, it can be used to define a  widget  and  will
2919              then  store  the name of the widget in the function field of the
2920              context and call the completion system.  This allows custom com‐
2921              pletion  widgets  with  their  own  set  of style settings to be
2922              defined easily.  For example, to define a widget  that  performs
2923              normal completion and starts menu selection:
2924
2925                     zle -C foo complete-word _generic
2926                     bindkey '...' foo
2927                     zstyle ':completion:foo:*' menu yes select=1
2928
2929              Note  in  particular that the completer style may be set for the
2930              context in order to change the set of functions used to generate
2931              possible  matches.   If _generic is called with arguments, those
2932              are passed through to _main_complete as the list  of  completers
2933              in place of those defined by the completer style.
2934
2935       _history_complete_word (\e/)
2936              Complete  words  from the shell's command history. This uses the
2937              list, remove-all-dups, sort, and stop styles.
2938
2939       _most_recent_file (^Xm)
2940              Complete the name of the most recently  modified  file  matching
2941              the  pattern on the command line (which may be blank).  If given
2942              a numeric argument N, complete the Nth  most  recently  modified
2943              file.  Note the completion, if any, is always unique.
2944
2945       _next_tags (^Xn)
2946              This command alters the set of matches used to that for the next
2947              tag, or set of tags, either as given by the tag-order  style  or
2948              as  set  by default; these matches would otherwise not be avail‐
2949              able.  Successive invocations of the command cycle  through  all
2950              possible sets of tags.
2951
2952       _read_comp (^X^R)
2953              Prompt the user for a string, and use that to perform completion
2954              on the current  word.   There  are  two  possibilities  for  the
2955              string.   First,  it  can  be  a set of words beginning `_', for
2956              example `_files -/', in which case the function with  any  argu‐
2957              ments  will  be called to generate the completions.  Unambiguous
2958              parts of the function name will be completed automatically (nor‐
2959              mal  completion is not available at this point) until a space is
2960              typed.
2961
2962              Second, any other string will be passed as a set of arguments to
2963              compadd and should hence be an expression specifying what should
2964              be completed.
2965
2966              A very restricted set of  editing  commands  is  available  when
2967              reading  the  string:  `DEL' and `^H' delete the last character;
2968              `^U' deletes the line, and `^C' and  `^G'  abort  the  function,
2969              while  `RET'  accepts  the  completion.  Note the string is used
2970              verbatim as a command line,  so  arguments  must  be  quoted  in
2971              accordance with standard shell rules.
2972
2973              Once  a  string  has been read, the next call to _read_comp will
2974              use the existing string instead of reading a new one.  To  force
2975              a  new  string  to be read, call _read_comp with a numeric argu‐
2976              ment.
2977
2978       _complete_debug (^X?)
2979              This widget performs ordinary completion, but captures in a tem‐
2980              porary  file  a trace of the shell commands executed by the com‐
2981              pletion system.  Each completion attempt gets its own  file.   A
2982              command  to  view  each of these files is pushed onto the editor
2983              buffer stack.
2984
2985       _complete_help (^Xh)
2986              This widget displays information about the  context  names,  the
2987              tags,  and  the completion functions used when completing at the
2988              current cursor position. If given a numeric argument other  than
2989              1 (as in `ESC-2 ^Xh'), then the styles used and the contexts for
2990              which they are used will be shown, too.
2991
2992              Note that the information about styles  may  be  incomplete;  it
2993              depends  on  the information available from the completion func‐
2994              tions called, which in turn is  determined  by  the  user's  own
2995              styles and other settings.
2996
2997       _complete_help_generic
2998              Unlike  other  commands  listed  here, this must be created as a
2999              normal ZLE widget rather than a completion widget (i.e. with zle
3000              -N).   It is used for generating help with a widget bound to the
3001              _generic widget that is described above.
3002
3003              If this widget is created using the name of the function, as  it
3004              is  by  default, then when executed it will read a key sequence.
3005              This is expected to be bound to a call to a completion  function
3006              that  uses  the  _generic widget.  That widget will be executed,
3007              and information provided in  the  same  format  that  the  _com‐
3008              plete_help widget displays for contextual completion.
3009
3010              If  the  widget's name contains debug, for example if it is cre‐
3011              ated as `zle -N _complete_debug_generic _complete_help_generic',
3012              it  will  read and execute the keystring for a generic widget as
3013              before, but then generate debugging information as done by _com‐
3014              plete_debug for contextual completion.
3015
3016              If  the  widget's  name  contains  noread,  it  will  not read a
3017              keystring but instead arrange that the next  use  of  a  generic
3018              widget  run  in the same shell will have the effect as described
3019              above.
3020
3021              The   widget   works   by   setting    the    shell    parameter
3022              ZSH_TRACE_GENERIC_WIDGET  which  is read by _generic.  Unsetting
3023              the parameter cancels any pending effect of the noread form.
3024
3025              For example, after executing the following:
3026
3027                     zle -N _complete_debug_generic _complete_help_generic
3028                     bindkey '^x:' _complete_debug_generic
3029
3030              typing `C-x :' followed by the key sequence for a generic widget
3031              will cause trace output for that widget to be saved to a file.
3032
3033       _complete_tag (^Xt)
3034              This  widget completes symbol tags created by the etags or ctags
3035              programmes (note there is no connection with the completion sys‐
3036              tem's  tags) stored in a file TAGS, in the format used by etags,
3037              or tags, in the format created by ctags.  It will look  back  up
3038              the  path  hierarchy for the first occurrence of either file; if
3039              both exist, the file TAGS is preferred.   You  can  specify  the
3040              full path to a TAGS or tags file by setting the parameter $TAGS‐
3041              FILE or $tagsfile respectively.   The  corresponding  completion
3042              tags used are etags and vtags, after emacs and vi respectively.
3043

UTILITY FUNCTIONS

3045       Descriptions follow for utility functions that may be useful when writ‐
3046       ing completion functions.  If functions are  installed  in  subdirecto‐
3047       ries,  most of these reside in the Base subdirectory.  Like the example
3048       functions for commands in the distribution, the utility functions  gen‐
3049       erating  matches  all follow the convention of returning status zero if
3050       they generated completions and  non-zero  if  no  matching  completions
3051       could be added.
3052
3053       Two  more  features  are  offered  by the _main_complete function.  The
3054       arrays compprefuncs and comppostfuncs may contain  names  of  functions
3055       that  are  to be called immediately before or after completion has been
3056       tried.  A function will only be called once unless it explicitly  rein‐
3057       serts itself into the array.
3058
3059       _all_labels [ -x ] [ -12VJ ] tag name descr [ command args ... ]
3060              This  is  a  convenient  interface  to  the _next_label function
3061              below, implementing the loop shown in the  _next_label  example.
3062              The  command  and  its  arguments  are  called  to  generate the
3063              matches.  The options stored in the parameter name will automat‐
3064              ically  be  inserted  into the args passed to the command.  Nor‐
3065              mally, they are put directly after the command, but  if  one  of
3066              the  args  is a single hyphen, they are inserted directly before
3067              that.  If the hyphen is the last argument, it  will  be  removed
3068              from  the  argument  list  before  the  command is called.  This
3069              allows _all_labels to be used in  almost  all  cases  where  the
3070              matches can be generated by a single call to the compadd builtin
3071              command or by a call to one of the utility functions.
3072
3073              For example:
3074
3075                     local expl
3076                     ...
3077                     if _requested foo; then
3078                       ...
3079                       _all_labels foo expl '...' compadd ... - $matches
3080                     fi
3081
3082              Will complete the strings from the matches parameter, using com‐
3083              padd  with  additional  options  which will take precedence over
3084              those generated by _all_labels.
3085
3086       _alternative [ -O name ] [ -C name ] spec ...
3087              This function is useful in simple cases where multiple tags  are
3088              available.   Essentially  it  implements  a  loop  like  the one
3089              described for the _tags function below.
3090
3091              The tags to use and the action to perform if a tag is  requested
3092              are   described   using   the  specs  which  are  of  the  form:
3093              `tag:descr:action'.  The tags are offered using _tags and if the
3094              tag is requested, the action is executed with the given descrip‐
3095              tion descr.  The actions are those accepted  by  the  _arguments
3096              function  (described  below), excluding the `->state' and `=...'
3097              forms.
3098
3099              For example, the action may be a simple function call:
3100
3101                     _alternative \
3102                         'users:user:_users' \
3103                         'hosts:host:_hosts'
3104
3105              offers usernames and hostnames as possible matches, generated by
3106              the _users and _hosts functions respectively.
3107
3108              Like  _arguments,  this function uses _all_labels to execute the
3109              actions, which will loop over all sets of  tags.   Special  han‐
3110              dling  is only required if there is an additional valid tag, for
3111              example inside a function called from _alternative.
3112
3113              The option `-O name' is used in the same way as  by  the  _argu‐
3114              ments  function.  In other words, the elements of the name array
3115              will be passed to compadd when executing an action.
3116
3117              Like _tags this function supports the -C option to give  a  dif‐
3118              ferent name for the argument context field.
3119
3120       _arguments [ -nswWACRS ] [ -O name ] [ -M matchspec ] [ : ] spec ...
3121              This  function  can be used to give a complete specification for
3122              completion for a command whose arguments  follow  standard  UNIX
3123              option  and  argument  conventions.  The following forms specify
3124              individual sets of options and arguments;  to  avoid  ambiguity,
3125              these  may be separated from the options to _arguments itself by
3126              a single colon.  Options to _arguments itself must be  in  sepa‐
3127              rate words, i.e. -s -w, not -sw.
3128
3129              With the option -n, _arguments sets the parameter NORMARG to the
3130              position of the first normal argument in the $words array,  i.e.
3131              the position after the end of the options.  If that argument has
3132              not been reached, NORMARG is  set  to  -1.   The  caller  should
3133              declare  `integer NORMARG' if the -n option is passed; otherwise
3134              the parameter is not used.
3135
3136              n:message:action
3137              n::message:action
3138                     This describes the n'th  normal  argument.   The  message
3139                     will  be  printed  above  the  matches  generated and the
3140                     action indicates what can be completed in  this  position
3141                     (see  below).  If there are two colons before the message
3142                     the argument is optional.  If the message  contains  only
3143                     white  space,  nothing  will be printed above the matches
3144                     unless the action adds an explanation string itself.
3145
3146              :message:action
3147              ::message:action
3148                     Similar, but describes the next argument, whatever number
3149                     that  happens  to  be.  If all arguments are specified in
3150                     this form in the correct order the numbers  are  unneces‐
3151                     sary.
3152
3153              *:message:action
3154              *::message:action
3155              *:::message:action
3156                     This  describes  how  arguments (usually non-option argu‐
3157                     ments, those not beginning with - or +) are  to  be  com‐
3158                     pleted  when neither of the first two forms was provided.
3159                     Any number of arguments can be completed in this fashion.
3160
3161                     With two colons before the  message,  the  words  special
3162                     array  and  the CURRENT special parameter are modified to
3163                     refer only to the normal arguments  when  the  action  is
3164                     executed or evaluated.  With three colons before the mes‐
3165                     sage they are modified to refer only to the normal  argu‐
3166                     ments covered by this description.
3167
3168              optspec
3169              optspec:...
3170                     This  describes  an option.  The colon indicates handling
3171                     for one or more arguments to the option;  if  it  is  not
3172                     present, the option is assumed to take no arguments.
3173
3174                     By default, options are multi-character name, one `-word'
3175                     per option.  With -s, options may be  single  characters,
3176                     with more than one option per word, although words start‐
3177                     ing with two hyphens, such as `--prefix', are still  con‐
3178                     sidered  complete  option  names.   This  is suitable for
3179                     standard GNU options.
3180
3181                     The  combination  of  -s  with  -w  allows  single-letter
3182                     options  to  be  combined in a single word even if one or
3183                     more of the options take arguments.  For example,  if  -a
3184                     takes  an  argument,  with no -s `-ab' is considered as a
3185                     single (unhandled) option; with -s -ab is an option  with
3186                     the  argument  `b';  with  both -s and -w, -ab may be the
3187                     option -a and the option -b with arguments still to come.
3188
3189                     The option -W takes this a stage further:  it is possible
3190                     to  complete single-letter options even after an argument
3191                     that occurs in the same word.  However, it depends on the
3192                     action performed whether options will really be completed
3193                     at this point.  For more control, use a utility  function
3194                     like _guard as part of the action.
3195
3196                     The  following  forms  are available for the initial opt‐
3197                     spec, whether or not the option has arguments.
3198
3199                     *optspec
3200                            Here optspec is one of the remaining forms  below.
3201                            This   indicates  the  following  optspec  may  be
3202                            repeated.  Otherwise if the  corresponding  option
3203                            is already present on the command line to the left
3204                            of the cursor it will not be offered again.
3205
3206                     -optname
3207                     +optname
3208                            In the simplest  form  the  optspec  is  just  the
3209                            option name beginning with a minus or a plus sign,
3210                            such as `-foo'.  The first argument for the option
3211                            (if  any)  must follow as a separate word directly
3212                            after the option.
3213
3214                            Either of `-+optname' and `+-optname' can be  used
3215                            to  specify  that  -optname  and +optname are both
3216                            valid.
3217
3218                            In all the remaining forms, the leading `-' may be
3219                            replaced by or paired with `+' in this way.
3220
3221                     -optname-
3222                            The   first  argument  of  the  option  must  come
3223                            directly after the option name in the  same  word.
3224                            For  example,  `-foo-:...' specifies that the com‐
3225                            pleted  option  and  argument   will   look   like
3226                            `-fooarg'.
3227
3228                     -optname+
3229                            The  first  argument  may appear immediately after
3230                            optname in the same word, or may appear as a sepa‐
3231                            rate   word   after   the  option.   For  example,
3232                            `-foo+:...' specifies that  the  completed  option
3233                            and  argument  will  look like either `-fooarg' or
3234                            `-foo arg'.
3235
3236                     -optname=
3237                            The argument may appear as the next  word,  or  in
3238                            same  word  as the option name provided that it is
3239                            separated from it by an equals sign,  for  example
3240                            `-foo=arg' or `-foo arg'.
3241
3242                     -optname=-
3243                            The  argument  to  the option must appear after an
3244                            equals sign in the same word, and may not be given
3245                            in the next argument.
3246
3247                     optspec[explanation]
3248                            An  explanation  string  may be appended to any of
3249                            the preceding forms of optspec by enclosing it  in
3250                            brackets, as in `-q[query operation]'.
3251
3252                            The  verbose  style  is used to decide whether the
3253                            explanation strings are displayed with the  option
3254                            in a completion listing.
3255
3256                            If  no  bracketed  explanation string is given but
3257                            the auto-description style is  set  and  only  one
3258                            argument  is described for this optspec, the value
3259                            of the style is displayed, with any appearance  of
3260                            the sequence `%d' in it replaced by the message of
3261                            the first optarg that  follows  the  optspec;  see
3262                            below.
3263
3264              It  is possible for options with a literal `+' or `=' to appear,
3265              but that character must be quoted, for example `-\+'.
3266
3267              Each optarg following an optspec must take one of the  following
3268              forms:
3269
3270              :message:action
3271              ::message:action
3272                     An argument to the option; message and action are treated
3273                     as for ordinary arguments.  In the first form, the  argu‐
3274                     ment is mandatory, and in the second form it is optional.
3275
3276                     This  group may be repeated for options which take multi‐
3277                     ple arguments.  In  other  words,  :message1:action1:mes‐
3278                     sage2:action2  specifies  that the option takes two argu‐
3279                     ments.
3280
3281              :*pattern:message:action
3282              :*pattern::message:action
3283              :*pattern:::message:action
3284                     This describes multiple arguments.  Only the last  optarg
3285                     for  an  option taking multiple arguments may be given in
3286                     this form.  If the pattern is empty (i.e., :*:), all  the
3287                     remaining  words  on  the  line  are  to  be completed as
3288                     described by the action; otherwise, all the words  up  to
3289                     and  including a word matching the pattern are to be com‐
3290                     pleted using the action.
3291
3292                     Multiple colons are treated as for the `*:...' forms  for
3293                     ordinary  arguments:  when the message is preceded by two
3294                     colons, the words special array and the  CURRENT  special
3295                     parameter are modified during the execution or evaluation
3296                     of the action to  refer  only  to  the  words  after  the
3297                     option.  When preceded by three colons, they are modified
3298                     to refer only to the words covered by this description.
3299
3300       Any literal colon in an optname, message, or action must be preceded by
3301       a backslash, `\:'.
3302
3303       Each  of  the  forms  above may be preceded by a list in parentheses of
3304       option names and argument numbers.  If the given option is on the  com‐
3305       mand  line, the options and arguments indicated in parentheses will not
3306       be offered.  For  example,  `(-two  -three  1)-one:...'  completes  the
3307       option  `-one';  if  this appears on the command line, the options -two
3308       and -three and the first ordinary argument will not be completed  after
3309       it.   `(-foo):...' specifies an ordinary argument completion; -foo will
3310       not be completed if that argument is already present.
3311
3312       Other items may appear in the list of excluded options to indicate var‐
3313       ious other items that should not be applied when the current specifica‐
3314       tion is matched: a single star (*) for the rest arguments (i.e. a spec‐
3315       ification   of   the   form  `*:...');  a  colon  (:)  for  all  normal
3316       (non-option-) arguments; and a hyphen (-) for all options.   For  exam‐
3317       ple,  if  `(*)'  appears before an option and the option appears on the
3318       command line, the list of remaining arguments (those shown in the above
3319       table beginning with `*:') will not be completed.
3320
3321       To aid in reuse of specifications, it is possible to precede any of the
3322       forms above with `!'; then  the  form  will  no  longer  be  completed,
3323       although  if  the  option  or argument appears on the command line they
3324       will be skipped as normal.  The main use for this is when the arguments
3325       are  given  by  an  array, and _arguments is called repeatedly for more
3326       specific contexts: on the first call  `_arguments  $global_options'  is
3327       used, and on subsequent calls `_arguments !$^global_options'.
3328
3329       In each of the forms above the action determines how completions should
3330       be generated.  Except for the `->string' form below, the action will be
3331       executed by calling the _all_labels function to process all tag labels.
3332       No special handling of tags is needed unless a function call introduces
3333       a new one.
3334
3335       The forms for action are as follows.
3336
3337         (single unquoted space)
3338              This  is useful where an argument is required but it is not pos‐
3339              sible or desirable to generate matches for it.  The message will
3340              be  displayed but no completions listed.  Note that even in this
3341              case the colon at the end of the message is needed; it may  only
3342              be omitted when neither a message nor an action is given.
3343
3344       (item1 item2 ...)
3345              One of a list of possible matches, for example:
3346
3347                     :foo:(foo bar baz)
3348
3349       ((item1\:desc1 ...))
3350              Similar  to  the  above, but with descriptions for each possible
3351              match.  Note the backslash before the colon.  For example,
3352
3353                     :foo:((a\:bar b\:baz))
3354
3355              The matches will be listed together with their  descriptions  if
3356              the description style is set with the values tag in the context.
3357
3358       ->string
3359              In this form, _arguments processes the arguments and options and
3360              then returns control to the calling function with parameters set
3361              to  indicate  the state of processing; the calling function then
3362              makes its own  arrangements  for  generating  completions.   For
3363              example,  functions  that implement a state machine can use this
3364              type of action.
3365
3366              Where _arguments encounters action in the `->string' format,  it
3367              will  strip  all leading and trailing whitespace from string and
3368              set the array state to the set  of  all  strings  for  which  an
3369              action   is   to  be  performed.   The  elements  of  the  array
3370              state_descr are assigned the corresponding  message  field  from
3371              each optarg containing such an action.
3372
3373              By  default and in common with all other well behaved completion
3374              functions, _arguments returns status zero if it was able to  add
3375              matches  and  non-zero  otherwise.  However, if the -R option is
3376              given, _arguments will instead return a status of 300  to  indi‐
3377              cate that $state is to be handled.
3378
3379              In addition to $state and $state_descr, _arguments also sets the
3380              global parameters `context', `line' and `opt_args' as  described
3381              below, and does not reset any changes made to the special param‐
3382              eters such as PREFIX and words.  This gives the calling function
3383              the  choice of resetting these parameters or propagating changes
3384              in them.
3385
3386              A function calling _arguments with at least one action  contain‐
3387              ing a `->string' must therefore declare appropriate local param‐
3388              eters:
3389
3390                     local context state state_descr line
3391                     typeset -A opt_args
3392
3393              to prevent _arguments from altering the global environment.
3394
3395       {eval-string}
3396              A string in braces  is  evaluated  as  shell  code  to  generate
3397              matches.  If the eval-string itself does not begin with an open‐
3398              ing parenthesis or brace it is split into separate words  before
3399              execution.
3400
3401       = action
3402              If  the  action  starts  with `= ' (an equals sign followed by a
3403              space), _arguments will insert  the  contents  of  the  argument
3404              field  of  the  current  context as the new first element in the
3405              words special array and increment the value of the CURRENT  spe‐
3406              cial  parameter.   This has the effect of inserting a dummy word
3407              onto the completion command line while not changing the point at
3408              which completion is taking place.
3409
3410              This is most useful with one of the specifiers that restrict the
3411              words on the command line on which the action is to operate (the
3412              two-  and  three-colon forms above).  One particular use is when
3413              an action itself causes _arguments on a restricted range; it  is
3414              necessary  to  use  this  trick to insert an appropriate command
3415              name into the range for the second call to _arguments to be able
3416              to parse the line.
3417
3418        word...
3419       word...
3420              This  covers  all  forms  other than those above.  If the action
3421              starts with a space, the remaining list of words will be invoked
3422              unchanged.
3423
3424              Otherwise  it  will  be  invoked  with some extra strings placed
3425              after the first word; these are to be passed down as options  to
3426              the  compadd  builtin.   They ensure that the state specified by
3427              _arguments, in particular the descriptions of options and  argu‐
3428              ments,  is  correctly  passed  to the completion command.  These
3429              additional arguments are taken from the array parameter  `expl';
3430              this will be set up before executing the action and hence may be
3431              referred to inside it, typically in an  expansion  of  the  form
3432              `$expl[@]' which preserves empty elements of the array.
3433
3434       During  the  performance  of the action the array `line' will be set to
3435       the command name and normal arguments from the command line,  i.e.  the
3436       words  from the command line excluding all options and their arguments.
3437       Options are stored in the  associative  array  `opt_args'  with  option
3438       names as keys and their arguments as the values.  For options that have
3439       more than one argument these are given  as  one  string,  separated  by
3440       colons.   All  colons in the original arguments are preceded with back‐
3441       slashes.
3442
3443       The parameter `context' is set when returning to the  calling  function
3444       to  perform an action of the form `->string'.  It is set to an array of
3445       elements corresponding to the elements of $state.  Each  element  is  a
3446       suitable name for the argument field of the context: either a string of
3447       the form `option-opt-n' for the n'th argument of the option -opt, or  a
3448       string  of  the  form  `argument-n'  for the n'th argument.  For `rest'
3449       arguments, that is those in the list at the end not  handled  by  posi‐
3450       tion,  n  is the string `rest'.  For example, when completing the argu‐
3451       ment of the -o option, the name is `option-o-1', while for  the  second
3452       normal (non-option-) argument it is `argument-2'.
3453
3454       Furthermore,  during  the  evaluation of the action the context name in
3455       the curcontext parameter is altered to append the same string  that  is
3456       stored in the context parameter.
3457
3458       It  is  possible to specify multiple sets of options and arguments with
3459       the sets separated by single hyphens.  The  specifications  before  the
3460       first  hyphen (if any) are shared by all the remaining sets.  The first
3461       word in every other set provides a name for the set which may appear in
3462       exclusion  lists  in  specifications, either alone or before one of the
3463       possible values described above.  In  the  second  case  a  `-'  should
3464       appear between this name and the remainder.
3465
3466       For example:
3467
3468              _arguments \
3469                  -a \
3470                - set1 \
3471                  -c \
3472                - set2 \
3473                  -d \
3474                  ':arg:(x2 y2)'
3475
3476       This defines two sets.  When the command line contains the option `-c',
3477       the `-d' option and the argument will not be considered  possible  com‐
3478       pletions.   When  it contains `-d' or an argument, the option `-c' will
3479       not be considered.  However, after `-a' both sets will still be consid‐
3480       ered valid.
3481
3482       If the name given for one of the mutually exclusive sets is of the form
3483       `(name)' then only one value from each set will ever be completed; more
3484       formally, all specifications are mutually exclusive to all other speci‐
3485       fications in the same set.  This is useful for defining  multiple  sets
3486       of  options  which  are mutually exclusive and in which the options are
3487       aliases for each other.  For example:
3488
3489              _arguments \
3490                  -a -b \
3491                - '(compress)' \
3492                  {-c,--compress}'[compress]' \
3493                - '(uncompress)' \
3494                  {-d,--decompress}'[decompress]'
3495
3496       As the completion code has to parse the  command  line  separately  for
3497       each  set  this  form  of argument is slow and should only be used when
3498       necessary.  A useful alternative is often an option specification  with
3499       rest-arguments  (as  in `-foo:*:...'); here the option -foo swallows up
3500       all remaining arguments as described by the optarg definitions.
3501
3502       The options -S and -A are available to simplify the specifications  for
3503       commands with standard option parsing.  With -S, no option will be com‐
3504       pleted after a `--' appearing on its own on  the  line;  this  argument
3505       will otherwise be ignored; hence in the line
3506
3507              foobar -a -- -b
3508
3509       the  `-a'  is  considered an option but the `-b' is considered an argu‐
3510       ment, while the `--' is considered to be neither.
3511
3512       With -A, no options will be completed after the first non-option  argu‐
3513       ment  on  the  line.  The -A must be followed by a pattern matching all
3514       strings which are not to be taken as arguments.  For example,  to  make
3515       _arguments stop completing options after the first normal argument, but
3516       ignoring all strings starting with  a  hyphen  even  if  they  are  not
3517       described by one of the optspecs, the form is `-A "-*"'.
3518
3519       The option `-O name' specifies the name of an array whose elements will
3520       be passed as arguments to functions called  to  execute  actions.   For
3521       example,  this can be used to pass the same set of options for the com‐
3522       padd builtin to all actions.
3523
3524       The option `-M spec' sets a match specification to  use  to  completion
3525       option  names  and  values.   It  must appear before the first argument
3526       specification.  The default is `r:|[_-]=* r:|=*': this  allows  partial
3527       word  completion after `_' and `-', for example `-f-b' can be completed
3528       to `-foo-bar'.
3529
3530       The option -C tells _arguments to modify the curcontext  parameter  for
3531       an  action  of the form `->state'.  This is the standard parameter used
3532       to keep track of the current context.  Here it  (and  not  the  context
3533       array)  should  be  made local to the calling function to avoid passing
3534       back the modified value and should be initialised to the current  value
3535       at the start of the function:
3536
3537              local curcontext="$curcontext"
3538
3539       This is useful where it is not possible for multiple states to be valid
3540       together.
3541
3542       The option `--' allows _arguments to work out the names of long options
3543       that  support  the  `--help'  option which is standard in many GNU com‐
3544       mands.  The command word is called with the argument `--help'  and  the
3545       output examined for option names.  Clearly, it can be dangerous to pass
3546       this to commands which may not support this option as the behaviour  of
3547       the command is unspecified.
3548
3549       In addition to options, `_arguments --' will try to deduce the types of
3550       arguments available for options when the form `--opt=val' is valid.  It
3551       is  also  possible  to  provide hints by examining the help text of the
3552       command and adding specifiers  of  the  form  `pattern:message:action';
3553       note  that  normal  _arguments specifiers are not used.  The pattern is
3554       matched against the help text for an option, and if it matches the mes‐
3555       sage  and  action are used as for other argument specifiers.  For exam‐
3556       ple:
3557
3558              _arguments -- '*\*:toggle:(yes no)' \
3559                            '*=FILE*:file:_files' \
3560                            '*=DIR*:directory:_files -/' \
3561                            '*=PATH*:directory:_files -/'
3562
3563       Here, `yes' and `no' will be completed as the argument of options whose
3564       description  ends  in  a star; file names will be completed for options
3565       that contain the substring `=FILE' in the description; and  directories
3566       will  be  completed  for  options  whose description contains `=DIR' or
3567       `=PATH'.  The last three are in fact the default and  so  need  not  be
3568       given  explicitly, although it is possible to override the use of these
3569       patterns.  A typical help text which uses this feature is:
3570
3571                -C, --directory=DIR          change to directory DIR
3572
3573       so that the above specifications will cause directories to be completed
3574       after `--directory', though not after `-C'.
3575
3576       Note  also that _arguments tries to find out automatically if the argu‐
3577       ment for an option is optional.  This can be  specified  explicitly  by
3578       doubling the colon before the message.
3579
3580       If the pattern ends in `(-)', this will be removed from the pattern and
3581       the action will be used only directly after the `=', not  in  the  next
3582       word.  This is the behaviour of a normal specification defined with the
3583       form `=-'.
3584
3585       The `_arguments --' can be followed by the option `-i patterns' to give
3586       patterns  for  options which are not to be completed.  The patterns can
3587       be given as the name of an array parameter or  as  a  literal  list  in
3588       parentheses.  For example,
3589
3590              _arguments -- -i \
3591                  "(--(en|dis)able-FEATURE*)"
3592
3593       will  cause  completion  to  ignore  the options `--enable-FEATURE' and
3594       `--disable-FEATURE' (this example is useful with GNU configure).
3595
3596       The `_arguments --' form can also be followed by the option  `-s  pair'
3597       to  describe  option  aliases.   Each  pair consists of a pattern and a
3598       replacement.  For example, some configure-scripts describe options only
3599       as  `--enable-foo',  but also accept `--disable-foo'.  To allow comple‐
3600       tion of the second form:
3601
3602              _arguments -- -s "(#--enable- --disable-)"
3603
3604       Here is a more general example of the use of _arguments:
3605
3606              _arguments '-l+:left border:' \
3607                         '-format:paper size:(letter A4)' \
3608                         '*-copy:output file:_files::resolution:(300 600)' \
3609                         ':postscript file:_files -g \*.\(ps\|eps\)' \
3610                         '*:page number:'
3611
3612       This describes three options: `-l', `-format', and `-copy'.  The  first
3613       takes  one  argument described as `left border' for which no completion
3614       will be offered because of the empty action.   Its  argument  may  come
3615       directly  after  the  `-l'  or  it may be given as the next word on the
3616       line.
3617
3618       The `-format' option takes one argument in the next word, described  as
3619       `paper  size' for which only the strings `letter' and `A4' will be com‐
3620       pleted.
3621
3622       The `-copy' option may appear more than once on the  command  line  and
3623       takes two arguments.  The first is mandatory and will be completed as a
3624       filename.  The second is optional (because of the second  colon  before
3625       the  description  `resolution')  and will be completed from the strings
3626       `300' and `600'.
3627
3628       The last two descriptions say what should be  completed  as  arguments.
3629       The first describes the first argument as a `postscript file' and makes
3630       files ending in `ps' or `eps' be completed.  The last description gives
3631       all  other  arguments the description `page numbers' but does not offer
3632       completions.
3633
3634       _cache_invalid cache_identifier
3635              This function returns status zero if the completions cache  cor‐
3636              responding  to  the given cache identifier needs rebuilding.  It
3637              determines this by looking up the  cache-policy  style  for  the
3638              current  context.   This should provide a function name which is
3639              run with the full path to the relevant cache file  as  the  only
3640              argument.
3641
3642              Example:
3643
3644                     _example_caching_policy () {
3645                         # rebuild if cache is more than a week old
3646                         local -a oldp
3647                         oldp=( "$1"(Nm+7) )
3648                         (( $#oldp ))
3649                     }
3650
3651       _call_function return name [ args ... ]
3652              If a function name exists, it is called with the arguments args.
3653              The return argument gives the name of a parameter in  which  the
3654              return status from the function name should be stored; if return
3655              is empty or a single hyphen it is ignored.
3656
3657              The return status of _call_function itself is zero if the  func‐
3658              tion name exists and was called and non-zero otherwise.
3659
3660       _call_program tag string ...
3661              This  function provides a mechanism for the user to override the
3662              use of an external command.  It looks up the command style  with
3663              the supplied tag.  If the style is set, its value is used as the
3664              command to execute.  The strings from the call to _call_program,
3665              or  from  the style if set, are concatenated with spaces between
3666              them and the resulting string is evaluated.  The  return  status
3667              is the return status of the command called.
3668
3669       _combination [ -s pattern ] tag style spec ... field opts ...
3670              This  function  is used to complete combinations of values,  for
3671              example pairs of hostnames and usernames.   The  style  argument
3672              gives  the  style  which defines the pairs; it is looked up in a
3673              context with the tag specified.
3674
3675              The style name consists of field names separated by hyphens, for
3676              example  `users-hosts-ports'.   For  each  field  for a value is
3677              already known, a spec of the form `field=pattern' is given.  For
3678              example,  if the command line so far specifies a user `pws', the
3679              argument `users=pws' should appear.
3680
3681              The next argument with no equals sign is taken as  the  name  of
3682              the  field for which completions should be generated (presumably
3683              not one of the fields for which the value is known).
3684
3685              The matches generated will be taken from the value of the style.
3686              These should contain the possible values for the combinations in
3687              the appropriate  order  (users,  hosts,  ports  in  the  example
3688              above).   The  different  fields  the  values  for the different
3689              fields are separated by colons.  This can be  altered  with  the
3690              option  -s to _combination which specifies a pattern.  Typically
3691              this is a character class, as for example  `-s  "[:@]"'  in  the
3692              case  of the users-hosts style.    Each `field=pattern' specifi‐
3693              cation restricts the completions which apply to elements of  the
3694              style with appropriately matching fields.
3695
3696              If no style with the given name is defined for the given tag, or
3697              if none of the strings in style's value match,  but  a  function
3698              name of the required field preceded by an underscore is defined,
3699              that function will be called to generate the matches.  For exam‐
3700              ple,  if there is no `users-hosts-ports' or no matching hostname
3701              when a host is required, the function  `_hosts'  will  automati‐
3702              cally be called.
3703
3704              If  the  same  name is used for more than one field, in both the
3705              `field=pattern' and the argument that  gives  the  name  of  the
3706              field  to  be  completed, the number of the field (starting with
3707              one) may be given after the fieldname, separated from  it  by  a
3708              colon.
3709
3710              All  arguments  after the required field name are passed to com‐
3711              padd when generating matches from the style  value,  or  to  the
3712              functions for the fields if they are called.
3713
3714       _describe [ -oO | -t tag ] descr name1 [ name2 ] opts ... -- ...
3715              This  function associates completions with descriptions.  Multi‐
3716              ple groups separated by -- can  be  supplied,  potentially  with
3717              different completion options opts.
3718
3719              The  descr  is taken as a string to display above the matches if
3720              the format style for the descriptions tag is set.  This is  fol‐
3721              lowed  by one or two names of arrays followed by options to pass
3722              to compadd.  The first array contains the  possible  completions
3723              with  their  descriptions  in the form `completion:description'.
3724              Any literal colons in completion must be  quoted  with  a  back‐
3725              slash.  If a second array is given, it should have the same num‐
3726              ber of elements as the first; in  this  case  the  corresponding
3727              elements  are  added as possible completions instead of the com‐
3728              pletion strings from the first array.  The completion list  will
3729              retain the descriptions from the first array.  Finally, a set of
3730              completion options can appear.
3731
3732              If the option  `-o'  appears  before  the  first  argument,  the
3733              matches  added will be treated as names of command options (N.B.
3734              not shell options), typically following a `-', `--'  or  `+'  on
3735              the  command  line.  In this case _describe uses the prefix-hid‐
3736              den, prefix-needed and verbose styles to find out if the strings
3737              should be added as completions and if the descriptions should be
3738              shown.  Without the `-o' option, only the verbose style is  used
3739              to  decide  how descriptions are shown.  If `-O' is used instead
3740              of `-o', command options are completed as  above  but  _describe
3741              will not handle the prefix-needed style.
3742
3743              With the -t option a tag can be specified.  The default is `val‐
3744              ues' or, if the -o option is given, `options'.
3745
3746              If selected by the list-grouped style,  strings  with  the  same
3747              description will appear together in the list.
3748
3749              _describe uses the _all_labels function to generate the matches,
3750              so it does not need to appear inside a loop over tag labels.
3751
3752       _description [ -x ] [ -12VJ ] tag name descr [ spec ... ]
3753              This function is not to be confused with the previous one; it is
3754              used  as  a helper function for creating options to compadd.  It
3755              is buried inside many of the higher level  completion  functions
3756              and so often does not need to be called directly.
3757
3758              The  styles listed below are tested in the current context using
3759              the given tag.  The resulting options for compadd are  put  into
3760              the  array  named  name  (this is traditionally `expl', but this
3761              convention is not enforced).  The  description  for  the  corre‐
3762              sponding set of matches is passed to the function in descr.
3763
3764              The styles tested are: format, hidden, matcher, ignored-patterns
3765              and group-name.  The format style is first tested for the  given
3766              tag  and  then  for  the descriptions tag if no value was found,
3767              while the remainder are only tested for the  tag  given  as  the
3768              first argument.  The function also calls _setup which tests some
3769              more styles.
3770
3771              The string returned by the format style (if any) will  be  modi‐
3772              fied so that the sequence `%d' is replaced by the descr given as
3773              the third argument without any leading or trailing white  space.
3774              If,  after  removing  the  white  space,  the descr is the empty
3775              string, the format style will not be used and  the  options  put
3776              into the name array will not contain an explanation string to be
3777              displayed above the matches.
3778
3779              If _description is called with more than  three  arguments,  the
3780              additional specs should be of the form `char:str'.  These supply
3781              escape sequence replacements for the format style: every appear‐
3782              ance of `%char' will be replaced by string.
3783
3784              If  the  -x  option  is given, the description will be passed to
3785              compadd using the -x option instead of  the  default  -X.   This
3786              means  that  the description will be displayed even if there are
3787              no corresponding matches.
3788
3789              The options placed  in  the  array  name  take  account  of  the
3790              group-name  style,  so  matches  are  placed in a separate group
3791              where necessary.  The group normally has its elements sorted (by
3792              passing  the  option  -J  to compadd), but if an option starting
3793              with `-V', `-J', `-1', or `-2' is passed to  _description,  that
3794              option  will be included in the array.  Hence it is possible for
3795              the completion group to be unsorted by giving the  option  `-V',
3796              `-1V', or `-2V'.
3797
3798              In most cases, the function will be used like this:
3799
3800                     local expl
3801                     _description files expl file
3802                     compadd "$expl[@]" - "$files[@]"
3803
3804              Note  the use of the parameter expl, the hyphen, and the list of
3805              matches.  Almost all calls to compadd within the completion sys‐
3806              tem  use  a  similar  format;  this  ensures that user-specified
3807              styles are correctly passed down to the builtins which implement
3808              the internals of completion.
3809
3810       _dispatch context string ...
3811              This  sets  the current context to context and looks for comple‐
3812              tion functions to handle this context  by  hunting  through  the
3813              list  of  command  names or special contexts (as described above
3814              for compdef) given as string ....  The first completion function
3815              to  be  defined  for  one of the contexts in the list is used to
3816              generate matches.  Typically, the last string  is  -default-  to
3817              cause  the function for default completion to be used as a fall‐
3818              back.
3819
3820              The function sets the parameter $service  to  the  string  being
3821              tried,  and  sets  the context/command field (the fourth) of the
3822              $curcontext parameter to the context given as  the  first  argu‐
3823              ment.
3824
3825       _files The  function _files calls _path_files with all the arguments it
3826              was passed except for -g and -/.  The use of these  two  options
3827              depends on the setting of the  file-patterns style.
3828
3829              This  function  accepts  the  full  set  of  options  allowed by
3830              _path_files, described below.
3831
3832       _gnu_generic
3833              This function is a simple wrapper around the _arguments function
3834              described  above.  It can be used to determine automatically the
3835              long options understood by commands that  produce  a  list  when
3836              passed  the  option  `--help'.   It  is intended to be used as a
3837              top-level completion function in its own right.  For example, to
3838              enable option completion for the commands foo and bar, use
3839
3840                     compdef _gnu_generic foo bar
3841
3842              after the call to compinit.
3843
3844              The  completion system as supplied is conservative in its use of
3845              this function, since it is important  to  be  sure  the  command
3846              understands the option `--help'.
3847
3848       _guard [ options ] pattern descr
3849              This function is intended to be used in the action for the spec‐
3850              ifications passed  to  _arguments  and  similar  functions.   It
3851              returns  immediately with a non-zero return status if the string
3852              to be completed does not match  the  pattern.   If  the  pattern
3853              matches,  the descr is displayed; the function then returns sta‐
3854              tus zero if the word to complete is not empty,  non-zero  other‐
3855              wise.
3856
3857              The  pattern may be preceded by any of the options understood by
3858              compadd that are passed down from _description, namely  -M,  -J,
3859              -V,  -1,  -2,  -n,  -F  and  -X.   All  of these options will be
3860              ignored.  This fits in conveniently  with  the  argument-passing
3861              conventions of actions for _arguments.
3862
3863              As  an  example,  consider  a  command taking the options -n and
3864              -none, where -n must be followed by a numeric value in the  same
3865              word.  By using:
3866
3867                     _arguments '-n-: :_guard "[0-9]#" "numeric value"' '-none'
3868
3869              _arguments  can  be  made  to  both display the message `numeric
3870              value' and complete options after `-n<TAB>'.   If  the  `-n'  is
3871              already  followed  by  one or more digits (the pattern passed to
3872              _guard) only the message will be displayed; if the `-n' is  fol‐
3873              lowed by another character, only options are completed.
3874
3875       _message [ -r12 ] [ -VJ group ] descr
3876       _message -e [ tag ] descr
3877              The  descr  is used in the same way as the third argument to the
3878              _description function, except that  the  resulting  string  will
3879              always  be shown whether or not matches were generated.  This is
3880              useful for displaying a help message in places where no  comple‐
3881              tions can be generated.
3882
3883              The  format  style  is  examined with the messages tag to find a
3884              message; the usual tag, descriptions, is used only if the  style
3885              is not set with the former.
3886
3887              If  the -r option is given, no style is used; the descr is taken
3888              literally as the string to display.  This is  most  useful  when
3889              the descr comes from a pre-processed argument list which already
3890              contains an expanded description.
3891
3892              The -12VJ options and the group are passed to compadd and  hence
3893              determine the group the message string is added to.
3894
3895              The second form gives a description for completions with the tag
3896              tag to be shown even if there are no matches for that tag.   The
3897              tag can be omitted and if so the tag is taken from the parameter
3898              $curtag; this is maintained by the completion system and  so  is
3899              usually correct.
3900
3901       _multi_parts sep array
3902              The  argument  sep  is  a separator character.  The array may be
3903              either the name of an array parameter or a literal array in  the
3904              form  `(foo  bar)',  a  parenthesised list of words separated by
3905              whitespace.  The possible completions are the strings  from  the
3906              array.   However,  each chunk delimited by sep will be completed
3907              separately.  For example, the _tar function uses `_multi_parts /
3908              patharray'  to  complete partial file paths from the given array
3909              of complete file paths.
3910
3911              The -i option causes _multi_parts to insert a unique match  even
3912              if  that  requires  multiple separators to be inserted.  This is
3913              not usually the expected behaviour with filenames,  but  certain
3914              other types of completion, for example those with a fixed set of
3915              possibilities, may be more suited to this form.
3916
3917              Like other utility functions, this function  accepts  the  `-V',
3918              `-J',  `-1',  `-2',  `-n',  `-f',  `-X', `-M', `-P', `-S', `-r',
3919              `-R', and `-q' options and passes them to the compadd builtin.
3920
3921       _next_label [ -x ] [ -12VJ ] tag name descr [ options ... ]
3922              This function is used to implement the loop over  different  tag
3923              labels for a particular tag as described above for the tag-order
3924              style.  On each call it checks to see if there are any more  tag
3925              labels;  if there is it returns status zero, otherwise non-zero.
3926              As this function requires a current  tag  to  be  set,  it  must
3927              always follow a call to _tags or _requested.
3928
3929              The  -x12VJ  options and the first three arguments are passed to
3930              the _description function.  Where appropriate the  tag  will  be
3931              replaced  by a tag label in this call.  Any description given in
3932              the  tag-order  style  is  preferred  to  the  descr  passed  to
3933              _next_label.
3934
3935              The options given after the descr are set in the parameter given
3936              by name, and hence are to be passed to compadd or whatever func‐
3937              tion is called to add the matches.
3938
3939              Here  is  a  typical  use of this function for the tag foo.  The
3940              call to _requested determines if tag foo is required at all; the
3941              loop  over _next_label handles any labels defined for the tag in
3942              the tag-order style.
3943
3944                     local expl ret=1
3945                     ...
3946                     if _requested foo; then
3947                       ...
3948                       while _next_label foo expl '...'; do
3949                         compadd "$expl[@]" ... && ret=0
3950                       done
3951                       ...
3952                     fi
3953                     return ret
3954
3955       _normal
3956              This is the standard function called to handle  completion  out‐
3957              side  any  special -context-.  It is called both to complete the
3958              command word and also the arguments for a command.  In the  sec‐
3959              ond  case,  _normal looks for a special completion for that com‐
3960              mand, and if there is  none  it  uses  the  completion  for  the
3961              -default- context.
3962
3963              A  second  use is to reexamine the command line specified by the
3964              $words array and the $CURRENT parameter after  those  have  been
3965              modified.   For  example,  the  function _precommand, which com‐
3966              pletes after pre-command specifiers such as nohup,  removes  the
3967              first  word from the words array, decrements the CURRENT parame‐
3968              ter, then calls _normal again.  The effect is  that  `nohup  cmd
3969              ...' is treated in the same way as `cmd ...'.
3970
3971              If  the command name matches one of the patterns given by one of
3972              the options -p or -P to compdef,  the  corresponding  completion
3973              function  is called and then the parameter _compskip is checked.
3974              If it is set completion is terminated at that point even  if  no
3975              matches  have  been  found.   This  is the same effect as in the
3976              -first- context.
3977
3978       _options
3979              This can be used to complete the names  of  shell  options.   It
3980              provides  a  matcher  specification that ignores a leading `no',
3981              ignores underscores and allows upper-case letters to match their
3982              lower-case   counterparts   (for   example,   `glob',  `noglob',
3983              `NO_GLOB' are all completed).  Any arguments are  propagated  to
3984              the compadd builtin.
3985
3986       _options_set and _options_unset
3987              These  functions  complete  only  set or unset options, with the
3988              same matching specification used in the _options function.
3989
3990              Note that you need to uncomment a few lines  in  the  _main_com‐
3991              plete  function for these functions to work properly.  The lines
3992              in question are used to store  the  option  settings  in  effect
3993              before  the completion widget locally sets the options it needs.
3994              Hence these functions are not generally used by  the  completion
3995              system.
3996
3997       _parameters
3998              This is used to complete the names of shell parameters.
3999
4000              The  option  `-g  pattern'  limits  the completion to parameters
4001              whose type matches the pattern.  The type of a parameter is that
4002              shown by `print ${(t)param}', hence judicious use of `*' in pat‐
4003              tern is probably necessary.
4004
4005              All other arguments are passed to the compadd builtin.
4006
4007       _path_files
4008              This function is used throughout the completion system  to  com‐
4009              plete  filenames.   It  allows completion of partial paths.  For
4010              example,  the  string   `/u/i/s/sig'   may   be   completed   to
4011              `/usr/include/sys/signal.h'.
4012
4013              The options accepted by both _path_files and _files are:
4014
4015              -f     Complete all filenames.  This is the default.
4016
4017              -/     Specifies that only directories should be completed.
4018
4019              -g pattern
4020                     Specifies  that only files matching the pattern should be
4021                     completed.
4022
4023              -W paths
4024                     Specifies path prefixes that are to be prepended  to  the
4025                     string  from  the  command line to generate the filenames
4026                     but that should not be inserted as completions nor  shown
4027                     in  completion  listings.  Here, paths may be the name of
4028                     an array parameter, a literal list of paths  enclosed  in
4029                     parentheses or an absolute pathname.
4030
4031              -F ignored-files
4032                     This  behaves as for the corresponding option to the com‐
4033                     padd builtin.  It gives direct control over  which  file‐
4034                     names  should  be ignored.  If the option is not present,
4035                     the ignored-patterns style is used.
4036
4037              Both _path_files and _files also accept  the  following  options
4038              which are passed to compadd: `-J', `-V', `-1', `-2', `-n', `-X',
4039              `-M', `-P', `-S', `-q', `-r', and `-R'.
4040
4041              Finally, the  _path_files  function   uses  the  styles  expand,
4042              ambiguous,  special-dirs,  list-suffixes and file-sort described
4043              above.
4044
4045       _pick_variant [ -b builtin-label ] [ -c
4046              command ] [ -r name ]
4047          label=pattern ... label [ args ... ]
4048              This function is used to resolve situations where a single  com‐
4049              mand  name  requires  more  than  one  type  of handling, either
4050              because it has more than one variant or because there is a  name
4051              clash between two different commands.
4052
4053              The  command to run is taken from the first element of the array
4054              words unless this is overridden by the option -c.  This  command
4055              is  run  and  its  output is compared with a series of patterns.
4056              Arguments to be passed to the command can be  specified  at  the
4057              end after all the other arguments.  The patterns to try in order
4058              are given by the arguments label=pattern; if the output of `com‐
4059              mand  args  ...' contains pattern, then label is selected as the
4060              label for the command variant.  If none of the  patterns  match,
4061              the final command label is selected and status 1 is returned.
4062
4063              If the `-b builtin-label' is given, the command is tested to see
4064              if it is provided as a shell builtin,  possibly  autoloaded;  if
4065              so,  the  label  builtin-label  is selected as the label for the
4066              variant.
4067
4068              If the `-r name' is given, the label picked  is  stored  in  the
4069              parameter named name.
4070
4071              The  results  are  also  cached  in the _cmd_variant associative
4072              array indexed by the name of the command run.
4073
4074       _regex_arguments name spec ...
4075              This function generates a completion function name which matches
4076              the  specifications  spec  ...,  a set of regular expressions as
4077              described below.  After running _regex_arguments,  the  function
4078              name should be called as a normal completion function.  The pat‐
4079              tern to be matched is given by the contents of the  words  array
4080              up  to  the  current  cursor  position joined together with null
4081              characters; no quotation is applied.
4082
4083              The arguments are grouped as sets of alternatives  separated  by
4084              `|',  which  are  tried  one  after the other until one matches.
4085              Each alternative consists of a one or more specifications  which
4086              are  tried  left  to  right,  with  each  pattern  matched being
4087              stripped in turn from the command line being tested,  until  all
4088              of  the  group  succeeds or until one fails; in the latter case,
4089              the next alternative is tried.  This structure can  be  repeated
4090              to  arbitrary depth by using parentheses; matching proceeds from
4091              inside to outside.
4092
4093              A special procedure is applied  if  no  test  succeeds  but  the
4094              remaining command line string contains no null character (imply‐
4095              ing the remaining word is the one for which completions  are  to
4096              be  generated).   The  completion  target  is  restricted to the
4097              remaining word and any actions for  the  corresponding  patterns
4098              are  executed.   In this case, nothing is stripped from the com‐
4099              mand line string.  The order of evaluation of the actions can be
4100              determined by the tag-order style; the various formats supported
4101              by _alternative can be used in action.  The descr  is  used  for
4102              setting up the array parameter expl.
4103
4104              Specification  arguments  take  one of following forms, in which
4105              metacharacters such as `(', `)', `#' and `|' should be quoted.
4106
4107              /pattern/ [%lookahead%] [-guard] [:tag:descr:action]
4108                     This is a single primitive component.  The function tests
4109                     whether  the  combined  pattern  `(#b)((#B)pattern)looka‐
4110                     head*' matches the command line string.  If  so,  `guard'
4111                     is  evaluated and its return status is examined to deter‐
4112                     mine if the test has succeeded.  The pattern string  `[]'
4113                     is  guaranteed  never  to  match.   The  lookahead is not
4114                     stripped from the command line before the next pattern is
4115                     examined.
4116
4117                     The  argument  starting with : is used in the same manner
4118                     as an argument to _alternative.
4119
4120                     A component is used as follows: pattern is tested to  see
4121                     if  the component already exists on the command line.  If
4122                     it does, any following  specifications  are  examined  to
4123                     find  something  to  complete.  If a component is reached
4124                     but no such pattern exists yet on the command  line,  the
4125                     string  containing the action is used to generate matches
4126                     to insert at that point.
4127
4128              /pattern/+ [%lookahead%] [-guard] [:tag:descr:action]
4129                     This is similar to `/pattern/ ...' but the left  part  of
4130                     the command line string (i.e. the part already matched by
4131                     previous patterns) is also considered part of the comple‐
4132                     tion target.
4133
4134              /pattern/- [%lookahead%] [-guard] [:tag:descr:action]
4135                     This is similar to `/pattern/ ...' but the actions of the
4136                     current and previously matched patterns are ignored  even
4137                     if the following `pattern' matches the empty string.
4138
4139              ( spec )
4140                     Parentheses may be used to groups specs; note each paren‐
4141                     thesis is a single argument to _regex_arguments.
4142
4143              spec # This allows any number of repetitions of spec.
4144
4145              spec spec
4146                     The two specs are to be matched one after  the  other  as
4147                     described above.
4148
4149              spec | spec
4150                     Either of the two specs can be matched.
4151
4152              The  function  _regex_words  can be used as a helper function to
4153              generate matches for a set of alternative  words  possibly  with
4154              their own arguments as a command line argument.
4155
4156              Examples:
4157
4158                     _regex_arguments _tst /$'[^\0]#\0'/ \
4159                     /$'[^\0]#\0'/ :'compadd aaa'
4160
4161              This  generates  a  function _tst that completes aaa as its only
4162              argument.  The tag and description  for  the  action  have  been
4163              omitted for brevity (this works but is not recommended in normal
4164              use).  The first component matches the command  word,  which  is
4165              arbitrary; the second matches  any argument.  As the argument is
4166              also arbitrary, any following component would not depend on  aaa
4167              being present.
4168
4169                     _regex_arguments _tst /$'[^\0]#\0'/ \
4170                     /$'aaa\0'/ :'compadd aaa'
4171
4172              This  is  a  more  typical use; it is similar, but any following
4173              patterns would only match if aaa was present as the first  argu‐
4174              ment.
4175
4176                     _regex_arguments _tst /$'[^\0]#\0'/ \( \
4177                     /$'aaa\0'/ :'compadd aaa' \
4178                     /$'bbb\0'/ :'compadd bbb' \) \#
4179
4180              In  this  example, an indefinite number of command arguments may
4181              be completed.  Odd arguments are completed as aaa and even argu‐
4182              ments  as  bbb.   Completion fails unless the set of aaa and bbb
4183              arguments before the current one is matched correctly.
4184
4185                     _regex_arguments _tst /$'[^\0]#\0'/ \
4186                     \( /$'aaa\0'/ :'compadd aaa' \| \
4187                     /$'bbb\0'/ :'compadd bbb' \) \#
4188
4189              This is similar, but either aaa or bbb may be completed for  any
4190              argument.  In this case _regex_words could be used to generate a
4191              suitable expression for the arguments.
4192
4193       _regex_words tag description spec ...
4194              This  function  can  be  used  to  generate  arguments  for  the
4195              _regex_arguments  command  which  may  be  inserted at any point
4196              where a set of rules is expected.  The tag and description  give
4197              a  standard  tag  and description pertaining to the current con‐
4198              text.  Each spec contains two or three arguments separated by  a
4199              colon: note that there is no leading colon in this case.
4200
4201              Each  spec  gives one of a set of words that may be completed at
4202              this point, together with arguments.  It is thus roughly equiva‐
4203              lent  to the _arguments function when used in normal (non-regex)
4204              completion.
4205
4206              The part of the spec before the first colon is the  word  to  be
4207              completed.   This  may  contain a *; the entire word, before and
4208              after the * is completed, but only the  text  before  the  *  is
4209              required  for  the  context to be matched, so that further argu‐
4210              ments may be completed after the abbreviated form.
4211
4212              The second part of spec is a description for the word being com‐
4213              pleted.
4214
4215              The  optional third part of the spec describes how words follow‐
4216              ing the one being completed are themselves to be completed.   It
4217              will be evaluated in order to avoid problems with quoting.  This
4218              means that typically it contains a reference to  an  array  con‐
4219              taining previously generated regex arguments.
4220
4221              The  option  -t term specifies a terminator for the word instead
4222              of the usual space.  This is handled as an auto-removable suffix
4223              in the manner of the option -s sep to _values.
4224
4225              The  result  of  the processing by _regex_words is placed in the
4226              array reply, which should be made local to the calling function.
4227              If the set of words and arguments may be matched repeatedly, a #
4228              should be appended to the generated array at that point.
4229
4230              For example:
4231
4232                     local -a reply
4233                     _regex_words mydb-commands 'mydb commands' \
4234                       'add:add an entry to mydb:$mydb_add_cmds' \
4235                       'show:show entries in mydb'
4236                     _regex_arguments _mydb "$reply[@]"
4237                     _mydb "$@"
4238
4239              This shows a completion function for a command mydb which  takes
4240              two  command  arguments, add and show.  show takes no arguments,
4241              while the arguments for add have already  been  prepared  in  an
4242              array  mydb_add_cmds,  quite  possibly  by  a  previous  call to
4243              _regex_words.
4244
4245       _requested [ -x ] [ -12VJ ] tag [ name descr [ command args ... ] ]
4246              This function is called to decide whether a tag  already  regis‐
4247              tered  by  a call to _tags (see below) has been requested by the
4248              user and hence  completion  should  be  performed  for  it.   It
4249              returns  status zero if the tag is requested and non-zero other‐
4250              wise.  The function is typically used as part  of  a  loop  over
4251              different tags as follows:
4252
4253                     _tags foo bar baz
4254                     while _tags; do
4255                       if _requested foo; then
4256                         ... # perform completion for foo
4257                       fi
4258                       ... # test the tags bar and baz in the same way
4259                       ... # exit loop if matches were generated
4260                     done
4261
4262              Note  that  the  test  for whether matches were generated is not
4263              performed until the end of the _tags loop.  This is so that  the
4264              user  can set the tag-order style to specify a set of tags to be
4265              completed at the same time.
4266
4267              If name and descr are given, _requested calls  the  _description
4268              function  with  these arguments together with the options passed
4269              to _requested.
4270
4271              If command is given, the _all_labels  function  will  be  called
4272              immediately with the same arguments.  In simple cases this makes
4273              it possible to perform the test for the tag and the matching  in
4274              one go.  For example:
4275
4276                     local expl ret=1
4277                     _tags foo bar baz
4278                     while _tags; do
4279                       _requested foo expl 'description' \
4280                           compadd foobar foobaz && ret=0
4281                       ...
4282                       (( ret )) || break
4283                     done
4284
4285              If  the command is not compadd, it must nevertheless be prepared
4286              to handle the same options.
4287
4288       _retrieve_cache cache_identifier
4289              This function retrieves completion  information  from  the  file
4290              given  by  cache_identifier,  stored in a directory specified by
4291              the cache-path  style  which  defaults  to  ~/.zcompcache.   The
4292              return status is zero if retrieval was successful.  It will only
4293              attempt retrieval if the use-cache style is set, so you can call
4294              this  function without worrying about whether the user wanted to
4295              use the caching layer.
4296
4297              See _store_cache below for more details.
4298
4299       _sep_parts
4300              This function is passed alternating  arrays  and  separators  as
4301              arguments.   The arrays specify completions for parts of strings
4302              to be separated by the separators.  The arrays may be the  names
4303              of  array  parameters  or a quoted list of words in parentheses.
4304              For  example,  with  the  array  `hosts=(ftp  news)'  the   call
4305              `_sep_parts  '(foo  bar)' @ hosts' will complete the string  `f'
4306              to `foo' and the string `b@n' to `bar@news'.
4307
4308              This function accepts the  compadd  options  `-V',  `-J',  `-1',
4309              `-2',  `-n',  `-X',  `-M',  `-P', `-S', `-r', `-R', and `-q' and
4310              passes them on to the compadd builtin used to add the matches.
4311
4312       _setup tag [ group ]
4313              This function sets up the special parameters used by the comple‐
4314              tion  system  appropriately for the tag given as the first argu‐
4315              ment.    It   uses   the   styles   list-colors,    list-packed,
4316              list-rows-first, last-prompt, accept-exact, menu and force-list.
4317
4318              The  optional  group supplies the name of the group in which the
4319              matches will be placed.  If it is not given, the tag is used  as
4320              the group name.
4321
4322              This  function  is  called  automatically  from _description and
4323              hence is not normally called explicitly.
4324
4325       _store_cache cache_identifier params ...
4326              This function, together with _retrieve_cache and _cache_invalid,
4327              implements  a  caching layer which can be used in any completion
4328              function.  Data obtained by  costly  operations  are  stored  in
4329              parameters; this function then dumps the values of those parame‐
4330              ters to a file.  The data can then  be  retrieved  quickly  from
4331              that  file  via  _retrieve_cache, even in different instances of
4332              the shell.
4333
4334              The cache_identifier specifies the file which the data should be
4335              dumped  to.   The file is stored in a directory specified by the
4336              cache-path style which defaults to ~/.zcompcache.  The remaining
4337              params arguments are the parameters to dump to the file.
4338
4339              The  return status is zero if storage was successful.  The func‐
4340              tion will only attempt storage if the use-cache style is set, so
4341              you  can  call  this function without worrying about whether the
4342              user wanted to use the caching layer.
4343
4344              The completion function may avoid calling  _retrieve_cache  when
4345              it  already  has  the  completion  data available as parameters.
4346              However, in that case it should  call  _cache_invalid  to  check
4347              whether  the  data  in the parameters and in the cache are still
4348              valid.
4349
4350              See the _perl_modules completion function for a  simple  example
4351              of the usage of the caching layer.
4352
4353       _tags [ [ -C name ] tags ... ]
4354              If  called  with  arguments,  these are taken to be the names of
4355              tags valid for completions in the current context.   These  tags
4356              are stored internally and sorted by using the tag-order style.
4357
4358              Next, _tags is called repeatedly without arguments from the same
4359              completion function.  This successively selects the first,  sec‐
4360              ond,  etc. set of tags requested by the user.  The return status
4361              is zero if at least one of the tags is  requested  and  non-zero
4362              otherwise.   To  test  if  a  particular tag is to be tried, the
4363              _requested function should be called (see above).
4364
4365              If `-C name' is given, name is temporarily stored in  the  argu‐
4366              ment  field (the fifth) of the context in the curcontext parame‐
4367              ter during the call to _tags; the field  is  restored  on  exit.
4368              This  allows _tags to use a more specific context without having
4369              to change and reset the curcontext parameter (which has the same
4370              effect).
4371
4372       _values [ -O name ] [ -s sep ] [ -S sep ] [ -wC ] desc spec ...
4373              This  is  used to complete arbitrary keywords (values) and their
4374              arguments, or lists of such combinations.
4375
4376              If the first argument is the option `-O name', it will  be  used
4377              in  the same way as by the _arguments function.  In other words,
4378              the elements of the name array will be passed  to  compadd  when
4379              executing an action.
4380
4381              If the first argument (or the first argument after `-O name') is
4382              `-s', the next argument is used as the character that  separates
4383              multiple  values.   This  character is automatically added after
4384              each value in an auto-removable fashion (see below); all  values
4385              completed by `_values -s' appear in the same word on the command
4386              line, unlike completion using _arguments.  If this option is not
4387              present, only a single value will be completed per word.
4388
4389              Normally,  _values  will  only use the current word to determine
4390              which values are already present on the command line  and  hence
4391              are not to be completed again.  If the -w option is given, other
4392              arguments are examined as well.
4393
4394              The first non-option argument is used as a string to print as  a
4395              description before listing the values.
4396
4397              All other arguments describe the possible values and their argu‐
4398              ments in the same format used for the description of options  by
4399              the  _arguments  function (see above).  The only differences are
4400              that no minus or plus sign is required at the beginning,  values
4401              can  have  only  one argument, and the forms of action beginning
4402              with an equal sign are not supported.
4403
4404              The character separating a value from its argument  can  be  set
4405              using  the  option -S (like -s, followed by the character to use
4406              as the separator in the next argument).  By default  the  equals
4407              sign will be used as the separator between values and arguments.
4408
4409              Example:
4410
4411                     _values -s , 'description' \
4412                             '*foo[bar]' \
4413                             '(two)*one[number]:first count:' \
4414                             'two[another number]::second count:(1 2 3)'
4415
4416              This  describes  three possible values: `foo', `one', and `two'.
4417              The first is described as  `bar',  takes  no  argument  and  may
4418              appear more than once.  The second is described as `number', may
4419              appear  more  than  once,  and  takes  one  mandatory   argument
4420              described  as  `first count'; no action is specified, so it will
4421              not be completed.  The `(two)' at the beginning says that if the
4422              value  `one'  is  on the line, the value `two' will no longer be
4423              considered a  possible  completion.   Finally,  the  last  value
4424              (`two')  is  described as `another number' and takes an optional
4425              argument described as `second count' for which  the  completions
4426              (to  appear  after  an  `=') are `1', `2', and `3'.  The _values
4427              function will complete lists of these values separated  by  com‐
4428              mas.
4429
4430              Like  _arguments, this function temporarily adds another context
4431              name component to the arguments element (the fifth) of the  cur‐
4432              rent context while executing the action.  Here this name is just
4433              the name of the value for which the argument is completed.
4434
4435              The style verbose is used to decide if the descriptions for  the
4436              values (but not those for the arguments) should be printed.
4437
4438              The  associative  array  val_args  is  used to report values and
4439              their arguments; this works similarly to the  opt_args  associa‐
4440              tive array used by _arguments.  Hence the function calling _val‐
4441              ues should declare  the  local  parameters  state,  state_descr,
4442              line, context and val_args:
4443
4444                     local context state state_descr line
4445                     typeset -A val_args
4446
4447              when using an action of the form `->string'.  With this function
4448              the context parameter will be set to the name of the value whose
4449              argument  is  to be completed.  Note that for _values, the state
4450              and state_descr are scalars rather than arrays.  Only  a  single
4451              matching state is returned.
4452
4453              Note  also  that _values normally adds the character used as the
4454              separator between values as an auto-removable suffix (similar to
4455              a  `/'  after a directory).  However, this is not possible for a
4456              `->string' action as the matches for the argument are  generated
4457              by  the calling function.  To get the usual behaviour, the call‐
4458              ing function can add the separator x as a suffix by passing  the
4459              options `-qS x' either directly or indirectly to compadd.
4460
4461              The option -C is treated in the same way as it is by _arguments.
4462              In that case the  parameter  curcontext  should  be  made  local
4463              instead of context (as described above).
4464
4465       _wanted [ -x ] [ -C name ]  [ -12VJ ] tag name descr command args ...
4466              In  many  contexts,  completion can only generate one particular
4467              set of matches, usually corresponding to a single tag.  However,
4468              it  is  still  necessary  to  decide  whether  the user requires
4469              matches of this type.  This function is useful in such a case.
4470
4471              The arguments to _wanted are the same as  those  to  _requested,
4472              i.e.  arguments  to be passed to _description.  However, in this
4473              case the command is not optional;  all the processing  of  tags,
4474              including the loop over both tags and tag labels and the genera‐
4475              tion of matches, is carried out automatically by _wanted.
4476
4477              Hence to offer only one tag and immediately add the  correspond‐
4478              ing matches with the given description:
4479
4480                     local expl
4481                     _wanted tag expl 'description' \
4482                         compadd matches...
4483
4484              Note that, as for _requested, the command must be able to accept
4485              options to be passed down to compadd.
4486
4487              Like _tags this function supports the -C option to give  a  dif‐
4488              ferent  name  for the argument context field.  The -x option has
4489              the same meaning as for _description.
4490

COMPLETION DIRECTORIES

4492       In the source distribution, the files are contained in  various  subdi‐
4493       rectories of the Completion directory.  They may have been installed in
4494       the same structure, or into one single function directory.  The follow‐
4495       ing  is  a  description  of  the  files found in the original directory
4496       structure.  If you wish to alter an installed file, you  will  need  to
4497       copy  it to some directory which appears earlier in your fpath than the
4498       standard directory where it appears.
4499
4500       Base   The core functions and special completion widgets  automatically
4501              bound  to  keys.   You will certainly need most of these, though
4502              will probably not need to alter them.  Many of these  are  docu‐
4503              mented above.
4504
4505       Zsh    Functions for completing arguments of shell builtin commands and
4506              utility functions for this.  Some of  these  are  also  used  by
4507              functions from the Unix directory.
4508
4509       Unix   Functions  for  completing  arguments  of  external commands and
4510              suites of commands.  They may need modifying  for  your  system,
4511              although in many cases some attempt is made to decide which ver‐
4512              sion of a command is present.  For example, completion  for  the
4513              mount  command  tries  to determine the system it is running on,
4514              while completion for many other utilities try to decide  whether
4515              the  GNU version of the command is in use, and hence whether the
4516              --help option is supported.
4517
4518       X, AIX, BSD, ...
4519              Completion and utility function for commands available  only  on
4520              some  systems.   These  are not arranged hierarchically, so, for
4521              example, both the Linux and Debian directories, as well as the X
4522              directory, may be useful on your system.
4523
4524
4525
4526zsh 5.0.2                      December 21, 2012                 ZSHCOMPSYS(1)
Impressum