Welcome to Linux Knowledge Base and Tutorial
"The place where you learn linux"

 Create an AccountHome | Submit News | Your Account  

Tutorial Menu
Linux Tutorial Home
Table of Contents

· Introduction to Operating Systems
· Linux Basics
· Working with the System
· Shells and Utilities
· Editing Files
· Basic Administration
· The Operating System
· The X Windowing System
· The Computer Itself
· Networking
· System Monitoring
· Solving Problems
· Security
· Installing and Upgrading
· Linux and Windows

Man Pages
Linux Topics
Test Your Knowledge

Site Menu
Site Map
Copyright Info
Terms of Use
Privacy Info
Masthead / Impressum
Your Account

Private Messages

News Archive
Submit News
User Articles
Web Links


The Web

Who's Online
There are currently, 58 guest(s) and 0 member(s) that are online.

You are an Anonymous user. You can register for free by clicking here




       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, while those begin­
       ning `_' are called by the  completion  code.   The  shell
       functions  of  the  second set, which implement completion
       behaviour and may be bound to keystrokes, are referred  to
       as `widgets'.


       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.

   Use of compinit
       This section describes the use of compinit  to  initialize
       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

       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­

       To  speed  up  the  running of compinit, it can be made to
       produce a dumped configuration that will  be  read  in  on
       future invocations; this is the default, but 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'.  The
       next invocation of compinit  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.

       If  the  parameter  _compdir is set, compinit uses it as a
       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­

   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­

       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
       these tags are not considered to be part of the completion
       system and will not be treated specially.

       The tags are:

       #compdef names... [ -[pP] patterns... [ -N 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

              Each  name  may  also be of the form `cmd=service'.
              When completing the command cmd, the function typi­
              cally  behaves  as  if the command (or special con­
              text) service was being  completed  instead.   This
              provides  a  way of altering the behaviour of func­
              tions that can perform many different  completions.
              It is implemented by setting the parameter $service
              when calling the function; the function may  choose
              to  interpret this how it wishes, and simpler func­
              tions will probably ignore it.

              If the #compdef line contains one of the options -p
              or  -P,  the  words  following are taken to be pat­
              builtin  widget  style  and  binds  it to the given
              key-sequences, if any.  The style must  be  one  of
              the builtin widgets that perform completion, namely
              complete-word, delete-char-or-list,  expand-or-com­
              plete,   expand-or-complete-prefix,   list-choices,
              menu-complete,     menu-expand-or-complete,      or
              reverse-menu-complete.   If the zsh/complist module
              is   loaded   (see   zshmodules(1))   the    widget
              menu-select is also available.

              When  one  of the key-sequences is typed, the func­
              tion 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.

       #compdef -K widget-name style key-sequences ...
              This   is  similar  to  -k  except  that  only  one
              key-sequences argument may be given for  each  wid­
              get-name  style  pair.   However, the entire set of
              three arguments may be repeated  with  a  different
              set of arguments.  Note in particular that the wid­
              get-name must be distinct in each set.  If it  does
              not  begin  with  `_' this will be added.  The wid­
              get-name 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 ]
              Functions with the #autoload  tag  are  marked  for
              autoloading  but  are  not  otherwise  treated spe­
              cially.  Typically  they  are  to  be  called  from
              within   one  of  the  completion  functions.   Any
              options supplied will be  passed  to  the  autoload
              builtin;  a typical use is +X to force the function
              to be loaded immediately.  Note that the -U flag is
              always added implicitly.

       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.


              The  name  of  a  parameter expansion within braces

              The name of a parameter in an assignment,  i.e.  on
              the left hand side of an `='

              A word in command position

              A word inside a condition (`[[...]]')

              Any word for which no other completion is defined

              A word beginning with an equals sign

              This is tried before any other completion function.
              The function called may set the _compskip parameter
              to  one  of various values: all: no further comple­
              tion is attempted; a  string  containing  the  sub­
              string  patterns:  no  pattern completion functions
              will be called; a string  containing  default:  the
              function  for  the  `-default-' context will not be
              called, but functions defined for commands will

       -math- Inside mathematical contexts, such as `((...))'

              The name of a parameter expansion (`$...')

              The word after a redirection operator.

              The contents of a parameter subscript.

              After an initial tilde (`~'), but before the  first
              slash in the word.

              On the right hand side of an assignment.

       Default  implementations  are  supplied  for each of these
       contexts.  In most cases the context -context-  is  imple­

       For the -value- context, the  form  is  `-value-,name,com­
       mand',  where  name  is the name of the parameter.  In the
       case of elements of  an  associative  array,  for  example
       `assoc=(key  <TAB>',  name  is expanded to `name-key'.  In
       certain special contexts, such as completing  after  `make
       CFLAGS=',  the command part gives the name of the command,
       here make; otherwise it is empty.

       It is not necessary to define fully  specific  completions
       as the functions provided will try to generate completions
       by progressively replacing the elements with  `-default-'.
       For  example,  when  completing  after `foo=<TAB>', _value
       will try the names `-value-,foo,' (note the empty  command
       part),                             `-value-,foo,-default-'
       and`-value-,-default-,-default-', in that order, until  it
       finds a function to handle the context.

       As an example:

              compdef '_files -g "*.log"' '-redirect-,2>,-default-'

       completes  files matching `*.log' after `2> <TAB>' for any
       command with no more specific handler defined.


              compdef _foo -value-,-default-,-default-

       specifies that _foo provides completions for the values of
       parameters for which no special function has been defined.
       This is usually handled by the function _value itself.

       The same lookup rules are used when looking up styles  (as
       described below); for example

              zstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log'

       is  another  way  to make completion after `2> <TAB>' com­
       plete files matching `*.log'.

       The following function is defined by compinit and  may  be
       called directly.

       compdef [ -an ] function names... [ -[pP] patterns... [ -N
       names... ] ]
       compdef -d names...
       compdef -k [ -an ] function style key-sequences...
       compdef -K [ -an ] function name style key-sequences ...
              The  first  form  defines  the function to call for
              ple, to complete files ending in `.h' as  arguments
              to the command foo:

                     compdef '_files -g "*.h"' foo

              The  option  -n  prevents  any  completions already
              defined for the command or context from being over­

              The  option  -d  deletes any completion defined for
              the command or contexts listed.

              The names may also contain -p, -P and -N options as
              described  for the #compdef tag.  The effect on the
              argument list is identical, switching between defi­
              nitions of patterns tried initially, patterns tried
              finally, and normal commands and contexts.

              The parameter $_compskip may be set by any function
              defined  for  a pattern context.  If it is set to a
              value containing the substring `patterns'  none  of
              the  pattern-functions will be called; if it is set
              to a value containing the substring `all', no other
              function will be called.

              The  form  with  -k  defines a widget with the same
              name as the function that 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.

              Wherever  applicable, the -a option makes the func­
              tion autoloadable, equivalent to autoload -U  func­

       The  function  compdef  can  be used to associate existing
       system works, and then more detail on how users  can  con­
       figure how and when matches are generated.

       When completion is attempted somewhere on the command line
       the completion system first works out the  context.   This
       takes  account of a number of things including the command
       word (such as `grep' or `zsh') and options  to  which  the
       current  word  may be an argument (such as the `-o' option
       to zsh which takes a shell option as an argument).

       This context information is condensed into a  string  con­
       sisting  of  multiple fields separated by colons, referred
       to simply as `the context' in the remainder of  the  docu­
       mentation.  This is used to look up styles, context-sensi­
       tive options that can be used to configure the  completion
       system.   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.  This dis­
              tinguishes the context  from  those  used  by,  for
              example, zle widgets and ZFTP functions.

       ·      The  function, if completion is called from a named
              widget rather than through  the  normal  completion
              system.   Typically this is blank, but it is set by
              special widgets such as predict-on and the  various
              functions  in the Widget directory of the distribu­
              tion to the name of  that  function,  often  in  an
              abbreviated form.

       ·      The  completer  currently  active,  the name of the
              function without the leading underscore.   A  `com­
              pleter'  is in overall control of how completion is
              to be performed; `complete' is  the  simplest,  but
              other  completers  exist  to  perform related tasks
              such as correction, or to modify the behaviour of a
              later  completer.   See  the section `Control Func­
              tions' below for more information.

       ·      The command or a  special  -context-,  just  at  it
              appears  following  the #compdef tag or the compdef
              function.  Completion functions for  commands  that
              ever, this is only the case if the command line  is
              parsed  with  standard UNIX-style options and argu­
              ments, so many completions do not set this.

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

       As an example, the context name


       says  that  normal  completion  was attempted as the first
       argument to the option -o of the command dvips:

              dvips -o ...

       and the completion function will generate filenames.

       Each type of completion the system can perform in a  given
       context  is  described  by  a  `tag',  a short descriptive
       string such as files in the example above.  Any completion
       function  may use any tag name it likes, but a list of the
       more common ones is given below.

       Usually completion will be tried by all possible  tags  in
       an  order given by the completion function.  However, this
       can be altered by using the tag-order  style.   Completion
       is  then restricted to the list of given tags in the given

       The _complete_help bindable command shows all the contexts
       and  tags  available for completion at a particular point.
       This provides an  easy  way  of  finding  information  for
       tag-order  and  other styles.  It is described in the sec­
       tion `Bindable Commands' below.

       Styles determine such things as how the matches are gener­
       ated,  similarly  to shell options but with much more con­
       trol.  They can have any number of strings as their value.
       They are defined with the zstyle builtin command (see zsh­

       When looking up styles the  completion  system  uses  full
       context names, including the tag.  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.

       Many such general purpose styles can be configured  simply
       by using the compinstall function.

       A more specific example of the use of the verbose style is
       by the completion for the kill builtin.  If the  style  is
       set,  the builtin lists full job texts and process command
       lines; otherwise it shows the bare job numbers  and  PIDs.
       To turn the style off for this use only:

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

       For  even  more control, the style can use one of the tags
       `jobs' or `processes'.  To turn off verbose  display  only
       for jobs:

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

       The  -e  option  to zstyle even allows completion function
       code to appear as the argument to a style;  this  requires
       some  understanding  of  the internals of completion func­
       tions (see see zshcompwid(1))).  For example:

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

       uses the value `_complete' for the completer style in most
       contexts,  but the value `_complete _approximate' when the
       first word on the command line is `cvs'.  This is probably
       more  conveniently  done  by  specifying the style for two
       different contexts.  This form can be slow and  should  be
       avoided  for  commonly  examined  styles  such as menu and

       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.

       Style names like those of tags are arbitrary and depend on
       the  completion function.  However, the following two sec­
       tions list some of the most common tags and styles.

   Standard Tags
       Some of the following are only used when looking  up  par­
              for arguments to a command

       arrays for names of array parameters

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

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

              for names of builtin commands

              for single characters in arguments of commands such
              as stty.    Also  used  when  completing  character
              classes after an opening bracket

              for X colormap ids

       colors for color names

              for  names of external commands.  Also used by com­
              plex commands such as  cvs  when  completing  names

              for  contexts  in  arguments  to the zstyle builtin

              used by the _approximate  and  _correct  completers
              for possible corrections

              for cursor names used by X programs

              used in some contexts to provide a way of supplying
              a default when more specific tags are  also  valid.
              Note  that  this tag is used when only the function
              field of the context name is set

              used when looking up the value of the format  style
              to generate descriptions for types of matches

              used  by the _expand completer for individual words
              (as opposed to  the  complete  set  of  expansions)
              resulting  from the expansion of a word on the com­
              mand line

              for X server extensions

              for numbers of open file descriptors

       files  the generic file-matching  tag  used  by  functions
              completing filenames

       fonts  for X font names

              for file system types (e.g. for the mount command)

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

              for  filenames  when the name has been generated by
              pattern matching

       groups for names of user groups

              for words from the history

       hosts  for hostnames

              for array indexes

       jobs   for jobs (as listed by the `jobs' builtin)

              for network interfaces

              for names of zsh keymaps

              for names of X keysyms

              for names of system libraries

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

              used to look up the format style for messages

              for names of X modifiers

              for modules (e.g. zsh modules)

              used to look up the users-hosts style

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

       names  for all kinds of names

              for USENET groups

              for nicknames of NIS maps

              for command options

              used by the _approximate, _correct and _expand com­
              pleters  when  offering  the  original  string as a

              used to look up the users-hosts style

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

              for names of parameters

              for  names  of  directories  found by searching the
              cdpath array when completing arguments  of  cd  and
              related  builtin  commands  (compare local-directo­

       paths  used to look up the values of the expand, ambiguous

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

              for sequences (e.g. mh sequences)

              for sessions in the zftp function suite

              for signal names

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

       styles for styles used by the zstyle builtin command

              for filename extensions

       tags   for tags (e.g. rpm tags)

              for makefile targets

              for time zones (e.g. when setting the TZ parameter)

       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 for one of a set of values in certain lists

              used by _pick_variant to look up the command to run
              when  determining  what  program is installed for a
              particular command name.

              for X visuals

              used to look up the format style for warnings

       strings  `false',  `off',  `no',  and  `0'  for  the value
       `false'.  The behavior for any other  value  is  undefined
       except  where explicitly mentioned.  The default value may
       be either true or false if the style is not set.

       Some of these styles are tested first for  every  possible
       tag  corresponding to a type of match, and if no style was
       found, for the default tag.  The most  notable  styles  of
       this  type  are  menu,  list-colors and styles controlling
       completion listing such as list-packed  and  last-prompt).
       When  tested  for the default tag, only the function field
       of the context will be set  so  that  a  style  using  the
       default tag will normally be defined along the lines of:

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

              This  is  tested for the default tag in addition to
              the tags valid for the current context.  If  it  is
              set  to  `true' and any of the trial matches is the
              same as the string on the command line, this  match
              will immediately be accepted (even if it would oth­
              erwise be considered ambiguous).

              When completing pathnames (where the  tag  used  is
              `paths')  this style accepts any number of patterns
              as the value in addition  to  the  boolean  values.
              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

              This style is also used by the _expand completer to
              decide if words beginning with a tilde or parameter
              expansion  should  be  expanded.   For  example, if
              there are parameters foo  and  foobar,  the  string
              `$foo' will only be expanded if accept-exact is set
              to `true'; otherwise the completion system will  be
              allowed to complete $foo to $foobar.

              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, or a
              slash in the case of directory names.  If the value
              is  `file',  the completer will only add a space to
              names of existing files.  Either a boolean true  or
              the  value  `file' may be combined with `subst', in
              which case the completer will not add  a  space  to
              words  generated  from the expansion of a substitu­
              tion of the form `$(...)' or `${...}'.
              When  completing after an equals sign that is being
              treated as an  assignment,  the  completion  system
              normally  completes  only  one  filename.   In some
              cases the value  may be a list of  filenames  sepa­
              rated  by  colons, as with PATH and similar parame­
              ters.  This style can be set to a list of  patterns
              matching the names of such parameters.

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

              If set, this style's value  will  be  used  as  the
              description  for  options that 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.

              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.

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

              This  style  defines the function that will be used
              to determine whether a cache needs rebuilding.  See
              the section on the _cache_invalid function below.

              This  style  is  used  in the function for commands
              such as make and  ant  where  calling  the  command
              directly  to generate matches suffers problems such
              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 completion function for process
              IDs uses this style with the processes tag to  gen­
              erate 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 specified command for each attempt to gen­
              erate  the  completion  list.  Hence care should be
              taken to specify only commands that  take  a  short
              time  to  run,  and in particular to avoid any that
              may never terminate.

              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).   Its 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'.

              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.

              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 either the name of a completer
              function or a string of the  form  `function:name'.
              In  the  first case the completer field of the con­
              text will contain the name of the completer without
              the  leading  underscore  and with all other under­
              Normally, using the same completer more  than  once
              only   makes   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': only  completion  will  be  done,  first
              using  the  ignored-patterns style and the $fignore
              array and then without ignoring matches.

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

              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'.

              This is used with an empty tag by the _cvs function
              to  decide  whether  the  zsh/stat module should be
              used to generate names of  modified  files  in  the
              appropriate  places (this is its only use).  If the
              style is set, completion will use the ls command.

              A list of names of network domains for  completion.
              If this is not set, 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  one  of  its values is the string `prefix', the
              partially typed word from the line will be expanded
              as far as possible even if trailing parts cannot be

              If one of its values is the string `suffix', match­
              ing  names for components after the first ambiguous
              one will  also  be  added.   This  means  that  the
              resulting  string is the longest unambiguous string
              possible.  However, menu completion can be used  to
              cycle through all matches.

       fake   This  style  may be set for any completion context.
              It specifies additional strings that will always be
              completed in that context.  The form of each string
              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.

              This is used by the completion function for parame­
              ter names.  Its values are names of parameters that
              might  not  yet  be  set  but  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  the  type  is given, the name will only be com­
              pleted if parameters of that type are  required  in
              the particular context.  Names for which no type is
              specified will always be completed.

              This is used by the standard function for  complet­
              ing filenames, _files.  If the style is unset up to
              three tags are  offered,  `globbed-files',`directo­
              ries'  and  `all-files',  depending on the types of
              files  expected by the caller of _files.  The first
              two  (`globbed-files'  and  `directories') are nor­
              mally offered together to make it  easier  to  com­
              plete files in sub-directories.

              The  file-patterns  style  provides alternatives to
              the default tags, which are not  used.   Its  value
              consists  of  elements  of  the form `pattern:tag';
              each string may contain any number of such specifi­
              cations separated by spaces.

              The pattern is a pattern that is to be used to gen­
              erate filenames.  Any occurrence  of  the  sequence
              `%p'  is  replaced  by any pattern(s) passed by the
              function calling _files.   Colons  in  the  pattern
              must  be  preceded by a backslash to make them dis­
              tinguishable 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  and used when looking up other
              styles.  Any tags in the same word will be  offered
              all files if there is no matching object file:

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

              To  alter  the default behaviour of file completion
              --- offer files matching a pattern and  directories
              on  the  first attempt, then all files --- to offer
              only matching files  on  the  first  attempt,  then
              directories, and finally all files:

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

              This  works even where there is no special pattern:
              _files matches all files using the pattern  `*'  at
              the first step and stops when it sees this pattern.
              Note also it will never try  a  pattern  more  than
              once for a single completion attempt.

              During  the  execution of completion functions, the
              EXTENDED_GLOB option is in effect, so  the  charac­
              ters  `#', `~' and `^' have special meanings in the

              The standard filename completion function uses this
              style without a tag to determine in which order the
              names should be listed; menu completion will  cycle
              through  them in the same order.  The possible val­
              ues are: `size' to sort by the size  of  the  file;
              `links' to sort by the number of links to the file;
              `modification' (or `time' or `date') to sort by the
              last  modification  time;  `access'  to sort by the
              last access time; and `inode' (or `change') to sort
              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 con­
              tains the string `reverse', sorting is done in  the
              opposite order.

       filter This  is used by the LDAP plugin for e-mail address
              completion  to  specify  the  attributes  to  match
              against when filtering entries.  So for example, if
              the style is set to `sn', matching is done  against
              surnames.   Standard LDAP filtering is used so nor­
              mal completion matching is bypassed.  If this style
              is  not  set,  the LDAP plugin is skipped.  You may
              also need to set the command style to  specify  how
              to connect to your LDAP server.

              Hence  the  listing  can be forced only for certain
              types of match.

       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 `%{...%}'.

              The style is tested with each  tag  valid  for  the
              current  completion  before  it  is  tested for the
              descriptions tag.  Hence different  format  strings
              can be defined for different types of match.

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

              Some completion functions display messages that may
              be customised by setting this style  for  the  mes­
              sages  tag.  Here, the `%d' is replaced with a mes­
              sage given by the completion function.

              Finally, the format string is looked  up  with  the
              warnings tag, for use when no matches could be gen­
              erated at all.  In this case the `%d'  is  replaced
              with  the  descriptions  for  the matches that were
              expected separated by spaces.  The sequence `%D' is
              replaced  with  the  same descriptions separated by

              It is possible  to  use  printf-style  field  width
              specifiers  with `%d' and similar escape sequences.
              This is handled by 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 a previous
              substitution (see the substitute style) or else 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.

              The  completion system can group different types of
              matches, which  appear  in  separate  lists.   This
              style  can  be used to give the names of groups for
              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 ''

              All matches for which no group name is defined will
              be put in a group named -default-.

              This style is additional to the group-name style to
              specify the order for display of the groups defined
              by that style (compare tag-order, which  determines
              which completions appear at all).  The groups named
              are shown in the given order; any other groups  are
              shown  in the order defined by the completion func­

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

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

       groups A list of names of UNIX groups.   If  this  is  not
              set,  group names are taken from the YP database or
              the file `/etc/group'.

       hidden If this is set to true, matches for the given  con­
              text  will  not be listed, although any description
              for the matches set with the format style  will  be
              shown.   If  it  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

       hosts  A list of names of hosts that should be  completed.
              If  this  is  not set, hostnames are taken from the
              file `/etc/hosts'.

              This style is used by commands that need or  accept
              hostnames  and  network  ports.  The strings in the
              value should be of  the  form  `host:port'.   Valid
              ports  are determined by the presence of hostnames;
              multiple ports for the same host may appear.

              like  the opposite of the accept-exact style:  only
              strings with missing characters will be  completed.

              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.

              The style is tested without a tag by  the  function
              completing  pathnames in order to determine whether
              to ignore the names  of  directories  already  men­
              tioned in the current word, or the name of the cur­
              rent 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; hence,  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 the specified directories  only  when
                     names of directories are completed, not when
                     completing names of files.

              Excluded values act in a similar fashion to  values
              of  the  ignored-patterns  style,  so  they  can be
              restored to  consideration  by  the  _ignored  com­

              A  list  of patterns; any trial completion matching
              one of the patterns will be excluded from consider­
              ation.   The  _ignored  completer can appear in the
              list of completers to restore the ignored  matches.
              This  is  a  more configurable version of the shell
              parameter $fignore.
              command may 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', the shell
              will wait until the user has typed enough  to  make
              the command unique before converting the name to an
              ID; attempts at  completion  will  be  unsuccessful
              until  that  point.   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 to the corresponding IDs.

              If this is set to  `true',  the  completion  system
              will insert a TAB character (assuming that was used
              to start completion) instead of performing  comple­
              tion  when  there  is no non-blank character to the
              left of the cursor.  If it is set to `false',  com­
              pletion will be done even there.

              The value may also contain the substrings `pending'
              or `pending=val'.  In this case, the typed  charac­
              ter  will be inserted instead of staring completion
              when there is unprocessed input pending.  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 when pasting characters 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

              The  default  value  of this style is `true' except
              for completion within vared builtin  command  where
              it is `false'.

              This  is  used  by the _match and _approximate com­
              pleters.  These completers are often used with menu
              completion  since  the  word  typed may bear little
              resemblance to the final completion.   However,  if
              this style is `true', the completer will start menu
              completion only if it  could  find  no  unambiguous
              initial  string  at  least  as long as the original
              string typed by the user.

              In the case of the _approximate completer, the com­
              pleter  field in the context will already have been
              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 forces  the
              prefix to be expanded unconditionally.

              The  behaviour of expand when this style is true is
              to cause _expand to give up when a single expansion
              with  the restored prefix is the same as the origi­
              nal; hence any remaining completers may be  called.

              This    is    a   more   flexible   form   of   the
              ALWAYS_LAST_PROMPT option.  If it is true, the com­
              pletion system will try to return the cursor to the
              previous command line after displaying a completion
              list.  It is tested for all tags valid for the cur­
              rent completion, then the default tag.  The  cursor
              will  be  moved  back  to the previous line if this
              style is `true' for all types of match.  Note  that
              unlike  the ALWAYS_LAST_PROMPT option this is inde­
              pendent of the numeric prefix argument.

       list   This style is used  by  the  _history_complete_word
              bindable command.  If it is set to `true' it has no
              effect.  If it is set to `false' matches  will  not
              be  listed.   This  overrides  the  setting  of the
              options controlling listing behaviour, in  particu­
              lar  AUTO_LIST.   The  context  always  starts with

              If the zsh/complist module is  loaded,  this  style
              can  be  used  to  set  color specifications.  This
              mechanism replaces the use of  the  ZLS_COLORS  and
              ZLS_COLOURS  parameters  described  in  the section
              `The zsh/complist Module' in zshmodules(1), but the
              syntax is the same.

              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.

              In addition to setting styles for specific tags, it
              is also  possible  to  use  group  names  specified
              explicitly  by the group-name tag together with the
              `(group)' syntax  allowed  by  the  ZLS_COLORS  and
              ZLS_COLOURS parameters and simply using the default
              tion  system  will  try  to make certain completion
              listings more compact  by  grouping  matches.   For
              example,  options  for  commands that have the same
              description (shown when the verbose style is set to
              `true')  will  appear  as a single entry.  However,
              menu selection can be used to cycle through all the

              This  is  tested  for each tag valid in the current
              context as well as the default tag.  If it  is  set
              to  `true',  the  corresponding  matches  appear in
              listings as if the LIST_PACKED option were set.  If
              it is set to `false', they are listed normally.

              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', the number of the  last match shown
              and the total number of matches; and `%p' and `%P',
              `Top'  when  at the beginning of the list, `Bottom'
              when at the end and the position shown  as  a  per­
              centage  of  the  total  length otherwise.  In each
              case the form with the  uppercase  letter  will  be
              replaced  by a string of fixed width, padded to the
              right with spaces, while the lowercase form will be
              replaced  by  a variable width string.  As in other
              prompt strings, the escape  sequences  `%S',  `%s',
              `%B', `%b', `%U', `%u' for entering and leaving the
              display modes standout, bold and underline are also
              available,  as  is the form `%{...%}' for enclosing
              escape sequences which display with zero width.

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

              This  style  is used by the function that completes
              filenames.   If  it  is  true,  and  completion  is
              consist of three strings: a hostname, the  path  to
              the  default  web  pages  for  the  server, and the
              directory name used by a  user  placing  web  pages
              within their home area.

              For example:

                     zstyle ':completion:*' local toast \
                         /var/http/public/toast public_html

              Completion  after  `http://toast/stuff/'  will look
              for   files   in   the   directory   /var/http/pub­
              lic/toast/stuff,      while     completion    after
              `http://toast/~yousir/' will look for files in  the
              directory ~yousir/public_html.

              If  set,  zsh will assume that mailbox files can be
              found in the directory specified.  It  defaults  to

              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  performed  with  the
              `*' inserted.

              This  style is tested separately for each tag valid
              in the current context.  Its value is added to  any
              match  specifications  given  by  the  matcher-list
              style.  It should be in the form described  in  the
              section `Matching Control' in zshcompwid(1).

              This style can be set to a list of match specifica­
              tions that are  to  be  applied  everywhere.  Match
              specifications are described in the section `Match­
              ing Control' in zshcompwid(1).  The completion sys­
              tem  will  try them one after another for each com­
              pleter selected.  For example, to try first  simple
              completion  and,  if  that  generates  no  matches,
              case-insensitive completion:

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

              By default each specification replaces the previous
                     zstyle ':completion:*:complete:*' matcher-list \
                            '' 'm:{a-zA-Z}={A-Za-z}'

              User-defined names, as explained for the  completer
              style,  are  available.   This makes it possible to
              try the same completer more than once with  differ­
              ent  match  specifications each time.  For example,
              to try normal completion without a match specifica­
              tion,  then normal completion with case-insensitive
              matching, then correction, and finally partial-word

                     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.  Note  also  that  some  com­
              pleters  such  as  _correct and _approximate do not
              use the match specifications at all,  though  these
              completers  will  only ever called once even if the
              matcher-list contains more than one element.

              Where multiple specifications are useful, note that
              the  entire  completion is done for each element of
              matcher-list, which can quickly reduce the  shell's
              performance.   As  a  rough  rule  of thumb, one to
              three strings will give acceptable performance.  On
              the  other  hand,  putting multiple space-separated
              values into the same string does not have an appre­
              ciable impact on performance.

              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

              two errors are allowed if no  numeric  argument  is
              given,  but  with  a numeric argument of six (as in
              The default value for this style is `2 numeric'.

              This style is  used  to  determine  the  trade  off
              between  the  width of the display used for matches
              and the width used for their descriptions when  the
              verbose  style  is  in effect.  The value gives the
              number  of  display  columns  to  reserve  for  the
              matches.   The  default  is  half  the width of the

              This has the most impact when several matches  have
              the   same  description  and  so  will  be  grouped
              together.  Increasing the  style  will  allow  more
              matches  to be grouped together; decreasing it will
              allow more of the description to be visible.

       menu   If this is true in the context of any of  the  tags
              defined  for the current completion menu completion
              will be used.  The value for a  specific  tag  will
              take precedence over that for the `default' tag.

              If none of the values found in this way is true but
              at least one is set to `auto', the shell behaves as
              if the AUTO_MENU option is set.

              If  one  of  the values is explicitly set to false,
              menu completion  will  be  explicitly  turned  off,
              overriding  the MENU_COMPLETE option and other set­

              In the form `yes=num', where `yes' may  be  any  of
              the true values (`yes', `true', `on' and `1'), menu
              completion will be turned on if there are at  least
              num  matches.  In the form `yes=long', menu comple­
              tion will be turned on if the list does not fit  on
              the screen.  This does not activate menu completion
              if the widget normally only lists completions,  but
              menu  completion can be activated in that case with
              the value  `yes=long-list'  (Typically,  the  value
              `select=long-list'  described  later is more useful
              as it provides control over scrolling.)

              Similarly, with any of the `false'  values  (as  in
              `no=10'), menu completion will not be used if there
              are num or more matches.

              The value of this widget also controls menu  selec­
              tion,  as  implemented  by the zsh/complist module.
              The following values may appear either alongside or
              instead of the values above.

              selection even if the current widget only  performs
              listing, use the value `select=long-list'.

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

              Finally,  it  is  possible  to activate two special
              modes of menu selection.  The word `interactive' in
              the  value  causes  interactive  mode to be entered
              immediately when menu selection is started; see the
              description  of  the zsh/complist module in zshmod­
              ules(1).RE for a description of  interactive  mode.
              Including  the  string  `search'  does the same for
              incremental search mode.  To select backward incre­
              mental  search,  include  the  string `search-back­
              ward'.  )

              muttrc If set, gives the location of the mutt  con­
                     figuration  file.   It  defaults to `~/.mut­

                     This is used with the jobs tag.   If  it  is
                     `true',  the shell will complete job numbers
                     instead of the shortest  unambiguous  prefix
                     of  the job command text.  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.

                     This  is used by the _oldlist completer.  If
                     it is set to `always', then standard widgets
                     which  perform  listing will retain the cur­
                     rent list of matches, however they were gen­
                     erated;  this  can  be turned off explicitly
                     with the value `never', giving 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 function that gen­
                     erated  the  list, then the old list will be
                     set to `true' it inserts only a common  pre­
                     fix  string, if there is any.  However, this
                     may remove parts of the original pattern, so
                     that  further  completion could produce more
                     matches than on the first attempt.  By using
                     the  _oldlist  completer  and  setting  this
                     style to _match, the list of matches  gener­
                     ated  on  the  first  attempt  will  be used

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

                     If  this style is set it is generally unwise
                     to call the _all_matches completer  uncondi­
                     tionally.   One  possible  use is for either
                     this style or  the  completer  style  to  be
                     defined with the -e option to zstyle to make
                     the style conditional.

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

                     For  example, suppose you type ^Xc to gener­
                     ate a list of corrections, and menu  comple­
                     tion  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.

                     This is used by the _approximate  and  _cor­
                     an override for 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  standard  loca­
                     tions it will be used as the default.

                     If  set,  specifies the directory containing
                     PINE  mailbox   files.    It   defaults   to

              ports  A  list  of  Internet service names (network
                     ports) to complete.  If  this  is  not  set,
                     service   names  are  taken  from  the  file

                     This is used for certain  completions  which
                     share  a  common prefix, for example command
                     options beginning with  dashes.   If  it  is
                     `true',  the prefix will not be shown in the
                     list of matches.

                     The default value for this style is `false'.

                     This, too, is used for matches with a common
                     prefix.  If it is set to `true' this  common
                     prefix must be typed by the user to generate
                     the  matches.   In  the  case   of   command
                     options,  this  means  that the initial `-',
                     `+', or `--' must be typed explicitly before
                     option names will be completed.

                     The  default value for this style is `true'.

                     This style  is  used  when  completing  path
                     names.  Its value should be a pattern match­
                     ing an initial prefix of the  word  to  com­
                     words from the history will be completed.

                     If  it  is  a range of the form `max:slice',
                     the last slice words will be completed; then
                     if  that  yields no matches, the slice words
                     before those will be tried and so on.   This
                     process stops either when at least one match
                     was been  found,  or  max  words  have  been

                     The  default  is  to complete all words from
                     the history at once.

                     This style is used by the _expand_alias com­
                     pleter  and  bindable  command.   If  set to
                     `true' (the default), regular  aliases  will
                     be  expanded  but  only in command position.
                     If it is set  to  `false',  regular  aliases
                     will  never  be  expanded.   If it is set to
                     `always', regular aliases will  be  expanded
                     even if not in command position.

                     If  set  to  false, certain commands will be
                     prevented from making  Internet  connections
                     to   retrieve   remote   information.   This
                     includes the completion for the CVS command.

                     It is not always possible to know if connec­
                     tions are in fact to a remote site, so  some
                     may be prevented unnecessarily.

                     The  _history_complete_word bindable command
                     and  the  _history  completer  use  this  to
                     decide  if  all  duplicate matches should be
                     removed, rather than just consecutive dupli­

                     If  this  is  set  for  the default tag, its
                     value will be displayed during  menu  selec­
                     tion  (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,  except
                     that  the numbers refer to the match or line
                     the mark is on.  A default  prompt  is  used
                     when the value is the empty string.

                     This style is used with the manuals tag when
                     completing names of manual pages.  If it  is
                     `true',  entries  for different sections are
                     added separately using tag names of the form
                     `manual.X',  where  X is the section number.
                     When the group-name style is also in effect,
                     pages  from  different  sections will appear
                     separately.  This style is also  used  simi­
                     larly  with  the words style when completing
                     words for the dict command. It allows  words
                     from  different  dictionary  databases to be
                     added  separately.   The  default  for  this
                     style is `false'.

                     This  is used by the _ignored completer when
                     there is only one match.  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,  making  it easy to
                     select either of them.

              sort   If set to `true', completing words from  the
                     command  history  sorts the words alphabeti­
                     cally 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.
                     If  it is set to `true', the expansions gen­
                     erated will always be sorted.  If it is  set
                     to  `menu',  then  the  expansions  are only
                     sorted  when  they  are  offered  as  single
                     strings but not in the string containing all
                     possible expansions.

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

                     The  following  example sets special-dirs to
                     `..' when the current prefix is empty, is  a
                     single  `.',  or  consists  only  of  a path
                     beginning with `../'.  Otherwise  the  value
                     is `false'.
                     bindable command will stop once when  reach­
                     ing  the  beginning  or  end of the history.
                     Invoking  _history_complete_word  will  then
                     wrap  around to the opposite end of the his­
                     tory.  If this style is set to `false'  (the
                     default),  _history_complete_word  will loop
                     immediately as in a menu completion.

                     If  set  to  `true',   this   style   causes
                     non-essential  comment  text  to  be removed
                     from completion matches.   Currently  it  is
                     only  used  when completing e-mail addresses
                     where it removes any display name  from  the
                     addresses,   cutting   them  down  to  plain
                     user@host form.

                     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'.

                     This  boolean  style  controls  whether  the
                     _expand  completer  will first try to expand
                     all substitutions 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   expansion.   If  it  is  set  to
                     `true', the word will only be expanded if it
                     doesn't  have  a suffix, i.e. if it is some­
                     thing like  `~foo'  or  `$foo'  rather  than
                     `~foo/'  or  `$foo/bar',  unless that suffix
                     itself  contains  characters  eligible   for
                     expansion.   The  default  for this style is

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

                     shell  functions.   Remaining  tags  will be
                     tried if no completions are found.

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

                      -      If  any  value  consists  of  only a
                             hyphen, then only the tags specified
                             in  the  other values are generated.
                             Normally  all  tags  not  explicitly
                             selected are tried last if the spec­
                             ified  tags  fail  to  generate  any
                             matches.   This  means that a single
                             value consisting only  of  a  single
                             hyphen turns off completion.

                     ! tags...
                             A  string  starting with an exclama­
                             tion 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

                     tag:label ...
                             Here, tag is  one  of  the  standard
                             tags and label is an arbitrary name.
                             Matches are generated as normal  but
                             the  name  label is used in contexts
                             instead of tag.  This is not  useful
                             in words starting with !.

                             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 different style set­
                             tings  for  each  attempt; see below
                             for an example.

                             As  before,  but  description   will
                             replace the `%d' in the value of the
                             format style instead of the  default
                             description  supplied by the comple­
                             tion  function.    Spaces   in   the
                             description  must  be  quoted with a
                             backslash.   A  `%d'  appearing   in
                             description  is  replaced  with  the
                             description given by the  completion

                     an underscore the first time  completion  is

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

                     On  the  first  attempt,  all  tags  will be
                     offered  but  the  functions  tag  will   be
                     replaced    by    functions-non-comp.    The
                     ignored-patterns style is set for  this  tag
                     to exclude functions starting with an under­
                     score.  If there are no matches, the  second
                     value  of  the tag-order style is used which
                     completes functions using the  default  tag,
                     this  time presumably including all function

                     The matches for one tag can  be  split  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 '???*'

                     With  the  group-names  style  set,  options
                     beginning with `--', options beginning  with
                     a  single `-' or `+' but containing multiple
                     characters, and single-letter  options  will
                     be displayed in separate groups with differ­
                     ent descriptions.

                     Another use of patterns is to  try  multiple
                     match specifications one after another.  The
                     matcher-list style offers something similar,
                     but  it  is tested very early in the comple­
                     tion system and hence can't be set for  sin­
                     gle commands nor for more specific contexts.
                     Here is how to try normal completion without
                     any  match specification and, if that gener­
                     ates no matches, try again with  case-insen­
                     sitive  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}'


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

                     Completion  in  command  position  will   be
                     attempted only if the string typed so far is
                     not empty.  This is tested using the  PREFIX
                     special  parameter;  see  zshcompwid  for  a
                     description of parameters which are  special
                     inside completion widgets.  Setting reply to
                     an  empty   array   provides   the   default
                     behaviour  of  trying all tags at once; set­
                     ting it to an array containing only a hyphen
                     disables  the  use  of all tags and hence of
                     all completions.

                     If no tag-order 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 behav­
                     ior  that  causes  arguments (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 functions completing URLs.

                     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  which
                     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, the  directory  hierarchy
                     rooted  at  this directory gives the comple­
                     tions.  The top level  directory  should  be
                     the  file  access  method,  such  as `http',
                     `ftp', `bookmark' and so on.  In many  cases
                     the  next  level  of  directories  will be a
                     filename.   The  directory   hierarchy   can
                     pleted  without reference to the urls style.

                     See the description in  the  function  _urls
                     itself  for  more  information  (e.g.  `more

                     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 direc­
                     tory  containing  the  cache  files  can  be
                     changed with the cache-path style.

                     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  use  completions  defined  with
                     `compctl -T', and the substring `default' to
                     use the  completion  defined  with  `compctl

                     Note  that  this  is only intended to smooth
                     the transition from compctl to the new  com­
                     pletion  system  and  may  disappear  in the

                     Note also that the definitions from  compctl
                     will  only  be  used if there is no specific
                     completion function for the command in ques­
                     tion.   For  example, if there is a function
                     _foo to complete arguments  to  the  command
                     foo,  compctl will never be invoked for foo.
                     However, the compctl version will  be  tried
                     if foo only uses default completion.

                     Various parts of the function system use awk
                     to extract words from files or command  out­
                     put as this universally available.  However,
                     many versions of awk have  arbitrary  limits
                     on the size of input.  If this style is set,
                     perl will be used instead.  This  is  almost
                     always  preferable  if  perl is available on
                     your system.

                     Currently this is only used  in  completions
                     usernames from this style (only),  and  will
                     restrict  subsequent  hostname completion to
                     hosts paired with that user in  one  of  the
                     values of the style.

                     It  is  possible to group values for sets of
                     commands which allow a remote login, such as
                     rlogin  and  ssh,  by  using the my-accounts
                     tag.  Similarly, values for sets of commands
                     which usually refer to the accounts of other
                     people, such as  talk  and  finger,  can  be
                     grouped  by  using  the  other-accounts tag.
                     More  ambivalent  commands   may   use   the
                     accounts tag.

                     Like  users-hosts but used for commands like
                     telnet and containing strings  of  the  form

                     If  set, as it is by default, the completion
                     listing is more verbose.  In particular many
                     commands  show  descriptions  for options if
                     this style is `true'.

              word   This is used by the _list  completer,  which
                     prevents  the insertion of completions until
                     a second completion 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 occa­
                     sions.  If this style is true, the  compari­
                     son is instead performed only on the current
                     word.  Hence if completion is  performed  on
                     another word with the same contents, comple­
                     tion will not be delayed.


       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
       matches.  If  _main_complete  is  called  with  arguments,
       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

       ments give a command name and arguments to call to  gener­
       ate the matches.

       The  following  completer  functions  are contained in the
       distribution, although users may write  their  own.   Note
       that  in  contexts the leading underscore is stripped, for
       example basic  completion  is  performed  in  the  context

              This completer can be used to add a string consist­
              ing of all other matches.  As it  influences  later
              completers it must appear as the first completer in
              the list.  The list of all matches is  affected  by
              the    avoid-completer   and   old-matches   styles
              described above.

              It may be  useful  to  use  the  _generic  function
              described  below  to  bind  _all_matches to its own
              keystroke, for example:

                     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

              This is similar to the  basic  _complete  completer
              but  allows the completions to undergo corrections.
              The maximum number of errors can  be  specified  by
              the   max-errors  style;  see  the  description  of
              approximate matching in zshexpn(1) for  how  errors
              are  counted.  Normally this completer will only be
              tried after the normal _complete completer:

                     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.

              The completer progressively increases the number of
              Note  that  this  completer  (and the _correct com­
              pleter mentioned below) can be quite  expensive  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  completion
              is  attempted  a  second  time  on the same string,

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

              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.

              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

              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- are handled specifically. These  are  all
              mentioned  above as possible arguments to the #com­
              pdef tag.

              Before trying to find a  function  for  a  specific
              context,  _complete  checks if the parameter `comp­
              context' is set. Setting `compcontext'  allows  the
              usual completion dispatching to be overridden which
              is useful in places such as a  function  that  uses
              vared for input. If it is set to an array, the ele­
              ments 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 associative
              array,  the  keys  are used as the possible comple­
              tions and the values (if  non-empty)  are  used  as
              descriptions  for the matches.  If `compcontext' is
              system  itself  but  is  nonetheless  handled  when
              explicitly called.

              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.  The  effect  is
              similar to spell-checking.  It is based on _approx­
              imate, but the completer field in the context  name
              is correct.

              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 is in the same form a  values
              to 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

              This  completer  function  does  not really perform
              completion, 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.  For this to happen, the completion system
              needs  to  be  invoked  with   complete-word,   not
              expand-or-complete  (the  default binding for TAB),
              as otherwise the string will  be  expanded  by  the
              shell's  internal  mechanism  before the completion
              system is started.  Note also this completer should
              be  called before the _complete completer function.
              The  kind of expansion to be tried is controlled by
              the substitute, glob and subst-globs-only styles.

              It is also possible to call _expand as a  function,
              in  which  case the different modes may be selected
              with options: -s for substitute, -g for glob and -o
              for subst-globs-only.

              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 styles regular, global and dis­

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

              Complete words from the shell's  command   history.
              This   completer   can   be   controlled   by   the
              remove-all-dups, and sort styles as for  the  _his­
              tory_complete_word  bindable  command, see the sec­
              tion `Bindable  Commands'  below  and  the  section
              `Completion System Configuration' above.

              The  ignored-patterns style can be set to a list of
              patterns which are compared against  possible  com­
              pletions;  matching  ones  are  removed.  With this
              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  invoked  is determined in the same
              way  as  for  the  _prefix  completer.   The   sin­
              gle-ignored  style  is  also available as described

       _list  This completer allows the insertion of  matches  to
              be  delayed  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 Con­
              figuration' above.

       _match This completer is intended to  be  used  after  the
              _complete  completer.  It behaves similarly but the
              string on the command line  may  be  a  pattern  to
              match  against  trial  completions.  This gives the
              effect of the GLOB_COMPLETE option.

              matcher-list and matcher) will not be used.

       _menu  This completer is a simple example function  imple­
              mented  to  show how menu completion can be done in
              shell code.  It should be used as  the  first  com­
              pleter  and  has  the  effect  of making later com­
              pleters perform menu completion.  Note that this is
              independent  of  the  setting  of the MENU_COMPLETE
              option and does not work with the other  menu  com­
              pletion  widgets  such as reverse-menu-complete, or

              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.

              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.  The effect  is
              similar to the expand-or-complete-prefix command.

              The  completer  style is used to decide which other
              completers are to be called  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

              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.

              This  function  provides  compatibility with bash's
              programmable completion system.  When run  it  will
              define  the  functions,  compgen and complete which
              correspond to  the  bash  builtins  with  the  same
              names.   It will then be possible to use completion
              specifications and functions written for bash.


       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.

              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

              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
              global and disabled.

              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  is  not  the  name of an alias, _expand_alias
              tries to complete the word to  a  full  alias  name
              without   expanding   it.   It  leaves  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 of the context is set to `expand-word'.

              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 set­
              tings to be defined easily.  For example, to define
              a widget that performs normal completion and starts
              menu selection:

                     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

       _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
              for the next tag, or set of tags, either  as  given
              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.
              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.

       will  only  be  called once unless it explicitly reinserts
       itself into the array.

       _all_labels [ -x ] [ -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 and its arguments
              are  called  to  generate the matches.  The options
              stored in the parameter name will automatically  be
              inserted into the args passed to the command.  Nor­
              mally, 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,  it  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:

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

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

       _alternative [ -C name ] spec ...
              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 below.

              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  are  those  accepted  by the
              _arguments function  (described  below),  excluding
              the `->state' and `=...' forms.

              For  example,  the  action may be a simple function

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

       _arguments [ -swWACRS ] [ -O name ] [ -M matchspec ] [ : ]
       spec ...
              This function can be used to give a complete speci­
              fication  for  completion for a command whose argu­
              ments follow standard UNIX option and argument con­
              ventions.   The  following forms specify individual
              sets of options and arguments; to avoid  ambiguity,
              these  may  be separated from the options to _argu­
              ments itself by a single colon.

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

                     Similar, but describes  the  next  argument,
                     whatever  number that happens to be.  If all
                     arguments are specified in this form in  the
                     correct order the numbers are unnecessary.

                     This   describes   how   arguments  (usually
                     non-option arguments,  those  not  beginning
                     with  -  or +) are to be completed when nei­
                     ther of the first two  forms  was  provided.
                     Any  number of arguments can be completed in
                     this fashion.

                     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
                     names.  This is suitable  for  standard  GNU

                     The  combination  of  -s with -w allows sin­
                     gle-letter options to be combined in a  sin­
                     gle  word even if one or more of the options
                     take arguments.  For example, if -a takes an
                     argument,  with no -s `-ab' is considered as
                     a single (unhandled) option; with -s -ab  is
                     an  option  with the argument `b'; with both
                     -s and -w, -ab may be the option -a and  the
                     option(-b) with arguments still to come.

                     The  option  -W  takes this a stage further:
                     it is  possible  to  complete  single-letter
                     options  even  after an argument that occurs
                     in the same word.  However,  it  depends  on
                     the  action  performed  whether options will
                     really be completed at this point.  For more
                     control,  use a utility function like _guard
                     as part of the action.

                     The following forms are  available  for  the
                     initial  optspec,  whether or not the option
                     has arguments.

                             Here optspec is one of the remaining
                             forms  below.   This  indicates  the
                             following optspec may  be  repeated.
                             Otherwise   if   the   corresponding
                             option is  already  present  on  the
                             command line to the left of the cur­
                             sor it will not be offered again.

                             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

                             Either of  `-+optname'  and  `+-opt­
                             name'  can  be  used to specify that
                             -optname  and  +optname   are   both

                             In  all  the  remaining  forms,  the
                             leading `-' may be  replaced  by  or
                             word after the option.  For example,
                             `-foo+:...' specifies that the  com­
                             pleted option and argument will look
                             like either `-fooarg' or `-foo arg'.

                             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, for exam­
                             ple `-foo=arg' or `-foo arg'.

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

                             An   explanation   string   may   be
                             appended  to  any  of  the preceding
                             forms of optspec by enclosing it  in
                             brackets,  as  in  `-q[query  opera­

                             The verbose style is used to  decide
                             whether  the explanation strings are
                             displayed with the option in a  com­
                             pletion 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 optarg that follows the
                             optspec; see below.

              It  is  possible  for options with a literal `+' or
              `=' to appear, but that character must  be  quoted,
              for example `-\+'.

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

                     An  argument  to  the  option;  message  and
                     action  are  treated  as  for ordinary argu­
                     ments.  In the first form, the  argument  is
                     pattern  is  empty  (i.e.,  :*:),  all   the
                     remaining  words  on the line are to be com­
                     pleted as described by  the  action;  other­
                     wise,  all  the  words up to a word matching
                     the pattern are to be  completed  using  the

                     Multiple  colons  are  treated  as  for  the
                     `*:...' forms for ordinary arguments:   when
                     the  message  is preceded by two colons, the
                     words special array and the CURRENT  special
                     parameter  are modified during the execution
                     or evaluation of the action to refer only to
                     the  words  after the option.  When preceded
                     by three colons, they are modified to  refer
                     only  to  the words covered by this descrip­

       Any literal colon in an optname, message, or  action  must
       be preceded by a backslash, `\:'.

       Each  of  the  forms  above  may  be preceded by a list in
       parentheses of option names and argument numbers.  If  the
       given option is on the command line, the options and argu­
       ments indicated in parentheses will not be  offered.   For
       example,  `(-two  -three  1)-one:...' completes the option
       `-one'; if this appears on the command line,  the  options
       -two  and  -three and the first ordinary argument will not
       be completed after it.  `(-foo):...' specifies an ordinary
       argument  completion;  -foo  will not be completed if that
       argument is already present.

       Other items may appear in the list of excluded options  to
       indicate  various  other  items that should not be applied
       when the current specification is matched: a  single  star
       (*)  for  the  rest arguments (i.e. a specification of the
       form `*:...'); a colon (:) for  all  normal  (non-option-)
       arguments; and a hyphen (-) for all options.  For example,
       if `(*)' appears before an option and the  option  appears
       on  the  command  line,  the  list  of remaining arguments
       (those shown in the above table beginning with `*:')  will
       not be completed.

       To  aid in reuse of specifications, it is possible to pre­
       cede any of the forms above with `!'; then the  form  will
       no longer be completed, although if the option or argument
       appears on the command line they will be skipped  as  nor­
       mal.   The  main  use  for  this is when the arguments are
       given by an array, and _arguments is called repeatedly for
       more  specific  contexts:  on  the  first call `_arguments
       $global_options' is used, and on subsequent calls  `_argu­
       ments !$^global_options'.
              pletions  listed.   Note that even in this case the
              colon at the end of the message is needed;  it  may
              only  be  omitted  when  neither  a  message nor an
              action is given.

       (item1 item2 ...)
              One of a list of possible matches, for example:

                     :foo:(foo bar baz)

       ((item1\:desc1 ...))
              Similar to the above,  but  with  descriptions  for
              each possible match.  Note the backslash before the
              colon.  For example,

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

              The matches will  be  listed  together  with  their
              descriptions  if  the description style is set with
              the values tag in the context.

              In this form, _arguments  processes  the  arguments
              and options and then returns control to the calling
              function with parameters set to indicate the  state
              of  processing; the calling function then makes its
              own arrangements for generating  completions.   For
              example,  functions  that implement a state machine
              can use this type of action.

              Where _arguments encounters a `->string',  it  will
              strip  all  leading  and  trailing  whitespace from
              string and set the array state to the  set  of  all
              stringss for which an action is to be performed.

              By  default  and  in  common  with  all  other well
              behaved completion  functions,  _arguments  returns
              zero  if  it  was  able to add matches and non-zero
              otherwise. However, if  the  -R  option  is  given,
              _arguments  will  instead return a status of 300 to
              indicate that $state is to be handled.

              In addition to $state,  _arguments  also  sets  the
              global  parameters `context', `line' and `opt_args'
              as described below, and does not reset any  changes
              made  to  the special parameters such as PREFIX and
              words.  This gives the calling function the  choice
              of   resetting   these  parameters  or  propagating
              changes in them.

              A function calling _arguments  with  at  least  one
              action   containing  a  `->string'  therefore  must

       = action
              If the action starts with `= ' (an equals sign fol­
              lowed  by a space), _arguments will insert the con­
              tents of the argument field of the current  context
              as the new first element in the words special array
              and increment the  value  of  the  CURRENT  special
              parameter.   This  has  the  effect  of inserting a
              dummy word onto the completion command  line  while
              not  changing the point at which completion is tak­
              ing place.

              This is most useful with one of the specifiers that
              restrict the words on the command line on which the
              action is to  operate  (the  two-  and  three-colon
              forms above).  One particular use is when an action
              itself causes _arguments on a restricted range;  it
              is  necessary to use this trick to insert an appro­
              priate command name into the range for  the  second
              call to _arguments to be able to parse the line.

              This  covers  all forms other than those above.  If
              the action starts with a space, the remaining  list
              of words will be invoked unchanged.

              Otherwise  it  will  be  invoked  with  some  extra
              strings placed after the first word; these  are  to
              be  passed  down as options to the compadd builtin.
              They ensure that the state specified by _arguments,
              in particular the descriptions of options and argu­
              ments, is correctly passed to the  completion  com­
              mand.   These  additional  arguments are taken from
              the array parameter `expl'; this  will  be  set  up
              before  executing  the  action  and  hence  may  be
              referred to inside it, typically in an expansion of
              the  form `$expl[@]' which preserves empty elements
              of the array.

       During the performance of the action the array `line' will
       be  set  to the command name and normal arguments from the
       command line, i.e. the words from the command line exclud­
       ing  all  options and their arguments.  Options are stored
       in the associative array `opt_args' with 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' is set when returning to the call­
       ing  function to perform an action of the form `->string'.
       It is set to an array of  elements  corresponding  to  the
       It  is  possible  to  specify multiple sets of options and
       arguments with the sets separated by single hyphens.   The
       specifications before the first hyphen (if any) are shared
       by all the remaining sets.  The first word in every  other
       set provides a name for the set which may appear in exclu­
       sion lists in specifications, either alone or  before  one
       of  the  possible  values  described above.  In the second
       case a `-' should appear between this name and the remain­

       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 considered.  How­
       ever, after `-a' both sets will still be considered valid.

       If the name given for one of the mutually  exclusive  sets
       is  of the form `(name)' then only one value from each set
       will ever be completed; more formally, all  specifications
       are  mutually exclusive to 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.  For example:

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

       As the completion code has to parse the command line sepa­
       rately  for  each  set  this  form of argument is slow and
       should only be used when necessary.  A useful  alternative
       is  often  an option specification with rest-arguments (as
       in `-foo:*:...'); here the option  -foo  swallows  up  all
       remaining  arguments  as  described  by the optarg defini­

       The options -S and -A are available to simplify the speci­
       fications for commands with standard option parsing.  With
       -S, no option will be completed after a `--' appearing  on
       ignoring  all  strings starting with a hyphen even if they
       are not described by one of the optspecs, the form is  `-A

       The  option `-O name' specifies the name of an array whose
       elements will be passed as arguments to  functions  called
       to execute actions.  For example, this can be used to pass
       the same set of options for the  compadd  builtin  to  all

       The  option `-M spec' sets a match specification to use to
       completion option names and values.  It must appear before
       the   first   argument   specification.   The  default  is
       `r:|[_-]=* r:|=*': this  allows  partial  word  completion
       after  `_' and `-', for example `-f-b' can be completed to

       The option -C tells _arguments to  modify  the  curcontext
       parameter  for  an  action of the form `->state'.  This is
       the standard parameter used to keep track of  the  current
       context.   Here  it  (and not the context array) should be
       made local to the calling function to avoid  passing  back
       the  modified  value and should be initialised to the cur­
       rent value at the start of the function:

              local curcontext="$curcontext"

       This is useful where  it  is  not  possible  for  multiple
       states to be valid together.

       The option `--' allows _arguments to work out the names of
       long options that support the  `--help'  option  which  is
       standard in many GNU commands.  The command word is called
       with the argument `--help' and  the  output  examined  for
       option  names.   Clearly, it can be dangerous to pass this
       to commands which may  not  support  this  option  as  the
       behaviour of the command is unspecified.

       In addition to options, `_arguments --' will try to deduce
       the types of arguments available for options when the form
       `--opt=val'  is  valid.   It  is  also possible to provide
       hints by examining the help text of the command and adding
       specifiers of the form `pattern:message:action'; note that
       normal _arguments specifiers are not used.  The pattern is
       matched  against  the  help  text for an option, and if it
       matches the message and action are used as for other argu­
       ment specifiers.  For example:

              _arguments -- '*\*:toggle:(yes no)' \
                            '*=FILE*:file:_files' \
                            '*=DIR*:directory:_files -/' \
                            '*=PATH*:directory:_files -/'

       be completed after `--directory', though not after `-C'.

       Note also that _arguments tries to find out  automatically
       if  the  argument  for an option is optional.  This can be
       specified explicitly by doubling the colon before the mes­

       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.  This is the behaviour of a
       normal specification defined with the form `=-'.

       The `_arguments --' can be followed by the option `-i pat­
       terns'  to  give  patterns for options which are not to be
       completed.  The patterns can be given as the  name  of  an
       array  parameter or as a literal list in parentheses.  For

              _arguments -- -i \

       will cause completion to ignore the options `--enable-FEA­
       TURE' and `--disable-FEATURE' (this example is useful with
       GNU configure).

       The `_arguments --' form  can  also  be  followed  by  the
       option  `-s  pair'  to describe option aliases.  Each pair
       consists of a pattern and  a  replacement.   For  example,
       some    configure-scripts   describe   options   only   as
       `--enable-foo', but also accept `--disable-foo'.  To allow
       completion of the second form:

              _arguments -- -s "(#--enable- --disable-)"

       Here is a more general example of the use of _arguments:

              _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 takes one argument described as  `left
       border' for which no completion will be offered because of
       the empty action.  Its argument may  come  directly  after
       the  `-l' or it may be given as the next word on the line.

       The `-format' option takes one argument in the next  word,
       described as `paper size' for which only the strings `let­
       ter' and `A4' will be completed.

       _cache_invalid cache_identifier
              This function returns status zero  if  the  comple­
              tions  cache corresponding to the given cache iden­
              tifier needs rebuilding.   It  determines  this  by
              looking  up  the cache-policy style for the current
              context.  This should provide a function name which
              is  run  with  the  full path to the relevant cache
              file as the only argument.


                     _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.  The return argument gives the name
              of a parameter in which the return status from  the
              function  name;  if  return  is  empty  or a single
              hyphen it is ignored.

              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 provides a mechanism for the user  to
              override  the use of an external command.  It looks
              up the command style with the supplied tag.  If the
              style  is  set, its value is used as the command to
              execute.  The strings from the call  to  _call_pro­
              gram,  or  from  the style if set, are concatenated
              with spaces between them and the  resulting  string
              is evaluated.  The return value is the return value
              of the command called.

       _combination [ -s pattern ] tag style spec ... field  opts
              This function is used to complete  combinations  of
              values,   for  example pairs of hostnames and user­
              names.  The style argument gives  the  style  which
              defines  the  pairs;  it  is looked up in a context
              with the tag specified.

              The style name consists of field names separated by
              hyphens, for example `users-hosts-ports'.  For each
              field for a value is already known, a spec  of  the
              form `field=pattern' is given.  For example, if the
              command line so far specifies  a  user  `pws',  the
              specifies a pattern.  Typically this is a character
              class, as for example `-s "[:@]"' in  the  case  of
              the   users-hosts  style.     Each  `field=pattern'
              specification restricts the completions which apply
              to  elements of the style with appropriately match­
              ing fields.

              If no style with the given name is defined for  the
              given  tag,  or  if  none of the strings in style's
              value match, but a function name  of  the  required
              field  preceded  by  an underscore is defined, that
              function will be called to  generate  the  matches.
              For  example, if there is no `users-hosts-ports' or
              no matching hostname when a host is  required,  the
              function `_hosts' will automatically be called.

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

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

       _describe  [ -oO | -t tag ] descr name1 [ name2 ] opts ...
       -- ...
              This  function associates completions with descrip­
              tions.  Multiple groups separated by -- can be sup­
              plied,   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.  This is followed by 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  `comple­
              tion:description'.  If a second array is given,  it
              should  have  the  same  number  of elements as the
              first; in this case the corresponding elements  are
              added  as  possible completions instead of the com­
              pletion strings from the first array.  The  comple­
              tion  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 names of

              If selected by the list-grouped style, strings with
              the same description will appear  together  in  the

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

       _description [ -x ] [ -12VJ ] tag name descr [ spec ... ]
              This function is not to be confused with the previ­
              ous one; it is used as a helper function for creat­
              ing  options  to compadd.  It is buried inside many
              of the higher level  completion  functions  and  so
              often does not need to be called directly.

              The  styles  listed below are tested in the current
              context using the given tag.  The resulting options
              for compadd are put into the array named name (this
              is traditionally `expl', but this convention is not
              enforced).   The  description for the corresponding
              set of matches is passed to the function in  descr.

              The  styles  tested  are:  format, hidden, matcher,
              ignored-patterns and group-name.  The format  style
              is  first tested for the given tag and then for the
              descriptions tag if no value was found,  while  the
              remainder  are only tested for the tag given as the
              first argument.  The  function  also  calls  _setup
              which tests some more styles.

              The  string  returned  by the format style (if any)
              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'.   These  supply  escape  sequence
              replacements for the format style: every appearance
              of `%char' will be replaced by string.

              If  the -x option is given, the description will be
              passed to compadd using the -x  option  instead  of
              the  default  -X.   This means that the description
              will be displayed even if there are no  correspond­
                     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.

       _dispatch context string ...
              This  sets the current context to context and looks
              for completion functions to handle this context  by
              hunting  through  the list of command names or spe­
              cial contexts  (as  described  above  for  compdef)
              given as string ....  The first completion function
              to be defined for one of the contexts in  the  list
              is  used  to generate matches.  Typically, the last
              string is  -default-  to  cause  the  function  for
              default completion to be used as a fallback.

              The  function  sets  the  parameter $service to the
              string being tried, and  sets  the  context/command
              field  (the fourth) of the $curcontext parameter to
              the context given as the first argument.

       _files The function _files calls _path_files with all  the
              arguments  it was passed except for -g and -/.  The
              use of these two options depends on the setting  of
              the  file-patterns style.

              This  function  accepts  the  full  set  of options
              allowed by _path_files, described below.

              This function is a simple wrapper around the _argu­
              ments  function described above.  It can be used to
              determine automatically the long options understood
              by  commands  that  produce  a list when passed the
              option `--help'.  It is intended to be  used  as  a
              top-level  completion  function  in  its own right.
              For example, to enable option  completion  for  the
              commands foo and bar, use

                     compdef _gnu_generic foo bar

              after the call to compinit.

              The  completion  system as supplied is conservative
              in its use of this function, since it is  important
              to  be  sure  the  command  understands  the option
              _description, namely -M, -J, -V, -1, -2, -n, -F and
              -X.  All of these options will  be  ignored.   This
              fits in conveniently with the argument-passing con­
              ventions of actions for _arguments.

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

                     _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 (the pattern passed to _guard) only
              the message will be displayed; if the `-n' is  fol­
              lowed  by  another character, only options are com­

       _message [ -r12 ] [ -VJ group ] descr
       _message -e [ tag ] descr
              The descr is used in the  same  way  as  the  third
              argument  to the _description function, except that
              the resulting string will always be  shown  whether
              or  not matches were generated.  This is useful for
              displaying a help message in places where  no  com­
              pletions can be generated.

              The  format style is examined with the messages tag
              to find a message; the usual tag, descriptions,  is
              used  only if the style is not set with the former.

              If the -r option is given, no style  is  used;  the
              descr  is taken literally as the string to display.
              This is most useful when the  descr  comes  from  a
              pre-processed  argument list which already contains
              an expanded description.

              The -12VJ options and the group are passed to  com­
              padd  and  hence  determine  the  group the message
              string is added to.

              The second form gives a description for completions
              with  the  tag tag to be shown even if there are no
              matches for that tag.  The tag can be  omitted  and
              if  so the tag is taken from the parameter $curtag;
              this is maintained by the completion system and  so
              is usually correct.

       _multi_parts sep array
              The  argument  sep  is  a separator character.  The
              array may be either the name of an array  parameter
              fixed  set  of possibilities, may be more suited to
              this form.

              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  [ -x ] [ -12VJ ] tag name descr [ options ...
              This  function  is  used to implement the loop over
              different  tag  labels  for  a  particular  tag  as
              described  above  for the tag-order style.  On each
              call it checks to see if there  are  any  more  tag
              labels;  if there is it returns status zero, other­
              wise non-zero.  As this function requires a current
              tag  to  be  set,  it  must always follow a call to
              _tags or _requested.

              The -x12VJ options and the  first  three  arguments
              are  passed  to  the  _description function.  Where
              appropriate the tag will be replaced by a tag label
              in   this  call.   Any  description  given  in  the
              tag-order style is preferred to the descr passed to

              The  options  given  after the descr are set in the
              parameter given by name, and hence are to be passed
              to  compadd  or  whatever function is called to add
              the matches.

              Here is a typical use of this function for the  tag
              foo.   The call to _requested determines if tag foo
              is required at all; the loop over _next_label  han­
              dles   any  labels  defined  for  the  tag  in  the
              tag-order style.

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

              This is the standard function called to handle com­
              pletion  outside  any  special  -context-.   It  is
              called both to complete the command word  and  also

              If the command name matches  one  of  the  patterns
              given  by  one  of the options -p or -P to compdef,
              the corresponding completion function is called and
              then  the parameter _compskip is checked.  If it is
              set completion is terminated at that point even  if
              no  matches  have  been  found.   This  is the same
              effect as in the -first- context.

              This can be used to complete  the  names  of  shell
              options.   It provides a matcher specification that
              ignores a leading  `no',  ignores  underscores  and
              allows upper-case letters to match their lower-case
              counterparts  (for   example,   `glob',   `noglob',
              `NO_GLOB'  are  all  completed).  Any arguments are
              propagated to the compadd 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  functions are not generally used by the com­
              pletion system.

              This is used to complete the names of shell parame­

              The  option  `-g  pattern' limits the completion to
              parameters whose type  matches  the  pattern.   The
              type  of  a  parameter  is  that  shown  by  `print
              ${(t)param}', hence judicious use of `*' in pattern
              is probably necessary.

              All  other  arguments  are  passed  to  the compadd

              This function 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

              The options accepted by both _path_files and _files
                     prepended  to  the  string  from the command
                     line to  generate  the  filenames  but  that
                     should  not  be  inserted as completions nor
                     shown in completion listings.   Here,  paths
                     may  be  the  name  of an array parameter, a
                     literal list of paths enclosed in  parenthe­
                     ses or an absolute pathname.

              -F ignored-files
                     This behaves as for the corresponding option
                     to the compadd  builtin.   It  gives  direct
                     control   over  which  filenames  should  be
                     ignored.  If the option is not present,  the
                     ignored-patterns style is used.

              Both _path_files and _files also accept the follow­
              ing options which  are  passed  to  compadd:  `-J',
              `-V',  `-1',  `-2',  `-n',  `-X', `-M', `-P', `-S',
              `-q', `-r', and `-R'.

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

       _pick_variant [ -c command ] [ -r name ] label=pattern ...
       label [ args ... ]
              This function is used to resolve situations where a
              single  command name requires more than one type of
              handling, either because it has more than one vari­
              ant  or  because  there is a name clash between two
              different commands.

              The command to run is taken from the first  element
              of the array words unless this is overridden by the
              option -c.  This command is run and its  output  is
              compared  with  a series of patterns.  Arguments to
              be passed to the command can be  specified  at  the
              end after all the other arguments.  The patterns to
              try in order are given by the arguments  label=pat­
              tern;  if the output of `command args ...' contains
              pattern, then label is selected as  the  label  for
              the  command  variant.   If  none  of  the patterns
              match, the final command label is selected and sta­
              tus 1 is returned.

              If  the  `-r  name'  is  given, the label picked is
              stored in the parameter named name.

              The results are also  cached  in  the  _cmd_variant
              associative  array  indexed by the name of the com­
              mand run.

              left  to  right,  with  each  pattern matched being
              stripped  in  turn  from  the  command  line  being
              tested,  until  all  of the group succeeds or until
              one fails; in the latter case, the next alternative
              is  tried.  This structure can be repeated to arbi­
              trary depth by using parentheses; matching proceeds
              from inside to outside.

              A  special procedure is applied if no test succeeds
              but the remaining command line string  contains  no
              null  character (implying the remaining word is the
              one for which completions  are  to  be  generated).
              The  completion target is restricted to the remain­
              ing word and any actions for the corresponding pat­
              terns  are  executed.   In  this  case,  nothing is
              stripped from the command line string.   The  order
              of  evaluation  of the actions can be determined by
              the tag-order style; the various formats  supported
              by  _alternative  can be used in action.  The descr
              is used for setting up the array parameter expl.

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

              /pattern/          [%lookahead%]           [-guard]
                     This is a single primitive  component.   The
                     function  tests whether the combined pattern
                     `(#b)((#B)pattern)lookahead*'  matches   the
                     command  line  string.   If  so,  `guard' is
                     evaluated and its return status is  examined
                     to determine if the test has succeeded.  The
                     pattern string `[]' is guaranteed  never  to
                     match.   The  lookahead is not stripped from
                     the command line before the next pattern  is

              /pattern/+          [%lookahead%]          [-guard]
                     This  is  similar to `/pattern/ ...' but the
                     left part of the command line  string  (i.e.
                     the  part  already  matched by previous pat­
                     terns) is also considered part of  the  com­
                     pletion target.

              /pattern/-          [%lookahead%]          [-guard]
                     This  is  similar to `/pattern/ ...' but the
                     actions  of  the  current   and   previously
                     matched  patterns  are  ignored  even if the
                     following  `pattern'   matches   the   empty

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

       _requested  [  -x  ]  [ -12VJ ] tag [ name descr [ command
       args ... ] ]
              This  function  is  called  to decide whether a tag
              already registered by a call to _tags  (see  below)
              has been requested by the user and hence completion
              should be performed for it.  It returns status zero
              if  the  tag  is  requested and non-zero otherwise.
              The function is typically used as part  of  a  loop
              over different tags as follows:

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

              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  set the
              tag-order style to specify a set of tags to be com­
              pleted at the same time.

              If  name  and descr are given, _requested calls the
              _description function with these arguments together
              with the options passed to _requested.

              If  command is given, the _all_labels function will
              be called immediately with the same arguments.   In
              simple  cases this makes it possible to perform the
              test for the tag and the matching in one  go.   For

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

              If the command is not compadd, it must nevertheless
              be prepared to handle the same options.

       _retrieve_cache cache_identifier
              This function retrieves completion information from
              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  accepts  the  compadd options `-V',
              `-J', `-1', `-2', `-n',  `-X',  `-M',  `-P',  `-S',
              `-r', `-R', and `-q' and passes them on to the com­
              padd builtin used to add the matches.

       _setup tag [ group ]
              This function sets up the special  parameters  used
              by  the completion system appropriately for the tag
              given as the first argument.  It  uses  the  styles
              list-colors,      list-packed,     list-rows-first,
              last-prompt, accept-exact, menu and force-list.

              The optional group supplies 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.

              This  function   is   called   automatically   from
              _description  and  hence  is  not  normally  called

       _store_cache cache_identifier params ...
              This function, together  with  _retrieve_cache  and
              _cache_invalid,  implements  a  caching layer which
              can be  used  in  any  completion  function.   Data
              obtained by costly operations are stored in parame­
              ters; this function then dumps the values of  those
              parameters  to  a  file.   The  data  can  then  be
              retrieved    quickly    from    that    file    via
              _retrieve_cache, even in different instances of the

              The cache_identifier specifies the file  which  the
              data  should be dumped to.  The file is stored in a
              directory specified by the cache-path  style  which
              defaults  to  ~/.zsh/cache.   The  remaining params
              arguments are the parameters to dump to the file.

              The return value is zero if storage was successful.
              The  function  will  only  attempt  storage  if the
              use-cache style is set, so you can call this  func­
              tion without worrying about whether the user wanted
              to use the caching layer.

              The   completion   function   may   avoid   calling
              _retrieve_cache  when it already has the completion
              Next,  _tags is called repeatedly without arguments
              from the same completion  function.   This  succes­
              sively  selects the first, second, etc. set of tags
              requested by the user.  The return value is zero if
              at  least one of the tags is requested and non-zero
              otherwise.  To test if a particular tag  is  to  be
              tried,  the  _requested  function  should be called
              (see above).

              If `-C name' is given, name is  temporarily  stored
              in the argument field (the fifth) of the context in
              the curcontext parameter during the call to  _tags;
              the  field  is restored on exit.  This allows _tags
              to use a more specific context  without  having  to
              change  and  reset  the curcontext parameter (which
              has the same effect).

       _values [ -O name ] [ -s sep ] [ -S sep ]  [  -wC  ]  desc
       spec ...
              This is used to complete arbitrary  keywords  (val­
              ues) and their arguments, or lists of such combina­

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

              If the first argument (or the first argument  after
              `-O  name')  is  `-s', the next argument is used as
              the character that separates multiple values.  This
              character  is  automatically added after each value
              in an auto-removable fashion (see below); all  val­
              ues  completed  by  `_values -s' appear in the same
              word on the command line, unlike  completion  using
              _arguments.   If this option is not present, only a
              single value will be completed per word.

              Normally, _values will only use the current word to
              determine  which  values are already present on the
              command line and hence  are  not  to  be  completed
              again.   If the -w option is given, other arguments
              are examined as well.

              The first non-option argument is used as  a  string
              to  print  as a description before listing the val­

              All other arguments describe  the  possible  values
              and their arguments in the same format used for the
              description of options by the  _arguments  function
                     _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'; no action is specified,
              so it will not be completed.  The  `(two)'  at  the
              beginning  says  that  if the value `one' is on the
              line, the value `two' will no longer be  considered
              a  possible  completion.   Finally,  the last value
              (`two') is described as `another number' and  takes
              an  optional  argument  described as `second count'
              for which the completions (to appear after an  `=')
              are  `1',  `2', and `3'.  The _values function will
              complete lists of these values separated by commas.

              Like  _arguments,  this  function  temporarily adds
              another context name  component  to  the  arguments
              element  (the  fifth)  of the current context while
              executing the action.  Here this name is  just  the
              name  of  the  value for which the argument is com­

              The style verbose is used to decide if the descrip­
              tions  for  the values (but not those for the argu­
              ments) should be printed.

              The associative array val_args is  used  to  report
              values and their arguments; this works similarly to
              the opt_args associative array used by  _arguments.
              Hence  the  function calling _values should declare
              the  local  parameters  state,  line,  context  and

                     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­

              Note also that _values normally adds the  character
              used   as   the  separator  between  values  as  an
              auto-removable suffix (similar to  a  `/'  after  a
              directory).   However,  this  is not possible for a
              `->string' action as the matches for  the  argument
              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.

              The  arguments  to _wanted are the same as those to
              _requested,  i.e.  arguments  to   be   passed   to
              _description.  However, in this case the command is
              not optional;  all the processing of tags,  includ­
              ing  the loop over both tags and tag labels and the
              generation of matches, is carried out automatically
              by _wanted.

              Hence to offer only one tag and immediately add the
              corresponding matches with the given description:

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

              Note that, as for _requested, the command  must  be
              able  to  accept  options to be passed down to com­

              Like _tags this function supports the -C option  to
              give  a  different  name  for  the argument context
              field.  The -x option has the same meaning  as  for


       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

       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­

zsh 4.1.1                 June 18, 2003             ZSHCOMPSYS(1)
Show your Support for the Linux Tutorial

Purchase one of the products from our new online shop. For each product you purchase, the Linux Tutorial gets a portion of the proceeds to help keep us going.



Security Code
Security Code
Type Security Code

Don't have an account yet? You can create one. As a registered user you have some advantages like theme manager, comments configuration and post comments with your name.

Help if you can!

Amazon Wish List

Did You Know?
The Linux Tutorial can use your help.


Tell a Friend About Us

Bookmark and Share

Web site powered by PHP-Nuke

Is this information useful? At the very least you can help by spreading the word to your favorite newsgroups, mailing lists and forums.
All logos and trademarks in this site are property of their respective owner. The comments are property of their posters. Articles are the property of their respective owners. Unless otherwise stated in the body of the article, article content (C) 1994-2013 by James Mohr. All rights reserved. The stylized page/paper, as well as the terms "The Linux Tutorial", "The Linux Server Tutorial", "The Linux Knowledge Base and Tutorial" and "The place where you learn Linux" are service marks of James Mohr. All rights reserved.
The Linux Knowledge Base and Tutorial may contain links to sites on the Internet, which are owned and operated by third parties. The Linux Tutorial is not responsible for the content of any such third-party site. By viewing/utilizing this web site, you have agreed to our disclaimer, terms of use and privacy policy. Use of automated download software ("harvesters") such as wget, httrack, etc. causes the site to quickly exceed its bandwidth limitation and are therefore expressly prohibited. For more details on this, take a look here

PHP-Nuke Copyright © 2004 by Francisco Burzi. This is free software, and you may redistribute it under the GPL. PHP-Nuke comes with absolutely no warranty, for details, see the license.
Page Generation: 0.51 Seconds