zshcompsys man page on Ultrix

Man page or keyword search:  
man Server   3690 pages
apropos Keyword Search (all sections)
Output format
Ultrix logo
[printable version]

ZSHCOMPSYS(1)							 ZSHCOMPSYS(1)

NAME
       zshcompsys - zsh completion system

DESCRIPTION
       This  describes	the shell code for the new completion system.  It con‐
       sists of various shell functions; those	beginning  `comp'  are	to  be
       called  directly	 by  the user, while those beginning `_' are called by
       the completion code.  The shell	functions  of  the  second  set	 which
       implement  completion  behaviour	 and which may be bound to keystrokes,
       are referred to as `widgets'.

INITIALIZATION
       If the system was installed completely, it should be enough to call the
       shell  function	compinit  from	your 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  run	 directly by the user; if you have run
       compinstall it will be called automatically from your .zshrc.

       To initialize the system, the function compinit should be in  a	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
       so that that widget is also  re-defined.	  If  completion  styles  (see
       below)  are  set	 up  to	 perform  expansion  as	 well as completion by
       default, and the TAB key is bound to expand-or-complete, compinit  will
       rebind  it  to complete-word; this is necessary to use the correct form
       of expansion.

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

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

       If the number of completion files changes, compinit will recognise this
       and produce a new dump file.  However, if the name of a function or the
       arguments in the first line of a #compdef function (as described below)
       change, it is easiest to delete the dump file by hand so that  compinit
       will  re-create it the next time it is run.  The check 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.

   Autoloaded files
       The convention for autoloaded functions used in completion is that they
       start with an underscore; as already mentioned, the fpath/FPATH parame‐
       ter  must  contain  the directory in which they are stored.  If zsh was
       properly installed on your system, then fpath/FPATH automatically  con‐
       tains the required directories for the standard functions.

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

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

	      Each name may also be of the form `cmd=service'.	This  is  used
	      by  functions  that offer multiple services, i.e. different com‐
	      pletion behaviour for multiple commands.	Such  a	 string	 makes
	      the  completion  system  call the function when completing argu‐
	      ments for the command `cmd', setting the parameter  $service  to
	      the  string `service'.  The function can then use that parameter
	      to decide what to complete.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

	      The  form	 with  -k  defines  a widget with the same name as the
	      function which will be called for	 each  of  the	key-sequences;
	      this  is like the #compdef -k tag.  The function should generate
	      the completions  needed  and  will  otherwise  behave  like  the
	      builtin  widget  whose  name is given as the style argument. The
	      widgets usable for this are: complete-word, delete-char-or-list,
	      expand-or-complete,   expand-or-complete-prefix,	 list-choices,
	      menu-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
	      are as for -k and the first must be a unique widget name	begin‐
	      ning with an underscore.

	      In each of the forms supporting it the -a option makes the func‐
	      tion autoloadable (exactly equivalent to autoload -U function).

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

	      compdef _pids foo

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

COMPLETION SYSTEM CONFIGURATION
       This section gives a short overview of how the completion system works,
       and then more detail on how users can configure how  and	 when  matches
       are generated.

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

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

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

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

       ·      The function; in many cases this field will be blank,  but  when
	      the  completion system is called from other functions, like pre‐
	      dict-on or one of the functions in the Command directory of  the
	      distribution,  this  field  contains  the name of that function,
	      often in an abbreviated form.

       ·      The completer currently active, which is the name of  the	 func‐
	      tion  without the leading underscore.  A `completer' is in over‐
	      all control of how completion is to be performed; `complete'  is
	      the  basic  one for ordinary completion, but completers may per‐
	      form various related tasks such as correction, or modify the be‐
	      haviour  of  a  later  completer (see the section `Control Func‐
	      tions' below for more information).

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

       ·      The argument, describing which argument we are completing.  Nor‐
	      mally this is either a string of the form argument-n, where n is
	      the number of the argument  or  it  is  a	 string	 of  the  form
	      option-opt-n  when  completing  the  n'th argument of the option
	      opt.

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

       As an example, the context name

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

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

       In many of the possible contexts the  completion	 system	 can  generate
       matches,	 often multiple types of matches.  These types are represented
       as simple names called  `tags'.	 The  completion  system  will	decide
       internally what sort of tags are allowed; a list of the standard possi‐
       bilities is given below.	 To determine in which order the tags  are  to
       be  used	 by  the  completion  function,	 the `tag-order' style for the
       appropriate context may be set, as described in the  list  of  standard
       styles  below.  Only those types of matches whose tags were selected by
       this style will be produced, and	 in  the  order	 given,	 although  the
       default	is to try all relevant tags in an order determined by the par‐
       ticular completion in use.

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

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

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

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

	      zstyle ':completion:*' verbose yes

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

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

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

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

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

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

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

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

       Note that the order in which styles are defined does  not  matter;  the
       style  mechanism uses the most specific 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.

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

   Standard Tags
       Here are the tags currently used by the	completion  system.   Some  of
       them are only used when looking up styles and do not refer to a partic‐
       ular 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
	      when an argument of a command may be completed

       arrays for names of array parameters

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

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

       builtins
	      for names of builtin commands

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

       colormapids
	      for X colormap ids

       colors for color names

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

       contexts
	      for contexts used by the zstyle builtin command

       corrections
	      used by the _approximate and _correct completers for the	possi‐
	      ble corrections

       cursors
	      for cursor names used by X programs

       default
	      used  to look up default values for various styles that may also
	      be set for tags that are used when generating matches; note that
	      this  tag	 is  used  when only the function field of the context
	      name is set up

       descriptions
	      used when looking up the value of the format style for  descrip‐
	      tions

       devices
	      for names of device special files

       directories
	      for names of directories

       directory-stack
	      for entries in the directory stack

       displays
	      for X display names

       domains
	      for network domains

       expansions
	      used  by	the  _expand  completer	 for  individual possibilities
	      resulting from expansion of a word

       extensions
	      for X server extensions

       file-descriptors
	      for the numbers of open file descriptors

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

       fonts  used for X font names

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

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

       groups used when completing names of user groups

       history-words
	      for words from the history

       hosts  for hostnames

       indexes
	      used for array indexes

       jobs   used for jobs

       keymaps
	      for names of zsh keymaps

       keysyms
	      for names of X keysyms

       libraries
	      for names of system libraries

       limits for system limits

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

       manuals
	      for names of manual pages

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

       messages
	      used to look up the format style for messages

       modifiers
	      for names of X modifiers

       modules
	      for modules (e.g. zsh modules)

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

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

       names  for all kinds of names

       nicknames
	      for nicknames of NIS maps

       options
	      for command options

       original
	      used by the _approximate, _correct and _expand  completers  when
	      adding the original string

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

       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 for the cd and related builtin commands

       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 printer names

       processes
	      for process identifiers

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

       sequences
	      for sequences (e.g. mh sequences)

       sessions
	      for sessions in the zftp function suite

       signals
	      for signal names

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

       styles for styles used by the zstyle builtin command

       tags   for tags (e.g. rpm tags)

       targets
	      for makefile targets

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

       urls   used to look up the urls and local styles when completing URLs

       users  for usernames

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

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

       warnings
	      used to look up the format style for warnings

       widgets
	      for zsh widget names

       windows
	      for IDs of X windows

       zsh-options
	      for shell options

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

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

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

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

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

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

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

	      It is also used by the _prefix completer	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.  If it is set, the cursor is left after the first ambigu‐
	      ous  component, even if menu completion is in use.  It is tested
	      with the paths tag.

       assign-list
	      When completing after an equals sign, the completion system nor‐
	      mally  completes only one filename.  In some cases, particularly
	      for certain parameters such as PATH, a list of  filenames	 sepa‐
	      rated by colons is required.  This style can be set to a list of
	      patterns matching the names of such parameters.

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

       auto-description
	      If  set,	this style's value will be used as the description for
	      options which are not described by the completion functions, but
	      that  have exactly one argument.	The sequence `%d' in the value
	      will be replaced by the description for this argument.   Depend‐
	      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.  Defaults to `$ZDOTDIR/.zcom‐
	      pcache', or `$HOME/.zcompcache' if $ZDOTDIR is not defined.  The
	      completion  layer will not be used unless the use-cache style is
	      set.

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

       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 which 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 function generating process IDs as matches
	      uses this style with the processes tag to generate  the  IDs  to
	      complete	and  the  list of processes to display (if the verbose
	      style is `true').	 The list produced by the command should  look
	      like  the	 output of the ps command.  The first line is not dis‐
	      played, but is searched for the string `PID' (or `pid') to  find
	      the  position of the process IDs in the following lines.	If the
	      line does not contain `PID', the first numbers in	 each  of  the
	      other lines are taken as the process IDs to complete.

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

       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).  It's 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 it set to `true' and the word on the  com‐
	      mand line is not the name of an alias, matching alias names will
	      be completed.

       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 the name of a completer function or a	string
	      of  the  form  `function:name'.  In the first case the completer
	      field of the context will contain	 the  name  of	the  completer
	      without  the  leading  underscore and with all other underscores
	      replaced by hyphens.  In the second case	the  function  is  the
	      name  of the completer to call, but the context will contain the
	      name in the completer field of the context.  If the name	starts
	      with a hyphen, the string for the context will be build from the
	      name of the completer function as in the	first  case  with  the
	      name appended to it.  For 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 makes only 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.

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

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

       disabled
	      If this is set to `true', the _expand_alias completer and	 bind‐
	      able  command  will  try	to  expand disabled aliases, too.  The
	      default is `false'.

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

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

       expand This style is used when completing strings consisting of	multi‐
	      ple parts, such as path names.  If its value contains 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  it  contains  the	 string	 `suffix'  and	normal
	      (non-menu-)  completion  is  used, matching names for components
	      after the first ambiguous one will also be  added.   This	 means
	      that the resulting string is the longest unambiguous string pos‐
	      sible, but if menu completion is started on the list of  matches
	      generated this way (e.g. due to the option AUTO_MENU being set),
	      this will also cycle through the names of the files in  pathname
	      components after the first ambiguous one.

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

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

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

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

	      If the file-patterns style is set,  the  default	tags  are  not
	      used.  Instead, the value of the style says which tags and which
	      patterns are to be offered.  The strings in  the	value  contain
	      specifications  of  the form `pattern:tag'; each string may con‐
	      tain any number of such specifications.	The  pattern  gives  a
	      glob  pattern  that  is to be used to generate filenames.	 If it
	      contains the sequence `%p', that is replaced by  the  pattern(s)
	      given  by	 the  calling function.	 Colons in the pattern must be
	      preceded by a backslash to make them  distinguishable  from  the
	      colon  before  the tag.  If more than one pattern is needed, the
	      patterns can be given inside braces, separated by	 commas.   The
	      tags  of	all  strings  in  the  value will be offered by _files
	      (again, one after	 another)  and	used  when  looking  up	 other
	      styles.  For strings containing more than one specification, the
	      filenames for all specifications will be generated at  the  same
	      try.   If	 no `:tag' is given the `files' tag will be used.  The
	      tag may also be followed by  an  optional	 second	 colon	and  a
	      description.   If	 that  is given, this description will be used
	      for the `%d' in the value of the 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 description supplied by the completion
	      function.

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

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

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

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

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

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

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

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

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

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

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

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

	      For the messages tag, this style defines a string used  by  some
	      completion  functions  to	 display  messages.  Here, the `%d' is
	      replaced with a message given by the completion function.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

	      The values `current' and `current-shown'	are  a	bit  like  the
	      opposite of accept-exact. They mean that only strings with miss‐
	      ing 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 by the function completing pathnames without
	      a	 tag  to  determine whether to ignore the names of directories
	      already mentioned in the current word, or the name of  the  cur‐
	      rent  working  directory.	 The value must include one or both of
	      the following strings:

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

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

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

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

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

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

       ignored-patterns
	      This  style  can be used to specify a list of patterns which are
	      tested against against the trial completions in a given context;
	      any matching completions will be removed from the list of possi‐
	      bilities.	 The _ignored completer can appear in the list of com‐
	      pleters  to  produce  a  list  which includes these matches once
	      more.  This is a more configurable version of the shell  parame‐
	      ter $fignore.

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

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

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

	      The value may also contain the substrings	 `pending'  or	`pend‐
	      ing=val'	to  make  the  character  typed to start completion be
	      inserted instead of completion being tried when there  is	 input
	      pending  which has not yet been processed by the shell. If a val
	      is given, completion will not be done if there are at least that
	      many  characters	of  unprocessed input. This is often useful to
	      have set when pasting characters into a terminal. Note  however,
	      that  it	relies	on  the	 $PENDING  special  parameter from the
	      zsh/zle module being set properly which is not guaranteed on all
	      platforms.

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

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

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

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

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

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

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

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

	      If this style is set for the default tag,	 the  strings  in  the
	      value  are  taken	 as  specifications that are to be used 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.
	      If  the  group-name tag specifies other names for the groups the
	      matches in these groups can be  colored  by  using  these	 names
	      together	 with  the  `(group)...'   syntax  described  for  the
	      ZLS_COLORS and ZLS_COLOURS parameters and adding the  specifica‐
	      tions to the value for this style with the default tag (although
	      in most cases it should work  by	setting	 this  style  for  the
	      appropriate tags).

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

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

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

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

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

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

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

       local  This  style  is used by completion functions which generate URLs
	      as possible matches to add suitable matches when a URL points to
	      a	 local	web  server,  that  is,	 one whose files are available
	      directly on the local file system.  Its value should consist  of
	      three strings: a hostname, the path to the default web pages for
	      the server and the directory name used by	 a  user  placing  web
	      pages  within  their  home  area.	 For example, completion after
	      `http://toast/~yousir/' will attempt to match the	 name  `toast'
	      against  the first argument to the style, and if successful will
	      look in the directory under ~yousir given by the third  argument
	      to the style for possible completions.

       match-original
	      This  is	used  by  the _match completer.	 If it is set to only,
	      _match will try to generate matches 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 done with the `*' inserted.

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

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

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

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

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

	      The style allows even finer control by specifying	 a  particular
	      completer, without the leading underscore, in the third field of
	      the completion context.  For example, if one uses the completers
	      _complete	 and _prefix but wants to try case-insensitive comple‐
	      tion only when using the _complete completer, one would do:

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

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

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

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

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

       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.

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

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

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

	      In  addition  to	(or  instead  of) the above possibilities, the
	      value may contain the string `select', optionally followed by an
	      equals  sign  and	 a  number.   In  this case menu selection (as
	      defined by the zsh/complist module) will	be  started.   Without
	      the optional number, it will be started unconditionally and with
	      a number it will be started only if at least that	 many  matches
	      are  generated;  if  the	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'.  This will only start menu selection if the  wid‐
	      get  invoked  does  completion,  not  simply  listing as done by
	      delete-char-or-list; to start menu selection even here, use  the
	      value `select=long-list'.

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

       numbers
	      This is used with the jobs tag.  If it is `true', the shell will
	      complete	the  job  numbers  instead of the shortest unambiguous
	      strings of the jobs' command lines.  If the value is  a  number,
	      job  numbers  will  only be used if that many words from the job
	      descriptions are required to resolve ambiguities.	 For  example,
	      if  the value is `1', strings will only be used if all jobs dif‐
	      fer 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.  It may be set to
	      one of the `true' values or to the string `only' to use  such  a
	      list.  If it is set to `only', _all_matches will only use an old
	      list and won't have any effect on the list of matches  currently
	      being generated.

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

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

       original
	      This  is	used  by  the  _approximate and _correct completers to
	      decide if the original string should be added  as	 one  possible
	      completion.   Normally,  this is done only if there are at least
	      two possible corrections, but if this style is set to `true', it
	      is  always  added.   Note	 that  these completers use this style
	      after setting the completer field in the context	name  to  cor‐
	      rect-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.

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

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

	      The default value for this style is `false'.

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

	      The default style for this style is `true'.

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

       regular
	      This  style  is used by the _expand_alias completer 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 and if it is set
	      to the string `always', regular aliases will be expanded even if
	      not in command position.

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

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

       select-scroll
	      This  style  is  tested for the default tag and 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.  Its value should be `0' (zero) to scroll  by
	      half-screenfuls, a positive integer to scroll by that many lines
	      and a negative number to scroll by the number of	lines  of  the
	      screen  minus that number (or plus the number, since it is nega‐
	      tive).  The default is to scroll by single lines.

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

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

	      This  is also used by the _expand completer.  Here, if it is set
	      to `true', the expansions generated will always be  sorted.   If
	      it  is  set  to `menu', then the expansions are only sorted when
	      they are offered as single strings (not in the string containing
	      all possible expansions).

       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.

       squeeze-slashes
	      If set to `true', sequences of slashes (as in  `foo//bar')  will
	      be  treated as if they were only one slash when completing path‐
	      names.  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.

       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 `true',
	      the word will only be expanded if it doesn't have a suffix, i.e.
	      if it is something like `~foo' or	 `$foo',  but  not  if	it  is
	      `~foo/'  or `$foo/bar', unless that suffix itself contains char‐
	      acters eligible for expansion.  The default for  this  style  is
	      `true'.

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

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

	      For example:

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

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

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

	      -	     If any string in the value consists  of  only  a  hyphen,
		     then  only the tags specified by the other strings in the
		     value are generated.  Normally all	 tags  not  explicitly
		     selected  are  tried  last	 if the specified tags fail to
		     generate any matches.  This means that a value consisting
		     only of a 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 ...
		     In strings not starting with an exclamation mark,	it  is
		     also possible to specify tag labels instead of only tags,
		     where tag is one of the tags offered  by  the  completion
		     function  for  the	 current  context and label is a name.
		     For this, the completion function will  generate  matches
		     in	 the same way as for the tag but it will use the label
		     in place of the tag in the context names used to look  up
		     styles.   If  the	label starts with a hyphen, the tag is
		     prepended to the label to form the name used for  lookup.
		     This can be used to make the completion system try a cer‐
		     tain tag more than once, supplying different  style  set‐
		     tings for each attempt, see below for an example.

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

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

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

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

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

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

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

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

       The  second  interesting use of patterns is the case where one wants to
       try multiple match specifications one after another.  The  matcher-list
       style offers something similar, but it is tested very early in the com‐
       pletion 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 arguments of the
       command foo:
	      zstyle ':completion:*:*:foo:*' tag-order '*' '*:-case'
	      zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}'

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

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

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

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

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

       urls   This  is used together with the the urls tag by completion func‐
	      tions that generate URLs as possible matches.  If the value con‐
	      sists  of	 more  than  one string or if the only string does not
	      name a file or directory, the strings are used as	 the  URLs  to
	      complete.

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

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

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

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

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

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

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

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

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

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

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

	      The default value for this style is `true'.

       word   This is used by the _list completer, which prevents  the	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:

	      zstyle ':completion:*' completer _complete _correct

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

       If the first argument to _main_complete is a single hyphen,  the	 argu‐
       ments  will  not	 be  taken as names of completers. Instead, the second
       argument gives a name to use in the completer field of the context  and
       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
       (users may write their own):

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

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

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

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

		     zstyle ':completion:*' completer _complete _approximate

	      This will give correcting completion if and only if normal  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
	      `%e' and `%o' which will be replaced by  the  number  of	errors
	      accepted	to  generate  the corrections and the original string,
	      respectively.

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

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

	      Note  that  this completer (and the _correct 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 ':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-, as mentioned above for the #compdef tag, are
	      handled specially.  These are:

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

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

	      -command-
		     for completing in a command position.

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

	      -default-
		     for  generating  completions  when	 no special completion
		     function is used.

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

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

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

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

	      -redirect-
		     for completion after a redirection operator.

	      -subscript-
		     for completion inside subscripts.

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

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

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

	      Before  trying  to find a function for a specific context, _com‐
	      plete checks if the parameter `compcontext' is set.   If	it  is
	      set  to  an  array,  the	elements  are taken to be the possible
	      matches which will be completed using the tag `values'  and  the
	      description `value'.   If it is set to an associative array, the
	      keys are used as the possible completions	 and  the  values  (if
	      non-empty)  are used as descriptions for the matches.  If `comp‐
	      context' 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  says  what
	      should be completed in one of the forms described for the _argu‐
	      ments utility function below.

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

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

	      For example, with:

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

	      correction will accept up to two errors.	If a numeric  argument
	      is  given, correction will not be performed, but correcting 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
	      should  be the same as the value of the accept style, all in one
	      string.

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

       _expand
	      This completer function  does  not  really  do  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.   When  using  this, one should not use the
	      expand-or-complete widget, but  instead  use  complete-word,  as
	      expand-or-complete will expand the string on the line before the
	      completion widget is called.  Also,  this	 completer  should  be
	      called before the _complete completer function.

	      The  tags used when generating expansions are all-expansions for
	      the string containing all possible expansions,  expansions  when
	      adding  the  possible  expansions as single matches and original
	      when adding the original string from the line.  In  which	 order
	      these  strings are generated and which of these strings are gen‐
	      erated at all can be controlled by using the  group-order	 style
	      and by modifying the tag-order style, 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.

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

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

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

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

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

       _ignored
	      The ignored-patterns style can be set  to	 a  list  of  patterns
	      which  are  compared against possible completions; matching ones
	      are removed.  With this completer those  matches	can  be	 rein‐
	      stated, as if no ignored-patterns style were set.	 The completer
	      actually generates its own list of matches; which completers are
	      used  for	 this is determined in the same way as for the _prefix
	      completer.

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

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

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

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

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

	      Note that the matcher specifications defined globally or used by
	      the completion functions will not be used.

       _menu  This completer is a simple example function implemented to  show
	      how  menu	 completion  can  be done in shell code.  It should be
	      used as the first completer and has the  effect  of  making  the
	      code  perform menu completion.  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‐
	      pletion keys to continue to use the  list	 of  completions  thus
	      generated,  instead  of producing a new list of ordinary contex‐
	      tual completions.	 It should appear in the  list	of  completers
	      before  any  of the widgets which generate matches.  It uses two
	      styles: old-list and old-menu, see the section `Completion  Sys‐
	      tem Configuration' above.

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

	      For example, consider this global completer style:

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

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

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

	      The add-space style is also used.	 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.

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

       _bash_completions
	      This function is used by two  widgets,  _bash_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 aliases expanded can be controlled with the regu‐
	      lar, global and disabled styles.

	      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  isn't  the  name	of  an	alias,
	      _expand_alias  tries  to	complete the word to a full alias name
	      without expanding it (but leaving the cursor directly after  the
	      completed	 word  so  that	 invoking _expand_alias once more will
	      expand the now-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 is set to `expand-word'.

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

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

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

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

       _next_tags (^Xn)
	      This command alters the set of matches used to that 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‐
	      porary file a trace of the shell commands executed by  the  com‐
	      pletion  system.	 Each completion attempt gets its own file.  A
	      command to view each of these files is pushed  onto  the	editor
	      buffer stack.

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

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

       _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
       Descriptions follow for utility functions that may be useful when writ‐
       ing  completion	functions.  Most of these reside in the Base subdirec‐
       tory. Like the example functions for commands in the distribution,  the
       utility	functions  generating  matches	all  follow  the convention of
       returning zero if they generated completions and non-zero if no	match‐
       ing completions could be added.

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

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

	      For example:

		     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 [ -C name ] specs ...
	      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 above.

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

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

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

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

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

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

       _arguments spec ...
	      This function can be used to  complete  words  on	 the  line  by
	      describing  the options and arguments which may be passed to the
	      command for which completion is being performed.	 The  descrip‐
	      tion  is	given  as  arguments  to this function, with each spec
	      describing one option or normal argument of  the	command.   The
	      forms of spec understood are:

	      n:message:action
	      n::message:action
		     This  describes  the  n'th	 normal argument.  The message
		     will be printed  above  the  matches  generated  and  the
		     action  says  what can be completed in this position (see
		     below).  If there are two colons before the message, this
		     describes	an optional argument.  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
		     Like the previous one, but describing the next  argument.
		     I.e.  if you want to describe all arguments a command can
		     get, you can leave out the numbers in the description and
		     just  use this form to describe them one after another in
		     the order they have to appear on the line.

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

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

	      optspec[description ...]
		     This  describes  an  option and (if description is given)
		     the arguments that have to come after the option.	If  no
		     description is given, this means to offer only the option
		     name as a possible completion in the right places.	 (Note
		     that  the	brackets,  above, around description, indicate
		     that zero or more descriptions may appear; but the brack‐
		     ets  are not themselves part of this format.  If brackets
		     are used, they are part of the optspec; see below.)

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

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

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

		     The forms of optspec are:

		     *optspec
			    If	the option may be given more than once, a star
			    (`*') must be added in front of one of the follow‐
			    ing forms of optspec.  Otherwise, if the option is
			    already on the line and to the left of the cursor,
			    it is not offered as a possible completion again.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

		     When  the	message	 is  preceded by two colons, the words
		     special array and the CURRENT special parameter are modi‐
		     fied  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.

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

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

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

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

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

       In every case above, the action determines how the possible completions
       should be generated.  In places where no sensible matches can be gener‐
       ated,  the  action  should  consist of only a space. This will make the
       message be displayed but no possible completions listed. Note that even
       in  this	 case  the colon at the end of the message is needed. The only
       case where it can be left is when neither a message, nor	 a  action  is
       given.

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

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

	      :foo:(foo bar baz)

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

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

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

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

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

	      local context state line
	      typeset -A opt_args

       This will ensure that _arguments does not create unused global  parame‐
       ters.

       A  string  in  braces  is  evaluated to generate the matches and if the
       action does not begin with an opening parentheses or brace, it is  also
       split  into  separate  words  and executed. If the action starts with a
       space, this list of words will be invoked unchanged, otherwise it  will
       be  invoked  with  some extra strings placed after the first word which
       can be given as arguments to the compadd builtin command and which make
       sure  that the message given in the description will be shown above the
       matches. These arguments are taken  from	 the  array  parameter	`expl'
       which  will be set up before executing the action and hence may be used
       in it (normally in an expansion like `$expl[@]').

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

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

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

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

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

       For example:

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

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

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

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

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

       To  simplify the specifications for commands with standard option pars‐
       ing, the options -S and -A may be given.	 With -S, no  option  will  be
       completed  after a `--' on the line and this argument will otherwise be
       ignored. With  -A,  no  options	will  be  completed  after  the	 first
       non-option  argument  on the line.  The -A has to be followed by a pat‐
       tern matching all strings which are not to be taken as  arguments.  For
       example,	 to  make  _arguments  stop completing options after the first
       normal argument, but ignoring all strings starting with a  hyphen  even
       if  they	 are  not described by one of the optspecs, one would use: `-A
       "-*"'.

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

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

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

	      local curcontext="$curcontext"

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

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

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

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

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

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

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

       Example:

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

       This describes three options: `-l', `-format', and `-copy'.  The	 first
       one  gets  one argument described as `left border' for which no comple‐
       tion will be offered because of the empty action. The argument may come
       directly	 after	the  `-l'  or  it may be given as the next word on the
       line. The `-format'  option  gets  one  argument	 (in  the  next	 word)
       described  as `paper size' for which only the strings `letter' and `A4'
       will be completed. The `-copy' option differs from  the	first  two  in
       that  it	 may  appear more than once on the command line and in that it
       accepts two arguments. The first one is mandatory and will be completed
       as  a filename. The second one is optional (because of the second colon
       before the description `resolution') and will  be  completed  from  the
       strings `300' and `600'.

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

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

	      Example:

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

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

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

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

       _combination [ -s pattern ] tag style specs ... field opts ...
	      This function is used to complete combinations of values such as
	      pairs of hostnames and usernames.	 The possible values  will  be
	      taken from the style whose name is given as the second argument.
	      The first argument is the tag to use to do the lookup.

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

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

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

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

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

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

       _contexts names ...
	      This function looks up the definitions for the context and  com‐
	      mand  names  given  as arguments and calls the handler functions
	      for them if there is a definition (given with the compdef	 func‐
	      tion).   For  example, the function completing inside subscripts
	      might use `_contexts -math-' to include the  completions	gener‐
	      ated for mathematical environments.

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

	      The descr is taken as a string to display above the  matches  if
	      the  format  style  for the descriptions tag is set.  After this
	      come one or two names of arrays followed by options to  pass  to
	      compadd.	The first array contains the possible completions with
	      their descriptions in the form `completion:description'.	 If  a
	      second  array  is	 given, it should have the same number of ele‐
	      ments as the first one and the corresponding elements are	 added
	      as  possible  completions instead of the completion strings from
	      the first array.	The completion list will retain	 the  descrip‐
	      tions  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 option names (typically follow‐
	      ing a `-', `--'  or  `+'	on  the	 command  line).   This	 makes
	      _describe	 use  the  prefix-hidden,  prefix-needed  and  verbose
	      styles to find out if the strings should be added at all and  if
	      the descriptions should be shown.	 Without the `-o' option, only
	      the verbose style is used.

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

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

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

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

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

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

	      Note  the use of the parameter expl, the hyphen, and the list of
	      matches.	Almost all calls to compadd within the completion 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.

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

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

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

		     compdef _gnu_generic foo bar

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

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

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

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

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

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

	      or

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

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

       _message [ -r ] descr
	      The  descr  is  used like the third argument to the _description
	      function. However, the resulting string  will  always  be	 shown
	      whether or not matches were generated. This is useful to display
	      help texts in places where no completions can be generated auto‐
	      matically.

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

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

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

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

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

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

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

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

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

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

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

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

	      If the command name matches a pattern, the  parameter  _compskip
	      is  checked after the call to the corresponding completion func‐
	      tion.  This has the same effect here as in the -first-  context:
	      if  it  is  set, no more completion functions are called even if
	      there are no matches so far.

       _options
	      This can be used to complete option names.  It uses  a  matching
	      specification  that  ignores a leading `no', ignores underscores
	      and allows the user to type upper-case letters which will	 match
	      their  lower-case	 counterparts.	 All  arguments passed to this
	      function are propagated unchanged to the 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  options  are  not generally used by the completion
	      system.

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

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

	      The options accepted by both _path_files and _files are:

	      -f     Complete all filenames.  This is the default.

	      -/     Specifies that only directories should be completed.

	      -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 line to generate the filenames  but  that
		     should  not be inserted in the line or shown in a comple‐
		     tion listing.  Here, paths may be the name	 of  an	 array
		     parameter,	 a literal list of paths enclosed in parenthe‐
		     ses or an absolute pathname.

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

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

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

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

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

	      /pattern/ [%lookahead%] [-guard] [:tag:descr:action]
		     This  is  a primitive element, corresponding to one state
		     of the compiled state machine.  The state is  entered  if
		     `(#b)((#B)pattern)(#B)lookahead*'	 matches  the  command
		     line string.  If it matches, `guard' is evaluated and its
		     return  status  is	 examined;  if this is successful, the
		     state is entered, otherwise the test fails and other can‐
		     didates are tried.	 The pattern string `[]' is guaranteed
		     never to match.

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

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

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

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

	      ( spec )
		     This groups specs.

	      spec # This allows any number of repetitions of spec.

	      spec spec
		     This represents the concatenation of two specs.

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

       _requested [ -12VJ ] tag [ name descr [ command args ... ] ]
	      This  function  is called to decide whether a tag already regis‐
	      tered by a call to _tags (see below) is requested and hence com‐
	      pletion  should  be  performed for it; it returns status zero if
	      the tag is requested and non-zero otherwise.  This will  usually
	      be done in a loop such as the following:

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

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

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

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

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

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

	      See _store_cache below for more details.

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

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

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

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

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

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

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

	      The return value is zero if storage was successful.   The	 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.

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

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

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

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

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

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

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

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

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

	      All other arguments describe the possible values and their 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, that
	      values can have only  one	 argument  and	that  those  forms  of
	      actions beginning with an equal sign are not supported.

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

	      Example:

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

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

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

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

	      One last difference from _arguments is that this	function  uses
	      the  associative array val_args to report values and their argu‐
	      ments, although otherwise this is the same as the opt_args asso‐
	      ciation  used  by _arguments.  This also means that the function
	      calling _values should declare  the  state,  line,  context  and
	      val_args parameters as in:

		     local context state line
		     typeset -A val_args

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

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

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

       _wanted [ -C name ]  [ -12VJ ] tag name descr command args ...
	      In many contexts, completion will 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.

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

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

	      Unlike _requested, however, _wanted cannot be called without the
	      command.	This is because _wanted also implements the loop  over
	      the tags, not just the one for the labels; conversely, it should
	      not be called in the middle of a _tags loop.

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

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‐
       ing is a description of the  files  found  in  the  original  directory
       structure.   If	you  wish to alter an installed file, you will need to
       copy it to some directory which appears earlier in your fpath than  the
       standard directory where it appears.

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

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

       Unix   Functions for completing	arguments  of  external	 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.

zsh 4.0.1			 June 1, 2001			 ZSHCOMPSYS(1)
[top]

List of man pages available for Ultrix

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net