LinuxGuruz
  • Last 5 Forum Topics
    Replies
    Views
    Last post


The Web Only This Site
  • BOOKMARK

  • ADD TO FAVORITES

  • REFERENCES


  • MARC

    Mailing list ARChives
    - Search by -
     Subjects
     Authors
     Bodies





    FOLDOC

    Computing Dictionary




  • Text Link Ads






  • LINUX man pages
  • Linux Man Page Viewer


    The following form allows you to view linux man pages.

    Command:

    zshcompsys

    
    
    

    DESCRIPTION

           This describes the shell code for the 'new' completion system, referred
           to as compsys.  It is written in shell functions based on the  features
           described in zshcompwid(1).
    
           The features are contextual, sensitive to the point at which completion
           is started.  Many completions are already provided.  For this reason, a
           user  can perform a great many tasks without knowing any details beyond
           how to initialize the system, which is described below  in  INITIALIZA-
           TION.
    
           The context that decides what completion is to be performed may be
           ?      an  argument  or option position: these describe the position on
                  the command line at which completion is requested.  For  example
                  'first  argument  to  rmdir,  the  word  being completed names a
                  directory';
    
           ?      a special context, denoting an element in  the  shell's  syntax.
                  For  example  'a  word  in  command  position' or 'an array sub-
                  script'.
    
           A full context specification  contains  other  elements,  as  we  shall
           describe.
    
           Besides  commands  names and contexts, the system employs two more con-
           cepts, styles and tags.  These provide ways for the user  to  configure
           the system's behaviour.
    
           Tags  play  a dual role.  They serve as a classification system for the
           matches, typically indicating a class of object that the user may  need
           to  distinguish.  For example, when completing arguments of the ls com-
           mand the user may prefer to try files before directories,  so  both  of
           these are tags.  They also appear as the rightmost element in a context
           specification.
    
           Styles modify various operations of the completion system, such as out-
           put formatting, but also what kinds of completers are used (and in what
           order), or which tags are examined.  Styles may  accept  arguments  and
           are  manipulated  using  the  zstyle  command  described in see zshmod-
           ules(1).
    
           In summary, tags describe what the completion objects  are,  and  style
           how they are to be completed.  At various points of execution, the com-
           pletion system checks what styles and/or tags are defined for the  cur-
           rent  context, and uses that to modify its behavior.  The full descrip-
           tion of context handling, which determines how tags and other  elements
           of the context influence the behaviour of styles, is described below in
           COMPLETION SYSTEM CONFIGURATION.
    
           When a completion is requested, a dispatcher function  is  called;  see
                  shell   functions   of  this  set,  which  implement  completion
                  behaviour and may be bound to keystrokes,  are  referred  to  as
                  'widgets'.  These proliferate as new completions are required.
    
    
    

    INITIALIZATION

           If the system was installed completely, it should be enough to call the
           shell function compinit from your initialization  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 usually 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 sec-
           tion 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  imme-
           diately.   However,  if  compinstall  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 men-
           tioned 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  directories  from  fpath.   Then  it  must  be  autoloaded
           ('autoload -U compinstall' is recommended).  You can abort the  instal-
           lation any time you are being prompted for information, and your .zshrc
           will not be altered at all; changes only take place right at  the  end,
           where you are specifically asked for confirmation.
    
       Use of compinit
           This section describes the use of compinit to initialize completion for
           the current session when called directly; if you have  run  compinstall
           it will be called automatically from your .zshrc.
    
           To  initialize  the system, the function compinit should be in a direc-
           tory mentioned  in  the  fpath  parameter,  and  should  be  autoloaded
           ('autoload  -U  compinit'  is  recommended),  and  then  run  simply as
           'compinit'.  This will define a few utility functions, arrange for  all
           the necessary shell functions to be autoloaded, and will then re-define
           all widgets that do completion to use the new system.  If you  use  the
           menu-select  widget,  which  is  part  of  the zsh/complist module, you
           should make sure that that module is loaded before the call to compinit
           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 ini-
           tialization.
    
           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 performed 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, compdump, 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  completion  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  directories  use  the  option  -i.  This security check is skipped
           entirely when the -C option is given.
    
           The security check can be retried at any time by running  the  function
           compaudit.   This  is  the  same check used by compinit, but when it is
           executed directly any changes to fpath are made local to  the  function
           so they do not persist.  The directories to be checked may be passed as
           arguments; if none are given, compaudit uses fpath and _compdir to find
           completion  system  directories, adding missing ones to fpath as neces-
           sary.  To force a check of exactly the directories currently  named  in
           fpath,  set  _compdir  to  an  empty string before calling compaudit or
           compinit.
    
           The function  bashcompinit  provides  compatibility  with  bash's  pro-
           grammable  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.
    
       Autoloaded files
           The convention for autoloaded functions used in completion is that they
           When  compinit  is  run,  it  searches  all  such  files accessible 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
                  below.
    
                  Each  name may also be of the form 'cmd=service'.  When complet-
                  ing the command cmd, the function typically behaves  as  if  the
                  command   (or  special  context)  service  was  being  completed
                  instead.  This provides a way of altering the behaviour of func-
                  tions that can perform many different completions.  It is imple-
                  mented by setting the parameter $service when calling the  func-
                  tion;  the  function may choose to interpret this how it wishes,
                  and simpler functions will probably ignore it.
    
                  If the #compdef line contains one of the options -p or  -P,  the
                  words  following are taken to be patterns.  The function will be
                  called when completion is attempted for  a  command  or  context
                  that  matches  one  of  the patterns.  The options -p and -P are
                  used to specify patterns to be tried before or after other  com-
                  pletions  respectively.  Hence -P may be used to specify default
                  actions.
    
                  The option -N is used after a list following -p or -P; it speci-
                  fies that remaining words no longer define patterns.  It is pos-
                  sible to toggle between the three options as many times as  nec-
                  essary.
    
           #compdef -k style key-sequences...
                  This  option  creates  a widget behaving like the builtin widget
                  style and binds it to the  given  key-sequences,  if  any.   The
                  style  must  be  one of the builtin widgets that perform comple-
                  tion, 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 function in the file
                  will  be  invoked to generate the matches.  Note that a key will
                  not be re-bound if it already was (that is, was bound  to  some-
                  thing  other  than  undefined-key).   The widget created has the
                  same name as the file and can be bound to any other  keys  using
    
                  (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 specially.  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 and -z flags are always added implicitly.
    
           The  #  is part of the tag name and no white space is allowed after it.
           The #compdef tags use the compdef function described  below;  the  main
           difference is that the name of the function is supplied implicitly.
    
           The special contexts for which completion functions can be defined are:
    
           -array-value-
                  The right hand side of an array-assignment ('foo=(...)')
    
           -brace-parameter-
                  The name of a parameter expansion within braces ('${...}')
    
           -assign-parameter-
                  The name of a parameter in an assignment, i.e. on the left  hand
                  side of an '='
    
           -command-
                  A word in command position
    
           -condition-
                  A word inside a condition ('[[...]]')
    
           -default-
                  Any word for which no other completion is defined
    
           -equal-
                  A word beginning with an equals sign
    
           -first-
                  This  is  tried before any other completion function.  The func-
                  tion called may set the _compskip parameter to  one  of  various
                  values:  all:  no further completion is attempted; a string con-
                  taining the substring 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 '((...))'
    
                  On the right hand side of an assignment.
    
           Default implementations are supplied for each of  these  contexts.   In
           most  cases  the  context  -context-  is implemented by a corresponding
           function _context, for example the context '-tilde-' and  the  function
           '_tilde').
    
           The contexts -redirect- and -value- allow extra context-specific infor-
           mation.  (Internally, this is handled by the functions for each context
           calling  the function _dispatch.)  The extra information is added sepa-
           rated by commas.
    
           For the -redirect- context,  the  extra  information  is  in  the  form
           '-redirect-,op,command',  where op is the redirection operator and com-
           mand is the name of the command on the line.  If there is no command on
           the line yet, the command field will be empty.
    
           For the -value- context, the form is '-value-,name,command', where name
           is the name of the parameter.  In the case of elements of  an  associa-
           tive  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  func-
           tions  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 func-
           tion 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.
    
           Also:
    
                  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  han-
           dled 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'
    
                  the given contexts as described for the #compdef tag above.
    
                  Alternatively,  all  the  arguments  may have the form 'cmd=ser-
                  vice'.   Here  service  should  already  have  been  defined  by
                  'cmd1=service' lines in #compdef files, as described above.  The
                  argument for cmd will be completed in the same way as service.
    
                  The function argument may alternatively be a  string  containing
                  almost  any  shell  code.  If the string contains an equal sign,
                  the above will take precedence.  The option -e may  be  used  to
                  specify the first argument is to be evaluated as shell code even
                  if it contains an equal sign.  The string will be executed using
                  the eval builtin command to generate completions.  This provides
                  a way of avoiding having to define a  new  completion  function.
                  For  example,  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 overwritten.
    
                  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 iden-
                  tical, switching between  definitions  of  patterns  tried  ini-
                  tially,  patterns  tried  finally,  and normal commands and con-
                  texts.
    
                  The parameter $_compskip may be set by any function defined  for
                  a  pattern context.  If it is set to a value containing the sub-
                  string '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-complete,  menu-expand-or-complete,  and  reverse-menu-com-
                  plete, 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
    
           to complete options for commands that understand the '--help' option.
    
    
    

    COMPLETION SYSTEM CONFIGURATION

           This section gives a short overview of how the completion system works,
           and then more detail on how users can configure how  and  when  matches
           are generated.
    
       Overview
           When  completion is attempted somewhere on the command line the comple-
           tion system first works out the context.  This takes account of a  num-
           ber  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 consisting of mul-
           tiple fields separated by colons, referred to simply as  'the  context'
           in the remainder of the documentation.  This is used to look up styles,
           context-sensitive 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 a fixed set of fields,  separated
           by  colons and with a leading colon before the first, in the form :com-
           pletion:function:completer:command:argument:tag.  These have  the  fol-
           lowing meaning:
    
           ?      The literal string completion, saying that this style is used by
                  the completion system.   This  distinguishes  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 and with other underscores converted to
                  hyphens.  A 'completer' is in overall control of how  completion
                  is  to  be performed; 'complete' is the simplest, but other com-
                  pleters exist to perform related tasks such as correction, or to
                  modify  the  behaviour  of  a  later completer.  See the section
                  'Control Functions' 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 have sub-commands usually modify this field to
    
           ?      The tag.  As described previously, tags are used to discriminate
                  between the types of matches a completion function can  generate
                  in  a  certain context.  Any completion function may use any tag
                  name it likes, but a list of  the  more  common  ones  is  given
                  below.
    
           The  context  is  gradually put together as the functions are executed,
           starting with the main entry point, which  adds  :completion:  and  the
           function  element  if necessary.  The completer then adds the completer
           element.  The contextual  completion  adds  the  command  and  argument
           options.   Finally,  the  tag is added when the types of completion are
           known.  For example, the context name
    
                  :completion::complete:dvips:option-o-1:files
    
           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.
    
           Usually  completion  will  be  tried  for 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 order.
    
           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 section 'Bindable Commands' below.
    
           Styles  determine  such  things as how the matches are generated, simi-
           larly to shell options but with much more control.  They can  have  any
           number  of  strings  as  their value.  They are defined with the zstyle
           builtin command (see zshmodules(1)).
    
           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.
    
           For example, many completion functions can generate matches in a simple
           and a verbose form and use the  verbose  style  to  decide  which  form
           should be used.  To make all such functions use the verbose form, put
    
                  zstyle ':completion:*' verbose yes
    
           in  a startup file (probably .zshrc).  This gives the verbose style the
    
           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 functions (see see zshcompwid(1))).  For  exam-
           ple,
    
                  zstyle -e ':completion:*' hosts 'reply=($myhosts)'
    
           This  forces  the value of the hosts style to be read from the variable
           myhosts each time a host name is needed; this is useful if the value of
           myhosts  can  change  dynamically.  For another useful example, see the
           example in the description of the file-list style below.  This form can
           be slow and should be avoided for commonly examined styles such as menu
           and list-rows-first.
    
           Note that the order in which styles are defined does  not  matter;  the
           style  mechanism uses the most specific possible match for a particular
           style to determine the set of values.  More precisely, strings are pre-
           ferred  over patterns (for example, ':completion::complete:foo' is more
           specific than ':completion::complete:*'), and longer patterns are  pre-
           ferred over shorter patterns.
    
           Style  names like those of tags are arbitrary and depend on the comple-
           tion function.  However, the following two sections list  some  of  the
           most common tags and styles.
    
       Standard Tags
           Some  of  the following are only used when looking up particular styles
           and do not refer to a type of match.
    
           accounts
                  used to look up the users-hosts style
    
           all-expansions
                  used by the _expand completer when adding the single string con-
                  taining all possible expansions
    
           all-files
                  for  the  names of all files (as distinct from a particular sub-
                  set, see the globbed-files tag).
    
           arguments
                  for arguments to a command
    
           arrays for names of array parameters
    
                  bracket
    
           colormapids
                  for X colormap ids
    
           colors for color names
    
           commands
                  for names of external commands.  Also used by  complex  commands
                  such as cvs when completing names subcommands.
    
           contexts
                  for contexts in arguments to the zstyle builtin command
    
           corrections
                  used  by  the  _approximate and _correct completers for possible
                  corrections
    
           cursors
                  for cursor names used by X programs
    
           default
                  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
    
           descriptions
                  used when looking up the value of the format style  to  generate
                  descriptions for types of matches
    
           devices
                  for names of device special files
    
           directories
                  for  names  of  directories -- local-directories is used instead
                  when completing arguments of cd  and  related  builtin  commands
                  when the cdpath array is set
    
           directory-stack
                  for entries in the directory stack
    
           displays
                  for X display names
    
           domains
                  for network domains
    
           expansions
                  used  by  the _expand completer for individual words (as opposed
                  to the complete set of expansions) resulting from the  expansion
                  of a word on the command line
    
           functions
                  names of functions -- normally shell functions, although certain
                  commands may understand other kinds of function
    
           globbed-files
                  for filenames when the name has been generated by pattern match-
                  ing
    
           groups for names of user groups
    
           history-words
                  for words from the history
    
           hosts  for hostnames
    
           indexes
                  for array indexes
    
           jobs   for jobs (as listed by the 'jobs' builtin)
    
           interfaces
                  for network interfaces
    
           keymaps
                  for names of zsh keymaps
    
           keysyms
                  for names of X keysyms
    
           libraries
                  for names of system libraries
    
           limits for system limits
    
           local-directories
                  for names of directories that are subdirectories of the  current
                  working  directory  when  completing arguments of cd and related
                  builtin commands (compare path-directories) -- when  the  cdpath
                  array is unset, directories is used instead
    
           manuals
                  for names of manual pages
    
           mailboxes
                  for e-mail folders
    
           maps   for map names (e.g. NIS maps)
    
           messages
                  used to look up the format style for messages
    
           modifiers
           newsgroups
                  for USENET groups
    
           nicknames
                  for nicknames of NIS maps
    
           options
                  for command options
    
           original
                  used by the _approximate, _correct and _expand  completers  when
                  offering the original string as a match
    
           other-accounts
                  used to look up the users-hosts style
    
           other-files
                  for  the names of any non-directory files.  This is used instead
                  of all-files when the list-dirs-first style is in effect.
    
           packages
                  for packages (e.g. rpm or installed Debian packages)
    
           parameters
                  for names of parameters
    
           path-directories
                  for names of directories found by  searching  the  cdpath  array
                  when  completing  arguments  of  cd and related builtin commands
                  (compare local-directories)
    
           paths  used to look up the values of the  expand,  ambiguous  and  spe-
                  cial-dirs styles
    
           pods   for perl pods (documentation files)
    
           ports  for communication ports
    
           prefixes
                  for prefixes (like those of a URL)
    
           printers
                  for print queue names
    
           processes
                  for process identifiers
    
           processes-names
                  used  to  look up the command style when generating the names of
                  processes for killall
    
           sequences
           suffixes
                  for filename extensions
    
           tags   for tags (e.g. rpm tags)
    
           targets
                  for makefile targets
    
           time-zones
                  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 completing URLs
    
           users  for usernames
    
           values for one of a set of values in certain lists
    
           variant
                  used by _pick_variant to look up the command to run when  deter-
                  mining  what program is installed for a particular command name.
    
           visuals
                  for X visuals
    
           warnings
                  used to look up the format style for warnings
    
           widgets
                  for zsh widget names
    
           windows
                  for IDs of X windows
    
           zsh-options
                  for shell options
    
       Standard Styles
           Note that the values of several of these styles represent boolean  val-
           ues.   Any  of the strings 'true', 'on', 'yes', and '1' can be used for
           the value 'true' and any of the 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 corre-
           sponding 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
                  the  boolean  values.   Pathnames matching one of these patterns
                  will be accepted immediately even if the command  line  contains
                  some more partially typed pathname components and these match no
                  file under the directory accepted.
    
                  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.  If the style is set to 'continue',
                  _expand will add the expansion as a  match  and  the  completion
                  system will also be allowed to continue.
    
           accept-exact-dirs
                  This  is used by filename completion.  Unlike accept-exact it is
                  a boolean.  By default, filename completion examines all  compo-
                  nents  of  a path to see if there are completions of that compo-
                  nent, even if the component matches an existing directory.   For
                  example,  when completion after /usr/bin/, the function examines
                  possible completions to /usr.
    
                  When this style is true, any prefix of a path  that  matches  an
                  existing  directory  is accepted without any attempt to complete
                  it further.  Hence, in the given example, the path /usr/bin/  is
                  accepted immediately and completion tried in that directory.
    
                  If  you  wish  to  inhibit  this  behaviour  entirely,  set  the
                  path-completion style (see below) to false.
    
           add-space
                  This style is used by the _expand completer.  If it is true (the
                  default),  a  space  will  be inserted after all words resulting
                  from the expansion, 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
                  substitution of the form '$(...)' or '${...}'.
    
                  The  _prefix completer uses this style as a simple boolean value
                  to decide if a space should be inserted before the suffix.
    
           ambiguous
                  This applies when completing non-final  components  of  filename
                  paths,  in  other  words  those with a trailing slash.  If it is
                  set, the cursor is left after  the  first  ambiguous  component,
                  even  if  menu completion is in use.  The style is always tested
                  with the paths tag.
    
           assign-list
                  When completing after an equals sign that is being treated as an
                  ing on personal preferences, it may be useful to set this  style
                  to  something  like  'specify: %d'.  Note that this may not work
                  for some commands.
    
           avoid-completer
                  This is used by the _all_matches  completer  to  decide  if  the
                  string  consisting  of  all  matches should be added to the list
                  currently being generated.  Its value is a list of names of com-
                  pleters.  If any of these is the name of the completer that gen-
                  erated the matches in this completion, the string  will  not  be
                  added.
    
                  The  default value for this style is '_expand _old_list _correct
                  _approximate', i.e. it  contains  the  completers  for  which  a
                  string with all matches will almost never be wanted.
    
           cache-path
                  This  style  defines  the  path where any cache files containing
                  dumped completion data  are  stored.   It  defaults  to  '$ZDOT-
                  DIR/.zcompcache',  or  '$HOME/.zcompcache'  if  $ZDOTDIR  is not
                  defined.  The completion cache  will  not  be  used  unless  the
                  use-cache style is set.
    
           cache-policy
                  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.
    
           call-command
                  This style is used in the function for commands such as make and
                  ant where calling the command directly to generate matches  suf-
                  fers  problems such as being slow or, as in the case of make can
                  potentially cause actions in the makefile to be executed. If  it
                  is  set to 'true' the command is called to generate matches. The
                  default value of this style is 'false'.
    
           command
                  In many places, completion functions need to call external  com-
                  mands  to  generate  the list of completions.  This style can be
                  used to override the command that is called in some such  cases.
                  The  elements of the value are joined with spaces to form a com-
                  mand line to execute.  The value can also start with  a  hyphen,
                  in  which  case the usual command will be added to the end; this
                  is most useful for putting 'builtin' or 'command'  in  front  to
                  make  sure  the  appropriate version of a command is called, for
                  example to avoid calling a shell function 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 generate the IDs to complete and
                  the  list  of  processes  to  display  (if  the verbose style is
                  'true').  The list produced by the command should look like  the
                  plete.  The default for this style is the value of  the  special
                  parameter path.
    
           commands
                  This  is  used  by  the function completing sub-commands for the
                  system initialisation scripts (residing in /etc/init.d or  some-
                  where  not too far away from that).  Its values give the default
                  commands to complete for those commands for which the completion
                  function isn't able to find them out automatically.  The default
                  for this style are the two strings 'start' and 'stop'.
    
           complete
                  This is used by the _expand_alias function  when  invoked  as  a
                  bindable  command.  If set to 'true' and the word on the command
                  line is not the name of an alias, matching alias names  will  be
                  completed.
    
           complete-options
                  This  is  used  by  the  completer for cd, chdir and pushd.  For
                  these commands a - is used to introduce a directory stack  entry
                  and  completion  of  these  is  far  more common than completing
                  options.  Hence unless the value of this style is  true  options
                  will  not be completed, even after an initial -.  If it is true,
                  options will be completed after an initial - unless there  is  a
                  preceding -- on the command line.
    
           completer
                  The  strings  given as the value of this style provide the names
                  of the completer functions to use. The available completer func-
                  tions 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  com-
                  pleter  field  of  the context will contain the name of the com-
                  pleter without the leading underscore and with all other  under-
                  scores  replaced by hyphens.  In the second case the function is
                  the name of the completer to call, but the context will  contain
                  the user-defined name in the completer field of the context.  If
                  the name starts with a hyphen, the string for the  context  will
                  be build from the name of the completer function as in the first
                  case with the name appended to it.  For example:
    
                         zstyle ':completion:*' completer _complete _complete:-foo
    
                  Here, completion will call the _complete completer  twice,  once
                  using  'complete' and once using 'complete-foo' in the completer
                  field of the context.  Normally, using the same  completer  more
                  than  once  only makes sense when used with the 'functions:name'
                  form, because otherwise the context name will be the same in all
                  calls to the completer; possible exceptions to this rule are the
                  _ignored and _prefix completers.
    
                  confused.  The default list is :, +, /, -, %.  The list  may  be
                  empty to force a delimiter to be typed.
    
           disabled
                  If  this is set to 'true', the _expand_alias completer and bind-
                  able command will try to  expand  disabled  aliases,  too.   The
                  default is 'false'.
    
           domains
                  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.
    
           environ
                  The environ style is used when completing for 'sudo'.  It is set
                  to an array of 'VAR=value' assignments to be exported  into  the
                  local  environment  before the completion for the target command
                  is invoked.
                  zstyle ':completion:*:sudo::' environ \
                    PATH="/sbin:/usr/sbin:$PATH" HOME="/root"
    
           expand This style is used when completing strings consisting of  multi-
                  ple 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 completed.
    
                  If  one of its values is the string 'suffix', matching names for
                  components after the first ambiguous one  will  also  be  added.
                  This  means that the resulting string is the longest unambiguous
                  string possible.  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  con-
                  text.  The form of each string is 'value:description'; the colon
                  and description may be omitted, but any literal colons in  value
                  must  be  quoted  with a backslash.  Any description provided is
                  shown alongside the value in completion listings.
    
                  It is important to use a sufficiently restrictive  context  when
                  specifying  fake  strings.   Note that the styles fake-files and
                  fake-parameters  provide  additional  features  when  completing
                  files or parameters.
    
           fake-always
                  This  works  identically  to  the  fake  style  except  that the
                  ignored-patterns style is not applied to it.  This makes it pos-
                  sible  to  override  a  set of matches completely by setting the
                  ignored patterns to '*'.
    
                           fake-always mydir1 mydir2
                         zstyle ':completion::complete:cd:*:named-directories-mine' \
                           ignored-patterns '*'
    
           fake-files
                  This style is used when completing files and looked up without a
                  tag.   Its values are of the form 'dir:names...'.  This will add
                  the names (strings separated by spaces) as possible matches when
                  completing  in  the  directory dir, even if no such files really
                  exist.  The dir may be a pattern; pattern characters  or  colons
                  in  dir  should  be quoted with a backslash to be treated liter-
                  ally.
    
                  This can be useful on systems that support special file  systems
                  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.
    
                  The  pattern  form can be used to add a certain 'magic' entry to
                  all directories on a particular file system.
    
           fake-parameters
                  This is used by the completion  function  for  parameter  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 completed if parameters of that type are
                  required in the particular context.  Names for which no type  is
                  specified will always be completed.
    
           file-list
                  This  style  controls whether files completed using the standard
                  builtin mechanism are to be listed with a long list  similar  to
                  ls  -l.   Note  that this feature uses the shell module zsh/stat
                  for file information; this loads the  builtin  stat  which  will
                  replace any external stat executable.  To avoid this the follow-
                  ing code can be included in an initialization file:
    
                         zmodload -i zsh/stat
                         disable stat
    
                  The style may either be set to a true value (or 'all'),  or  one
                  of  the  values 'insert' or 'list', indicating that files are to
                  be listed in long format in all circumstances, or when  attempt-
                  ing  to  insert  a file name, or when listing file names without
                  attempting to insert one.
    
                  More generally, the value may be an array of any  of  the  above
                  values, optionally followed by =num.  If num is present it gives
                  the maximum number of matches for which long listing style  will
                  be used.  For example,
                  This  is used by the standard function for completing filenames,
                  _files.  If the style is unset up to  three  tags  are  offered,
                  'globbed-files','directories'  and 'all-files', depending on the
                  types of files  expected by the caller of _files.  The first two
                  ('globbed-files'   and   'directories')   are  normally  offered
                  together to make it easier to complete 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
                  specifications separated by spaces.
    
                  The pattern is a pattern that is to be used  to  generate  file-
                  names.   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 distin-
                  guishable from the colon before the tag.  If more than one  pat-
                  tern  is  needed, the patterns can be given inside braces, sepa-
                  rated 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 at the same time and  before  later  words.
                  If no ':tag' is given the 'files' tag will be used.
    
                  The  tag  may also be followed by an optional second colon and a
                  description, which will be used for the '%d' in the value of the
                  format style (if that is set) instead of the default description
                  supplied by the completion function.  If the  description  given
                  here  contains itself a '%d', that is replaced with the descrip-
                  tion supplied by the completion function.
    
                  For example, to make the rm command first complete only names of
                  object  files  and  then  the  names of 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.
    
                  sorted alphabetically by name.  If the value contains the string
                  'reverse', sorting is done in the opposite order.  If the  value
                  contains the string 'follow', timestamps are associated with the
                  targets of symbolic links; the default is to use the  timestamps
                  of the links themselves.
    
           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  normal
                  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.
    
           force-list
                  This forces a list of completions to be shown at any point where
                  listing is done, even in cases where the list would  usually  be
                  suppressed.   For  example,  normally  the list is only shown if
                  there are at least two different matches.  By setting this style
                  to  'always',  the  list  will always be shown, even if there is
                  only a single match that  will  immediately  be  accepted.   The
                  style  may  also be set to a number.  In this case the list will
                  be shown if there are at least that many matches, even  if  they
                  would all insert the same string.
    
                  This style is tested for the default tag as well as for each tag
                  valid for the current completion.   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 following sequences to specify output attributes, as
                  described in the section EXPANSION OF PROMPT SEQUENCES  in  zsh-
                  misc(1): '%B', '%S', '%U', '%F', '%K' and their lower case coun-
                  terparts, as well as '%{...%}'.  '%F', '%K' and  '%{...%}'  take
                  arguments  in  the same form as prompt expansion.  Note that the
                  %G sequence is not available; an argument to '%{' should be used
                  instead.
    
                  The  style is tested with each tag valid for the current comple-
                  tion before it is tested for the descriptions tag.   Hence  dif-
                  ferent  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  cus-
                  tomised  by  setting this style for the messages tag.  Here, the
    
           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 com-
                  pleter and bindable command will try to expand global aliases.
    
           group-name
                  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 particular tags.  For example,  in  com-
                  mand  position  the completion system generates names of builtin
                  and external commands, names of  aliases,  shell  functions  and
                  parameters  and reserved words as possible completions.  To have
                  the external commands and shell functions listed separately:
    
                         zstyle ':completion:*:*:-command-:*:commands' group-name commands
                         zstyle ':completion:*:*:-command-:*:functions' group-name functions
    
                  As a consequence, any match with the same tag will be  displayed
                  in the same group.
    
                  If  the  name  given is the empty string the name of the tag for
                  the matches will be used as the name of the group.  So, to  have
                  all  different  types  of  matches displayed separately, one can
                  just set:
    
                         zstyle ':completion:*' group-name ''
    
                  All matches for which no group name is defined will be put in  a
                  group named -default-.
    
           group-order
                  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 function.
    
                  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 context  will  not
                  be listed, although any description for the matches set with the
                  'host:port'.   Valid  ports  are  determined  by the presence of
                  hostnames; multiple ports for the same host may appear.
    
           ignore-line
                  This is tested for each tag valid for  the  current  completion.
                  If  it  is  set to 'true', none of the words that are already on
                  the line will be considered as possible completions.  If  it  is
                  set  to 'current', the word the cursor is on will not be consid-
                  ered as a possible completion.   The  value  'current-shown'  is
                  similar but only applies if the list of completions is currently
                  shown on the screen.  Finally, if the style is set  to  'other',
                  all  words  on  the  line  except  for  the  current one will be
                  excluded from the possible completions.
    
                  The values 'current' and 'current-shown'  are  a  bit  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
                  multiple  times  even  if  the  command  in question accepts the
                  option more than once.
    
           ignore-parents
                  The style is tested without a tag  by  the  function  completing
                  pathnames  in  order to determine whether to ignore the names of
                  directories already mentioned in the current word, or  the  name
                  of the current working directory.  The value must include one or
                  both of the following strings:
    
                  parent The name of any directory whose path is already contained
                         in  the  word  on the line is ignored.  For example, when
                         completing after foo/../, the directory foo will  not  be
                         considered 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 '../'.
    
                  directory
                         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
                  Note that the EXTENDED_GLOB option is set during  the  execution
                  of completion functions, so the characters '#', '~' and '^' have
                  special meanings in the patterns.
    
           insert This style is used  by  the  _all_matches  completer  to  decide
                  whether  to  insert  the  list  of  all  matches unconditionally
                  instead of adding the list as another match.
    
           insert-ids
                  When completing process IDs, for example  as  arguments  to  the
                  kill and wait builtins the name of a 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 completion 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 con-
                  verting the name to an ID; attempts at completion will be unsuc-
                  cessful  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.
    
           insert-tab
                  If this is set to 'true', the completion system  will  insert  a
                  TAB  character  (assuming  that  was  used  to start completion)
                  instead of performing completion  when  there  is  no  non-blank
                  character  to  the left of the cursor.  If it is set to 'false',
                  completion will be done even there.
    
                  The value may also contain the substrings  'pending'  or  'pend-
                  ing=val'.   In  this  case, the typed character will be inserted
                  instead of starting 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 guaran-
                  teed on all platforms.
    
                  The default value of this style is 'true' except for  completion
                  within vared builtin command where it is 'false'.
    
           insert-unambiguous
                  This  is  used by the _match and _approximate completers.  These
                  completers are often used with menu completion  since  the  word
                  typed may bear little resemblance to the final completion.  How-
                  ever, 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.
    
                  the  style  is  set  to 'changed' (the default), the prefix will
                  only be left unchanged if there were other changes  between  the
                  expanded words and the original word from the command line.  Any
                  other value 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 original;  hence  any  remaining  com-
                  pleters may be called.
    
           last-prompt
                  This  is  a more flexible form of the ALWAYS_LAST_PROMPT option.
                  If it is true, the completion system will try to return the cur-
                  sor  to  the previous command line after displaying a completion
                  list.  It is tested for all tags valid for the  current  comple-
                  tion,  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
                  independent of the numeric prefix argument.
    
           known-hosts-files
                  This style should contain a list of files  to  search  for  host
                  names  and (if the use-ip style is set) IP addresses in a format
                  compatible with ssh known_hosts files.  If it is  not  set,  the
                  files  /etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts are used.
    
           list   This style is used by the _history_complete_word  bindable  com-
                  mand.  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 particular
                  AUTO_LIST.  The context  always  starts  with  ':completion:his-
                  tory-words'.
    
           list-colors
                  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 sec-
                  tion '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  every-
                  where.  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 pos-
                  sible  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 tag.
    
                  It  is  possible  to use any color specifications already set up
                  tag.
    
           list-grouped
                  If  this  style  is  'true' (the default), the completion 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 matches.
    
           list-packed
                  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.
    
           list-prompt
                  If  this style is set for the default tag, completion 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  screenful  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 percentage 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, and
                  '%F', '%f', '%K', '%k' for changing  the  foreground  background
                  colour, are also available, as is the form '%{...%}' for enclos-
                  ing escape sequences which display with zero (or, with a numeric
                  argument, some other) width.
    
                  After  deleting  this  prompt  the variable LISTPROMPT should be
                  unset for the removal to take effect.
    
           list-rows-first
                  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.
    
           list-suffixes
                  This style is used by the function that completes filenames.  If
                  it  is  true, and completion is attempted on a string containing
                  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/public/toast/stuff,   while  completion
                  after  'http://toast/~yousir/' will look for files in the direc-
                  tory ~yousir/public_html.
    
           mail-directory
                  If set, zsh will assume that mailbox files can be found  in  the
                  directory specified.  It defaults to '~/Mail'.
    
           match-original
                  This  is  used  by  the _match completer.  If it is set to only,
                  _match will try to generate matches without 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.
    
           matcher
                  This  style  is tested separately for each tag valid in the cur-
                  rent 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 'Completion Matching Control'  in  zsh-
                  compwid(1).
    
           matcher-list
                  This style can be set to a list of match specifications that are
                  to be applied everywhere. Match specifications are described  in
                  the section 'Completion Matching Control' in zshcompwid(1).  The
                  completion system 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  one;  how-
                  ever,  if a specification is prefixed with +, it is added to the
                  existing list.  Hence it is possible to create increasingly gen-
                  eral specifications without repetition:
    
                         zstyle ':completion:*' matcher-list '' '+m{a-z}={A-Z}' '+m{A-Z}={a-z}'
    
                  It is possible to create match specifications valid for particu-
                  lar completers by using the third field  of  the  context.   For
                  example,  to  use  the completers _complete and _prefix but only
                         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 specification is
                  applied.  Note also that some completers such  as  _correct  and
                  _approximate  do not use the match specifications at all, though
                  these completers will only ever  be  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 appreciable impact  on  perfor-
                  mance.
    
                  If  there  is  no current matcher or it is empty, and the option
                  NO_CASE_GLOB is in effect, the matching for files  is  performed
                  case-insensitively  in  any  case.   However,  any  matcher must
                  explicitly  specify  case-insensitive  matching   if   that   is
                  required.
    
           max-errors
                  This  is  used  by the _approximate and _correct completer func-
                  tions to determine the maximum number of errors to  allow.   The
                  completer will try to generate 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 'ESC-6 TAB'), up to six errors
                  are accepted.  Hence with a value of '0 numeric', no  correcting
                  completion will be attempted unless a numeric argument is given.
    
                  If the value contains the string  'not-numeric',  the  completer
                  will  not  try  to  generate  corrected completions when given a
                  numeric argument, so in this case the  number  given  should  be
                  greater  than zero.  For example, '2 not-numeric' specifies that
                  correcting completion with two errors will usually be performed,
                  but  if  a numeric argument is given, correcting completion will
                  not be performed.
    
           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 settings.
    
                  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
                  completion  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'  (Typi-
                  cally, the value 'select=long-list' described later is more use-
                  ful 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 selection, as imple-
                  mented by the zsh/complist module.   The  following  values  may
                  appear either alongside or instead of the values above.
    
                  If  the  value contains the string 'select', menu selection will
                  be started unconditionally.
    
                  In the form 'select=num', menu selection will only be started if
                  there are at least num matches.  If the values for more than one
                  tag provide a number, the smallest number is taken.
    
                  Menu selection can be turned off explicitly by defining a  value
                  containing the string'no-select'.
    
                  It  is also possible to start menu selection only if the list of
                  matches  does  not  fit  on  the  screen  by  using  the   value
                  'select=long'.  To start menu selection even if the current wid-
                  get 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  interac-
                  will only be used if that many words from the  job  descriptions
                  are  required to resolve ambiguities.  For example, if the value
                  is '1', strings will only be used if  all  jobs  differ  in  the
                  first word on their command lines.
    
           old-list
                  This  is  used  by  the  _oldlist  completer.   If  it is set to
                  'always', then  standard  widgets  which  perform  listing  will
                  retain the current list of matches, however they were generated;
                  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 com-
                  pletion list is generated; this  is  the  default  behaviour  of
                  _oldlist.   However, if there is an old list and this style con-
                  tains the name of the  completer  function  that  generated  the
                  list, then the old list will be used even if it was generated by
                  a widget which does not do listing.
    
                  For example, suppose you type ^Xc to use the _correct_word  wid-
                  get,  which  generates  a list of corrections for the word under
                  the cursor.  Usually, typing ^D would generate a  standard  list
                  of  completions for the word on the command line, and show that.
                  With _oldlist, it will instead  show  the  list  of  corrections
                  already generated.
    
                  As  another  example  consider  the  _match  completer: with the
                  insert-unambiguous style set to 'true' it inserts only a  common
                  prefix  string, if there is any.  However, this may remove parts
                  of the original pattern, so that further completion  could  pro-
                  duce  more  matches  than  on  the  first attempt.  By using the
                  _oldlist completer and setting this style to _match, the list of
                  matches generated on the first attempt will be used again.
    
           old-matches
                  This  is  used by the _all_matches completer to decide if an old
                  list of matches should be used if one exists.  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 unconditionally.  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.
    
           old-menu
                  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
                  decide if the original string should be added as a possible com-
                  pletion.   Normally, this is done only if there are at least two
                  possible corrections, but if this style is set to 'true', it  is
                  always  added.   Note  that  the style will be examined with the
                  completer field in  the  context  name  set  to  correct-num  or
                  approximate-num,  where  num  is  the number of errors that were
                  accepted.
    
           packageset
                  This style is used  when  completing  arguments  of  the  Debian
                  'dpkg' program.  It contains 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 contain-
                  ing  color  names  in the format of an X11 rgb.txt file.  If the
                  style is not set but this file is found in one of various  stan-
                  dard locations it will be used as the default.
    
           path-completion
                  This  is used by filename completion.  By default, filename com-
                  pletion examines all components of a path to see  if  there  are
                  completions  of that component.  For example, /u/b/z can be com-
                  pleted to /usr/bin/zsh.  Explicitly setting this style to  false
                  inhibits  this  behaviour for path components up to the / before
                  the cursor; this overrides the setting of accept-exact-dirs.
    
                  Even with the style set to false, it is still possible  to  com-
                  plete  multiple paths by setting the option COMPLETE_IN_WORD and
                  moving the cursor back to the first component in the path to  be
                  completed.  For example, /u/b/z can be completed to /usr/bin/zsh
                  if the cursor is after the /u.
    
           pine-directory
                  If set, specifies the directory containing PINE  mailbox  files.
                  There  is no default, since recursively searching this directory
                  is inconvenient for anyone who doesn't use PINE.
    
           ports  A list of Internet service names (network  ports)  to  complete.
                  If  this  is  not  set,  service  names  are taken from the file
                  '/etc/services'.
    
           prefix-hidden
                  This is used for certain completions which share a  common  pre-
                  fix,  for  example command options beginning with dashes.  If it
                  is 'true', the prefix will not be shown in the list of  matches.
    
                  For signals, an initial '-' is required before signal names will
                  be completed.
    
                  For  jobs,  an  initial '%' is required before job names will be
                  completed.
    
                  For function and parameter names,  an  initial  '_'  or  '.'  is
                  required  before function or parameter names starting with those
                  characters will be completed.
    
                  The default value for this style is  'false'  for  function  and
                  parameter completions, and  'true' otherwise.
    
           preserve-prefix
                  This style is used when completing path names.  Its value should
                  be a pattern matching an initial prefix of the word to  complete
                  that  should  be  left  unchanged  under all circumstances.  For
                  example, on some Unices an initial '//'  (double  slash)  has  a
                  special meaning; setting this style to the string '//' will pre-
                  serve it.  As another example, setting this style to '?:/' under
                  Cygwin would allow completion after 'a:/...' and so on.
    
           range  This  is  used  by  the _history completer and the _history_com-
                  plete_word bindable command to decide which words should be com-
                  pleted.
    
                  If  it is a singe number, only the last N 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 tried.
    
                  The default is to complete all words from the history at once.
    
           regular
                  This style is used by the _expand_alias completer  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.
    
           rehash If  this  is set when completing external commands, the internal
                  list (hash) of commands will be updated for each search by issu-
                  ing the rehash command.  There is a speed penalty for this which
                  is only likely to be noticeable when  directories  in  the  path
                  have slow file access.
    
                  If this is set for the default tag, its value will be  displayed
                  during  menu  selection (see the menu style above) when the com-
                  pletion 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.
    
           select-scroll
                  This  style  is  tested for the default tag and determines how a
                  completion list is scrolled during a  menu  selection  (see  the
                  menu  style  above) when the completion list does not fit on the
                  screen as a whole.  If the value is  '0'  (zero),  the  list  is
                  scrolled  by  half-screenfuls;  if it is a positive integer, the
                  list is scrolled by the given number of lines; if it is a  nega-
                  tive number, the list is scrolled by a screenful minus the abso-
                  lute value of the given number of  lines.   The  default  is  to
                  scroll by single lines.
    
           separate-sections
                  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 sepa-
                  rately.  This style is also used similarly 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'.
    
           show-completer
                  Tested  whenever  a  new completer is tried.  If it is true, the
                  completion system outputs a progress message in the listing area
                  showing  what  completer  is  being  tried.  The message will be
                  overwritten by any output when  completions  are  found  and  is
                  removed after completion is finished.
    
           single-ignored
                  This  is  used  by the _ignored completer when there is only one
                  match.  If its value is 'show', the single match  will  be  dis-
                  played  but not inserted.  If the value is 'menu', then the sin-
                  gle match and the original string are both added as matches  and
                  menu  completion  is started, making it easy to select either of
                  them.
    
           sort   Many completion widgets call _description at  some  point  which
                  decides  whether the matches are added sorted or unsorted (often
                  indirectly via _wanted or _requested).  This style  can  be  set
                  explicitly  to one of the usual true or false values as an over-
                  ride.  If it is not set for the context, the standard  behaviour
                  of the calling widget is used.
    
                  The style is tested first against the full context including the
    
           special-dirs
                  Normally, the completion code will  not  produce  the  directory
                  names  '.'  and  '..' as possible completions.  If this style is
                  set to 'true', it will add both '.' and '..' as possible comple-
                  tions; 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'.
    
                         zstyle -e ':completion:*' special-dirs \
                            '[[ $PREFIX = (../)#(|.|..) ]] && reply=(..)'
    
           squeeze-slashes
                  If  set  to  'true', sequences of slashes in filename paths (for
                  example in 'foo//bar') will be treated as a single slash.   This
                  is  the  usual behaviour of UNIX paths.  However, by default the
                  file completion function behaves as if there were a '*'  between
                  the slashes.
    
           stop   If  set  to  'true', the _history_complete_word bindable command
                  will stop once when reaching the beginning or end  of  the  his-
                  tory.   Invoking _history_complete_word will then wrap around to
                  the opposite end of the  history.   If  this  style  is  set  to
                  'false'  (the default), _history_complete_word will loop immedi-
                  ately as in a menu completion.
    
           strip-comments
                  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  dis-
                  play  name  from  the  addresses,  cutting  them  down  to plain
                  user@host form.
    
           subst-globs-only
                  This is used by the _expand completer.  If it is set to  'true',
                  the  expansion  will  only be used if it resulted from globbing;
                  hence, if expansions resulted from the  use  of  the  substitute
                  style  described  below,  but  these were not further changed by
                  globbing, the expansions will be rejected.
    
                  The default for this style is 'false'.
    
           substitute
                  This boolean style controls whether the _expand  completer  will
                  first  try  to  expand  all 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
    
                  For example:
    
                         zstyle ':completion:*:complete:-command-:*' tag-order \
                             'commands functions'
    
                  specifies that  completion  in  command  position  first  offers
                  external  commands  and 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.   Nor-
                         mally  all tags not explicitly selected are tried last if
                         the specified 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  exclamation  mark  specifies
                         names of tags that are not to be used.  The effect is the
                         same as if all other possible tags for  the  context  had
                         been listed.
    
                  tag:label ...
                         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 settings for
                         each attempt; see below for an example.
    
                  tag:label:description
                         As before, but description will replace the '%d'  in  the
                         value of the format style instead of the default descrip-
                         tion supplied by the completion 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 function.
    
                  In  any  of  the forms above the tag may be a pattern or several
                  patterns in the form '{pat1,pat2...}'.  In this case all  match-
                  ing  tags  will  be  used except for any given explicitly in the
                  same string.
    
                  One use of these features is to try one tag more than once, set-
                  of  the  tag-order style is used which completes functions using
                  the default tag, this time  presumably  including  all  function
                  names.
    
                  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 multi-
                  ple characters, and single-letter options will be  displayed  in
                  separate groups with different descriptions.
    
                  Another  use of patterns is to try multiple match specifications
                  one after another.  The matcher-list style offers something sim-
                  ilar,  but  it is tested very early in the completion system and
                  hence can't be set for single commands  nor  for  more  specific
                  contexts.   Here  is  how  to  try normal completion without any
                  match specification and, if that generates no matches, try again
                  with  case-insensitive matching, restricting the effect to argu-
                  ments of the command foo:
    
                         zstyle ':completion:*:*:foo:*' tag-order '*' '*:-case'
                         zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}'
    
                  First, all the tags offered when completing after foo are  tried
                  using  the  normal  tag name.  If that generates no matches, the
                  second value of tag-order is used, which tries  all  tags  again
                  except  that  this  time each has -case appended to its name for
                  lookup of styles.  Hence this time the  value  for  the  matcher
                  style  from  the second call to zstyle in the example is used to
                  make completion case-insensitive.
    
                  It is possible to use the -e option of the zstyle  builtin  com-
                  mand  to specify conditions for the use of particular tags.  For
                  example:
    
                         zstyle -e '*:-command-:*' tag-order '
                             if [[ -n $PREFIX$SUFFIX ]]; then
                               reply=( )
                             else
                               reply=( - )
                             fi'
    
                  completed before option names for most commands.
    
           urls   This is used together with 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 descend as deep as necessary.
    
                  For example,
    
                         zstyle ':completion:*' urls ~/.urls
                         mkdir -p ~/.urls/ftp/ftp.zsh.org/pub
    
                  allows  completion  of   all   the   components   of   the   URL
                  ftp://ftp.zsh.org/pub after suitable commands such as 'netscape'
                  or 'lynx'.  Note, however, that access  methods  and  files  are
                  completed  separately, so if the hosts style is set hosts can be
                  completed without reference to the urls style.
    
                  See the description in the function _urls itself for more infor-
                  mation (e.g. 'more $^fpath/_urls(N)').
    
           use-cache
                  If  this  is  set, the completion caching layer is activated for
                  any  completions   which   use   it   (via   the   _store_cache,
                  _retrieve_cache,  and  _cache_invalid functions).  The directory
                  containing the cache files can be changed  with  the  cache-path
                  style.
    
           use-compctl
                  If  this style is set to a string not equal to false, 0, no, and
                  off, the completion system may use any completion specifications
                  defined  with  the  compctl  builtin  command.   If the style is
                  unset, this is done only if the zsh/compctl  module  is  loaded.
                  The string may also contain the substring 'first' to use comple-
                  tions defined with 'compctl -T', and the substring 'default'  to
                  use the completion defined with 'compctl -D'.
    
                  Note  that  this  is only intended to smooth the transition from
                  compctl to the new completion system and may  disappear  in  the
                  set  before  the cache of host names is generated (typically the
                  first completion attempt).
    
           users  This may be set to a list of usernames to be completed.   If  it
                  is  not set all usernames will be completed.  Note that if it is
                  set only that list of users will be completed; this  is  because
                  on some systems querying all users can take a prohibitive amount
                  of time.
    
           users-hosts
                  The values of this style should be of the  form  'user@host'  or
                  'user:host'.  It  is  used for commands that need pairs of user-
                  and hostnames.  These commands will complete 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 com-
                  mands may use the accounts tag.
    
           users-hosts-ports
                  Like users-hosts but used for commands like telnet and  contain-
                  ing strings of the form 'user@host:port'.
    
           verbose
                  If set, as it is by default, the completion listing is more ver-
                  bose.  In particular many commands show descriptions for options
                  if this style is 'true'.
    
           word   This  is  used by the _list completer, which prevents the inser-
                  tion 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
                  occasions.   If  this  style  is true, the comparison is instead
                  performed only on the current word.  Hence if completion is per-
                  formed  on  another word with the same contents, completion will
                  not be delayed.
    
    
    

    CONTROL FUNCTIONS

           The initialization script compinit redefines all the widgets which per-
           form  completion  to  call the supplied widget function _main_complete.
           This function acts as a wrapper calling the so-called 'completer' func-
           tions  that  generate  matches.  If _main_complete is called with argu-
           ments, 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 com-
           pletion and correction if that doesn't generate any matches:
           the other arguments 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 ':completion::complete:...'.
    
           _all_matches
                  This completer can be used to add a  string  consisting  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
    
                  Note  that  this does not generate completions by itself:  first
                  use any of the standard ways of generating  a  list  of  comple-
                  tions, then use ^Xa to show all matches.  It is possible instead
                  to add a standard completer to the list  and  request  that  the
                  list of all matches should be directly inserted:
    
                         zstyle ':completion:all-matches::::' completer _all_matches _complete
                         zstyle ':completion:all-matches:*' insert true
    
                  In this case the old-matches style should not be set.
    
           _approximate
                  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  com-
                  pletion  yields no possible completions.  When corrected comple-
                  tions are found, the completer will normally start menu  comple-
                  tion allowing you to cycle through these strings.
    
                  This  completer uses the tags corrections and original when gen-
                  erating the possible corrections and the original  string.   The
                  format style for the former may contain the additional sequences
                  is in the same format  as  the  max-errors  style,  all  in  one
                  string.
    
                  Note  that  this completer (and the _correct completer 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, e.g.:
    
                         zstyle -e ':completion:*' completer '
                           if [[ $_last_try != "$HISTNO$BUFFER$CURSOR" ]]; then
                             _last_try="$HISTNO$BUFFER$CURSOR"
                             reply=(_complete _match _prefix)
                           else
                             reply=(_ignored _correct _approximate)
                           fi'
    
                  This uses the HISTNO parameter and the BUFFER and CURSOR special
                  parameters  that are available inside zle and completion widgets
                  to find out if the command line hasn't changed  since  the  last
                  time completion was tried.  Only then are the _ignored, _correct
                  and _approximate completers called.
    
           _complete
                  This completer generates all  possible  completions  in  a  con-
                  text-sensitive  manner, i.e. using the settings defined with the
                  compdef function explained above and the current settings of all
                  special parameters.  This gives the normal completion behaviour.
    
                  To complete arguments of commands, _complete  uses  the  utility
                  function  _normal,  which is in turn responsible for finding the
                  particular function; it is described below.  Various contexts of
                  the  form -context- are handled specifically. These are all men-
                  tioned above as possible arguments to the #compdef tag.
    
                  Before trying to find a function for a specific  context,  _com-
                  plete  checks  if  the  parameter  'compcontext' 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 elements are
                  taken  to  be the possible matches which will be completed using
                  the tag 'values' and the description 'value'. If it is set to an
                  associative array, the keys are used as the possible completions
                  and the values (if non-empty) are used as descriptions  for  the
                  matches.  If 'compcontext' is set to a string containing colons,
                  it should be of the form 'tag:descr:action'.  In this  case  the
                  tag and descr give the tag and description to use and the action
                  indicates what should be completed in one of the forms  accepted
                  by the _arguments utility function described below.
    
                  Finally, if 'compcontext' is set to a string without colons, the
                  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  com-
                  pletion  will be, and will accept as many errors as given by the
                  numeric argument.  Without a numeric argument, first  correction
                  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
                  _approximate will at least generate the corrected strings gener-
                  ated by the _correct completer -- and probably more.
    
           _expand
                  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  tags used when generating expansions are all-expansions for
                  the string containing all possible expansions,  expansions  when
                  adding  the  possible  expansions as single matches and original
                  when adding the original string from the  line.   The  order  in
                  which  these strings are generated, if at all, can be controlled
                  by the group-order and tag-order styles, as usual.
    
                  The format string for all-expansions and for expansions may con-
                  tain  the  sequence  '%o' which will be replaced by the original
                  string from the line.
    
                  The kind of expansion to be tried is controlled by  the  substi-
                  tute, 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 substi-
                  tute, -g for glob and -o for subst-globs-only.
    
                  tem Configuration' above.
    
           _ignored
                  The  ignored-patterns  style  can  be  set to a list of patterns
                  which are compared against possible completions;  matching  ones
                  are   removed.    With  this  completer  those  matches  can  be
                  reinstated, as if no ignored-patterns style were set.  The  com-
                  pleter  actually  generates  its own list of matches; which com-
                  pleters are invoked is determined in the same  way  as  for  the
                  _prefix  completer.   The single-ignored style is also available
                  as described above.
    
           _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  Configuration'
                  above.
    
           _match This  completer  is intended to be used after the _complete com-
                  pleter.  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.
    
                  Normally completion will be performed by taking the pattern from
                  the  line,  inserting a '*' at the cursor position and comparing
                  the resulting pattern with the possible  completions  generated.
                  This  can  be  modified  with the match-original style described
                  above.
    
                  The generated matches will  be  offered  in  a  menu  completion
                  unless  the  insert-unambiguous  style is set to 'true'; see the
                  description above for other options for this style.
    
                  Note that matcher specifications defined globally or used by the
                  completion  functions (the styles matcher-list and matcher) will
                  not be used.
    
           _menu  This completer was written as simple example  function  to  show
                  how  menu  completion  can be enabled in shell code. However, it
                  has the notable effect of disabling menu selection which can  be
                  useful  with  _generic  based  widgets. It should be used as the
                  first completer in the list.  Note that this is  independent  of
                  the  setting  of the MENU_COMPLETE option and does not work with
                  the other menu completion widgets such as reverse-menu-complete,
                  or accept-and-menu-complete.
    
           _oldlist
                  This  completer  controls  how  the  standard completion widgets
                  behave when there is an existing list of completions  which  may
                  have  been  generated  by  a  special  completion  (i.e. a sepa-
                  rately-bound completion command).  It allows the  ordinary  com-
                  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  com-
                  pleters  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 _correct completer after it,  _prefix  will
                  be called a second time and, now only trying correction with the
                  suffix ignored.  On the second invocation the completer part  of
                  the context appears as 'foo'.
    
                  To use _prefix as the last resort and try only normal completion
                  when it is invoked:
    
                         zstyle ':completion:*' completer _complete ... _prefix
                         zstyle ':completion::prefix:*' completer _complete
    
                  The add-space style is also respected.  If it is set  to  'true'
                  then  _prefix  will insert a space between the matches generated
                  (if any) and the suffix.
    
                  Note that this completer is only useful if the  COMPLETE_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.
    
           _user_expand
                  This  completer  behaves  similarly to the _expand completer but
                  instead  performs  expansions  defined  by  users.   The  styles
                  add-space  and sort styles specific to the _expand completer are
                  usable with _user_expand in addition  to  other  styles  handled
                  more generally by the completion system.  The tag all-expansions
                  is also available.
    
                  The expansion depends  on  the  array  style  user-expand  being
                  defined  for  the current context; remember that the context for
                  completers is less specific than that for contextual  completion
                  as  the  full  context has not yet been determined.  Elements of
                  the array may have one of the following forms:
                  $hash   hash is the name of an associative array.  Note this  is
                         not  a  full  parameter  expression, merely a $, suitably
                         quoted to prevent immediate expansion,  followed  by  the
                         name  of  an  associative  array.  If the trial expansion
                         word matches a key in hash, the  resulting  expansion  is
    
           _bash_completions
                  This  function  is  used by two widgets, _bash_complete-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; '$',  environ-
                  ment  variables;  '@',  host  names;  '/',  file names; '~' user
                  names.  In bash, the binding preceded by '\e' gives  completion,
                  and  preceded  by '^X' lists options.  As some of these bindings
                  clash with standard zsh bindings, only '\e~' and '^X~' are bound
                  by  default.   To add the rest, the following should be added to
                  .zshrc after compinit has been run:
    
                         for key in '!' '$' '@' '/' '~'; do
                           bindkey "\e$key" _bash_complete-word
                           bindkey "^X$key" _bash_list-choices
                         done
    
                  This includes the bindings for '~' in  case  they  were  already
                  bound  to  something else; the completion code does not override
                  user bindings.
    
           _correct_filename (^XC)
                  Correct the filename path at the cursor position.  Allows up  to
                  six  errors in the name.  Can also be called with an argument to
                  correct a filename path, independently of zle; the correction is
                  printed on standard output.
    
           _correct_word (^Xc)
                  Performs correction of the current argument using the usual con-
                  textual completions as possible choices. This stores the  string
                  'correct-word'  in  the  function  field of the context name and
                  then calls the _correct completer.
    
           _expand_alias (^Xa)
                  This function can be used as a completer and as a bindable  com-
                  mand.   It  expands the word the cursor is on if it is an alias.
                  The types of alias expanded can be controlled  with  the  styles
                  regular, global and disabled.
    
                  When  used as a bindable command there is one additional 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-complete alias name.
    
           _expand_word (^Xe)
                  Performs expansion on the current word:  equivalent to the stan-
                  dard expand-word  command,  but  using  the  _expand  completer.
                  Before  calling  it, the function field of the context is set to
    
                  Note in particular that the completer style may be set  for  the
                  context in order to change the set of functions used to generate
                  possible matches.  If _generic is called with  arguments,  those
                  are  passed  through to _main_complete as the list of completers
                  in place of those defined by the completer style.
    
           _history_complete_word (\e/)
                  Complete words from the shell's command history. This  uses  the
                  list, remove-all-dups, sort, and stop styles.
    
           _most_recent_file (^Xm)
                  Complete  the  name  of the most recently modified file matching
                  the pattern on the command line (which may be blank).  If  given
                  a  numeric  argument  N, complete the Nth most recently modified
                  file.  Note the completion, if any, is always unique.
    
           _next_tags (^Xn)
                  This command alters the set of matches used to that 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  avail-
                  able.   Successive  invocations of the command cycle through all
                  possible sets of tags.
    
           _read_comp (^X^R)
                  Prompt the user for a string, and use that to perform completion
                  on  the  current  word.   There  are  two  possibilities for the
                  string.  First, it can be a set  of  words  beginning  '_',  for
                  example  '_files  -/', in which case the function with any argu-
                  ments will be called to generate the  completions.   Unambiguous
                  parts of the function name will be completed automatically (nor-
                  mal completion is not available at this point) until a space  is
                  typed.
    
                  Second, any other string will be passed as a set of arguments to
                  compadd and should hence be an expression specifying what should
                  be completed.
    
                  A  very  restricted  set  of  editing commands is available 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  argu-
                  ment.
    
           _complete_debug (^X?)
                  This widget performs ordinary completion, but captures in a tem-
                  tions  called,  which  in  turn  is determined by the user's own
                  styles and other settings.
    
           _complete_help_generic
                  Unlike other commands listed here, this must  be  created  as  a
                  normal ZLE widget rather than a completion widget (i.e. with zle
                  -N).  It is used for generating help with a widget bound to  the
                  _generic widget that is described above.
    
                  If  this widget is created using the name of the function, as it
                  is by default, then when executed it will read a  key  sequence.
                  This  is expected to be bound to a call to a completion function
                  that uses the _generic widget.  That widget  will  be  executed,
                  and  information  provided  in  the  same  format that the _com-
                  plete_help widget displays for contextual completion.
    
                  If the widget's name contains debug, for example if it  is  cre-
                  ated as 'zle -N _complete_debug_generic _complete_help_generic',
                  it will read and execute the keystring for a generic  widget  as
                  before, but then generate debugging information as done by _com-
                  plete_debug for contextual completion.
    
                  If the widget's  name  contains  noread,  it  will  not  read  a
                  keystring  but  instead  arrange  that the next use of a generic
                  widget run in the same shell will have the effect  as  described
                  above.
    
                  The    widget    works    by   setting   the   shell   parameter
                  ZSH_TRACE_GENERIC_WIDGET which is read by  _generic.   Unsetting
                  the parameter cancels any pending effect of the noread form.
    
                  For example, after executing the following:
    
                         zle -N _complete_debug_generic _complete_help_generic
                         bindkey '^x:' _complete_debug_generic
    
                  typing 'C-x :' followed by the key sequence for a generic widget
                  will cause trace output for that widget to be saved to a file.
    
           _complete_tag (^Xt)
                  This widget completes symbol tags created by the etags or  ctags
                  programmes (note there is no connection with the completion sys-
                  tem'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 preferred.  You can specify the
                  full path to a TAGS or tags file by setting the parameter $TAGS-
                  FILE  or  $tagsfile  respectively.  The corresponding completion
                  tags used are etags and vtags, after emacs and vi  respectively.
    
    
    

    UTILITY FUNCTIONS

           _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 automat-
                  ically  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
                         fi
    
                  Will complete the strings from the matches parameter, using com-
                  padd  with  additional  options  which will take precedence over
                  those generated by _all_labels.
    
           _alternative [ -O name ] [ -C name ] spec ...
                  This function is useful in simple cases where multiple tags  are
                  available.   Essentially  it  implements  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 descrip-
                  tion 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 call:
    
                         _alternative \
                             'users:user:_users' \
                             'hosts:host:_hosts'
    
                  offers usernames and hostnames as possible matches, generated by
                  the _users and _hosts functions respectively.
    
                  Like  _arguments,  this function uses _all_labels to execute the
                  actions, which will loop over all sets of  tags.   Special  han-
                  dling  is only required if there is an additional valid tag, for
                  these  may be separated from the options to _arguments itself by
                  a single colon.  Options to _arguments itself must be  in  sepa-
                  rate words, i.e. -s -w, not -sw.
    
                  With the option -n, _arguments sets the parameter NORMARG to the
                  position of the first normal argument in the $words array,  i.e.
                  the position after the end of the options.  If that argument has
                  not been reached, NORMARG is  set  to  -1.   The  caller  should
                  declare  'integer NORMARG' if the -n option is passed; otherwise
                  the parameter is not used.
    
                  n:message:action
                  n::message:action
                         This describes the n'th  normal  argument.   The  message
                         will  be  printed  above  the  matches  generated and the
                         action 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.
    
                  :message:action
                  ::message:action
                         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  unneces-
                         sary.
    
                  *:message:action
                  *::message:action
                  *:::message:action
                         This  describes  how  arguments (usually non-option argu-
                         ments, those not beginning with - or +) are  to  be  com-
                         pleted  when neither 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 mes-
                         sage  they are modified to refer only to the normal argu-
                         ments covered by this description.
    
                  optspec
                  optspec:...
                         This describes an option.  The colon  indicates  handling
                         for  one  or  more  arguments to the option; if it is not
                         present, the option is assumed to take no arguments.
    
                         By default, options are multi-character name, one '-word'
                         per  option.   With -s, options may be single characters,
                         with more than one option per word, although words start-
                         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 opt-
                         spec, whether or not the option has arguments.
    
                         *optspec
                                 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 cursor it will not be offered  again.
    
                         -optname
                         +optname
                                 In  the  simplest  form  the  optspec is just the
                                 option name beginning with  a  minus  or  a  plus
                                 sign, such as '-foo'.  The first argument for the
                                 option (if any) must follow as  a  separate  word
                                 directly after the option.
    
                                 Either of '-+optname' and '+-optname' can be used
                                 to specify that -optname and  +optname  are  both
                                 valid.
    
                                 In  all  the remaining forms, the leading '-' may
                                 be replaced by or paired with '+' in this way.
    
                         -optname-
                                 The  first  argument  of  the  option  must  come
                                 directly  after the option name in the same word.
                                 For example, '-foo-:...' specifies that the  com-
                                 pleted   option   and  argument  will  look  like
                                 '-fooarg'.
    
                         -optname+
                                 The first argument may appear  immediately  after
                                 optname in the same word, or may appear as a sep-
                                 arate  word  after  the  option.   For   example,
                                 '-foo+:...'  specifies  that the completed option
                                 and argument will look like either  '-fooarg'  or
                                 '-foo arg'.
    
                         -optname=
                                 The  argument  may appear as the next word, or in
                                 same word as the option name provided that it  is
                                 separated  from it by an equals sign, for example
                                 '-foo=arg' or '-foo arg'.
    
                         -optname=-
                                 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:
    
                  :message:action
                  ::message:action
                         An argument to the option; message and action are treated
                         as  for ordinary arguments.  In the first form, the argu-
                         ment is mandatory, and in the second form it is optional.
    
                         This  group may be repeated for options which take multi-
                         ple arguments.  In  other  words,  :message1:action1:mes-
                         sage2:action2  specifies  that the option takes two argu-
                         ments.
    
                  :*pattern:message:action
                  :*pattern::message:action
                  :*pattern:::message:action
                         This describes multiple arguments.  Only the last  optarg
                         for  an  option taking multiple arguments may be given in
                         this form.  If the pattern is empty (i.e., :*:), all  the
                         remaining  words  on  the  line  are  to  be completed as
                         described by the action; otherwise, all the words  up  to
                         and  including a word matching the pattern are to be com-
                         pleted using the action.
    
                         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 description.
    
           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  com-
           mand  line, the options and arguments 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
           although  if  the  option  or argument appears on the command line they
           will be skipped as normal.  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 '_arguments !$^global_options'.
    
           In each of the forms above the action determines how completions should
           be generated.  Except for the '->string' form below, the action will be
           executed by calling the _all_labels function to process all tag labels.
           No special handling of tags is needed unless a function call introduces
           a new one.
    
           The forms for action are as follows.
    
             (single unquoted space)
                  This  is useful where an argument is required but it is not pos-
                  sible or desirable to generate matches for it.  The message will
                  be  displayed but no completions 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.
    
           ->string
                  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 action in the '->string' format, it
                  will strip all leading and trailing whitespace from  string  and
                  set  the  array  state  to  the  set of all strings for which an
                  action  is  to  be  performed.   The  elements  of   the   array
                  state_descr  are  assigned  the corresponding message field from
                  each optarg containing such an action.
    
                  By default and in common with all other well behaved  completion
                  functions,  _arguments returns status zero if it was able to add
    
                         local context state state_descr line
                         typeset -A opt_args
    
                  to prevent _arguments from altering the global environment.
    
           {eval-string}
                  A  string  in  braces  is  evaluated  as  shell code to generate
                  matches.  If the eval-string itself does not begin with an open-
                  ing  parenthesis or brace it is split into separate words before
                  execution.
    
           = action
                  If the action starts with '= ' (an equals  sign  followed  by  a
                  space),  _arguments  will  insert  the  contents 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 spe-
                  cial parameter.  This has the effect of inserting a  dummy  word
                  onto the completion command line while not changing the point at
                  which completion is taking 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  appropriate  command
                  name into the range for the second call to _arguments to be able
                  to parse the line.
    
            word...
           word...
                  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  command.   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 excluding 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  back-
           the  curcontext  parameter is altered to append the same string that is
           stored in the context parameter.
    
           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
           exclusion 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 remainder.
    
           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 com-
           pletions.  When it contains '-d' or an argument, the option  '-c'  will
           not be considered.  However, after '-a' both sets will still be consid-
           ered 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 speci-
           fications  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)' \
                      {-d,--decompress}'[decompress]'
    
           As  the  completion  code  has to parse the command line separately 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 definitions.
    
           The  options -S and -A are available to simplify the specifications for
           commands with standard option parsing.  With -S, no option will be com-
           pleted  after  a  '--'  appearing on its own on the line; this argument
           will otherwise be ignored; hence in the line
    
           example, this can be used to pass the same set of options for the  com-
           padd builtin to all actions.
    
           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 '-foo-bar'.
    
           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 current 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  com-
           mands.   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 mes-
           sage and action are used as for other argument specifiers.   For  exam-
           ple:
    
                  _arguments -- '*\*:toggle:(yes no)' \
                                '*=FILE*:file:_files' \
                                '*=DIR*:directory:_files -/' \
                                '*=PATH*:directory:_files -/'
    
           Here, 'yes' and 'no' will be completed as the argument of options whose
           description ends in a star; file names will be  completed  for  options
           that  contain the substring '=FILE' in the description; and directories
           will be completed for options  whose  description  contains  '=DIR'  or
           '=PATH'.   The  last  three  are in fact the default and so need not be
           given explicitly, although it is possible to override the use of  these
           patterns.  A typical help text which uses this feature is:
    
                    -C, --directory=DIR          change to directory DIR
    
           be  given  as  the  name  of an array parameter or as a literal list in
           parentheses.  For example,
    
                  _arguments -- -i \
                      "(--(en|dis)able-FEATURE*)"
    
           will cause completion to  ignore  the  options  '--enable-FEATURE'  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  comple-
           tion 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 'letter' and 'A4' will be  com-
           pleted.
    
           The  '-copy'  option  may appear more than once on the command line and
           takes two arguments.  The first is mandatory and will be completed as a
           filename.   The  second is optional (because of the second colon before
           the description 'resolution') and will be completed  from  the  strings
           '300' and '600'.
    
           The  last  two  descriptions say what should be completed as arguments.
           The first describes the first argument as a 'postscript file' and makes
           files ending in 'ps' or 'eps' be completed.  The last description gives
           all other arguments the description 'page numbers' but does  not  offer
           completions.
    
           _cache_invalid cache_identifier
                  This  function returns status zero if the completions cache cor-
                  responding to the given cache identifier needs  rebuilding.   It
                  determines  this  by  looking  up the cache-policy style for the
                  current context.  This should provide a function name  which  is
                  The  return  argument gives the name of a parameter in which the
                  return status from the function name should be stored; if return
                  is empty or a single hyphen it is ignored.
    
                  The  return status of _call_function itself is zero if the func-
                  tion 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_program,
                  or from the style if set, are concatenated with  spaces  between
                  them  and  the resulting string is evaluated.  The return status
                  is the return status 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 usernames.  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
                  argument 'users=pws' should appear.
    
                  The  next  argument  with no equals sign is taken as the name of
                  the field for which completions should be generated  (presumably
                  not one of the fields for which the value is known).
    
                  The matches generated will be taken from the value of the style.
                  These should contain the possible values for the combinations in
                  the  appropriate  order  (users,  hosts,  ports  in  the example
                  above).  The different  fields  the  values  for  the  different
                  fields  are  separated  by colons.  This can be altered with the
                  option -s to _combination which specifies a pattern.   Typically
                  this  is  a  character  class, as for example '-s "[:@]"' in the
                  case of the users-hosts style.    Each 'field=pattern'  specifi-
                  cation  restricts the completions which apply to elements of the
                  style with appropriately matching 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 exam-
                  ple, if there is no 'users-hosts-ports' or no matching  hostname
                  when  a  host  is required, the function '_hosts' will automati-
                  cally be called.
    
                  If the same name is used for more than one field,  in  both  the
                  The descr is taken as a string to display above the  matches  if
                  the  format style for the descriptions tag is set.  This is fol-
                  lowed 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  'completion:description'.
                  Any  literal  colons  in  completion must be quoted with a back-
                  slash.  If a second array is given, it should have the same num-
                  ber  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 completion list will
                  retain the descriptions from the first array.  Finally, a set of
                  completion options can appear.
    
                  If  the  option  '-o'  appears  before  the  first argument, the
                  matches added will be treated as names of command options  (N.B.
                  not  shell  options),  typically following a '-', '--' or '+' on
                  the command line.  In this case _describe uses  the  prefix-hid-
                  den, prefix-needed and verbose styles to find out if the strings
                  should be added as completions and if the descriptions should be
                  shown.   Without the '-o' option, only the verbose style is used
                  to decide how descriptions are shown.  If '-O' is  used  instead
                  of  '-o',  command  options are completed as above but _describe
                  will not handle the prefix-needed style.
    
                  With the -t option a tag can be specified.  The default is 'val-
                  ues' or, if the -o option is given, 'options'.
    
                  If  selected  by  the  list-grouped style, strings with the same
                  description will appear together in the list.
    
                  _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 previous one; it is
                  used as a helper function for creating 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 corre-
                  sponding 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.
    
                  compadd  using  the  -x  option instead of the default -X.  This
                  means that the description will be displayed even if  there  are
                  no corresponding matches.
    
                  The  options  placed  in  the  array  name  take  account of the
                  group-name style, so matches are  placed  in  a  separate  group
                  where necessary.  The group normally has its elements sorted (by
                  passing the option -J to compadd), but  if  an  option  starting
                  with  '-V',  '-J', '-1', or '-2' is passed to _description, that
                  option will be included in the array.  Hence it is possible  for
                  the  completion  group to be unsorted by giving the option '-V',
                  '-1V', or '-2V'.
    
                  In most cases, the function will be used like this:
    
                         local expl
                         _description files expl file
                         compadd "$expl[@]" - "$files[@]"
    
                  Note the use of the parameter expl, the hyphen, and the list  of
                  matches.  Almost all calls to compadd within the completion sys-
                  tem use a  similar  format;  this  ensures  that  user-specified
                  styles are correctly passed down to the builtins which implement
                  the internals of completion.
    
           _dispatch context string ...
                  This sets the current context to context and looks  for  comple-
                  tion  functions  to  handle  this context by hunting through the
                  list of command names or special 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  fall-
                  back.
    
                  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 argu-
                  ment.
    
           _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.
    
           _gnu_generic
                  This function is a simple wrapper around the _arguments 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
                  returns immediately with a non-zero return status if the  string
                  to  be  completed  does  not  match the pattern.  If the pattern
                  matches, the descr is displayed; the function then returns  sta-
                  tus  zero  if the word to complete is not empty, non-zero other-
                  wise.
    
                  The pattern may be preceded by any of the options understood  by
                  compadd  that  are passed down from _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
                  conventions 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:
    
                         _arguments '-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 completed.
    
           _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 comple-
                  tions 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 compadd 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
                  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, otherwise  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
                  _next_label.
    
                  The options given after the descr are set in the parameter given
                  by name, and hence are to be passed to compadd or whatever func-
                  tion 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 handles 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
                           done
                           ...
                         fi
                         return ret
    
           _normal
                  This  is  the standard function called to handle completion out-
                  side any special -context-.  It is called both to  complete  the
                  command  word and also the arguments for a command.  In the sec-
                  ond case, _normal looks for a special completion for  that  com-
                  mand,  and  if  there  is  none  it  uses the completion for the
                  -default- context.
    
                  A second use is to reexamine the command line specified  by  the
                  $words  array  and  the $CURRENT parameter after those have been
                  modified.  For example, the  function  _precommand,  which  com-
                  pletes  after  pre-command specifiers such as nohup, removes the
                  first word from the words array, decrements the CURRENT  parame-
                  ter,  then  calls  _normal again.  The effect is that 'nohup cmd
                  '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_com-
                  plete 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 completion
                  system.
    
           _parameters
                  This is used to complete the names of shell parameters.
    
                  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 pat-
                  tern is probably necessary.
    
                  All other arguments are passed to the compadd builtin.
    
           _path_files
                  This  function  is used throughout the completion system to com-
                  plete filenames.  It allows completion of  partial  paths.   For
                  example,   the   string   '/u/i/s/sig'   may   be  completed  to
                  '/usr/include/sys/signal.h'.
    
                  The options accepted by both _path_files and _files are:
    
                  -f     Complete all filenames.  This is the default.
    
                  -/     Specifies that only directories should be completed.
    
                  -g pattern
                         Specifies that only files matching the pattern should  be
                         completed.
    
                  -W paths
                         Specifies  path  prefixes that are to be 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
                         parentheses or an absolute pathname.
    
                  -F ignored-files
                         This behaves as for the corresponding option to the  com-
                         padd  builtin.   It gives direct control over which file-
                         names should be ignored.  If the option is  not  present,
    
                  mand name requires  more  than  one  type  of  handling,  either
                  because  it has more than one variant 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=pattern; if the output of 'com-
                  mand 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 status 1 is returned.
    
                  If the '-b builtin-label' is given, the command is tested to see
                  if  it  is  provided as a shell builtin, possibly autoloaded; if
                  so, the label builtin-label is selected as  the  label  for  the
                  variant.
    
                  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 command run.
    
           _regex_arguments name spec ...
                  This function generates a completion function name which matches
                  the specifications spec ..., a set  of  regular  expressions  as
                  described  below.   After running _regex_arguments, the function
                  name should be called as a normal completion function.  The pat-
                  tern  to  be matched is given by the contents of the words array
                  up to the current cursor  position  joined  together  with  null
                  characters; no quotation is applied.
    
                  The  arguments  are grouped as sets of alternatives separated by
                  '|', which are tried one after  the  other  until  one  matches.
                  Each  alternative consists of a one or more specifications which
                  are tried  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 arbitrary 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 (imply-
                  ing  the  remaining word is the one for which completions are to
                  be generated).  The  completion  target  is  restricted  to  the
                  remaining  word  and  any actions for the corresponding patterns
                  are executed.  In this case, nothing is stripped from  the  com-
                  mand line string.  The order of evaluation of the actions can be
                  determined by the tag-order style; the various formats supported
                         examined.
    
                         The argument starting with : is used in the  same  manner
                         as an argument to _alternative.
    
                         A  component is used as follows: pattern is tested to see
                         if the component already exists on the command line.   If
                         it  does,  any  following  specifications are examined to
                         find something to complete.  If a  component  is  reached
                         but  no  such pattern exists yet on the command line, the
                         string containing the action is used to generate  matches
                         to insert at that point.
    
                  /pattern/+ [%lookahead%] [-guard] [:tag:descr:action]
                         This  is  similar to '/pattern/ ...' but the left part of
                         the command line string (i.e. the part already matched by
                         previous patterns) is also considered part of the comple-
                         tion target.
    
                  /pattern/- [%lookahead%] [-guard] [:tag:descr:action]
                         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 string.
    
                  ( spec )
                         Parentheses may be used to groups specs; note each paren-
                         thesis is a single argument to _regex_arguments.
    
                  spec # This allows any number of repetitions of spec.
    
                  spec spec
                         The  two  specs  are to be matched one after the other as
                         described above.
    
                  spec | spec
                         Either of the two specs can be matched.
    
                  The function _regex_words can be used as a  helper  function  to
                  generate  matches  for  a set of alternative words possibly with
                  their own arguments as a command line argument.
    
                  Examples:
    
                         _regex_arguments _tst /$'[^\0]#\0'/ \
                         /$'[^\0]#\0'/ :'compadd aaa'
    
                  This generates a function _tst that completes aaa  as  its  only
                  argument.   The  tag  and  description  for the action have been
                  omitted for brevity (this works but is not recommended in normal
                  use).   The  first  component matches the command word, which is
                  arbitrary; the second matches  any argument.  As the argument is
                  also  arbitrary, any following component would not depend on aaa
                  be completed.  Odd arguments are completed as aaa and even argu-
                  ments as bbb.  Completion fails unless the set of  aaa  and  bbb
                  arguments before the current one is matched correctly.
    
                         _regex_arguments _tst /$'[^\0]#\0'/ \
                         \( /$'aaa\0'/ :'compadd aaa' \| \
                         /$'bbb\0'/ :'compadd bbb' \) \#
    
                  This  is similar, but either aaa or bbb may be completed for any
                  argument.  In this case _regex_words could be used to generate a
                  suitable expression for the arguments.
    
           _regex_words tag description spec ...
                  This  function  can  be  used  to  generate  arguments  for  the
                  _regex_arguments command which may  be  inserted  at  any  point
                  where  a set of rules is expected.  The tag and description give
                  a standard tag and description pertaining to  the  current  con-
                  text.   Each spec contains two or three arguments separated by a
                  colon: note that there is no leading colon in this case.
    
                  Each spec gives one of a set of words that may be  completed  at
                  this point, together with arguments.  It is thus roughly equiva-
                  lent to the _arguments function when used in normal  (non-regex)
                  completion.
    
                  The  part  of  the spec before the first colon is the word to be
                  completed.  This may contain a *; the entire  word,  before  and
                  after  the  *  is  completed,  but only the text before the * is
                  required for the context to be matched, so  that  further  argu-
                  ments may be completed after the abbreviated form.
    
                  The second part of spec is a description for the word being com-
                  pleted.
    
                  The optional third part of the spec describes how words  follow-
                  ing  the one being completed are themselves to be completed.  It
                  will be evaluated in order to avoid problems with quoting.  This
                  means  that  typically  it contains a reference to an array con-
                  taining previously generated regex arguments.
    
                  The option -t term specifies a terminator for the  word  instead
                  of the usual space.  This is handled as an auto-removable suffix
                  in the manner of the option -s sep to _values.
    
                  The result of the processing by _regex_words is  placed  in  the
                  array reply, which should be made local to the calling function.
                  If the set of words and arguments may be matched repeatedly, a #
                  should be appended to the generated array at that point.
    
                  For example:
    
                  This  function  is called to decide whether a tag already regis-
                  tered 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  other-
                  wise.   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
                           fi
                           ... # test the tags bar and baz in the same way
                           ... # exit loop if matches were generated
                         done
    
                  Note that the test for whether matches  were  generated  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
                  completed 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 example:
    
                         local expl ret=1
                         _tags foo bar baz
                         while _tags; do
                           _requested foo expl 'description' \
                               compadd foobar foobaz && ret=0
                           ...
                           (( ret )) || break
                         done
    
                  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 the file
                  given by cache_identifier, stored in a  directory  specified  by
                  the  cache-path  style  which  defaults  to  ~/.zcompcache.  The
                  return status is zero if retrieval was successful.  It will only
                  attempt retrieval if the use-cache style is set, so you can call
                  this function without worrying about whether the user wanted  to
                  use the caching layer.
    
                  See _store_cache below for more details.
    
           _setup tag [ group ]
                  This function sets up the special parameters used by the comple-
                  tion system appropriately for the tag given as the  first  argu-
                  ment.     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 explicitly.
    
           _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
                  parameters; this function then dumps the values of those parame-
                  ters to a file.  The data can then  be  retrieved  quickly  from
                  that  file  via  _retrieve_cache, even in different instances of
                  the shell.
    
                  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 ~/.zcompcache.  The remaining
                  params arguments are the parameters to dump to the file.
    
                  The  return status is zero if storage was successful.  The func-
                  tion will only attempt storage if the use-cache style is set, so
                  you  can  call  this function without worrying about whether the
                  user wanted to use the caching layer.
    
                  The completion function may avoid calling  _retrieve_cache  when
                  it  already  has  the  completion  data available as parameters.
                  However, in that case it should  call  _cache_invalid  to  check
                  whether  the  data  in the parameters and in the cache are still
                  valid.
    
                  See the _perl_modules completion function for a  simple  example
                  of the usage of the caching layer.
    
           _tags [ [ -C name ] tags ... ]
                  If  called  with  arguments,  these are taken to be the names of
                  tags valid for completions in the current context.   These  tags
                  are stored internally and sorted by using the tag-order style.
    
                  Next, _tags is called repeatedly without arguments from the same
                  completion function.  This successively selects the first,  sec-
                  ond,  etc. set of tags requested by the user.  The return status
                  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).
                  the elements of the name array will be passed  to  compadd  when
                  executing an action.
    
                  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  values
                  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 values.
    
                  All other arguments describe the possible values and their argu-
                  ments in the same format used for the description of options  by
                  the  _arguments  function (see above).  The only differences are
                  that no minus or plus sign is required at the beginning,  values
                  can  have  only  one argument, and the forms of action beginning
                  with an equal sign are not supported.
    
                  The character separating a value from its argument  can  be  set
                  using  the  option -S (like -s, followed by the character to use
                  as the separator in the next argument).  By default  the  equals
                  sign will be used as the separator between values and arguments.
    
                  Example:
    
                         _values -s , 'description' \
                                 '*foo[bar]' \
                                 '(two)*one[number]:first count:' \
                                 'two[another number]::second count:(1 2 3)'
    
                  This describes three possible values: 'foo', 'one',  and  'two'.
                  The  first  is  described  as  'bar',  takes no argument and may
                  appear more than once.  The second is described as 'number', may
                  appear   more  than  once,  and  takes  one  mandatory  argument
                  described as 'first count'; 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 com-
                  mas.
    
                         local context state state_descr 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 completed.  Note that for _values,  the  state
                  and  state_descr  are scalars rather than arrays.  Only a single
                  matching state is returned.
    
                  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 are generated
                  by the calling function.  To get the usual behaviour, the  call-
                  ing  function can add the separator x as a suffix by passing the
                  options '-qS x' either directly or indirectly to compadd.
    
                  The option -C is treated in the same way as it is by _arguments.
                  In  that  case  the  parameter  curcontext  should be made local
                  instead of context (as described above).
    
           _wanted [ -x ] [ -C name ]  [ -12VJ ] tag name descr command args ...
                  In many contexts, completion can only  generate  one  particular
                  set of matches, usually corresponding to a single tag.  However,
                  it is still  necessary  to  decide  whether  the  user  requires
                  matches of this type.  This function is useful in such a case.
    
                  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,
                  including the loop over both tags and tag labels and the genera-
                  tion of matches, is carried out automatically by _wanted.
    
                  Hence  to offer only one tag and immediately add the correspond-
                  ing matches with the given description:
    
                         local expl
                         _wanted tag expl 'description' \
                             compadd matches...
    
                  Note that, as for _requested, the command must be able to accept
                  options to be passed down to compadd.
    
                  Like  _tags  this function supports the -C option to give a dif-
                  ferent name for the argument context field.  The -x  option  has
                  the same meaning as for _description.
    
    
    

    COMPLETION DIRECTORIES

           In  the  source distribution, the files are contained in various subdi-
           rectories of the Completion directory.  They may have been installed in
           the same structure, or into one single function directory.  The follow-
           Unix   Functions for completing  arguments  of  external  commands  and
                  suites  of  commands.   They may need modifying for your system,
                  although in many cases some attempt is made to decide which ver-
                  sion  of  a command is present.  For example, completion for the
                  mount command tries to determine the system it  is  running  on,
                  while  completion for many other utilities try to decide whether
                  the GNU version of the command is in use, and hence whether  the
                  --help option is supported.
    
           X, AIX, BSD, ...
                  Completion  and  utility function for commands available only on
                  some systems.  These are not arranged  hierarchically,  so,  for
                  example, both the Linux and Debian directories, as well as the X
                  directory, may be useful on your system.
    
    
    

    zsh 4.3.17 February 22, 2011 ZSHCOMPSYS(1)

    
    
  • MORE RESOURCE


  • Linux

    The Distributions





    Linux

    The Software





    Linux

    The News



  • MARKETING






  • Toll Free

webmaster@linuxguruz.com
Copyright © 1999 - 2016 by LinuxGuruz