zshcompsys - zsh completion system


DESCRIPTION

       This  describes the shell code for the new completion sys­
       tem.  It consists of various shell functions; those begin­
       ning  `comp'  are to be called directly by the user, while
       those beginning `_' are called  by  the  completion  code.
       The shell functions of the second set which implement com­
       pletion behaviour and which may be  bound  to  keystrokes,
       are referred to as `widgets'.


INITIALIZATION

       If  the  system  was  installed  completely,  it should be
       enough to call the shell function compinit from your  ini­
       tialization  file;  see  the  next  section.  However, the
       function compinstall can be run by  a  user  to  configure
       various aspects of the completion system.

       Usually,   compinstall   will  insert  code  into  .zshrc,
       although if that is  not  writable  it  will  save  it  in
       another file and tell you that file's location.  Note that
       it is up to you to make  sure  that  the  lines  added  to
       .zshrc  are  actually  run;  you may, for example, need to
       move them to an earlier place in the file if  .zshrc  usu­
       ally returns early.  So long as you keep them all together
       (including the comment lines at the start and finish), you
       can  rerun  compinstall  and  it will correctly locate and
       modify these lines.  Note, however, that any code you  add
       to  this section by hand is likely to be lost if you rerun
       compinstall, although lines  using  the  command  `zstyle'
       should be gracefully handled.

       The  new  code  will  take  effect next time you start the
       shell, or run .zshrc by hand; there is also an  option  to
       make  them  take  effect immediately.  However, if compin­
       stall has removed definitions, you will  need  to  restart
       the shell to see the changes.

       To  run  compinstall you will need to make sure it is in a
       directory mentioned in your fpath parameter, which  should
       already be the case if zsh was properly configured as long
       as your startup files do not remove the appropriate direc­
       tories  from fpath.  Then it must be autoloaded (`autoload
       -U  compinstall'  is  recommended).   You  can  abort  the
       installation  any time you are being prompted for informa­
       tion, and your .zshrc will not be altered at all;  changes
       only  take  place right at the end, where you are specifi­
       cally asked for confirmation.

       This section describes the use of compinit  to  initialize
       completion  for  the  current session when run directly by
       the user; if you have run compinstall it  will  be  called
       automatically from your .zshrc.

       To  initialize the system, the function compinit should be
       in a directory  mentioned  in  the  fpath  parameter,  and
       should  be  autoloaded  (`autoload  -U compinit' is recom­
       mended), and then run simply  as  `compinit'.   This  will
       define a few utility functions, arrange for all the neces­
       sary shell functions  to  be  autoloaded,  and  will  then
       re-define  all  widgets  that do completion to use the new
       system.  If you use the menu-select widget, which is  part
       of the zsh/complist module, you should make sure that that
       module is loaded before the call to compinit so that  that
       widget  is  also  re-defined.   If  completion styles (see
       below) are set up to perform expansion as well as  comple­
       tion   by   default,   and   the   TAB  key  is  bound  to
       expand-or-complete,  compinit  will  rebind  it  to   com­
       plete-word;  this  is necessary to use the correct form of
       expansion.

       Should you need to use the original  completion  commands,
       you  can  still  bind keys to the old widgets by putting a
       `.' in front of the  widget  name,  e.g.  `.expand-or-com­
       plete'.

       To  speed  up  the  running of compinit, it can be made to
       produce a dumped configuration which will be  read  in  on
       future  invocations;  this is the default, although it can
       be turned off by calling compinit with the option -D.  The
       dumped  file  is  .zcompdump  in the same directory as the
       startup files (i.e. $ZDOTDIR or $HOME); alternatively,  an
       explicit file name can be given by `compinit -d dumpfile'.
       On the next call to compinit, it will read the dumped file
       instead of performing a full initialization.

       If  the  number of completion files changes, compinit will
       recognise this and produce a new dump file.   However,  if
       the  name of a function or the arguments in the first line
       of a #compdef function (as described below) change, it  is
       easiest  to  delete the dump file by hand so that compinit
       will re-create it the next time it is run.  The check per­
       formed to see if there are new functions can be omitted by
       giving the option -C.  In this case  the  dump  file  will
       only be created if there isn't one already.

       The  dumping  is  actually done by another function, comp­
       dump, but you will only need to run this yourself  if  you
       change  the  configuration  (e.g.  using compdef) and then
       want to dump the new one.  The name of the old dumped file
       will be remembered for this purpose.

       directory where completion functions can be found; this is
       only  necessary  if  they  are not already in the function
       search path.

       For security reasons compinit also checks if  the  comple­
       tion  system  would  use files not owned by root or by the
       current user, or files in directories that are  world-  or
       group-writable  or  that  are  not owned by root or by the
       current user.  If such files  or  directories  are  found,
       compinit  will  ask if the completion system should really
       be used.  To avoid these tests and make all files found be
       used  without  asking,  use  the  option  -u,  and to make
       compinit silently ignore all insecure files  and  directo­
       ries  use  the  option -i.  This security check is skipped
       entirely when the -C option is given.

       The security check can be retried at any time  by  running
       the  function  compaudit.   This is the same check used by
       compinit, but when it is executed directly any changes  to
       fpath  are  made local to the function so they do not per­
       sist.  The directories to be  checked  may  be  passed  as
       arguments;  if  none  are  given, compaudit uses fpath and
       _compdir to find  completion  system  directories,  adding
       missing  ones  to fpath as necessary.  To force a check of
       exactly the directories  currently  named  in  fpath,  set
       _compdir  to  an  empty string before calling compaudit or
       compinit.

   Autoloaded files
       The convention for autoloaded functions used in completion
       is  that  they  start  with an underscore; as already men­
       tioned, the fpath/FPATH parameter must contain the  direc­
       tory  in  which  they  are  stored.   If  zsh was properly
       installed on your system, then  fpath/FPATH  automatically
       contains  the  required directories for the standard func­
       tions.

       For incomplete installations, if compinit  does  not  find
       enough  files  beginning  with  an  underscore (fewer than
       twenty) in the search path, it will try to  find  more  by
       adding the directory _compdir to the search path.  If that
       directory has a subdirectory named Base,  all  subdirecto­
       ries  will be added to the path.  Furthermore, if the sub­
       directory Base has a  subdirectory  named  Core,  compinit
       will  add  all  subdirectories of the subdirectories is to
       the path: this allows the functions to be in the same for­
       mat as in the zsh source distribution.

       When  compinit is run, it searches all such files accessi­
       ble via fpath/FPATH and reads the first line  of  each  of
       them.   This line should contain one of the tags described
       below.  Files whose first line does not start with one  of

       system and will not be treated specially.

       The tags are:

       #compdef names...
              The file will be made autoloadable and the function
              defined in it will be called when completing names,
              each of which is either the name of a command whose
              arguments are to be completed or one of a number of
              special contexts in the  form  -context-  described
              below for the _complete function.

              Each  name  may  also be of the form `cmd=service'.
              This is used by functions that offer multiple  ser­
              vices, i.e. different completion behaviour for mul­
              tiple commands.  Such a string makes the completion
              system  call the function when completing arguments
              for the command `cmd', setting the parameter  $ser­
              vice  to  the  string  `service'.  The function can
              then use that parameter to decide what to complete.

       #compdef -p pattern
              The file will be made autoloadable and the function
              defined in it will be called when completing for  a
              command  whose  name  matches  the given pattern (a
              standard globbing pattern).   Note  that  only  one
              pattern may be given.

       #compdef -P pattern
              Like  the  previous  one,  but the function will be
              called only if no completion function for the  com­
              mand on the line could be found.

       #compdef -k style key-sequences...
              This  can  be used to bind special completion func­
              tions to the key-sequences specified.  It creates a
              widget  behaving  like  the  builtin  widget style,
              which must be one of those that perform completion,
              namely      complete-word,     delete-char-or-list,
              expand-or-complete,      expand-or-complete-prefix,
              list-choices,   menu-complete,  menu-expand-or-com­
              plete, or reverse-menu-complete.  If  the  zsh/com­
              plist  module  is  loaded  (see zshmodules(1)), the
              same happens to the menu-select widget.

              The widget is then bound to all  the  key-sequences
              given,  if  any:  when  one of the key-sequences is
              typed, the function in the file will be invoked  to
              generate  the matches.  Note that a key will not be
              re-bound if if it already was (that is,  was  bound
              to something other than undefined-key).  The widget
              created has the same name as the file  and  can  be
              bound to any other keys using bindkey as usual.

              This  is  similar  to  -k,  with the same style and
              key-sequences arguments, preceded by a string  giv­
              ing  the  name  of a widget.  In this case only one
              key-sequences argument may be given, but the entire
              set  of three arguments may be repeated with a dif­
              ferent set of arguments.  In particular,  the  wid­
              get-name  must  be distinct in each set.  It should
              begin with `_', else one will be added, and  should
              not  clash  with  the  name of any existing widget:
              names based on the name of the  function  are  most
              useful.  For example,

                     #compdef -K _foo_complete complete-word "^X^C" \
                       _foo_list list-choices "^X^D"

              (all  on  one  line) defines a widget _foo_complete
              for completion,  bound  to  `^X^C',  and  a  widget
              _foo_list for listing, bound to `^X^D'.

       #autoload [ options ]
              This  is  used for files defining utility functions
              that are not to be called  directly  as  completion
              functions  but  should be loaded automatically when
              invoked.  Typically they  are  to  be  called  from
              within one of the completion functions.

              The  options  will be given to the autoload builtin
              command when making the function autoloaded.   Most
              often,  this will be +X to force the function to be
              loaded immediately.   Note  that  the  -U  flag  is
              always implicitly added.

       The  #  is  part  of  the  tag  name and no white space is
       allowed after it.  The #compdef tags use the compdef func­
       tion described below; the main difference is that the name
       of the function is supplied implicitly.

       Note also that the functions  for  the  completion  system
       assume  that the KSH_AUTOLOAD option is not set and cannot
       be loaded when it  is  set.   To  avoid  having  to  unset
       KSH_AUTOLOAD,  you can instead use one or more zwc file(s)
       which have been created with the command  zcompile  -z  to
       load  the  functions  for  the completion system; see zsh­
       builtins(1).  This forces the functions to  be  autoloaded
       the way zsh normally loads functions.

   Functions
       The  compinit  file  defines the following function, which
       may also be called directly by the user.

       compdef [ -an ] function names...

       compdef -p [ -a ] function pattern
       compdef -P [ -a ] function pattern
       compdef -k [ -an ] function style key-sequences...
       compdef -K [ -an ] function name style key-sequences ...
              The first form tells the completion system to  call
              the given function when completing for the contexts
              or commands whose names are given:   this  is  like
              the  #compdef tag unless the first word contains an
              equal sign.  In this case all words have to  be  of
              the form `cmd=service' where service is the name of
              a command or of a service defined by an  autoloaded
              function  with  the #compdef tag and an argument of
              the form `cmd=service'.  This kind of use makes the
              arguments of the cmds be completed as those for the
              services.

              If the -n option is given, any existing  completion
              behaviour  for particular contexts or commands will
              not be altered.  These definitions can  be  deleted
              by giving the -d option as in the second form.

              The form with -p is similar to the first, but func­
              tion will be called for  all  commands  whose  name
              matches  the  pattern; this is like the #compdef -p
              function tag.

              The form with -P is like the third, but  the  func­
              tion  will  be  called  only if no function for the
              command itself was found or if one was found and it
              set the _compskip parameter to a value not contain­
              ing the substring patterns.

              The form with -k defines a  widget  with  the  same
              name  as the function which will be called for each
              of the key-sequences; this is like the #compdef  -k
              tag.   The function should generate the completions
              needed and will otherwise behave like  the  builtin
              widget  whose  name is given as the style argument.
              The widgets usable  for  this  are:  complete-word,
              delete-char-or-list,            expand-or-complete,
              expand-or-complete-prefix, list-choices,  menu-com­
              plete,         menu-expand-or-complete,         and
              reverse-menu-complete, as well  as  menu-select  if
              the  zsh/complist  module is loaded.  The option -n
              prevents the key being bound if it  is  already  to
              bound to something other than undefined-key.

              The  form  with  -K is similar and defines multiple
              widgets based on the same function, each  of  which
              requires the set of three arguments name, style and
              key-sequences, where the latter two are as  for  -k
              and  the  first must be a unique widget name begin­
              ning with an underscore.

              makes the function autoloadable (exactly equivalent
              to autoload -U function).

       The compdef function is the place  to  turn  to  when  one
       wants to define what the completion system should complete
       for a certain command.  The function named can  of  course
       be  one  of  the  functions supplied or one written by the
       user.  For example, if one has a  command  foo  that  gets
       process identifiers as arguments, one could do:

              compdef _pids foo

       using the _pids function from the distribution to generate
       the process identifiers.  Not also the _gnu_generic  func­
       tion  described  below,  which  can  be  used  to complete
       options for commands that understand the `--help'  option.


COMPLETION SYSTEM CONFIGURATION

       This  section gives a short overview of how the completion
       system works, and then more detail on how users  can  con­
       figure how and when matches are generated.

   Overview
       When  completion  is attempted somewhere on a command line
       the completion system first tries to find out the  context
       where  completion  was tried.  The context depends on such
       things as the name of the command when completing an argu­
       ment,  and  possibly  also the name of an option when com­
       pleting an argument to that option.

       The `context' of a completion is a  string  consisting  of
       multiple  fields.  This is used to look up styles that can
       be used to configure the completion system.  Since  it  is
       not possible to build the whole context string in advance,
       completion functions may modify some  of  the  fields  and
       hence the context used for lookup may vary during the same
       call to the completion system.

       The  context  string  always  consists  of  the  following
       fields,  separated  by  colons  and  with  a leading colon
       before the first:

       ·      The literal string  completion,  saying  that  this
              style is used by the completion system.

       ·      The  function;  in  many  cases  this field will be
              blank, but when the  completion  system  is  called
              from other functions, like predict-on or one of the
              functions in the Command directory of the distribu­
              tion,   this   field  contains  the  name  of  that


       ·      The completer currently active, which is  the  name
              of  the function without the leading underscore.  A
              `completer' is in overall control of how completion
              is to be performed; `complete' is the basic one for
              ordinary completion,  but  completers  may  perform
              various related tasks such as correction, or modify
              the behaviour of a later completer (see the section
              `Control Functions' below for more information).

       ·      The  context or command.  This is either one of the
              special  context  names  such  as  -condition-   as
              explained for the _complete completer below, or the
              name of the command  we  are  completing  arguments
              for.   Completion  functions for commands that have
              sub-commands usually modify this field  to  contain
              the  name  of  the command followed by a minus sign
              and the sub-command (e.g. the  completion  function
              for the cvs command sets this field to strings such
              as cvs-add when completing  for  the  add  sub-com­
              mand).

       ·      The argument, describing which argument we are com­
              pleting.  Normally this is either a string  of  the
              form argument-n, where n is the number of the argu­
              ment or it is a string  of  the  form  option-opt-n
              when  completing  the  n'th  argument of the option
              opt.

       ·      The tag.  Tags are used to discriminate between the
              types of matches a completion function can generate
              in a certain context.

       As an example, the context name

              :completion::complete:dvips:option-o-1:files

       says that normal completion was attempted on  an  argument
       of  the  dvips  command  (more  precisely:  completion was
       attempted on the first argument after the -o  option)  and
       the  completion  function will generate filenames for this
       context.

       In many of the possible contexts the completion system can
       generate  matches, often multiple types of matches.  These
       types are represented as simple names called `tags'.   The
       completion system will decide internally what sort of tags
       are allowed; a list of the standard possibilities is given

       used by the completion function, the `tag-order' style for
       the  appropriate  context  may be set, as described in the
       list of  standard  styles  below.   Only  those  types  of
       matches  whose  tags  were  selected by this style will be
       produced, and in the order given, although the default  is
       to  try  all  relevant  tags in an order determined by the
       particular completion in use.

       The _complete_help bindable command described in the  sec­
       tion  `Bindable Commands' below can be invoked to find out
       the context and tag names and styles used at a  particular
       point  in  completion.   It shows the list of contexts and
       tags that would be used in if completion were tried at the
       current  cursor  position.   Hence one can easily find out
       all the information needed to change the behaviour of  the
       tag-order style for a particular context.

       Completion  behaviour  can  be  modified  by various other
       styles defined with the zstyle builtin command  (see  zsh­
       modules(1)).  When looking up styles the completion system
       uses full context names, including the tag.

       Styles determine such things as how the matches are gener­
       ated;  some of them correspond to shell options (for exam­
       ple, the use of menu completion), but styles provide  more
       specific  control.  They can have any number of strings as
       their value.  Looking up the value of  a  style  therefore
       consists of two things:  the context, which may be matched
       as a pattern, and the name of the style itself, which must
       be given exactly.

       For   example,  many  completion  functions  can  generate
       matches in a simple and a verbose form and use the verbose
       style  to  decide  which form should be used.  To make all
       such functions use the verbose form, put

              zstyle ':completion:*' verbose yes

       in one of the startup files  like  .zshrc;  this  sort  of
       style  can  also  be configured with the compinstall func­
       tion.  This definition simply means that the verbose style
       has  yes  as its value in every context inside the comple­
       tion system.  If the context pattern were `*', the verbose
       style  would  have this value anywhere the style mechanism
       is used, not just in completion.

       As a more specific example, the  completion  function  for
       the  kill builtin command uses the verbose style to decide
       if jobs and processes are listed only as job  numbers  and
       process  identifiers  or  if they are listed with the full
       job texts and the command lines of the processes (the lat­
       ter  is achieved by calling the ps command).  To make this
       builtin list the matches only as numbers one could call:


       Furthermore, if one wanted to see the  command  lines  for
       processes  but  not  the  job texts one could use the fact
       that the context name contains the tag  name  when  styles
       are  looked up.  As the function for the kill builtin com­
       mand uses the tags jobs and processes, we can use:

              zstyle ':completion:*:*:kill:*:jobs' verbose no

       To have more control over when certain values  for  styles
       are  used  one can use the special parameters available in
       completion widgets (see see  zshcompwid(1)))  and  the  -e
       option  to  zstyle  that makes the value be evaluated when
       looked up.  For example, to make the completer style  have
       a different value when completing for the cvs command, one
       could use the words special array:

              zstyle -e ':completion:*' completer '
                  if [[ $words[1] = cvs ]]; then
                    reply=(_complete)
                  else
                    reply=(_complete _approximate)
                  fi'

       One should be careful not to use too complicated code with
       this  option,  at  least for the styles that are looked up
       quite often.  These are basically those that  define  some
       global completion behaviour but allow that to be different
       for all matches or groups of matches (such as the menu and
       list-rows-first styles).  Alternatively one can always use
       a less general pattern for the context than in the example
       above  and use a second call to zstyle with a generic pat­
       tern and without using the -e option to define the default
       behaviour.

       Note  that  the order in which styles are defined does not
       matter; the style mechanism uses the most specific  possi­
       ble  match  for a particular style to determine the set of
       values.  More precisely, strings are preferred  over  pat­
       terns  (for  example,  `:completion::complete:foo' is more
       specific than `:completion::complete:*'), and longer  pat­
       terns are preferred over shorter patterns.

       As  with tags, completion functions can use any style they
       choose, so there can't be a complete list.   However,  the
       following two sections list those tags and styles that are
       used in many places of the completion system.

   Standard Tags
       Here are the tags currently used by the completion system.
       Some  of  them are only used when looking up styles and do
       not refer to a particular type of match.

              used to look up the users-hosts style

       all-expansions
              used by the _expand completer when adding the  sin­
              gle string containing all possible expansions

       all-files
              for the names of all files (as distinct from a par­
              ticular subset, see the globbed-files tag).

       arguments
              when an argument of a command may be completed

       arrays for names of array parameters

       association-keys
              for keys of associative arrays; used when  complet­
              ing inside a subscript of a parameter of this type

       bookmarks
              when  completing  bookmarks  (e.g. for URLs and the
              zftp function suite)

       builtins
              for names of builtin commands

       characters
              used for commands like stty when completing charac­
              ters;  also  used when completing character classes
              after a opening bracket

       colormapids
              for X colormap ids

       colors for color names

       commands
              for  names  of  external  commands  and  names   of
              sub-commands (used by some commands like cvs)

       contexts
              for contexts used by the zstyle builtin command

       corrections
              used  by  the  _approximate and _correct completers
              for the possible corrections

       cursors
              for cursor names used by X programs

       default
              used to look up default values for  various  styles
              that  may  also  be set for tags that are used when

              only  the function field of the context name is set
              up

       descriptions
              used when looking up the value of the format  style
              for descriptions

       devices
              for names of device special files

       directories
              for names of directories

       directory-stack
              for entries in the directory stack

       displays
              for X display names

       domains
              for network domains

       expansions
              used by the _expand completer for individual possi­
              bilities resulting from expansion of a word

       extensions
              for X server extensions

       file-descriptors
              for the numbers of open file descriptors

       files  the generic file-matching tag  used  by  completion
              functions  that can complete the names of some kind
              of file

       fonts  used for X font names

       functions
              names  of  functions,  normally   shell   functions
              although  certain  commands  may  understand  other
              kinds of function

       globbed-files
              for names of files matching the glob  pattern  used
              by  completion functions that expect a certain type
              of file

       groups used when completing names of user groups

       history-words
              for words from the history


       indexes
              used for array indexes

       jobs   used for jobs

       keymaps
              for names of zsh keymaps

       keysyms
              for names of X keysyms

       libraries
              for names of system libraries

       limits for system limits

       local-directories
              for names of directories which  are  subdirectories
              of  the  current  working directory when completing
              for the cd and related builtin commands

       manuals
              for names of manual pages

       maps   for map names (e.g. NIS maps)

       messages
              used to look up the format style for messages

       modifiers
              for names of X modifiers

       modules
              for modules (e.g. zsh modules)

       my-accounts
              used to look up the users-hosts style

       named-directories
              for named directories (you  wouldn't  have  guessed
              that, would you?)

       names  for all kinds of names

       nicknames
              for nicknames of NIS maps

       options
              for command options

       original
              used  by  the  _approximate,  _correct  and _expand


       other-accounts
              used to look up the users-hosts style

       packages
              for packages (e.g. rpm or  installed  Debian  pack­
              ages)

       parameters
              for names of parameters

       path-directories
              for  names  of  directories  found by searching the
              cdpath array when completing for the cd and related
              builtin commands

       paths  used to look up the values of the expand, ambiguous
              and special-dirs styles

       pods   for perl pods (documentation files)

       ports  for communication ports

       prefixes
              for prefixes (like those of a URL)

       printers
              for printer names

       processes
              for process identifiers

       processes-names
              used to look up the command style  when  generating
              the names of processes for killall

       sequences
              for sequences (e.g. mh sequences)

       sessions
              for sessions in the zftp function suite

       signals
              for signal names

       strings
              for  strings  (e.g. the replacement strings for the
              cd builtin command)

       styles for styles used by the zstyle builtin command

       tags   for tags (e.g. rpm tags)

              for makefile targets

       types  for types of whatever (e.g. address types  for  the
              xhost command)

       urls   used to look up the urls and local styles when com­
              pleting URLs

       users  for usernames

       values when completing a value out of a set of values  (or
              a list of such values)

       version
              used by _call_program to look up the command to run
              to determine the installed version of various other
              commands (such as diff and make).

       warnings
              used to look up the format style for warnings

       widgets
              for zsh widget names

       windows
              for IDs of X windows

       zsh-options
              for shell options

   Standard Styles
       Here  are  the  names of the styles used by the completion
       system.  Note that the values of several of  these  styles
       represent boolean values; here, any of the strings `true',
       `on', `yes', and `1' can  be  used  for  the  truth  value
       `true'  and  the strings `false', `off', `no', and `0' are
       interpreted as `false'.  The behavior for any other  value
       is  undefined  unless  the  description for the particular
       style mentions other possible values; in  particular,  the
       default  value may be either on or off if the style is not
       set.

       Some of these styles are tested for every tag used to  add
       possible  matches  and  for  the default tag (most notably
       menu, list-colors and the styles controlling  the  comple­
       tion  listing  like  list-packed  and  last-prompt).  When
       tested for the default tag, only the function field of the
       context will be set up, so the default value will normally
       be set like:

              zstyle ':completion:*:default' menu ...

              This is tested for the default  tag  and  the  tags
              used  when  generating  matches.   If  it is set to
              `true' for at least one match which is the same  as
              the string on the line, this match will immediately
              be accepted.

              When completing pathnames (where it  is  looked  up
              for  the  paths  tag),  this style also accepts any
              number of patterns as the value. If this  is  used,
              pathnames  matching  one  of these patterns will be
              accepted immediately even if the command line  con­
              tains some more partially typed pathname components
              and  these  match  no  file  under  the   directory
              accepted.

              Note  that  this  is  also used by the _expand com­
              pleter to decide if words beginning with a tilde or
              parameter  expansion should be expanded. This means
              that if, for example, there are parameters foo  and
              foobar,  the string `$foo' will only be expanded if
              accept-exact is set to `true'.

       add-space
              This style is used by the _expand completer.  If it
              is  `true'  (the default), a space will be inserted
              after  all  words  resulting  from  the   expansion
              (except  for  directory  names  which get a slash).
              The value may also be the string `file' to make the
              completer  add  a  space  only to names of existing
              files.  Finally, the `true' values and  `file'  may
              be combined with `subst' to keep the completer from
              adding a space when the resulting words were gener­
              ated  by  expanding  a  substitution  of  the  form
              `$(...)' or `${...}'.

              It is also used by the _prefix completer as a  sim­
              ple  boolean  value  to decide if a space should be
              inserted before the suffix.

       ambiguous
              This applies when completing  non-final  components
              of  filename  paths.   If  it is set, the cursor is
              left after the first ambiguous component,  even  if
              menu  completion  is in use.  It is tested with the
              paths tag.

       assign-list
              When completing after an equals sign,  the  comple­
              tion  system  normally completes only one filename.
              In some cases, particularly for certain  parameters
              such  as  PATH,  a  list  of filenames separated by
              colons is required.  This style can  be  set  to  a
              list   of  patterns  matching  the  names  of  such


              The default is to complete lists when the  word  on
              the line already contains a colon.

       auto-description
              If  set,  this  style's  value  will be used as the
              description for options which are not described  by
              the completion functions, but that have exactly one
              argument.  The sequence `%d' in the value  will  be
              replaced  by  the  description  for  this argument.
              Depending on personal preferences, it may be useful
              to  set this style to something like `specify: %d'.
              Note that this may not work for some commands.

       avoid-completer
              This is  used  by  the  _all_matches  completer  to
              decide  if  the  string  consisting  of all matches
              should be added to the list currently being  gener­
              ated.   Its value is a list of names of completers.
              If any of these is the name of the  completer  that
              generated  the  matches  in  this  completion,  the
              string will not be added.

              The  default  value  for  this  style  is  `_expand
              _old_list  _correct _approximate', i.e. it contains
              the completers for which a string with all  matches
              will almost never be wanted.

       cache-path
              This  style  defines the path where any cache files
              containing  dumped  completion  data  are   stored.
              Defaults      to     `$ZDOTDIR/.zcompcache',     or
              `$HOME/.zcompcache' if  $ZDOTDIR  is  not  defined.
              The  completion  layer  will not be used unless the
              use-cache style is set.

       call-command
              Currently this is only used by  the  function  com­
              pleting  make  targets.  If it is set to `true' and
              the installed version of the  make  command  allows
              it,  make is called in a way to generate all possi­
              ble targets.  The default value of  this  style  is
              `false' because calling make can potentially take a
              very long time and in some  cases  may  even  cause
              actions  from  the makefile be executed despite the
              options given to make.

       command
              In many places, completion functions need  to  call
              external  commands  to generate the list of comple­
              tions.  This style can be used to override the com­
              mand  which is called in some such cases.  The ele­
              ments of the value are joined with spaces to form a

              with a hyphen, in which case the usual command will
              be  added  to  the  end;  this  is  most useful for
              putting `builtin' or `command'  in  front  to  make
              sure  the  appropriate  version  of  a  command  is
              called, for example to avoid calling a shell  func­
              tion with the same name as an external command.

              As  an example, the function generating process IDs
              as matches uses this style with the  processes  tag
              to  generate  the  IDs  to complete and the list of
              processes to  display  (if  the  verbose  style  is
              `true').   The  list produced by the command should
              look like the output of the ps command.  The  first
              line  is  not  displayed,  but  is searched for the
              string `PID' (or `pid') to find the position of the
              process  IDs  in  the following lines.  If the line
              does not contain `PID', the first numbers  in  each
              of  the other lines are taken as the process IDs to
              complete.

              Note that the completion function generally has  to
              call  the command every time it is called.  Because
              of that care should be taken to specify  only  com­
              mands  that take a short time to run (and that will
              eventually stop at all).

       commands
              This is used by the  function  completing  sub-com­
              mands for the system initialisation scripts (resid­
              ing in /etc/init.d or somewhere not  too  far  away
              from  that).  It's values give the default commands
              to complete for those commands for which  the  com­
              pletion  function isn't able to find them out auto­
              matically.  The default for this style are the  two
              strings `start' and `stop'.

       complete
              This  is  used  by  the _expand_alias function when
              invoked as a bindable command.  If it set to `true'
              and the word on the command line is not the name of
              an alias, matching alias names will be completed.

       completer
              The strings given as the value of this  style  pro­
              vide  the  names of the completer functions to use.
              The available completer functions are described  in
              the section `Control Functions' below.

              Each string may be the name of a completer function
              or a string of the  form  `function:name'.  In  the
              first  case the completer field of the context will
              contain the name of the completer without the lead­
              ing  underscore  and  with  all  other  underscores

              tion  is the name of the completer to call, but the
              context will contain  the  name  in  the  completer
              field  of  the  context.  If the name starts with a
              hyphen, the string for the context  will  be  build
              from  the  name of the completer function as in the
              first case with the name appended to it.  For exam­
              ple:

                     zstyle ':completion:*' completer _complete _complete:-foo

              Here,  completion will call the _complete completer
              twice, once using `complete' and once  using  `com­
              plete-foo'  in  the completer field of the context.
              Normally, using the same completer more  than  once
              makes   only   sense  when  used  with  the  `func­
              tions:name' form,  because  otherwise  the  context
              name  will  be  the  same  in all calls to the com­
              pleter; possible exceptions to this  rule  are  the
              _ignored and _prefix completers.

              The  default  value  for  this  style  is _complete
              _ignored, i.e. normally  only  completion  will  be
              done,  first  using  the ignored-patterns style and
              the  $fignore  array  and  then  without   ignoring
              matches.

       condition
              This  style is used by the _list completer function
              to decide if insertion of matches should be delayed
              unconditionally. The default is `true'.

       disabled
              If  this  is  set to `true', the _expand_alias com­
              pleter and bindable command will try to expand dis­
              abled aliases, too.  The default is `false'.

       disable-stat
              This is used with an empty tag by the function com­
              pleting for  the  cvs  command  to  decide  if  the
              zsh/stat module should be used to generate names of
              modified files in the appropriate places  (this  is
              its  only use).  If set, completion will use the ls
              command.

       domains
              If set, gives the names  of  network  domains  that
              should  be  completed.   If  this is not set by the
              user domain names  will  be  taken  from  the  file
              /etc/resolv.conf.

       expand This style is used when completing strings consist­
              ing of multiple parts, such as path names.  If  its
              value  contains  the string `prefix', the partially

              possible  even  if  trailing  parts  cannot be com­
              pleted.  If it contains  the  string  `suffix'  and
              normal  (non-menu-)  completion  is  used, matching
              names for components after the first ambiguous  one
              will  also be added.  This means that the resulting
              string is the longest unambiguous string  possible,
              but  if  menu  completion is started on the list of
              matches generated this way (e.g. due to the  option
              AUTO_MENU  being set), this will also cycle through
              the names of the files in pathname components after
              the first ambiguous one.

       fake-files
              This style is used when completing files and looked
              up without a tag.   Its  values  are  of  the  form
              `dir:names...'.   This  will add the names (strings
              separated by spaces) as possible matches when  com­
              pleting in the directory dir, even if no such files
              really exist.

              This can be useful on systems that support  special
              filesystems  whose  top-level  pathnames can not be
              listed or generated with  glob  patterns.   It  can
              also be used for directories for which one does not
              have read permission.

       fake-parameters
              This is used by the completion function  generating
              parameter  names  as matches.  Its values are names
              of parameters which might not yet be set, but which
              should  be  completed  nonetheless.   Each name may
              also be followed by a colon and a string specifying
              the  type  of the parameter (like `scalar', `array'
              or `integer').  If such a type is given,  the  name
              will  only  be completed if parameters of that type
              are requested in the particular context.  Names for
              which  no  type  is  specified  will always be com­
              pleted.

       file-patterns
              In most places where filenames are  completed,  the
              function  _files  is  used  which can be configured
              with this style.  If the  style  is  unset,  _files
              offers,  one  after  another,  up  to  three  tags:
              `globbed-files',  `directories'  and   `all-files',
              depending  on  the  types  of files expected by the
              caller of _files.

              If the file-patterns style is set, the default tags
              are not used.  Instead, the value of the style says
              which tags and which patterns are  to  be  offered.
              The  strings in the value contain specifications of
              the form `pattern:tag'; each string may contain any

              glob pattern that is to be used to  generate  file­
              names.   If  it contains the sequence `%p', that is
              replaced by the pattern(s)  given  by  the  calling
              function.   Colons  in the pattern must be preceded
              by a backslash to make  them  distinguishable  from
              the colon before the tag.  If more than one pattern
              is needed, the patterns can be given inside braces,
              separated  by  commas.   The tags of all strings in
              the value will be offered  by  _files  (again,  one
              after  another)  and  used  when  looking  up other
              styles.  For strings containing more than one spec­
              ification,  the  filenames  for  all specifications
              will be generated at the same try.  If no `:tag' is
              given  the  `files'  tag will be used.  The tag may
              also be followed by an optional second colon and  a
              description.   If  that  is given, this description
              will be used for the `%d' in the value of the  for­
              mat  style  (if that is set) instead of the default
              description supplied by  the  completion  function.
              If  the  description  given  here contains itself a
              `%d', that is replaced with  the  description  sup­
              plied by the completion function.

              For  example, to make the rm command first complete
              only names of object files and  the  names  of  all
              files  if  no object file matches the string on the
              line, one would do:

                     zstyle ':completion:*:*:rm:*' file-patterns \
                         '*.o:object-files' '%p:all-files'

              Another  interesting  example  is  to  change   the
              default behaviour that makes completion first offer
              files matching the patterns given  by  the  calling
              function,  then  directories  and  then  all files.
              Many people prefer to get both the  files  matching
              the given patterns and the directories in the first
              try and all files at the second  try.   To  achieve
              this, one could do:

                     zstyle ':completion:*' file-patterns \
                         '%p:globbed-files *(-/):directories' '*:all-files'

              This  works  even  for  contexts in which all files
              would be completed, because _files will not  try  a
              pattern  more  than once and it stops when the pat­
              tern `*' was tried.

              Note also that during the execution  of  completion
              functions,  the  EXTENDED_GLOB option is in effect,
              so the characters `#', `~'  and  `^'  have  special
              meanings in the patterns.

              The completion function that generates filenames as
              possible matches uses this style without a  tag  to
              determine in which order the names should be listed
              and completed  when  using  menu  completion.   The
              value may be one of `size' to sort them by the size
              of the file, `links' to sort them by the number  of
              links  to  the  file,  `modification' (or `time' or
              `date') to sort them by the last modification time,
              `access'  to  sort them by the last access time, or
              `inode' (or `change') to  sort  them  by  the  last
              inode  change  time.   If  the  style is set to any
              other value, or is  unset,  files  will  be  sorted
              alphabetically  by name.  If the value contains the
              string `reverse', sorting  is  done  in  decreasing
              order.

       force-list
              This  forces  a  list of completions to be shown at
              any point where listing  is  done,  even  in  cases
              where  the  list  would usually be suppressed.  For
              example, normally the list is only shown  if  there
              are  at  least  two  different matches.  By setting
              this style to `always', the  list  will  always  be
              shown,  even  if there is only a single match which
              is immediately accepted.  The style may also be set
              to  a  number.  In this case the list will be shown
              if there are at least that many  matches,  even  if
              they would all insert the same string.

              This  style  is  tested for the default tag and all
              tags used when generating matches. This allows  one
              to  turn unconditional listing on for certain types
              of matches.

       format If this is set for the descriptions tag, its  value
              is  used  as  a  string to display above matches in
              completion lists.  The sequence `%d' in this string
              will  be  replaced with a short description of what
              these matches are.  This string  may  also  contain
              the sequences to specify output attributes, such as
              `%B', `%S' and `%{...%}'.

              For the same purpose, this  style  is  also  tested
              with  the  tags  used  when  matches  are generated
              before it is tested for the descriptions tag.  This
              provides the possibility of defining different for­
              mat strings for different types of matches.

              Note also  that  some  completer  functions  define
              additional  `%'-sequences.  These are described for
              the completer functions that make use of them.

              For the messages tag, this style defines  a  string

              sages.  Here, the `%d' is replaced with  a  message
              given by the completion function.

              Finally, when set with the warnings tag, the format
              string is printed when no matches could  be  gener­
              ated  at  all.   In  this case the `%d' is replaced
              with the descriptions for  the  matches  that  were
              expected  separated by spaces and the sequence `%D'
              is replaced with those  descriptions  separated  by
              newlines.

              The  `%'  for  the  sequences  that are replaced by
              strings provided by the completion  functions  like
              the  `%d' may be followed by field width specifica­
              tions as  described for the zformat builtin command
              from the zsh/zutil module, see zshmodules(1).

       glob   This  is  used  by the _expand completer.  If it is
              set to  `true'  (the  default),  globbing  will  be
              attempted  on the words resulting from substitution
              (see the substitute style) or the  original  string
              from the line.

       global If  this  is  set  to  `true'  (the  default),  the
              _expand_alias completer and bindable  command  will
              try to expand global aliases.

       group-name
              The  completion  system  can put different types of
              matches in different groups  which  are  then  dis­
              played  separately  in the list of possible comple­
              tions.  This style can be used to  give  the  names
              for these groups for particular tags.  For example,
              in command position the completion system generates
              names  of  builtin  and external commands, names of
              aliases,  shell  functions   and   parameters   and
              reserved  words  as  possible completions.  To have
              the external commands and  shell  functions  listed
              separately, one can set:

                     zstyle ':completion:*:*:-command-:*:commands' group-name commands
                     zstyle ':completion:*:*:-command-:*:functions' group-name functions

              This  also  means that if the same name is used for
              different types of matches, then those matches will
              be displayed together in the same group.

              If  the  name  given  is the empty string, then the
              name of the tag for the matches will be used as the
              name  of the group. So, to have all different types
              of matches displayed separately, one can just set:

                     zstyle ':completion:*' group-name ''

              be put in a group named -default-.

       group-order
              This   style  is  to  be  used  together  with  the
              group-name style.  Once different types of  matches
              are  put  into  different groups, this style can be
              used to define in which order these  groups  should
              appear   when  listing  (compare  tag-order,  which
              determines which completions appear at  all).   The
              strings  in  the value are taken as group names and
              the named groups will be  shown  in  the  order  in
              which  their names appear in the value.  All groups
              whose names are not given  in  the  value  of  this
              style will appear in the order defined by the func­
              tion generating the matches.

              For example, to have  names  of  builtin  commands,
              shell  functions  and  external  commands appear in
              this order when completing in command position  one
              would set:

                     zstyle ':completion:*:*:-command-:*' group-order \
                            builtins functions commands

       groups A style holding the names of the groups that should
              be completed. If this is not set by the  user,  the
              group  names  from  the  YP  database  or  the file
              `/etc/group' will be used.

       hidden If this is set to one of  the  `true'  values,  the
              matches for the tags for which this is set will not
              appear in the list; only the  description  for  the
              matches as set with the format style will be shown.
              If this is set to `all', not even  the  description
              will be displayed.

              Note that the matches will still be completed; they
              are just not shown in the list.   To  avoid  having
              matches  considered as possible completions at all,
              the tag-order style can be  modified  as  described
              below.

       hosts  A  style  holding the names of hosts that should be
              completed. If this is not set by the user the host­
              names in `/etc/hosts' will be used.

       hosts-ports
              This  style is used by commands that need or accept
              hostnames and ports.   The  strings  in  the  value
              should be of the form `host:port'.  These hostnames
              and ports are completed depending on  the  informa­
              tion  already on the line, so that if, for example,
              the hostname is already  typed,  only  those  ports

              ple ports for the same host may appear.

       ignore-line
              This style is tested for the tags used when  gener­
              ating  matches.   If it is set to `true', then none
              of the words that are already on the line  will  be
              considered  possible  completions.  If it is set to
              `current', the word the cursor is on  will  not  be
              considered a possible completion.  The same happens
              if the value is `current-shown', but  only  if  the
              list  of  completions  is  currently  shown  on the
              screen.  Finally, if it is set to `other' all words
              except the current one will not be considered to be
              a possible completion.

              The values `current' and `current-shown' are a  bit
              like  the  opposite of accept-exact. They mean that
              only strings with missing characters will  be  com­
              pleted.

              Note  that  you  almost certainly don't want to set
              this to `true' or `other'  for  a  general  context
              such  as `:completion:*'.  This is because it would
              disallow completion of, for example, options multi­
              ple  times  even if the command in question accepts
              the option more than once.

       ignore-parents
              The style is  tested  by  the  function  completing
              pathnames  without  a  tag  to determine whether to
              ignore the names of directories  already  mentioned
              in  the  current  word,  or the name of the current
              working directory.  The value must include  one  or
              both of the following strings:

              parent The  name  of  any  directory  whose path is
                     already contained in the word on the line is
                     ignored.  For example, when completing after
                     foo/../, the directory foo will not be  con­
                     sidered a valid completion.

              pwd    The  name  of  the current working directory
                     will not be completed, so that, for example,
                     completion  after  ../ will not use the name
                     of the current directory.

              In addition, the value may include one or both of:

              ..     Ignore the specified directories  only  when
                     the  word on the line contains the substring
                     `../'.

                     Ignore only when names  of  directories  are
                     completed,  not  when  completing  names  of
                     files.

              Note that names of directories ignored  because  of
              one of the tests will be ignored in the same way as
              the matches ignored because of the ignored-patterns
              style.  I.e., by using the _ignored completer it is
              possible to complete these directories nonetheless.

       ignored-patterns
              This  style  can  be used to specify a list of pat­
              terns which are tested against  against  the  trial
              completions  in  a given context; any matching com­
              pletions will be removed from the list of possibil­
              ities.   The  _ignored  completer can appear in the
              list of completers to produce a list which includes
              these  matches  once  more.  This is a more config­
              urable version of the shell parameter $fignore.

              Note that during the execution of completion  func­
              tions,  the  EXTENDED_GLOB  option is in effect, so
              the characters `#', `~' and `^' have special  mean­
              ings in the patterns.

       insert-ids
              When  completing  process IDs, for example as argu­
              ments to the kill  and  wait  builtins,  completion
              allows  the  user  to  type  the name of a command,
              which will be converted to the appropriate  process
              ID.   A  problem arises when the process name typed
              is not unique.  By default (or if this style is set
              explicitly  to  `menu')  the name will be converted
              immediately to a set of possible IDs, and menu com­
              pletion  will be started to cycle through them.  If
              the value of the style is  `single',  however,  the
              shell  will wait until the user has typed enough to
              make the command unique before converting the  name
              to an ID; the user must type any additional charac­
              ters required.  If the value is any  other  string,
              menu  completion  will  be  started when the string
              typed by the user is longer than the common  prefix
              of the corresponding IDs.

       insert-tab
              If  this  has one of the `true' values, the comple­
              tion system will insert a TAB  character  (assuming
              it  was  used  to start completion) instead of per­
              forming completion when there is no non-blank char­
              acter  to  the  left  of  the  cursor.   If  set to
              `false', completion will be done even there.

              The value may also contain the substrings `pending'

              start completion be inserted instead of  completion
              being  tried  when there is input pending which has
              not yet been processed by the shell. If  a  val  is
              given,  completion will not be done if there are at
              least that many characters  of  unprocessed  input.
              This is often useful to have set when pasting char­
              acters into  a  terminal.  Note  however,  that  it
              relies  on  the $PENDING special parameter from the
              zsh/zle module being  set  properly  which  is  not
              guaranteed on all platforms.

              The  default  value  of this style is `true' unless
              when completing inside the vared  builtin  command,
              where it defaults to `false'.

       insert-unambiguous
              This  is  used  by the _match and _approximate com­
              pleter functions, where  the  possible  completions
              may  not  have a common prefix so that menu comple­
              tion is often the most useful may of choosing  com­
              pletions.   If the style is set to `true', the com­
              pleter will start menu completion only if no  unam­
              biguous  string could be generated that is at least
              as long as the original string typed by  the  user.
              Note  that the _approximate completer uses it after
              setting the completer field in the context name  to
              one of correct-num or approximate-num, where num is
              the number of errors that were accepted.

              When used for the _match completer, the  style  may
              also  be  set  to the string `pattern'.  This makes
              the pattern on the line be  left  unchanged  if  it
              didn't match unambiguously.

       keep-prefix
              This style is used by the _expand completer.  If it
              is `true', the completer will try to keep a  prefix
              containing  a  tilde or parameter expansion.  I.e.,
              the string `~/f*'  would  be  expanded  to  `~/foo'
              instead  of  `/home/user/foo'.  If the style is set
              to `changed' (the default), the prefix will only be
              left  unchanged if there were other changes between
              the expanded words and the original word  from  the
              command  line.  Any other value makes the prefix be
              expanded unconditionally.

              Note that  with  one  of  the  `true'  values,  the
              _expand  completer  returns  if  there  is only one
              expansion and that is, after restoring the original
              prefix,  the same as the original word.  This means
              that other completers will  be  called  immediately
              after _expand.

              This  is  used  to determine if the completion code
              should try to put the cursor back onto the previous
              command line after showing a completion listing (as
              for the ALWAYS_LAST_PROMPT option).  As  with  sev­
              eral other styles, it is tested for the default tag
              as well as all the possible  tags  when  generating
              matches.  The cursor will be moved back to the pre­
              vious line if this style is `true' for all types of
              matches  added.  Note also that this is independent
              of    the    numeric    argument,    unlike     the
              ALWAYS_LAST_PROMPT option.

       list   This  style  is  used by the _history_complete_word
              bindable command.  If it is set to `true' it has no
              effect,  but  if  it  is set to `false' the matches
              will not be listed, overriding the setting  of  the
              options  that control listing behaviour, especially
              AUTO_LIST. Use the context prefix `:completion:his­
              tory-words'.

       list-colors
              If  the zsh/complist module is used, this style can
              be used to set color  specifications  as  with  the
              ZLS_COLORS  and  ZLS_COLOURS parameters, which will
              not be honored under this  completion  system  (see
              the  section  `The  zsh/complist Module' in zshmod­
              ules(1)).

              If this style is  set  for  the  default  tag,  the
              strings  in  the  value are taken as specifications
              that are to be used everywhere.  If it is  set  for
              other  tags,  the  specifications are used only for
              matches of the type described by the tag.  For this
              to  work  best, the group-name style must be set to
              an empty string.  If the group-name  tag  specifies
              other  names  for  the  groups the matches in these
              groups can be colored by using these names together
              with  the  `(group)...'   syntax  described for the
              ZLS_COLORS and ZLS_COLOURS  parameters  and  adding
              the specifications to the value for this style with
              the default tag (although in most cases  it  should
              work  by  setting  this  style  for the appropriate
              tags).

              It is possible to use the same  specifications  set
              up for the GNU version of the ls command:

                     zstyle ':completion:*:default' list-colors ${(s.:.)LS_COLORS}

              The  default  colors are the same as for the GNU ls
              command and can be obtained by setting the style to
              an empty string (i.e. '').

              Like the list-colors style, this is tested with the
              default tag  and  all  tags  used  when  generating
              matches.   If  it  is  set to `true' for a tag, the
              matches added for it  will  be  listed  as  if  the
              LIST_PACKED  option  were  set.   If  it  is set to
              `false', they are listed normally.

       list-prompt
              If this style is set for the default  tag,  comple­
              tion  lists  that  don't  fit  on the screen can be
              scrolled (see the description of  the  zsh/complist
              module  in  zshmodules(1)).   The value, if not the
              empty string, will be displayed after every screen­
              ful  and  the shell will prompt for a key press; if
              the style is set to the  empty  string,  a  default
              prompt  will  be  used.   The value may contain the
              escape  sequences  `%l'  or  `%L',  which  will  be
              replaced  by  the number of the last line displayed
              and the total number of lines; `%m' or `%M',  which
              will  be  replaced by the number of the  last match
              shown and the total number of matches; and `%p' and
              `%P',  which  will be replaced by `Top' when at the
              beginning of the list, `Bottom' when at the end and
              the  position  shown in percent of the total length
              otherwise.  In each of these cases  the  form  with
              the  uppercase  letter  is  replaced by a string of
              fixed width, padded to the  right with spaces.   As
              in other prompt strings, the escape sequences `%S',
              `%s', `%B', `%b', `%U',  `%u',  and  `%{...%}'  for
              entering  and  leaving  the display modes standout,
              bold and underline are also available.

       list-rows-first
              This style  is  tested  in  the  same  way  as  the
              list-packed  style and determines if matches are to
              be listed in  a  rows-first  fashion,  as  for  the
              LIST_ROWS_FIRST option.

       list-suffixes
              This style is used by the function used to complete
              filenames.  If completion is attempted on a  string
              containing multiple partially typed pathname compo­
              nents and this style is set to `true',  all  compo­
              nents  starting  with  the first one for which more
              than one match could be generated will be shown.

       local  This style is used by  completion  functions  which
              generate  URLs  as possible matches to add suitable
              matches when a URL points to a  local  web  server,
              that  is, one whose files are available directly on
              the local file system.  Its value should consist of
              three  strings: a hostname, the path to the default
              web pages for the server  and  the  directory  name

              area.     For     example,     completion     after
              `http://toast/~yousir/'  will  attempt to match the
              name `toast' against  the  first  argument  to  the
              style, and if successful will look in the directory
              under ~yousir given by the third  argument  to  the
              style for possible completions.

       match-original
              This is used by the _match completer.  If it is set
              to only, _match will try to generate matches  with­
              out inserting a `*' at the cursor position.  If set
              to any other non-empty value, it will first try  to
              generate  matches  without inserting the `*' and if
              that yields no matches, it will try again with  the
              `*'  inserted.   If it is unset or set to the empty
              string, matching will only be  done  with  the  `*'
              inserted.

       matcher
              This  style is tested for tags used when generating
              matches.  Its value is used as an match  specifica­
              tion  additional  to  any given by the matcher-list
              style which should be in the form described in  the
              section `Matching Control' in zshcompwid(1).

       matcher-list
              This  style is used by the main completion function
              to retrieve match specifications  that  are  to  be
              used  everywhere.   Its  value  should be a list of
              such specifications.  The  completion  system  will
              try  them  one  after  another  for  each completer
              selected. For example, to first try simple  comple­
              tion and, if that generates no matches, case-insen­
              sitive completion one would do:

                     zstyle ':completion:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}'

              By default every  specification  replaces  previous
              ones.  If  specification  is prefixed with +, it is
              added to the existing  list.  This  allows  testing
              more  general  patterns without repeating the whole
              list every time, as in:

                     zstyle ':completion:*' matcher-list '' '+m{a-Z}={A-Z}' '+m{A-Z}={a-z}'

              The style allows even finer control by specifying a
              particular  completer,  without  the leading under­
              score, in the third field of  the  completion  con­
              text.   For  example,  if  one  uses the completers
              _complete and _prefix but wants to try  case-insen­
              sitive  completion  only  when  using the _complete
              completer, one would do:

                     zstyle ':completion:*:complete:*' matcher-list \
                            '' 'm:{a-zA-Z}={A-Za-z}'

              Note that the completer style  allows  user-defined
              names to be used in the context instead of the name
              of the completer.  This is useful if, for  example,
              one  wants to try normal completion without a match
              specification and  with  case-insensitive  matching
              first,  correction  if  that  doesn't  generate any
              matches and partial-word completion if that doesn't
              yield  any  matches  either.   In this case one can
              give the _complete completer more than once in  the
              completer style and define different match specifi­
              cations for each occurrence, as in:

                     zstyle ':completion:*' completer _complete _correct _complete:foo
                     zstyle ':completion:*:complete:*' matcher-list \
                         '' 'm:{a-zA-Z}={A-Za-z}'
                     zstyle ':completion:*:foo:*' matcher-list \
                         'm:{a-zA-Z}={A-Za-z} r:|[-_./]=* r:|=*'

              If the style is unset in any context no match spec­
              ification is applied; further, some completers such
              as _correct and _approximate do not use  the  match
              specifications  at all.  However, it is always safe
              to use the simple form for this style  (as  in  the
              first example above), since any completers which do
              not use match  specifications  will  only  ever  be
              called once, rather than once per specification.

              Since  the specification-strings in this style have
              to be tried one after another, it is a good idea to
              keep  their number low.  In most cases one to three
              strings (each of which may, without to large a per­
              formance hit, consist of more than one single match
              specification) will give acceptable performance.

       max-errors
              This is used by the _approximate and _correct  com­
              pleter functions to determine the maximum number of
              errors to allow.  The completer will try to  gener­
              ate  completions  by first allowing one error, then
              two errors, and so on,  until  either  a  match  or
              matches  were found or the maximum number of errors
              given by this style has been reached.

              If the value for this  style  contains  the  string
              `numeric',  the  completer  function  will take any
              numeric argument as the maximum  number  of  errors
              allowed. For example, with

                     zstyle ':completion:*:approximate:::' max-errors 2 numeric

              given, but with a numeric argument of  six  (as  in
              `ESC-6 TAB'), up to six errors are accepted.  Hence
              with a value of `0 numeric', no correcting  comple­
              tion will be attempted unless a numeric argument is
              given.

              If the value contains the string `not-numeric', the
              completer  will  not try to generate corrected com­
              pletions when given a numeric argument, so in  this
              case  the number given should be greater than zero.
              For example, `2 not-numeric'  specifies  that  cor­
              recting  completion with two errors will usually be
              performed, but if a numeric argument is given, cor­
              recting completion will not be performed.

              The default value for this style is `2 numeric'.

       menu   If  this  is  set to true in a given context, using
              any of the tags defined  for  a  given  completion,
              menu  completion  will  be used.  The tag `default'
              can be used to set the default value,  but  a  spe­
              cific  tag  will  take  precedence.  If none of the
              values found in this way is true but at  least  one
              is  set  to `auto' the behaviour will be as for the
              AUTO_MENU option.  Finally, if one of the values is
              explicitly  set  to  false, menu completion will be
              turned off even if it  would  otherwise  be  active
              (for example, with the MENU_COMPLETE option).

              Using the form `yes=num', where `yes' may be any of
              the true values (`yes', `true', `on' and `1') turns
              on  menu  completion if there at least num matches.
              Using this for one of the  `false'  values  (as  in
              `no=10') makes menu completion not be used if there
              are num or more matches.  Of course, this  is  only
              useful  when menu completion is normally used, e.g.
              by setting the MENU_COMPLETE  option.   The  `true'
              values  may  also be used in the form `yes=long' to
              turn on menu completion if the list  does  not  fit
              onto  the  screen.  This will start menu completion
              only if normal completion was attempted,  not  when
              only   the   list   of   possible  completions  was
              requested.  To start menu completion even then, the
              value `yes=long-list' can be used.

              In addition to (or instead of) the above possibili­
              ties, the value may contain  the  string  `select',
              optionally followed by an equals sign and a number.
              In this case menu  selection  (as  defined  by  the
              zsh/complist  module) will be started.  Without the
              optional number, it will be started unconditionally
              and  with  a  number  it will be started only if at
              least that  many  matches  are  generated;  if  the

              smallest number is taken.  Menu  selection  can  be
              turned  off explicitly by defining a value contain­
              ing the string `no-select'.

              It is also possible to start menu selection only if
              the  list  of matches does not fit on the screen by
              using the  value  `select=long'.   This  will  only
              start  menu  selection  if  the widget invoked does
              completion,  not  simply   listing   as   done   by
              delete-char-or-list;  to  start menu selection even
              here, use the value `select=long-list'.

              To turn on menu completion or menu selection when a
              certain  number of matches is generated or the list
              of matches does not fit onto the  screen,  both  of
              `yes='  and `select=' can be given twice, once with
              a number and once with `long' or `long-list'.

       numbers
              This is used with the jobs tag.  If it  is  `true',
              the  shell will complete the job numbers instead of
              the shortest unambiguous strings of the jobs'  com­
              mand  lines.  If the value is a number, job numbers
              will only be used if that many words from  the  job
              descriptions  are  required to resolve ambiguities.
              For example, if the value is `1', strings will only
              be  used  if  all  jobs differ in the first word on
              their command lines.

       old-list
              This is used by the _oldlist completer.  If  it  is
              set  to  `always', then standard widgets which per­
              form  listing  will  retain  the  current  list  of
              matches,  however  they were generated; this can be
              turned off explicitly with the value `never',  giv­
              ing  the  behaviour without the _oldlist completer.
              If the style is unset, or any other value, then the
              existing  list of completions is displayed if it is
              not already;  otherwise,  the  standard  completion
              list is generated; this is the default behaviour of
              _oldlist.  However, if there is  an  old  list  and
              this style contains the name of the completer func­
              tion that generated the list,  then  the  old  list
              will  be  used even if it was generated by a widget
              which does not do listing.

              For example, suppose you type ^Xc to use the  _cor­
              rect_word widget, which generates a list of correc­
              tions for the word under the cursor.  Usually, typ­
              ing  ^D  would  generate a standard list of comple­
              tions for the word on the command  line,  and  show
              that.  With _oldlist, it will instead show the list
              of corrections already generated.

              with  the insert-unambiguous style set to `true' it
              inserts only a common prefix string,  if  there  is
              any.   However, this may remove parts of the origi­
              nal pattern, so that further completion could  pro­
              duce  more  matches  than on the first attempt.  By
              using the _oldlist completer and setting this style
              to  _match,  the  list  of matches generated on the
              first attempt will be used again.

       old-matches
              This is  used  by  the  _all_matches  completer  to
              decide  if an old list of matches should be used if
              one exists.  It may be set to  one  of  the  `true'
              values  or to the string `only' to use such a list.
              If it is set to `only', _all_matches will only  use
              an  old  list and won't have any effect on the list
              of matches currently being generated.

       old-menu
              This is used by the _oldlist  completer.   It  con­
              trols how menu completion behaves when a completion
              has already been inserted  and  the  user  types  a
              standard  completion  key  type  such  as TAB.  The
              default behaviour of _oldlist is that menu  comple­
              tion  always  continues  with  the existing list of
              completions.  If this style is set to `false', how­
              ever,  a  new completion is started if the old list
              was generated by a  different  completion  command;
              this  is  the  behaviour without the  _oldlist com­
              pleter.

              For example, suppose you type  ^Xc  to  generate  a
              list of corrections, and menu completion is started
              in one of the usual ways.  Usually,  or  with  this
              style  set to false, typing TAB at this point would
              start  trying  to  complete  the  line  as  it  now
              appears.   With  _oldlist,  it instead continues to
              cycle through the list of corrections.

       original
              This is used by the _approximate and _correct  com­
              pleters  to decide if the original string should be
              added as one possible completion.   Normally,  this
              is  done  only  if  there are at least two possible
              corrections, but if this style is set to `true', it
              is  always  added.   Note that these completers use
              this style after setting the completer field in the
              context  name  to  correct-num  or approximate-num,
              where  num  is  the  number  of  errors  that  were
              accepted.

       packageset
              This style is used when completing arguments of the

              the  default  package set for a given context.  For
              example,

                     zstyle ':completion:*:complete:dpkg:option--status-1:*' \
                                    packageset avail

              causes  available  packages,   rather   than   only
              installed  packages,  to  be  completed  for  `dpkg
              --status'.

       path   The function that completes color names  uses  this
              style with the colors tag.  The value should be the
              pathname of a file containing color  names  in  the
              format of an X11 rgb.txt file.  If the style is not
              set but this file is found in one of various  stan­
              dard locations it will be used as the default.

       ports  A  style holding the service names of ports to com­
              plete.  If this is not set by the user, the service
              names from `/etc/services' will be used.

       prefix-hidden
              This  is used when matches with a common prefix are
              added (e.g. option names).  If it is  `true',  this
              prefix will not be shown in the list of matches.

              The default value for this style is `false'.

       prefix-needed
              This,  too,  is used for matches with a common pre­
              fix.  If it is set to `true' this common prefix has
              to  be  typed  by the user to generate the matches.
              E.g. for options this means that the `-',  `+',  or
              `--'  has to be on the line to make option names be
              completed at all.

              The default style for this style is `true'.

       range  This is used by  the  _history  completer  and  the
              _history_complete_word  bindable  command to decide
              which words should be completed.  It may be set  to
              a number, N, to say that only the last N words from
              the history should be  completed.   The  value  may
              also  be  of the form `max:slice'.  This means that
              first the last slice words will be  completed.   If
              that  yields  no  matches,  the  slice words before
              those will be tried and  so  on,  until  either  at
              least one match is generated or max words have been
              tried.  The default is to complete all  words  from
              the history at once.

       regular
              This  style  is used by the _expand_alias completer

              default), regular aliases will be expanded but only
              in command position.  If it is set to `false', reg­
              ular  aliases  will  never be expanded and if it is
              set to the string `always', regular aliases will be
              expanded even if not in command position.

       remove-all-dups
              The _history_complete_word bindable command and the
              _history completer use this to decide if all dupli­
              cate  matches  should  be removed, rather than just
              consecutive duplicates.

       select-prompt
              If this is set for the default tag, its value  will
              be  displayed  during  menu selection (see the menu
              style above) when the completion list does not  fit
              on  the screen as a whole.  The same escapes as for
              the list-prompt style are understood, but give  the
              number  of  the  match  or  line the mark is on.  A
              default prompt is used when the value is the  empty
              string.

       select-scroll
              This style is tested for the default tag and deter­
              mines how a completion list is  scrolled  during  a
              menu  selection (see the menu style above) when the
              completion list does not fit on  the  screen  as  a
              whole.  Its value should be `0' (zero) to scroll by
              half-screenfuls, a positive integer  to  scroll  by
              that  many lines and a negative number to scroll by
              the number of lines of the screen minus that number
              (or  plus  the  number, since it is negative).  The
              default is to scroll by single lines.

       single-ignored
              This is used by the _ignored completer.  It  speci­
              fies  what  should  be done if it can generate only
              one match, which is often a special case.   If  its
              value is `show', the single match will be displayed
              but not inserted.  If the value is `menu', then the
              single match and the original string are both added
              as matches and menu completion is started  so  that
              one can easily select either of them.

       sort   If  set to `true', completion functions that gener­
              ate words from the history as possible matches sort
              these  words alphabetically instead of keeping them
              in the order in which they appear  in  the  history
              (from youngest to oldest).

              This  is also used by the _expand completer.  Here,
              if it is set to `true',  the  expansions  generated
              will  always  be  sorted.   If it is set to `menu',

              offered  as  single strings (not in the string con­
              taining all possible expansions).

       special-dirs
              Normally, the completion code will not produce  the
              directory  names  `.'  and `..' as possible comple­
              tions.  If this style is set to `true', it will add
              both `.' and `..' as possible completions; if it is
              set to `..', only `..' will be added.

       squeeze-slashes
              If set to  `true',  sequences  of  slashes  (as  in
              `foo//bar')  will  be  treated as if they were only
              one slash when completing pathnames.  This  is  the
              usual behaviour of UNIX paths.  However, by default
              the file completion function behaves  as  if  there
              were a `*' between the slashes.

       stop   If  set to `true', the _history_complete_word bind­
              able command  will  stop  once  when  reaching  the
              beginning  or  end  of the history.  Invoking _his­
              tory_complete_word will then  wrap  around  to  the
              opposite  end of the history.  If this style is set
              to `false'  (the  default),  _history_complete_word
              will loop immediately as in a menu completion.

       subst-globs-only
              This  is  used  by the _expand completer.  If it is
              set to `true', the expansion will only be  used  if
              it  resulted  from  globbing;  hence, if expansions
              resulted from  the  use  of  the  substitute  style
              described below, but these were not further changed
              by globbing, the expansions will be rejected.

              The default for this style is `false'.

       substitute
              This boolean style  controls  whether  the  _expand
              completer  will  first  try to expand all substitu­
              tions  in  the  string  (such   as   `$(...)'   and
              `${...}').

              The default is `true'.

       suffix This  is  used by the _expand completer if the word
              starts with a tilde or contains a parameter  expan­
              sion. If it is set to `true', the word will only be
              expanded if it doesn't have a suffix, i.e. if it is
              something  like  `~foo' or `$foo', but not if it is
              `~foo/' or `$foo/bar', unless  that  suffix  itself
              contains  characters  eligible  for expansion.  The
              default for this style is `true'.

              This provides a mechanism for sorting how the  tags
              available in a particular context will be used.

              The  values  for  the style are sets of space-sepa­
              rated lists of tags.  The tags in each  value  will
              be  tried  at  the same time; if no match is found,
              the next value is  used.   (See  the  file-patterns
              style for an exception to this behavior.)

              For example:

                     zstyle ':completion:*:complete:-command-:*' tag-order \
                         'commands functions'

              specifies   that  completion  in  command  position
              should offer only completions for external commands
              and shell functions immediately.

              In  addition to tag names, each string in the value
              may take one of the following forms:

              -      If any string in the value consists of  only
                     a  hyphen,  then  only the tags specified by
                     the other strings in the  value  are  gener­
                     ated.   Normally  all  tags  not  explicitly
                     selected are tried  last  if  the  specified
                     tags  fail  to  generate  any matches.  This
                     means that a value consisting only of a sin­
                     gle hyphen turns off completion.

              ! tags...
                     A  string  starting with an exclamation mark
                     specifies names of tags that are not  to  be
                     used.   The  effect  is  the  same as if all
                     other possible tags for the context had been
                     listed.

              tag:label ...
                     In  strings not starting with an exclamation
                     mark, it is also  possible  to  specify  tag
                     labels  instead  of  only tags, where tag is
                     one of the tags offered  by  the  completion
                     function  for  the current context and label
                     is a name.  For this, the  completion  func­
                     tion  will  generate matches in the same way
                     as for the tag but it will use the label  in
                     place  of  the tag in the context names used
                     to look up styles.  If the label starts with
                     a  hyphen, the tag is prepended to the label
                     to form the name used for lookup.  This  can
                     be  used to make the completion system try a
                     certain tag more than once,  supplying  dif­
                     ferent  style settings for each attempt, see


                     The label may optionally be  followed  by  a
                     second   colon   and  a  description.   This
                     description will then be used for  the  `%d'
                     in  the value of the format style instead of
                     the default description supplied by the com­
                     pletion function.  Spaces in the description
                     have to be quoted by preceding them  with  a
                     backslash   and  a  `%d'  appearing  in  the
                     description is replaced with the description
                     given by the completion function.

       In  each of the cases above, the tag may also be a pattern
       or more than one pattern inside braces  and  separated  by
       commas.  In this case all of the offered tags matching the
       pattern(s) will be used except for those  that  are  given
       explicitly  in  the  same  string.  There are probably two
       main uses of this.  One is the case where one wants to try
       one  of the tags more than once, setting other styles dif­
       ferently for each try, but still  wants  to  use  all  the
       other  tags  without having to repeat them all.  For exam­
       ple, to make completion of function names in command posi­
       tion  ignore all the completion functions starting with an
       underscore the first time completion is tried,  one  could
       do:

              zstyle ':completion:*:*:-command-:*' tag-order \
                  'functions:-non-comp *' functions
              zstyle ':completion:*:functions-non-comp' ignored-patterns '_*'

       Here,  the  completion  system  will  first  try  all tags
       offered, but will use  the  tag  label  functions-non-comp
       when  looking  up styles for the function names completed.
       For this, the ignored-patterns style  is  set  to  exclude
       functions starting with an underscore from the set of pos­
       sible matches.  If none of the generated matches match the
       string  on  the  line,  the completion system will use the
       second value of the tag-order style and complete functions
       names  again,  but  this  time using the name functions to
       look up styles, so that the ignored-patterns style is  not
       used and all function names are considered.

       Of  course, this can also be used to split the matches for
       one tag into different groups. For example:

              zstyle ':completion:*' tag-order \
                  'options:-long:long\ options
                   options:-short:short\ options
                   options:-single-letter:single\ letter\ options'

              zstyle ':completion:*:options-long' ignored-patterns '[-+](|-|[^-]*)'
              zstyle ':completion:*:options-short' ignored-patterns '--*' '[-+]?'
              zstyle ':completion:*:options-single-letter' ignored-patterns '???*'

       ning with `--', options beginning with a single `-' or `+'
       but  containing  multiple  characters,  and  single-letter
       options  be  displayed  in  separate groups with different
       descriptions.

       The second interesting use of patterns is the  case  where
       one  wants  to try multiple match specifications one after
       another.  The matcher-list style offers something similar,
       but  it  is tested very early in the completion system and
       hence can't be set for single commands nor for  more  spe­
       cific  contexts.   Here  is  how  to try normal completion
       without any match specification and, if that generates  no
       matches,   try   again   with  case-insensitive  matching,
       restricting the effect to arguments of the command foo:
              zstyle ':completion:*:*:foo:*' tag-order '*' '*:-case'
              zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}'

       First, all the tags offered when completing after foo  are
       tried  using  the  normal  tag name.  If that generates no
       matches, the second value  of  tag-order  is  used,  which
       tries  all tags again except that this time each has -case
       appended to its name for lookup  of  styles.   Hence  this
       time  the value for the matcher style from the second call
       to zstyle in  the  example  is  used  to  make  completion
       case-insensitive.

       Using  the  -e option of the zstyle builtin command, it is
       possible to specify conditions saying  when  certain  tags
       are to be used. For example:

              zstyle -e '*:-command-:*' tag-order '
                  if [[ -n $PREFIX ]]; then
                    reply=( )
                  else
                    reply=( - )
                  fi'

       Makes  completion  in  command position happen only if the
       string on the line is not empty.  This is tested using the
       PREFIX  parameter  which is special in completion widgets;
       see zshcompwid for a description of these special  parame­
       ters.   Setting  reply to an empty array ensures that only
       the default behaviour of trying all tags at once  is  used
       and  setting  it to an array containing only a hyphen dis­
       ables that default behaviour -- thus keeping all tags from
       being tried.

       If  no  style  has been defined for a context, the strings
       `(|*-)argument-* (|*-)option-* values' and `options'  plus
       all  tags  offered by the completion function will be used
       to provide a sensible default behavior that  causes  argu­
       ments  (whether  normal  command arguments or arguments of
       options) to be completed  before  option  names  for  most


       urls   This is used together with the the urls tag by com­
              pletion functions that generate  URLs  as  possible
              matches.   If  the  value consists of more than one
              string or if the only string does not name  a  file
              or  directory,  the strings are used as the URLs to
              complete.

              If the value contains only one string and  that  is
              the  name of a normal file, the URLs are taken from
              that file (where the URLs may be separated by white
              space or newlines).

              Finally,  if  the  only string in the value names a
              directory,  that  should  contain   sub-directories
              named  after  the  retrieval methods which occur as
              the first part  of  a  URL,  i.e.   `http',  `ftp',
              `bookmark',   and  so  on.   These  sub-directories
              should  contain  files  and  other  sub-directories
              whose  pathnames are possible completions after the
              initial `http://', `ftp://', etc. See the  descrip­
              tion in the file _urls in the User sub-directory of
              the completion system for more information.

       use-cache
              If this is set, the  completion  caching  layer  is
              activated for any completions which use it (via the
              _store_cache, _retrieve_cache,  and  _cache_invalid
              functions).   The  directory  containing  the cache
              files can be changed with the cache-path style.

       use-compctl
              If this style is set  to  a  string  not  equal  to
              false,  0,  no,  and off, the completion system may
              use any completion specifications defined with  the
              compctl  builtin  command.   If the style is unset,
              this is done only  if  the  zsh/compctl  module  is
              loaded.   The string may also contain the substring
              `first' to make the definition for `compctl -T'  be
              used,  and  the substring `default' to make the one
              for `compctl -D' be used.

              Note that this is only intended to smooth the tran­
              sition  from  compctl  to the new completion system
              and may disappear in the future.

              Note also that the definitions  from  compctl  will
              only  be  used  if  there is no specific completion
              function for the command in question.  For example,
              while  completing  arguments to the command foo, if
              this was handled by a command function  _foo,  com­
              pctl  would never be tried, while if it was handled
              by _default, compctl would be tried.

              completed  whenever  a username is needed. If it is
              not set or the string on the line doesn't match any
              of  the strings in this list, all usernames will be
              completed.

       users-hosts
              The values of this style  should  be  of  the  form
              `user@host' or `user:host'. It is used for commands
              that need pairs of user- and hostnames.   For  such
              commands,  only  the pairs from this style are used
              and if, for example, the username is already typed,
              then  only  the hostnames for which there is a pair
              with that username is defined.

              If set for the my-accounts tag, this  is  used  for
              commands  such  as rlogin and ssh; in this case the
              style should contain the names of  the  user's  own
              accounts   on   remote   hosts.   If  set  for  the
              other-accounts tag, it is used for commands such as
              talk  and  finger and should contain other people's
              accounts.  Finally, it may also  be  used  by  some
              commands with the accounts tag.

       users-hosts-ports
              Like  users-hosts but used for commands like telnet
              and    containing    strings    of     the     form
              `user@host:port'.

       verbose
              This  is used in several contexts to decide if only
              a simple or a verbose list  of  matches  should  be
              generated.  For example some commands show descrip­
              tions for option names if this style is `true'.

              The default value for this style is `true'.

       word   This is used by the _list completer, which prevents
              the insertion of completions until a second comple­
              tion attempt when the line has  not  changed.   The
              normal  way  of finding out if the line has changed
              is to compare its entire contents between  the  two
              occasions.   If  this style is true, the comparison
              is instead performed  only  on  the  current  word.
              Hence  if  completion  is performed on another word
              with the same  contents,  completion  will  not  be
              delayed.


CONTROL FUNCTIONS

       The  initialization script compinit redefines all the wid­
       gets which perform completion to call the supplied  widget
       function  _main_complete.  This function acts as a wrapper
       calling the so-called `completer' functions that  generate

       these are taken as the names of completer functions to  be
       called in the order given.  If no arguments are given, the
       set of functions to try is taken from the completer style.
       For  example,  to  use normal completion and correction if
       that doesn't generate any matches:

              zstyle ':completion:*' completer _complete _correct

       after calling compinit. The default value for  this  style
       is  `_complete _ignored', i.e. normally only ordinary com­
       pletion  is  tried,  first  with   the   effect   of   the
       ignored-patterns   style   and   then   without  it.   The
       _main_complete function uses the return value of the  com­
       pleter  functions  to decide if other completers should be
       called.  If the return value is zero, no other  completers
       are tried and the _main_complete function returns.

       If  the  first  argument  to  _main_complete  is  a single
       hyphen, the arguments will not be taken as names  of  com­
       pleters.  Instead, the second argument gives a name to use
       in the completer field of the context and the other  argu­
       ments  give a command name and arguments to call to gener­
       ate the matches.

       The following completer functions  are  contained  in  the
       distribution (users may write their own):

       _all_matches
              This completer can be used to add a string consist­
              ing of all other matches.   To  ensure,  that  this
              string  is  always  added, this completer has to be
              used as the  first  completer  in  the  list.   The
              avoid-completer  style  is  used  to  decide if the
              string should be added.  This will only be done  if
              the matches were generated by a completer not named
              by one of the values of the style.

              This function also uses the style old-matches.   If
              it  is  set  to  `true' or to the string `only' and
              there is a list of matches from a previous  comple­
              tion, those matches will be inserted in the command
              line.  If it is set to the the  string  `only',  it
              will  only  insert  an  old  list and won't add the
              string for all matches of the list currently  being
              generated.

              With  the  old-matches  style  set,  this completer
              should  probably  not  be  called  unconditionally.
              Instead  one  could use the -e option of the zstyle
              builtin command to add a condition to the completer
              or  to  the  old-matches style.  Alternatively, one
              could   use   the   _generic   function   to   bind
              _all_matches   to   a  separate  key  binding,  for


                     zle -C all-matches complete-word _generic
                     bindkey '^Xa' all-matches
                     zstyle ':completion:all-matches:*' old-matches only
                     zstyle ':completion:all-matches:*' completer _all_matches

       _approximate
              This completer function  uses  the  _complete  com­
              pleter  to  generate a list of strings for the con­
              text the cursor is currently in,  allowing  you  to
              specify  a  maximum  number  of  errors:   see  the
              description of approximate matching  in  zshexpn(1)
              for  how errors are counted.  The resulting list of
              corrected and completed strings is  then  presented
              to  the  user.   The intended use of this completer
              function is to try after the normal _complete  com­
              pleter by setting:

                     zstyle ':completion:*' completer _complete _approximate

              This will give correcting completion if and only if
              normal completion yields no  possible  completions.
              When corrected completions are found, the completer
              will normally start menu completion allowing you to
              cycle through these strings.

              This completer uses the tags corrections and origi­
              nal when generating the  possible  corrections  and
              the original string.  The format style for the for­
              mer may contain the additional sequences  `%e'  and
              `%o' which will be replaced by the number of errors
              accepted to generate the corrections and the origi­
              nal string, respectively.

              As  with all completers, _approximate uses its name
              without the underscore in the  completer  field  of
              the  context  name.   Once it has started trying to
              generate matches, it will append a minus  sign  and
              the   number   of  errors  accepted  to  its  name.
              _approximate will first look for  completions  with
              one  error,  then two, and on so up to the limit on
              the number of errors set by the  max-errors  style.
              Hence  on  the first try the completer field of the
              context contains `approximate-1', on the second try
              `approximate-2', and so on.

              When  _approximate is called from another function,
              the number of errors to accept may  be  given  with
              the  -a option.  Its argument should be the same as
              the value of  the  max-errors  style,  all  in  one
              string.

              Note   that   this   completer  (and  the  _correct

              to  call,  especially when a large number of errors
              are allowed.  One way to avoid this is  to  set  up
              the  completer  style using the -e option to zstyle
              so that some completers are only used when  comple­
              tion is attempted a second time on the same string,
              e.g.:

                     zstyle ':completion:*' completer '
                       if [[ $_last_try != "$HISTNO$BUFFER$CURSOR" ]]; then
                         _last_try="$HISTNO$BUFFER$CURSOR"
                         reply=(_complete _match _prefix)
                       else
                         reply=(_ignored _correct _approximate)
                       fi'

              This uses the HISTNO parameter and the  BUFFER  and
              CURSOR special parameters that are available inside
              zle and completion widgets to find out if the  com­
              mand  line  hasn't changed since the last time com­
              pletion was tried.  Only  then  are  the  _ignored,
              _correct and _approximate completers called.

       _complete
              This  completer  generates all possible completions
              in a context-sensitive manner, i.e. using the  set­
              tings  defined  with the compdef function explained
              above and  the  current  settings  of  all  special
              parameters.    This  gives  the  normal  completion
              behaviour.

              To complete arguments of commands,  _complete  uses
              the  utility  function  _normal,  which  is in turn
              responsible for finding the particular function; it
              is  described  below.  Various contexts of the form
              -context-, as mentioned above for the #compdef tag,
              are handled specially.  These are:

              -array-value-
                     for  completion on the right hand side of an
                     array-assignment (`foo=(...)').

              -brace-parameter-
                     for  completing  the  name  of  a  parameter
                     expansion within braces (`${...}').

              -command-
                     for completing in a command position.

              -condition-
                     for     completion     inside     conditions
                     (`[[...]]').

                     for generating completions when  no  special
                     completion function is used.

              -equal-
                     for  completion  of  words beginning with an
                     equals sign

              -first-
                     for adding completions before any other com­
                     pletion  functions  are tried; if this func­
                     tion sets the _compskip parameter to all, no
                     other  completion  functions will be called,
                     if it is set to a string containing the sub­
                     string patterns, no pattern completion func­
                     tions will be called, and if it is set to  a
                     string  containing  default the function for
                     the `-default-' context will not be  called,
                     but functions defined for commands will.

              -math- for completion inside mathematical contexts,
                     such as `((...))'.

              -parameter-
                     for  completing  the  name  of  a  parameter
                     expansion (`$...').

              -redirect-
                     for completion after a redirection operator.

              -subscript-
                     for completion inside subscripts.

              -tilde-
                     for completion after a tilde  (`~')  charac­
                     ter, but before a slash.

              -value-
                     for  completion on the right hand side of an
                     assignment.

              Default implementations are supplied  for  each  of
              these  contexts, in most cases named after the con­
              text itself (e.g. completion for the `-tilde-' con­
              text is done by the function named `_tilde').

              Before  trying  to  find  a function for a specific
              context, _complete checks if the  parameter  `comp­
              context'  is  set.   If  it is set to an array, the
              elements are taken to be the possible matches which
              will  be  completed  using the tag `values' and the
              description `value'.   If it is set to an  associa­
              tive  array, the keys are used as the possible com­
              pletions and the values (if non-empty) are used  as

              set to a string containing colons, it should be  of
              the  form `tag:descr:action'.  In this case the tag
              and descr give the tag and description to  use  and
              the  action says what should be completed in one of
              the forms  described  for  the  _arguments  utility
              function below.

              Finally,  if `compcontext' is set to a string with­
              out colons, the value is taken as the name  of  the
              context  to  use  and the function defined for that
              context will be called.  For this purpose, there is
              a  special  context  named -command-line- that com­
              pletes whole  command  lines  (commands  and  their
              arguments) and is not used by the completion system
              itself, but has a function handling completion  for
              it.

       _correct
              Generate  corrections, but not completions, for the
              current word; this is similar to  _approximate  but
              will  not  allow  any number of extra characters at
              the cursor as that completer does,  hence  this  is
              similar  to  spell-checking.  It calls _approximate
              but uses a different completer field in the context
              name.

              For example, with:

                     zstyle ':completion:::::' completer _complete _correct _approximate
                     zstyle ':completion:*:correct:::' max-errors 2 not-numeric
                     zstyle ':completion:*:approximate:::' max-errors 3 numeric

              correction  will  accept  up  to  two errors.  If a
              numeric argument is given, correction will  not  be
              performed,  but  correcting completion will be, and
              will accept as many errors as given by the  numeric
              argument.   Without  a numeric argument, first cor­
              rection and  then  correcting  completion  will  be
              tried,  with the first one accepting two errors and
              the second one accepting three errors.

              When _correct is called as a function,  the  number
              of  errors  to accept may be given following the -a
              option.  The argument should be  the  same  as  the
              value of the accept style, all in one string.

              This  completer  function  is  intended  to be used
              without the _approximate completer or,  as  in  the
              example,  just  before  it.   Using  it  after  the
              _approximate completer is useless  since  _approxi­
              mate  will  at least generate the corrected strings
              generated by the _correct completer -- and probably
              more.

              This  completer function does not really do comple­
              tion, but instead checks if the word on the command
              line is eligible for expansion and, if it is, gives
              detailed control over how this expansion  is  done.
              When   using   this,   one   should   not  use  the
              expand-or-complete widget,  but  instead  use  com­
              plete-word,  as  expand-or-complete will expand the
              string on the line before the completion widget  is
              called.   Also,  this  completer  should  be called
              before the _complete completer function.

              The  tags  used  when  generating  expansions   are
              all-expansions for the string containing all possi­
              ble expansions, expansions when adding the possible
              expansions  as  single  matches  and  original when
              adding the original string from the line.  In which
              order  these  strings  are  generated  and which of
              these strings are generated  at  all  can  be  con­
              trolled by using the group-order style and by modi­
              fying the tag-order style, as usual.

              The format string for all-expansions and for expan­
              sions  may  contain the sequence `%o' which will be
              replaced by the original string from the line.

              Which kind of expansion is tried is  controlled  by
              the substitute, glob and subst-globs-only styles.

              When _expand is called as a function, the different
              modes may be selected with options.  The -s to sub­
              stitute, -g to glob and -o to subst-globs-only.

       _expand_alias
              If  the  word  the  cursor is on is an alias, it is
              expanded and no other completers are  called.   The
              types  of  aliases  which are to be expanded can be
              controlled with the regular,  global  and  disabled
              styles.

              This  function  is also a bindable command, see the
              section `Bindable Commands' below.

       _history
              Complete words from the shell's  command   history.
              This  completer  uses the remove-all-dups, and sort
              styles  also  used  by  the  _history_complete_word
              bindable  command,  see  the section `Bindable Com­
              mands' below and  the  section  `Completion  System
              Configuration' above.

       _ignored
              The  ignored-patterns style can be set to a list of
              patterns  which  are  compared   against   possible

              completer those matches can be reinstated, as if no
              ignored-patterns  style  were  set.   The completer
              actually generates its own list of  matches;  which
              completers  are  used for this is determined in the
              same way as for the _prefix completer.

              The single-ignored style is used if only one  match
              could  be generated.  It can be set to show to pre­
              vent that match from being  displayed  or  inserted
              into  the  line, or it can be set to menu, in which
              case the single match and the original string  from
              the line will be offered in a menu completion.

       _list  This completer allows one to delay the insertion of
              matches until completion is attempted a second time
              without the word on the line being changed.  On the
              first attempt, only the list  of  matches  will  be
              shown.   It is affected by the styles condition and
              word, see the section `Completion System Configura­
              tion' above.

       _match This  completer  is  intended  to be used after the
              _complete completer. It allows one to give patterns
              on  the  command  line  and to complete all strings
              matching these patterns from the  set  of  possible
              completions for the context the cursor is in, with­
              out having to set the GLOB_COMPLETE option.

              Normally this will be done by  taking  the  pattern
              from  the line, inserting a `*' at the cursor posi­
              tion and comparing the resulting pattern  with  the
              possible  completions  generated.   However, if the
              match-original style has a value of  only,  no  `*'
              will  be inserted.  If match-original has any other
              non-empty string as its value, this completer  will
              first  try to generate matches without, then with a
              `*' inserted at the cursor position.

              The generated matches will be  offered  in  a  menu
              completion  unless  the insert-unambiguous style is
              set to `true'.  In this case menu  completion  will
              only  be  started if no unambiguous string could be
              generated that is at least as long as the  original
              string.   The  style  may also be set to the string
              `pattern'.  This will keep the pattern on the  line
              intact  as  long as there isn't an unambiguous com­
              pletion with which it could be replaced.

              Note that the matcher specifications defined  glob­
              ally  or  used by the completion functions will not
              be used.

       _menu  This  completer  is  a  simple   example   function

              in shell code.  It should be used as the first com­
              pleter  and  has the effect of making the code per­
              form menu completion.  Note that this  is  indepen­
              dent of the setting of the MENU_COMPLETE option and
              does not work with the other menu  completion  wid­
              gets     such    as    reverse-menu-complete,    or
              accept-and-menu-complete.

       _oldlist
              This completer controls how the standard completion
              widgets  behave  when  there is an existing list of
              completions which may have been generated by a spe­
              cial completion (i.e. a separately-bound completion
              command).  It allows the ordinary  completion  keys
              to  continue  to  use  the list of completions thus
              generated, instead of producing a new list of ordi­
              nary  contextual  completions.  It should appear in
              the list of completers before any  of  the  widgets
              which   generate  matches.   It  uses  two  styles:
              old-list and old-menu, see the section  `Completion
              System Configuration' above.

       _prefix
              This  completer  can be used to try completion with
              the suffix (everything after the  cursor)  ignored.
              In  other  words, the suffix will not be considered
              to be part of the word to complete and  hence  does
              not  need  to  be  matched.   It uses the completer
              style to decide which other completers to  call  to
              try  to  generate matches.  If this style is unset,
              the list of completers set for the current  context
              is used -- except, of course, the _prefix completer
              itself.  Furthermore,  if  this  completer  appears
              more than once in the list of completers only those
              completers not already tried by the last invocation
              of _prefix will be called.

              For example, consider this global completer style:

                     zstyle ':completion:*' completer \
                         _complete _prefix _correct _prefix:foo

              Here, the _prefix completer tries normal completion
              but ignoring the suffix.  If that doesn't  generate
              any matches, and neither does the call to the _cor­
              rect completer after it, _prefix will be  called  a
              second  time  and,  now only trying correction with
              the suffix ignored.  If you want to use _prefix  as
              the last resort and try only normal completion, you
              can use:

                     zstyle ':completion:*' completer _complete ... _prefix
                     zstyle ':completion::prefix:*' completer _complete

              `true' then _prefix will insert a space between the
              matches generated (if any) and the suffix.

              Note that this completer is only useful if the COM­
              PLETE_IN_WORD  option is set; otherwise, the cursor
              will be moved to the end of the current word before
              the  completion code is called and hence there will
              be no suffix.


BINDABLE COMMANDS

       In addition to the context-dependent completions provided,
       which  are expected to work in an intuitively obvious way,
       there are a few  widgets  implementing  special  behaviour
       which can be bound separately to keys.  The following is a
       list of these and their default bindings.

       _bash_completions
              This function is used by  two  widgets,  _bash_com­
              plete-word  and  _bash_list-choices.   It exists to
              provide compatibility with completion  bindings  in
              bash.  The last character of the binding determines
              what is completed: `!', command names;  `$',  envi­
              ronment  variables;  `@',  host  names;  `/',  file
              names; `~' user names.  In bash, the  binding  pre­
              ceded  by  `\e'  gives  completion, and preceded by
              `^X' lists options.   As  some  of  these  bindings
              clash  with  standard  zsh bindings, only `\e~' and
              `^X~' are bound by default.  To add the  rest,  the
              following  should be added to .zshrc after compinit
              has been run:

                     for key in '!' '$' '@' '/' '~'; do
                       bindkey "\e$key" _bash_complete-word
                       bindkey "^X$key" _bash_list-choices
                     done

              This includes the bindings for  `~'  in  case  they
              were  already  bound to something else; the comple­
              tion code does not override user bindings.

       _correct_filename (^XC)
              Correct the filename path at the  cursor  position.
              Allows  up  to six errors in the name.  Can also be
              called with an argument to correct a filename path,
              independently  of zle; the correction is printed on
              standard output.

       _correct_word (^Xc)
              Performs correction of the current  argument  using
              the   usual   contextual  completions  as  possible
              choices. This stores the string  `correct-word'  in
              the  function  field  of  the context name and then


       _expand_alias (^Xa)
              This function can be used as a completer and  as  a
              bindable  command.   It expands the word the cursor
              is on if it is an  alias.   The  types  of  aliases
              expanded can be controlled with the regular, global
              and disabled styles.

              When used as a bindable command there is one  addi­
              tional  feature that can be selected by setting the
              complete style to `true'.  In  this  case,  if  the
              word  isn't  the  name  of  an alias, _expand_alias
              tries to complete the word to  a  full  alias  name
              without   expanding  it  (but  leaving  the  cursor
              directly after the completed word so that  invoking
              _expand_alias  once  more  will expand the now-com­
              plete alias name).

       _expand_word (^Xe)
              Performs expansion on the current word:  equivalent
              to  the standard expand-word command, but using the
              _expand completer.  Before calling it, the function
              field is set to `expand-word'.

       _generic
              This  function  is  not defined as a widget and not
              bound by default. However, it can be used to define
              a widget and will then store the name of the widget
              in the function field of the context and  call  the
              completion  system.  This  allows custom completion
              widgets with their own set of style settings to  be
              easily  defined.  For  example,  to define a widget
              that does normal completion and starts menu  selec­
              tion, one could do:

                     zle -C foo complete-word _generic
                     bindkey '...' foo
                     zstyle ':completion:foo:*' menu yes select=1

       _history_complete_word (\e/)
              Complete  words  from  the shell's command history.
              This uses the list, remove-all-dups, sort, and stop
              styles.

       _most_recent_file (^Xm)
              Complete  the  name  of  the most recently modified
              file matching  the  pattern  on  the  command  line
              (which  may be blank).  If given a numeric argument
              N, complete the Nth most  recently  modified  file.
              Note the completion, if any, is always unique.

       _next_tags (^Xn)
              This command alters the set of matches used to that

              by  the tag-order style or as set by default; these
              matches would otherwise not be available.   Succes­
              sive  invocations  of the command cycle through all
              possible sets of tags.

       _read_comp (^X^R)
              Prompt the user for a string, and use that to  per­
              form completion on the current word.  There are two
              possibilities for the string.  First, it can  be  a
              set  of  words  beginning  `_', for example `_files
              -/', in which case the function with any  arguments
              will  be called to generate the completions.  Unam­
              biguous parts of the function  name  will  be  com­
              pleted  automatically  (normal  completion  is  not
              available at this point) until a space is typed.

              Second, any other string will be passed as a set of
              arguments to compadd and should hence be an expres­
              sion specifying what should be completed.

              A very restricted set of editing commands is avail­
              able  when  reading  the  string:   `DEL'  and `^H'
              delete the last character; `^U' deletes  the  line,
              and  `^C'  and `^G' abort the function, while `RET'
              accepts the completion.  Note the  string  is  used
              verbatim  as  a  command line, so arguments must be
              quoted in accordance with standard shell rules.

              Once a string has  been  read,  the  next  call  to
              _read_comp  will use the existing string instead of
              reading a new one.  To force a  new  string  to  be
              read, call _read_comp with a numeric argument.

       _complete_debug (^X?)
              This  widget performs ordinary completion, but cap­
              tures in a temporary file a trace of the shell com­
              mands executed by the completion system.  Each com­
              pletion attempt gets its own file.   A  command  to
              view  each of these files is pushed onto the editor
              buffer stack.

       _complete_help (^Xh)
              This widget displays information about the  context
              names,  the tags, and the completion functions used
              when completing at the current cursor position.  If
              given a numeric argument other than 1 (as in `ESC-2
              ^Xh'), then the styles used and  the  contexts  for
              which they are used will be shown, too.

              Note  that  the  information  about  styles  may be
              incomplete; it depends on the information available
              from the completion functions called, which in turn
              is determined by the user's own  styles  and  other


       _complete_tag (^Xt)
              This  widget  completes  symbol tags created by the
              etags or ctags programmes (note there is no connec­
              tion with the completion system's tags) stored in a
              file TAGS, in the format used by etags, or tags, in
              the  format created by ctags.  It will look back up
              the path hierarchy  for  the  first  occurrence  of
              either  file;  if both exist, the file TAGS is pre­
              ferred.  You can specify the full path to a TAGS or
              tags  file  by  setting  the parameter $TAGSFILE or
              $tagsfile respectively.  The corresponding  comple­
              tion tags used are etags and vtags, after emacs and
              vi respectively.


UTILITY FUNCTIONS

       Descriptions follow for utility functions that may be use­
       ful  when  writing  completion  functions.   Most of these
       reside in the Base subdirectory. Like  the  example  func­
       tions  for commands in the distribution, the utility func­
       tions generating matches  all  follow  the  convention  of
       returning  zero if they generated completions and non-zero
       if no matching completions could be added.

       When writing completion functions  or  other  ZLE  widgets
       that  call  completion,  it  might  be interesting to know
       about two more  features  offered  by  the  _main_complete
       function. The arrays compprefuncs and comppostfuncs may be
       set to contain names of functions that are  to  be  called
       immediately before or after completion has been tried. The
       functions will only be called once, unless they put  them­
       selves into the arrays again.

       _all_labels [ -12VJ ] tag name descr [ command args ... ]
              This  is  a convenient interface to the _next_label
              function below, implementing the loop shown in  the
              _next_label  example.   The command is the one that
              should be  called  to  generate  the  matches.  The
              options stored in the parameter name will automati­
              cally be inserted into the args given to  the  com­
              mand.   Normally,  they  are put directly after the
              command, but if one of the args is a single hyphen,
              they  are  inserted  directly  before  that. If the
              hyphen is the last argument, that will  be  removed
              from  the  argument  list  before  the  command  is
              called. This  allows  _all_labels  to  be  used  in
              almost all cases where the matches can be generated
              by a single call to the compadd builtin command  or
              by a call to one of the utility functions.

              For example:

                     ...
                     if _requested foo; then
                       ...
                       _all_labels foo expl '...' compadd ... - $matches
                     fi

              Will  complete the strings from the matches parame­
              ter, using compadd with  additional  options  which
              will   take  precedence  over  those  generated  by
              _all_labels.

       _alternative [ -C name ] specs ...
              This function is useful in simple cases where  mul­
              tiple  tags  are available.  Essentially, it imple­
              ments a loop like the one described for  the  _tags
              function above.

              The  tags to use and the action to perform if a tag
              is requested are described using  the  specs  which
              are  of  the form: `tag:descr:action'. The tags are
              offered using _tags and if the  tag  is  requested,
              the  action  is executed with the given description
              descr.  The actions supported are those used by the
              _arguments  function (described below), without the
              `->state' and `=...' forms.

              For example, the action may be  a  simple  function
              call. With that one could do:

                     _alternative \
                         'users:user:_users' \
                         'hosts:host:_hosts'

              to   offer  usernames  and  hostnames  as  possible
              matches (which are  generated  by  the  _users  and
              _hosts functions respectively).

              Note  that,  like  _arguments  this  will  also use
              _all_labels to execute the actions, so one  doesn't
              need  to call that explicitly unless another tag is
              to be used, for example in a function  called  from
              _alternative.

              Like  _tags this function supports the -C option to
              give a different  name  for  the  argument  context
              field.

       _arguments spec ...
              This  function can be used to complete words on the
              line by describing the options and arguments  which
              may  be  passed to the command for which completion
              is being performed.  The description  is  given  as
              arguments   to   this   function,  with  each  spec

              command.  The forms of spec understood are:

              n:message:action
              n::message:action
                     This  describes  the  n'th  normal argument.
                     The  message  will  be  printed  above   the
                     matches  generated  and the action says what
                     can  be  completed  in  this  position  (see
                     below).   If there are two colons before the
                     message, this describes  an  optional  argu­
                     ment.   If  the  message contains only white
                     space, nothing will  be  printed  above  the
                     matches  unless  the action adds an explana­
                     tion string itself.

              :message:action
              ::message:action
                     Like the previous one,  but  describing  the
                     next  argument. I.e. if you want to describe
                     all arguments a command  can  get,  you  can
                     leave out the numbers in the description and
                     just use this  form  to  describe  them  one
                     after  another  in  the  order  they have to
                     appear on the line.

              *:message:action
              *::message:action
              *:::message:action
                     This  describes   how   arguments   (usually
                     non-option  arguments,  those  not beginning
                     with - or +) are to  be  completed  when  no
                     description  with one of the first two forms
                     was given. This also means that  any  number
                     of arguments can be completed.

                     With  two  colons  before  the  message, the
                     words special array and the CURRENT  special
                     parameter  are modified to refer only to the
                     normal arguments when the action is executed
                     or  evaluated.  With three colons before the
                     message they are modified to refer  only  to
                     the   normal   arguments   covered  by  this
                     description.

              optspec[description ...]
                     This describes an option and (if description
                     is  given)  the  arguments that have to come
                     after the  option.   If  no  description  is
                     given,  this  means to offer only the option
                     name as a possible completion in  the  right
                     places.   (Note  that  the  brackets, above,
                     around description, indicate  that  zero  or
                     more   descriptions   may  appear;  but  the

                     format.  If brackets are used, they are part
                     of the optspec; see below.)

                     In the descriptions below, the option  names
                     represented by optname are normally taken to
                     be multi-character names, and  a  word  from
                     the  line  is considered to contain only one
                     option (or none).  By giving the  -s  option
                     to  _arguments  before  the first spec, each
                     optname is considered to be a single charac­
                     ter  and each word from the line may contain
                     more than one such option letter.   However,
                     words   beginning  with  two  hyphens  (like
                     `--prefix') are still considered to  contain
                     only  one  option name.  This allows the use
                     of the `-s' option to describe single-letter
                     options   together  with  such  long  option
                     names.

                     The -s  option  may  be  combined  with  the
                     option -w to say that more option characters
                     are to be expected even after an option that
                     takes  an  argument.  For example, if a com­
                     mand takes the options `a'  and  `b',  where
                     `a'  takes  an  argument  in  the next word,
                     _arguments would normally not  complete  the
                     other  option  directly  after  `-a', but it
                     would allow that if given the -w option.

                     Similarly,  the  option  -W  may  be   given
                     together with -s to force completion of sin­
                     gle-letter options even after  options  that
                     get an argument in the same word.  For exam­
                     ple, if a command takes the options `a'  and
                     `b', where `a' needs an argument in the same
                     word, directly after the  option  character,
                     _arguments  would  normally only execute the
                     action for that argument and not offer other
                     single-letter  options  as  possible comple­
                     tions.  If given  the  -W  option,  it  will
                     offer  other options as possible completions
                     after executing the action for the argument.
                     Note that, depending on the action, this may
                     mean that the other options can't really  be
                     completed, but at least they will be listed.
                     For more control, use  an  utility  function
                     like _guard in the argument's action.

                     The forms of optspec are:

                      *optspec
                             If the option may be given more than
                             once, a star (`*') must be added  in

                             of  optspec.   Otherwise,   if   the
                             option is already on the line and to
                             the left of the cursor,  it  is  not
                             offered  as  a  possible  completion
                             again.

                      -optname
                      +optname
                             In the simplest form the optspec  is
                             just  the option name beginning with
                             a minus or  a  plus  sign,  such  as
                             `-foo'.   The first argument for the
                             option (if any)  must  follow  as  a
                             separate  word  directly  after  the
                             option.

                             If the command  accepts  the  option
                             with  either  a  leading  minus or a
                             leading  plus   sign,   use   either
                             `-+optname' or `+-optname' to define
                             both variants at once.

                             In  all  the  following  forms,  the
                             leading   `-'  may  be  replaced  or
                             paired with `+' in this way.

                      -optname-
                             The first  argument  of  the  option
                             must  come directly after the option
                             name  in  the  same  word,   as   in
                             `-foo-:...'.

                      -optname+
                             The  first argument may appear imme­
                             diately after optname  in  the  same
                             word,  or  may  instead  appear as a
                             separate word after the option.

                      -optname=
                             The argument may appear as the  next
                             word,  or in same word as the option
                             name provided that it  is  separated
                             from it by an equals sign.

                      -optname=-
                             The  argument  to  the  option  must
                             appear after an equals sign  in  the
                             same  word,  and may not be given in
                             the next argument.

                      optspec[explanation]
                             An   explanation   string   may   be
                             appended  to  any  of  the preceding

                             brackets,  as  in  `-q[query  opera­
                             tion]'.

                             The verbose style is used to  decide
                             if  these explanation strings should
                             be displayed with the  option  in  a
                             completion listing.

                             If  no  bracketed explanation string
                             is given  but  the  auto-description
                             style  is  set and only one argument
                             is described for this  optspec,  the
                             value  of  the  style  is displayed,
                             with any appearance of the  sequence
                             `%d'  in  it replaced by the message
                             of the first description  that  fol­
                             lows the optspec; see below.

              Note  that  the  special  meaning  of  a leading or
              trailing - or + in optspec means that when the com­
              mand  to  be completed accepts options like `-+' or
              `-=', the second character has to be quoted with  a
              backslash, as in `-\+'.

              Each description following an optspec must take one
              of the following forms:

              :message:action
              ::message:action
                     Describes  a  mandatory  argument  with  one
                     colon,  or  an  optional  argument  with two
                     colons.  As in other forms of spec, the mes­
                     sage  will be printed above the matches gen­
                     erated (unless it contains only white space,
                     see  above)  and the action says what can be
                     completed in this position.

              :*pattern:message:action
              :*pattern::message:action
              :*pattern:::message:action
                     This describes multiple arguments.  Only the
                     last  description may be given in this form.
                     If the pattern is  empty  (i.e.,  :*:),  all
                     following  words  on the line are to be com­
                     pleted as described by  the  action;  other­
                     wise,  all  words  up to a word matching the
                     pattern  are  to  be  completed  using   the
                     action.

                     When  the message is preceded by two colons,
                     the words special array and the CURRENT spe­
                     cial  parameter are modified during the exe­
                     cution or evaluation of the action to  refer

                     preceded by three colons, they are  modified
                     to  refer  only to the words covered by this
                     description.

                     Note that only one  such  `:*'-specification
                     is  useful  and no other argument specifica­
                     tion may be given after it.

       To include a colon in any optname, message, or action any­
       where  above,  it  has  to  be preceded by a backslash, as
       `\:'.

       Each of the six forms of spec (yes, there  are  six,  keep
       track of the nestings) may be preceded by a list of option
       names and argument numbers with which the option or  argu­
       ment  described is mutually exclusive.  This list is given
       in  parentheses,  as  in  `(-two  -three  1)-one:...'   or
       `(-foo):...'.   In  the  first example, the options `-two'
       and `-three' and the first argument will not be offered as
       possible  completions  if the option `-one' is on the line
       before the cursor, and in the second  example  the  option
       `-foo'  will  not  be offered if the argument described by
       the specification is on the line.

       The list may also contain a single star (*) as one of  its
       elements  to  specify  that  the  description for the rest
       arguments (i.e.  a  specification  of  the  form  `*:...')
       should  not  be  used,  a  colon  (:)  to specify that the
       descriptions for all normal (non-option-) arguments should
       not  be used and a hyphen (-) to specify that the descrip­
       tions for all options should not be used.  This  paragraph
       desperately needs rewriting.

       To simplify writing writing functions that call _arguments
       more than once, the specs may also start with the  charac­
       ter  `!'   (exclamation mark) to make the spec not be com­
       pleted.  However, if this is used with one  of  the  forms
       describing  options,  the option (and its arguments, if it
       takes any) will be understood and skipped if  they  appear
       on  the  command  line.   It's just that the option itself
       will not be completed. This is intended to be used with an
       array  containing  the  options  used in the first call to
       arguments.     The    second    call    can    then    use
       `\!${^global_options}'  to  ignore  those options and com­
       plete only the ones understood in the current context.

       In every case above, the action determines how the  possi­
       ble  completions  should be generated.  In places where no
       sensible matches can be generated, the action should  con­
       sist  of  only a space. This will make the message be dis­
       played but no possible completions listed. Note that  even
       in  this  case  the  colon  at  the  end of the message is
       needed. The only case where it can be left is when neither


       Except  for  the `->string' form below, the action will be
       executed by calling the _all_labels  function  to  process
       all  tag  labels, so one doesn't need to call that explic­
       itly unless another tag is to be used, for  example  in  a
       function called in the action.

       When  only one of a fixed set of strings can be completed,
       the action can consist of  these  strings  as  a  list  in
       parentheses, as in:

              :foo:(foo bar baz)

       Such  a list in doubled parentheses should contain strings
       consisting of the string to complete followed by `\:'  and
       a description, as in:

              :foo:((a\:bar b\:baz))

       The  matches  will  be listed together with their descrip­
       tions if the description style for the values tag is  set.

       An action of the form `->string' is used by functions that
       implement a state machine. In  this  case,  the  `string's
       (with all leading and trailing spaces and tabs removed) of
       all actions that have to be used will  be  stored  in  the
       global  array state.  The function returns with a non-zero
       return value if the cursor is  not  in  a  position  where
       options  can be completed or if the current word could not
       be completed to an option.  But if the -R option is  given
       to  _arguments,  the  function  will instead return with a
       return value of 300 (to make it distinguishable from other
       return  values) after setting the global `context', `line'
       and `opt_args' parameters as described below, and  without
       resetting  any changes made to the special parameters such
       as PREFIX  and  words.   This  enables  wrapper  functions
       around  _arguments  to be able to find out if they have to
       make sure that the special completion parameters  are  not
       reset when they return.

       Note  that  this  means that a function calling _arguments
       with at least one action containing such a `->string'  has
       to declare appropriate local parameters as in:

              local context state line
              typeset -A opt_args

       This  will  ensure  that _arguments does not create unused
       global parameters.

       A string in braces is evaluated to  generate  the  matches
       and if the action does not begin with an opening parenthe­
       ses or brace, it is also split  into  separate  words  and

       words will be invoked  unchanged,  otherwise  it  will  be
       invoked  with  some  extra  strings placed after the first
       word which can  be  given  as  arguments  to  the  compadd
       builtin command and which make sure that the message given
       in the description will be shown above the matches.  These
       arguments  are taken from the array parameter `expl' which
       will be set up before executing the action and  hence  may
       be  used in it (normally in an expansion like `$expl[@]').

       If the action starts with `= ' (an equals sign followed by
       a space), _arguments will insert the contents of the argu­
       ment field of the current context as the new first element
       in the words special array and increments the value of the
       CURRENT special parameter. In other words,  it  inserts  a
       dummy  element  in the words array and makes CURRENT still
       point to the word in that array where the cursor is.  This
       is only really useful when used with one of the forms that
       make _arguments modify the words  array  to  contain  only
       some  of the words from the line, i.e. one of the argument
       description forms where the message is preceded by two  or
       three colons. For example, when the function called in the
       action for such an argument itself  uses  _arguments,  the
       dummy element is needed to make that second call to _argu­
       ments use all words from the restricted range for argument
       parsing.  Without  the  inserted  dummy element, the first
       word in the range would be taken  (by  the  second  _argu­
       ments) to be the command name and hence ignored.

       During the evaluation or execution of the action the array
       `line' will be set to the command name  and  normal  argu­
       ments  from  the  command line, i.e. to the words from the
       command line excluding all options  and  their  arguments.
       These  are  stored  in  the  associative array `opt_args',
       using the option names as keys and their arguments as  the
       values. For options that have more than one argument these
       are given as one string, separated by colons.  All  colons
       in the original arguments are preceded with backslashes.

       The  parameter `context' (set only in the calling function
       when using an action of the form  `->string',  not  during
       the  evaluation  of other actions) is set to the automati­
       cally created context names. These are either  strings  of
       the  form  `option-opt-n'  for  the  n'th  argument of the
       option -opt, or strings of the form `argument-n'  for  the
       n'th  argument  (for  rest  arguments  the n is the string
       `rest'). For example, when completing the argument of  the
       -o  option,  the  name  is `option-o-1' and for the second
       normal (non-option-) argument it is `argument-2'.

       Also, during the evaluation of  the  action,  the  context
       name  in  the curcontext parameter is changed by appending
       the same string that is stored in the context parameter.

       and  arguments  with the sets separated by single hyphens.
       The specifications before the first hyphen are  shared  by
       all  sets given after the first hyphen.  The first word in
       every other set gives the name of the set. This  name  may
       appear  in  exclusion  lists in the specifications, either
       alone or before one of the possible values described above
       (with a `-' between the name and the rest).

       For example:

              _arguments \
                  -a \
                - set1 \
                  -c \
                - set2 \
                  -d \
                  ':arg:(x2 y2)'

       This  defines two sets. When the command line contains the
       option `-c', the `-d' option and the argument will not  be
       considered  possible completions. When it contains `-d' or
       an argument, the option `-c' will  not  be  completed  any
       more,  but  if `-a' is given, both sets will still be con­
       sidered valid, because it appears before the first hyphen,
       so both sets contain this option.

       If the name-string is of the form `(name)' then all speci­
       fications in the set have an implicit exclusion list  con­
       taining  the  name of the set, i.e. all specifications are
       mutual exclusive with all other specifications in the same
       set.  This is useful for defining multiple sets of options
       which are mutually exclusive and in which the options  are
       aliases for each other. E.g.:

              _arguments \
                  -a -b \
                - '(compress)' \
                  {-c,--compress}'[compress]' \
                - '(uncompress)' \
                  {-d,--decompress}'[decompress]'

       Note  that  using  multiple sets will be slower than using
       only one set because the completion code has to parse  the
       command  line  once  for  every  set. So more than one set
       should only be used if the command syntax is  too  compli­
       cated.   Note  also  that  an  option  specification  with
       rest-arguments (as in `-foo:*:...') often allows  the  use
       of multiple sets to be avoided.

       To  simplify the specifications for commands with standard
       option parsing, the options -S and -A may be given.   With
       -S,  no  option will be completed after a `--' on the line
       and this argument will otherwise be ignored. With  -A,  no

       ment on the line.  The -A has to be followed by a  pattern
       matching  all  strings  which are not to be taken as argu­
       ments. For example, to  make  _arguments  stop  completing
       options  after the first normal argument, but ignoring all
       strings starting with  a  hyphen  even  if  they  are  not
       described  by  one  of  the  optspecs,  one would use: `-A
       "-*"'.

       Another option supported is `-O name'. The  name  will  be
       taken  as  the  name  of an array and its elements will be
       given to functions called to generate matches when execut­
       ing  the  actions.  For  example,  this allows one to give
       options for the compadd builtin that should  be  used  for
       all actions.

       Also,  the  -M  option  followed  by a string may be given
       before the first description. The string will be  used  as
       the  match  specification when completing option names and
       values instead of the default `r:|[_-]=* r:|=*'.

       Finally, the option -C can be  given  to  make  _arguments
       modify the curcontext parameter when an action of the form
       `->state' is used. This parameter is used to keep track of
       the  current  context  and  in  this  case it (and not the
       parameter context as explained above) has to be made local
       to make sure that calling functions don't use the modified
       value. Also, the local version of  curcontext  has  to  be
       initialised with the old value as in:

              local curcontext="$curcontext"

       The  function  can  also be made to automatically complete
       long options for commands that support the `--help' option
       as,  for  example,  most of the GNU commands do. For this,
       the string `--' must be given as one argument  and  if  it
       is, the command from the line is invoked with the `--help'
       option and its output is parsed to  find  possible  option
       names.  Note that this means that you should be careful to
       make sure that this feature is not used for a command that
       does not support this option.

       For  such automatically found options that get an argument
       after an `=', the function  also  tries  to  automatically
       find  out  what  should be completed as the argument.  The
       possible completions for option-arguments can be described
       with  the  arguments after the `--' (which are not used as
       described above). Each argument contains  one  description
       of  the form `pattern:message:action'. The message and the
       action have the same  format  as  for  the  normal  option
       descriptions  described above. The action will be executed
       to complete arguments of options whose description in  the
       output  of  the  command  from  the line with the `--help'
       option matches the pattern. For example:

                            '*=FILE*:file:_files' \
                            '*=DIR*:directory:_files -/'

       Here, `yes' and `no' will be completed as the argument  of
       options  whose  description ends in a star, file names for
       options that contain the substring `=FILE' in the descrip­
       tion,  and  paths  for  options whose description contains
       `=DIR'. In fact, the last  two  patterns  are  not  needed
       since  this  function  always  completes  files for option
       descriptions  containing  `=FILE'  and  paths  for  option
       descriptions that contain `=DIR' or `=PATH'. These builtin
       patterns can be overridden by patterns given as arguments,
       however.

       Note  also that _arguments tries to find out automatically
       if the argument for an option is optional. If it fails  to
       automatically  detect  this,  the colon before the message
       can be doubled to tell it about this as described for  the
       normal option descriptions above.

       If  the  pattern ends in `(-)', this will removed from the
       pattern and the action will be used  only  directly  after
       the `=', not in the next word. I.e., this is like a normal
       specification as described above using `=-'.

       The option `-i patterns' (which must be  given  after  the
       `--')  can  be  used  to  give  patterns for options which
       should not be completed. The patterns can be given as  the
       name  of an array parameter or as a literal list in paren­
       theses. E.g. `-i  "(--(en|dis)able-FEATURE*)"'  will  make
       the  options `--enable-FEATURE' and `--disable-FEATURE' be
       ignored. The option `-s pairs' (again, after the `--') can
       be  used to describe option aliases. Each pair consists of
       a pattern and a replacement. E.g.  some  configure-scripts
       describe  options  only as `--enable-foo', but also accept
       `--disable-foo'. To allow completion of the  second  form,
       one would use `-s "(#--enable- --disable-)"'.

       Example:

              _arguments '-l+:left border:' \
                         '-format:paper size:(letter A4)' \
                         '*-copy:output file:_files::resolution:(300 600)' \
                         ':postscript file:_files -g \*.\(ps\|eps\)' \
                         '*:page number:'

       This   describes   three  options:  `-l',  `-format',  and
       `-copy'. The first one  gets  one  argument  described  as
       `left  border'  for  which  no  completion will be offered
       because  of  the  empty  action.  The  argument  may  come
       directly  after  the  `-l'  or it may be given as the next
       word on the line. The `-format' option gets  one  argument
       (in  the  next  word)  described as `paper size' for which

       `-copy'  option  differs from the first two in that it may
       appear more than once on the command line and in  that  it
       accepts two arguments. The first one is mandatory and will
       be completed as a filename. The  second  one  is  optional
       (because of the second colon before the description `reso­
       lution') and will be completed from the strings `300'  and
       `600'.

       The  last two descriptions say what should be completed as
       arguments. The first one describes the first argument as a
       `postscript  file' and makes files ending in `ps' or `eps'
       be completed. The last description  says  that  all  other
       arguments  are  `page  numbers' but does not give possible
       completions.

       _cache_invalid cache_identifier
              This function returns 0 if  the  completions  cache
              corresponding  to  the given cache identifier needs
              rebuilding.  It determines this by looking  up  the
              cache-policy  style for the current context, and if
              it exists, runs the function of the same name, sup­
              plying  the full path to the relevant cache file as
              the only argument.

              Example:

                     _example_caching_policy () {
                         # rebuild if cache is more than a week old
                         oldp=( "$1"(Nmw+1) )
                         (( $#oldp ))
                     }

       _call_function return name [ args ... ]
              If a function name exists, it is  called  with  the
              arguments  args. Unless it is the empty string or a
              single hyphen, return is taken as  the  name  of  a
              parameter  and  the  return  status from the called
              function is stored in  it.   The  return  value  of
              _call_function  itself is zero if the function name
              exists and was called and non-zero otherwise.

       _call_program tag string ...
              This function is used in places where a command  is
              called, making it possible for the user to override
              the default command call.  It looks up the  command
              style  with the supplied tag.  If the style is set,
              its value is used as the command to execute.

              In  any  case,  the  strings  from  the   call   to
              _call_program  or  from  the style are concatenated
              with spaces between them and the  resulting  string
              is evaluated.  The return value is the return value
              of the command called.

              ...
              This  function  is used to complete combinations of
              values such as pairs of  hostnames  and  usernames.
              The  possible  values  will be taken from the style
              whose name is given as the  second  argument.   The
              first  argument is the tag to use to do the lookup.

              The style name should  consist  of  multiple  parts
              separated  by  hyphens which are then used as field
              names.  Known values for such fields can  be  given
              after  the second argument in arguments of the form
              `field=pattern'.  The  first  argument  without  an
              equals  sign  is taken as the name of the field for
              which completions should be generated.

              The matches generated will be taken from the  value
              of the style.  These values should contain the pos­
              sible values for the combinations where the  values
              for the different fields are separated by colons or
              characters matching the pattern given after the  -s
              option  to  _combination;  normally this is used to
              define character classes like the `-s "[:@]"'  used
              for the users-hosts style.

              Only  the values for the requested fields for which
              the patterns given in the `field=pattern' match the
              respective  fields  in  the  strings from the style
              value are generated as possible matches.

              If no style with the given name is defined for  the
              given tag but a function named with the name of the
              requested  field  preceded  by  an  underscore   is
              defined,  that  function will be called to generate
              the matches.  This is also  done  if  none  of  the
              strings  in  the  value  of the style match all the
              patterns given as arguments.

              If the same name is used for more than  one  field,
              in  both  the `field=pattern' and the argument that
              gives the field name to complete for, the number of
              the  field  (starting  with one) may be given after
              the fieldname, separated from it by a colon.

              All arguments after the requested  field  name  are
              passed  to compadd when generating matches from the
              style value, or to the functions for the fields  if
              they are called.

       _contexts names ...
              This function looks up the definitions for the con­
              text and command names given as arguments and calls
              the  handler functions for them if there is a defi­
              nition (given  with  the  compdef  function).   For

              might use `_contexts -math-' to include the comple­
              tions generated for mathematical environments.

       _describe [ -o ] descr name1 [ name2 ] opts ... -- ...
              This  function  is  useful  for preparing a list of
              command options or arguments, together  with  their
              descriptions  descr,  as  matches.  Multiple groups
              separated by -- can be supplied,  potentially  with
              different completion options opts.

              The descr is taken as a string to display above the
              matches if the format style  for  the  descriptions
              tag  is  set.   After this come one or two names of
              arrays followed by options to pass to compadd.  The
              first  array contains the possible completions with
              their descriptions in the form `completion:descrip­
              tion'.   If a second array is given, it should have
              the same number of elements as the  first  one  and
              the  corresponding  elements  are added as possible
              completions instead of the completion strings  from
              the  first  array.  The completion list will retain
              the descriptions from the first array.  Finally,  a
              set of completion options can appear.

              If  the  option `-o' appears before the first argu­
              ment, the matches added will be treated  as  option
              names  (typically  following  a `-', `--' or `+' on
              the command line).  This makes  _describe  use  the
              prefix-hidden,  prefix-needed and verbose styles to
              find out if the strings should be added at all  and
              if  the  descriptions should be shown.  Without the
              `-o' option, only the verbose style is used.

              _describe uses the _all_labels function to generate
              the matches, so it does not need to appear inside a
              loop over tag labels.

       _description [ -12VJ ] tag name descr [ specs ... ]
              This function  is  called  before  completions  are
              added  (typically  by  a call to compadd); it tests
              various  styles  and  arranges  for  any  necessary
              options to be passed on to compadd.  The styles are
              tested in the current context using the given  tag;
              options  are  put  into  the  array called name for
              passing on to compadd; the description for the cur­
              rent set of matches is passed in descr.  The styles
              tested are: format (which is first tested  for  the
              given tag and then for the descriptions tag if that
              isn't defined), hidden,  matcher,  ignored-patterns
              and  group-name  (the  last are tested only for the
              tag given as the first  argument).   This  function
              also  calls  the  _setup  function which tests some
              more styles.

              will  be  modified  so  that  the  sequence `%d' is
              replaced by the descr given as the  third  argument
              without  any  leading or trailing white space.  If,
              after removing the white space, the  descr  is  the
              empty string, the format style will not be used and
              the options put into the name array will  not  con­
              tain  an  explanation  string to be displayed above
              the matches.  If _description is called  with  more
              than  three  arguments, the additional specs should
              be of the form `char:str' and every  appearance  of
              `%char'  in  the  format string will be replaced by
              string.

              The options placed in the array will also make sure
              that  the  matches  are placed in a separate group,
              depending on the value  of  the  group-name  style.
              Normally a sorted group will be used for this (with
              the `-J' option), but if an  option  starting  with
              `-V',  `-J',  `-1',  or  `-2' is given, that option
              will be included in the array, so that it is possi­
              ble to make the group unsorted by giving the option
              `-V', `-1V', or `-2V'.

              In most cases, the function will be used like this:

                     local expl
                     _description files expl file
                     compadd "$expl[@]" - "$files[@]"

              Note the use of the parameter expl, the hyphen, and
              the list of matches.  Almost all calls  to  compadd
              within  the completion system use a similar format;
              this ensures that user-specified  styles  are  cor­
              rectly  passed down to the builtins which implement
              the internals of completion.

       _files The function _files uses  the  file-patterns  style
              and calls _path_files with all the arguments it was
              passed except for -g and -/.  These two options are
              used  depending on the setting of the file-patterns
              style.

              See _path_files below for a description of the full
              set of options accepted by _files.

       _gnu_generic
              This function is a simple wrapper around the _argu­
              ments function described above.  It can be used  to
              automatically  complete  long  options for commands
              that understand the `--help'  option.   It  is  not
              intended  to  be used from completion functions but
              as a  top-level  completion  function  in  its  own
              right.   For  example,  to enable option completion


                     compdef _gnu_generic foo bar

              in one of the initialization files after  the  call
              to compinit.

              The default installation uses this function only to
              generate completions for some GNU-commands  because
              to  complete  the  options,  the  command has to be
              called and hence it shouldn't be used if one  can't
              be  sure  that the command understands the `--help'
              option.

       _guard [ options ] pattern [ descr ]
              This function is intended to be used in  an  action
              of  functions  like _arguments.  It returns immedi­
              ately with a non-zero return value if the string to
              be  completed  does  not match the pattern.  If the
              pattern matches, the descr  is  displayed  and  the
              function  returns  zero  if the word to complete is
              not empty and non-zero otherwise.

              The pattern may be preceded by those options under­
              stood   by   compadd  that  are  passed  down  from
              _description, namely -M, -J, -V, -1, -2, -n, -F and
              -X.   All  of  these  options,  except  -X, will be
              ignored.  If the -X option appears, the description
              following  it will be used as the string to display
              if the pattern matches, unless the option descr  is
              given to _guard itself, which will then take prece­
              dence.

              As  an  example,  consider  a  command  taking  the
              options  -n  and -none, where -n has to be followed
              by a numeric value in  the  same  word.   By  using
              either of:

                     _argument '-n-:numeric value:_guard "[0-9]#"' '-none'

              or

                     _argument '-n-: :_guard "[0-9]#" "numeric value"' '-none'

              _arguments  can be made to both display the message
              `numeric  value'   and   complete   options   after
              `-n<TAB>'.   If the `-n' is already followed by one
              or more  digits  (matching  the  pattern  given  to
              _guard),  only the message will be displayed and if
              the `-n' is followed  by  another  character,  only
              options are completed.

       _message [ -r ] descr
              The  descr  is  used like the third argument to the

              string  will always be shown whether or not matches
              were generated. This  is  useful  to  display  help
              texts  in places where no completions can be gener­
              ated automatically.

              This function also uses the format  style  for  the
              messages  tag in preference to the format style for
              the descriptions tag. The latter is  used  only  if
              the former is unset.

              If the -r option is given, no style is used and the
              descr is used literally as the string  to  display.
              This  is  only  used  in cases where that string is
              taken from some pre-processed  argument  list  con­
              taining an expanded description.

       _multi_parts sep array
              This  function  receives two arguments: a separator
              character and an array.  As usual, the array may be
              either  the name of an array parameter or a literal
              array in the form `(foo bar)' (i.e. a list of words
              separated  by  white  space  in parentheses).  With
              these arguments, this  function  will  complete  to
              strings from the array where the parts separated by
              the  separator  character  are  completed  indepen­
              dently.   For  example,  the _tar function from the
              distribution caches the pathnames from the tar file
              in  an  array, and then calls this function to com­
              plete these names in the way normal  filenames  are
              completed  by  the  _path_files  function, by using
              `_multi_parts / patharray'.

              If the -i option is present, then any time there is
              a unique match it will immediately be inserted even
              if  that  requires  additional  separators  to   be
              inserted as well.  When completing from a fixed set
              of possible completions  which  are  really  words,
              this  is  often the expected behaviour; however, if
              _multi_parts should behave  like  completing  path­
              names, the -i option should not be used.

              Like other utility functions, this function accepts
              the `-V', `-J', `-1', `-2', `-n', `-f', `-X', `-M',
              `-P', `-S', `-r', `-R', and `-q' options and passes
              them to the compadd builtin.

       _next_label [ -12VJ ] tag name descr [ options ... ]
              This function should be called repeatedly to gener­
              ate  the  tag labels. On each call it will check if
              another tag label is to be used and, if there is at
              least  one, zero is returned. If no more tag labels
              are to be used, a non-zero status is returned.

              given  to  the  _description function using the tag
              label instead of the first argument as appropriate.
              The  options  given after the descr should be other
              options to be used for compadd or whatever function
              is  to  be  called  to add the matches. _next_label
              will store these options  in  the  parameter  whose
              name  is given as the second argument. This is done
              in such a way that the  description  given  by  the
              user  to  the tag-order style is preferred over the
              one given to _next_label.

              Note that this function must not be called  without
              a  previous  call to _tags or _requested because it
              uses the tag label for the  current  tag  found  by
              these functions.

              A normal use of this function for the tag labels of
              the tag foo looks like this:

                     local expl ret=1
                     ...
                     if _requested foo; then
                       ...
                       while _next_label foo expl '...'; do
                         compadd "$expl[@]" ... && ret=0
                       done
                       ...
                     fi
                     return ret

       _normal
              This function is used for  normal  command  comple­
              tion.   It has two tasks: completing the first word
              on the command line as the name of a  command,  and
              completing  the  arguments to this command.  In the
              second case, the name of the command is  looked  up
              to  see  if  special  completions exists, including
              completions defined for patterns  which  match  the
              name.   If  none  is found, completion is performed
              for the context -default-.

              The function can also be called by other completion
              functions which need to treat a range of words as a
              command line.  For example, the  function  to  com­
              plete  after  the  pre-command  specifiers  such as
              nohup removes the first word from the words  array,
              decrements  the CURRENT parameter, then calls _nor­
              mal again, with the effect that `nohup cmd ...'  is
              treated the same way was `cmd ...'.

              If  the command name matches a pattern, the parame­
              ter _compskip is checked  after  the  call  to  the

              same effect here as in the -first- context:  if  it
              is  set,  no  more  completion functions are called
              even if there are no matches so far.

       _options
              This can be used to complete option names.  It uses
              a  matching  specification  that  ignores a leading
              `no', ignores underscores and allows  the  user  to
              type  upper-case  letters  which  will  match their
              lower-case counterparts.  All arguments  passed  to
              this  function are propagated unchanged to the com­
              padd builtin.

       _options_set and _options_unset
              These functions complete only set or unset options,
              with  the  same  matching specification used in the
              _options function.

              Note that you need to uncomment a few lines in  the
              _main_complete function for these functions to work
              properly.  The lines in question are used to  store
              the option settings in effect before the completion
              widget locally sets the options  it  needs.   Hence
              these options are not generally used by the comple­
              tion system.

       _parameters
              This should be used to  complete  parameter  names.
              _parameters  can  take  a  -g  pattern option which
              specifies that only parameters whose  type  matches
              the  pattern  should  be completed.  Strings of the
              same form as those  returned  by  the  t  parameter
              expansion  flag  are  used  here  when matching the
              type.  All other arguments are passed unchanged  to
              the compadd builtin.

       _path_files
              The  function  _path_files  is  used throughout the
              completion system to complete filenames.  It allows
              completion  of  partial  paths.   For  example, the
              string   `/u/i/s/sig'   may   be    completed    to
              `/usr/include/sys/signal.h'.

              The options accepted by both _path_files and _files
              are:

              -f     Complete  all  filenames.    This   is   the
                     default.

              -/     Specifies  that  only  directories should be
                     completed.

                     Specifies that only files matching the  pat­
                     tern should be completed.

              -W paths
                     Specifies  path  prefixes  that  are  to  be
                     prepended to the string  from  the  line  to
                     generate  the  filenames but that should not
                     be inserted in the line or shown in  a  com­
                     pletion  listing.   Here,  paths  may be the
                     name of an array parameter, a  literal  list
                     of paths enclosed in parentheses or an abso­
                     lute pathname.

              -F     This option from the compadd  builtin  gives
                     direct  control  over which filenames should
                     be ignored.  If the option is  not  present,
                     the ignored-patterns style is used.

              These  functions  also accept the `-J', `-V', `-1',
              `-2', `-n', `-X', `-M', `-P', `-S', `-q', `-r', and
              `-R' options from the compadd builtin.

              Finally,  the _path_files function  uses the styles
              expand, ambiguous, special-dirs, list-suffixes  and
              file-sort.

       _regex_arguments name specs ...
              This  function  is a compiler to generate a comple­
              tion function.  The first  argument  specifies  the
              name  of the generated function while the remaining
              arguments specify a completion as a set of  regular
              expressions  with  actions.  The generated function
              has the structure of a finite-state  machine  whose
              states  correspond  to the state (i.e. the context)
              of the completion. This state machine uses  a  com­
              mand  line,  which  comes from the concatenation of
              the words array up to the current  cursor  position
              using  null  characters as separators with no extra
              quotation.  This is analysed and  at  the  end  the
              appropriate action is executed.

              Specification   arguments  take  one  of  following
              forms, in which metacharacters such  as  `(',  `)',
              `#' and `|' should be quoted.

              /pattern/ [%lookahead%] [-guard]
                     [:tag:descr:action]
                     This is a primitive  element,  corresponding
                     to  one state of the compiled state machine.
                     The  state  is  entered  if   `(#b)((#B)pat­
                     tern)(#B)lookahead*'   matches  the  command
                     line string.   If  it  matches,  `guard'  is
                     evaluated and its return status is examined;

                     otherwise  the  test  fails and other candi­
                     dates are tried.  The pattern string `[]' is
                     guaranteed never to match.

                     If  the  test  succeeds  and  the  state  is
                     entered, the left part of the  command  line
                     string matched as pattern is removed and the
                     next state is tried, proceeding from  inside
                     to outside and from left to right.

                     If  no  test succeeds and the remaining com­
                     mand line string contains no null character,
                     the  completion  target is restricted to the
                     remainder of the  command  line  string  and
                     actions  for  the  target  are executed.  In
                     this case, nothing is actually removed  from
                     the command line string so that any previous
                     or  neighbouring   state   may   also   have
                     actionss.   actionss  evaluation are ordered
                     by the tag-order style and specified tag  by
                     _alternative.   So, the various formats sup­
                     ported  by  _alternative  can  be  used   in
                     action.   descr  is  used for setting up the
                     array parameter expl.

              /pattern/+ [%lookahead%] [-guard]
                     [:tag:descr:action]
                     This  is  similar to `/pattern/ ...' but the
                     left part of the command line string is also
                     considered as part of the completion target.

              /pattern/- [%lookahead%] [-guard]
                     [:tag:descr:action]
                     This  is  similar to `/pattern/ ...' but the
                     actions of the current and  previous  states
                     are  ignored  even  if the following state's
                     `pattern' matches the empty string.

              ( spec )
                     This groups specs.

              spec # This allows any  number  of  repetitions  of
                     spec.

              spec spec
                     This  represents  the  concatenation  of two
                     specs.

              spec | spec
                     Either of the two specs can be matched.

       _requested [ -12VJ ] tag [ name descr [ command args ... ]
              ]

              already registered by a call to _tags  (see  below)
              is  requested  and  hence completion should be per­
              formed for it; it returns status zero if the tag is
              requested  and  non-zero otherwise.  This will usu­
              ally be done in a loop such as the following:

                     _tags foo bar baz
                     while _tags; do
                       if _requested foo; then
                         ... # perform completion for foo
                       fi
                       ... # test the tags bar and baz in the same way
                       ... # exit loop if matches were generated
                     done

              Note that the test for whether matches were  gener­
              ated  is  not  performed until the end of the _tags
              loop.  This is so that the user can specify  a  set
              of  tags  to  be  tested  at  the  same time in the
              tag-order parameter.

              If the name and the  descr  are  given,  _requested
              calls  the  _description  function with these argu­
              ments, including the options.

              If the command is given, the  _all_labels  function
              will be called immediately with the same arguments.
              This is often useful to do both the testing of  the
              tag,  getting  the  description for the matches and
              adding the matches at once.  For example:

                     local expl ret=1
                     _tags foo bar baz
                     while _tags; do
                       _requested foo expl 'description' \
                           compadd foobar foobaz && ret=0
                       ...
                       (( ret )) || break
                     done

              Note that this means that the command has to accept
              the options that have to be passed down to compadd.

       _retrieve_cache cache_identifier
              This function retrieves completion information from
              the  file  given  by  cache_identifier, stored in a
              directory  specified  by   the   cache-path   style
              (defaults  to  ~/.zsh/cache).   The return value is
              zero if retrieval was  successful.   It  will  only
              attempt retrieval if the use-cache style is set, so
              you can call this function without  worrying  about
              whether the user wanted to use the caching layer.


       _sep_parts
              This function is passed alternating arrays and sep­
              arators as arguments.  The arrays  specify  comple­
              tions  for  parts of strings to be separated by the
              separators.  The arrays may be the names  of  array
              parameters  or  a quoted list of words in parenthe­
              ses.   For  example,  with  the  array  `hosts=(ftp
              news)'  the  call  `_sep_parts '(foo bar)' @ hosts'
              will complete the string   `f'  to  `foo'  and  the
              string `b@n' to `bar@news'.

              This  function  passes  the `-V', `-J', `-1', `-2',
              `-n', `-X', `-M', `-P', `-S', `-r', `-R', and  `-q'
              options  and their arguments to the compadd builtin
              used to add the matches.

       _setup tag [ group ]
              This function expects a tag  as  its  argument  and
              sets  up the special parameters used by the comple­
              tion system appropriately for the tag, using styles
              such as list-colors and last-prompt.

              The  optional  group gives the name of the group in
              which the matches will be  placed.  If  it  is  not
              given, the tag is used as the group name.

              Note  that  this  function  is called automatically
              from _description so that one normally doesn't have
              to call it explicitly.

       _store_cache cache_identifier vars ...
              This  function,  when combined with _retrieve_cache
              and _cache_invalid, makes it easy  to  implement  a
              caching  layer for your completion functions.  If a
              completion function needs to perform a costly oper­
              ation  in  order  to generate data which is used to
              calculate completions, you can store that  data  in
              variables, and use this function to dump the values
              of those variables to a file.  Then,  if  they  are
              needed in subsequent shell invocations, they can be
              retrieved    quickly    from    that    file    via
              _retrieve_cache,  avoiding the needly for repeating
              the costly operation.

              The cache_identifier specifies the file  which  the
              data should be dumped to, and is stored in a direc­
              tory specified by the cache-path style (defaults to
              ~/.zsh/cache).   The  remaining  vars arguments are
              the variables to dump to the file.

              The return value is zero if storage was successful.
              The  function  will  only  attempt  storage  if the

              tion without worrying about whether the user wanted
              to use the caching layer.

              If  your   completion   function   avoids   calling
              _retrieve_cache  when it already has the completion
              data in the  environment,  it  should  probably  at
              least  call  _cache_invalid  to  check whether this
              data and the data cached on disk is still valid.

              See the _perl_modules  completion  function  for  a
              simple example of usage of this caching layer.

       _tags [ -C name [ tags ... ] ]
              If  called  with  arguments, these are taken as the
              names of the tags for  the  types  of  matches  the
              calling  completion  function  can  generate in the
              current context.  These tags are stored  internally
              and sorted by using the tag-order style.  Following
              calls to this function without arguments  from  the
              same  function  will then select the first, second,
              etc. set of tags requested by the user.  To test if
              a certain tag should be tried, the _requested func­
              tion has to be called (see above).

              The return value is zero if at  least  one  of  the
              tags is requested and non-zero otherwise.

              This  function  also accepts the -C option followed
              by a name. This name is temporarily (i.e. not visi­
              ble  outside _tags) stored in the argument field of
              the context name in the curcontext parameter.  This
              allows _tags to be made to use a more specific con­
              text name without having to change  and  reset  the
              curcontext  parameter  (which  would otherwise have
              the same effect).

       _values specs ...
              This is used to complete values (strings) and their
              arguments  or lists of such values.  It can be used
              in two ways.

              If the first argument is the option `-O name', this
              will  be  used in the same way as by the _arguments
              function, in other words the elements of  the  name
              array  will  be  given to calls to compadd and when
              executing an action.

              Otherwise, if the  first  argument  (or  the  first
              argument  after  the  `-O  name'  option if that is
              used) is the option `-s', the next argument is used
              as  the  character  that separates multiple values.
              Thus the values completed appear in the  same  word
              on   the  command  line,  unlike  completion  using


              The first argument (after the options and separator
              character if they are given) is used as a string to
              print as a description before listing the values.

              All other arguments describe  the  possible  values
              and their arguments in the same format used for the
              description of options by the  _arguments  function
              (see  above).   The  only  differences  are that no
              minus or plus sign is required  at  the  beginning,
              that  values  can  have  only one argument and that
              those forms of actions beginning with an equal sign
              are not supported.

              The  character separating a value from its argument
              can be set using the option -S (like  -s,  followed
              by  the  character  to  use as the separator in the
              next argument).  If this option is  not  used,  the
              equal sign will be used as the separator.

              Example:

                     _values -s , 'description' \
                             '*foo[bar]' \
                             '(two)*one[number]:first count:' \
                             'two[another number]::second count:(1 2 3)'

              This describes three possible values: `foo', `one',
              and `two'.  The first is described as `bar',  takes
              no  argument  and  may  appear more than once.  The
              second is described as `number',  may  appear  more
              than   once,   and  takes  one  mandatory  argument
              described as `first count' for which no  action  is
              specified so that it will not be completed automat­
              ically.  The `(two)' at the beginning says that  if
              the  value  `one'  is  on the line, the value `two'
              will not be considered to be a possible  completion
              anymore.    Finally,  the  last  value  (`two')  is
              described as `another number' and takes an optional
              argument  described as `second count' which will be
              completed from the strings `1', `2', and  `3'.  The
              _values  function will complete lists of these val­
              ues separated by commas.

              Like  _arguments  this  function  temporarily  adds
              another  context name component to the current con­
              text name while executing the  action.   Here  this
              name  is  just  the name of the value for which the
              argument is completed.

              To decide if the descriptions for the  values  (not
              those  for  the  arguments)  should be printed, the
              style verbose is used.

              function  uses  the  associative  array val_args to
              report values and their arguments, although  other­
              wise  this  is the same as the opt_args association
              used by _arguments.  This also means that the func­
              tion  calling  _values  should  declare  the state,
              line, context and val_args parameters as in:

                     local context state line
                     typeset -A val_args

              when using an action of the form `->string'.   With
              this  function the context parameter will be set to
              the name of the value whose argument is to be  com­
              pleted.

              Note  also that _values normally adds the character
              used  as  the  separator  between   values   as   a
              auto-removable  suffix  so that users don't have to
              type it themselves.  But when  using  a  `->string'
              action  _values  can't  do that because the matches
              for the argument will be generated by  the  calling
              function.   To  get the usual behaviour, the imple­
              mentor of the calling function has to add the  suf­
              fix  directly by passing the options `-qS x' (where
              x is the separator character specified with the  -s
              option  of  _values) to the function generating the
              matches or to the compadd builtin.

              Like _arguments, _values supports the -C option  in
              which  case  you have to make the parameter curcon­
              text local instead of context (as described above).

       _wanted [ -C name ]  [ -12VJ ] tag name descr command args
              ...
              In many contexts, completion will generate one par­
              ticular  set of matches (usually corresponding to a
              single tag); however,  it  is  still  necessary  to
              decide  whether  the  user requires matches of this
              type.  This function is useful in such a case.

              Like _requested, it should be passed  arguments  as
              for  _description.   It  calls _tags with the given
              tag and if that returns zero (so that  the  tag  is
              requested  by  the  user)  it  calls  _description.
              Hence to offer only one tag and immediately use the
              description generated:

                     _wanted tag expl 'description' \
                         compadd matches...

              Unlike   _requested,  however,  _wanted  cannot  be
              called  without  the  command.   This  is   because
              _wanted also implements the loop over the tags, not

              not be called in the middle of a _tags loop.

              Note  that,  as  for _requested, the command has to
              accept the options that have to be passed  down  to
              compadd.

              Like  _tags this function supports the -C option to
              give a different  name  for  the  argument  context
              field.


COMPLETION DIRECTORIES

       In  the  source  distribution,  the files are contained in
       various subdirectories of the Completion directory.   They
       may have been installed in the same structure, or into one
       single function directory.  The following is a description
       of  the  files  found in the original directory structure.
       If you wish to alter an installed file, you will  need  to
       copy  it  to  some directory which appears earlier in your
       fpath than the standard directory where it appears.

       Base   The core functions and special  completion  widgets
              automatically  bound  to  keys.  You will certainly
              need most of these, though will probably  not  need
              to alter them.  Many of these are documented above.

       Zsh    Functions for completing arguments of shell builtin
              commands  and  utility functions for this.  Some of
              these are also used  by  functions  from  the  Unix
              directory.

       Unix   Functions for completing arguments of external com­
              mands and suites of commands.  They may need  modi­
              fying  for your system, although in many cases some
              attempt is made to decide which version of  a  com­
              mand  is  present.  For example, completion for the
              mount command tries to determine the system  it  is
              running  on, while completion for many other utili­
              ties try to decide whether the GNU version  of  the
              command  is  in  use,  and hence whether the --help
              option is supported..

       X, AIX, BSD, ...
              Completion and utility function for commands avail­
              able only on some systems.


Man(1) output converted with man2html