Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
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:

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

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

       o      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).

       o      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).

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

       o      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 an 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 one of its values	is the
	      string `prefix', the partially typed word	from the line will  be
	      expanded	as  far	 as  possible even if trailing parts cannot be
	      completed.  If one of its	values is the string `suffix',	match-
	      ing names	for components after the first ambiguous one will also
	      be added.	 This means that the resulting string is  the  longest
	      unambiguous  string  possible, but if menu completion is started
	      on the list of matches generated this way, 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 value	for this style is `true'.

       preserve-prefix
	      This style is used when completing path names.  Its value	should
	      be  a pattern matching an	initial	prefix of the word to complete
	      that should be left  unchanged  under  all  circumstances.   For
	      example,	on  some  Unices  an initial `//' (double slash) has a
	      special meaning and hence	should be kept.	 For  that  one	 could
	      set  this	style to the string `//'.  As another example, setting
	      this style to `?:/' under	Cygwin would  allow  completion	 after
	      `a:/...' and the like.

       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.

       separate-sections
	      This style is used with the manuals tag when completing names of
	      manual  pages.   If it is	`true',	entries	for different sections
	      are added	separately using tag names  of	the  form  `manual.X',
	      where  X	is the section number.	This means that	it is possible
	      to make pages from different sections be	listed	separately  by
	      setting  the  group-name	style.	 The default for this style is
	      `false'.

       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 [ -ACS ] [ -O	name ] [ -M matchspec ]	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

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

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

	      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  need  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 an  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.

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

	      Like  _tags  this	function supports the -C option	to give	a 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.6			August 14, 2002			 ZSHCOMPSYS(1)

NAME | DESCRIPTION | INITIALIZATION | COMPLETION SYSTEM CONFIGURATION | CONTROL FUNCTIONS | BINDABLE COMMANDS | UTILITY FUNCTIONS | COMPLETION DIRECTORIES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=zshcompsys&sektion=1&manpath=Red+Hat+Linux%2fi386+9>

home | help