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

FreeBSD Manual Pages


home | help
ZSHCOMPSYS(1)		    General Commands Manual		 ZSHCOMPSYS(1)

       zshcompsys - zsh	completion system

       This describes the shell	code for the `new' completion system, referred
       to as compsys.  It is written in	shell functions	based on the  features
       described in zshcompwid(1).

       The features are	contextual, sensitive to the point at which completion
       is started.  Many completions are already provided.  For	this reason, a
       user  can perform a great many tasks without knowing any	details	beyond
       how to initialize the system, which is described	below  in  INITIALIZA-

       The context that	decides	what completion	is to be performed may be
       o      an  argument  or option position:	these describe the position on
	      the command line at which	completion is requested.  For  example
	      `first  argument	to rmdir, the word being completed names a di-

       o      a	special	context, denoting an element in	 the  shell's  syntax.
	      For  example  `a	word  in  command  position' or	`an array sub-

       A full context specification contains other elements, as	we  shall  de-

       Besides	commands  names	and contexts, the system employs two more con-
       cepts, styles and tags.	These provide ways for the user	 to  configure
       the system's behaviour.

       Tags  play  a dual role.	 They serve as a classification	system for the
       matches,	typically indicating a class of	object that the	user may  need
       to  distinguish.	 For example, when completing arguments	of the ls com-
       mand the	user may prefer	to try files before directories,  so  both  of
       these are tags.	They also appear as the	rightmost element in a context

       Styles modify various operations	of the completion system, such as out-
       put formatting, but also	what kinds of completers are used (and in what
       order), or which	tags are examined.  Styles may	accept	arguments  and
       are  manipulated	 using	the  zstyle  command  described	in see zshmod-

       In summary, tags	describe what the completion objects  are,  and	 style
       how they	are to be completed.  At various points	of execution, the com-
       pletion system checks what styles and/or	tags are defined for the  cur-
       rent  context, and uses that to modify its behavior.  The full descrip-
       tion of context handling, which determines how tags and other  elements
       of the context influence	the behaviour of styles, is described below in

       When a completion is requested, a dispatcher function  is  called;  see
       the  description	of _main_complete in the list of control functions be-
       low. This dispatcher decides which function should be called to produce
       the completions,	and calls it. The result is passed to one or more com-
       pleters,	functions that	implement  individual  completion  strategies:
       simple  completion, error correction, completion	with error correction,
       menu selection, etc.

       More generally, the shell functions contained in	the completion	system
       are of two types:
       o      those beginning `comp' are to be called directly;	there are only
	      a	few of these;

       o      those beginning `_' are called  by  the  completion  code.   The
	      shell  functions	of this	set, which implement completion	behav-
	      iour and may be bound to keystrokes, are referred	 to  as	 `wid-
	      gets'.  These proliferate	as new completions are required.

       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 (`au-
       toload -U compinstall' is recommended).	You can	abort the installation
       any  time  you are being	prompted for information, and your .zshrc will
       not be altered at all; changes only take	place right at the end,	 where
       you are specifically asked for confirmation.

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

       To  initialize  the system, the function	compinit should	be in a	direc-
       tory mentioned in the fpath parameter, and should be  autoloaded	 (`au-
       toload -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 com-
       plete-word; this	is necessary to	use the	correct	form of	expansion.

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

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

       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 al-

       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  en-
       tirely 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 ex-
       ecuted  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

       The  function  bashcompinit provides compatibility with bash's program-
       mable completion	system.	 When run it will define the functions,	 comp-
       gen  and	 complete  which correspond to the bash	builtins with the same
       names.  It will then be possible	to use completion  specifications  and
       functions written for bash.

   Autoloaded files
       The convention for autoloaded functions used in completion is that they
       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 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	name ... [ -{p|P} pattern ... [	-N name	... ] ]
	      The file will be made autoloadable and the function  defined  in
	      it will be called	when completing	names, each of which is	either
	      the name of a command whose arguments are	to be completed	or one
	      of  a number of special contexts in the form -context- described

	      Each name	may also be of the form	`cmd=service'.	When  complet-
	      ing  the	command	 cmd, the function typically behaves as	if the
	      command (or special context) service  was	 being	completed  in-
	      stead.   This  provides a	way of altering	the behaviour of func-
	      tions that can perform many different completions.  It is	imple-
	      mented  by setting the parameter $service	when calling the func-
	      tion; the	function may choose to interpret this how  it  wishes,
	      and simpler functions will probably ignore it.

	      If  the  #compdef	line contains one of the options -p or -P, the
	      words following are taken	to be patterns.	 The function will  be
	      called  when  completion	is  attempted for a command or context
	      that matches one of the patterns.	 The options  -p  and  -P  are
	      used  to specify patterns	to be tried before or after other com-
	      pletions respectively.  Hence -P may be used to specify  default

	      The option -N is used after a list following -p or -P; it	speci-
	      fies that	remaining words	no longer define patterns.  It is pos-
	      sible  to	toggle between the three options as many times as nec-

       #compdef	-k style key-sequence ...
	      This option creates a widget behaving like  the  builtin	widget
	      style  and  binds	 it  to	 the given key-sequences, if any.  The
	      style must be one	of the builtin widgets	that  perform  comple-
	      tion,  namely complete-word, delete-char-or-list,	expand-or-com-
	      plete, expand-or-complete-prefix,	 list-choices,	menu-complete,
	      menu-expand-or-complete,	 or   reverse-menu-complete.   If  the
	      zsh/complist module is loaded  (see  zshmodules(1))  the	widget
	      menu-select is also available.

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

       #compdef	-K widget-name style key-sequence [ name style seq ... ]
	      This is similar to -k except that	only one key-sequence argument
	      may  be given for	each widget-name style pair.  However, the en-
	      tire set of three	arguments may be repeated with a different set
	      of  arguments.   Note in particular that the widget-name must be
	      distinct in each set.  If	it does	not begin with `_'  this  will
	      be added.	 The widget-name should	not clash with the name	of any
	      existing widget: names based on the name	of  the	 function  are
	      most useful.  For	example,

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

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

       #autoload [ options ]
	      Functions	 with the #autoload tag	are marked for autoloading but
	      are not otherwise	treated	specially.  Typically they are	to  be
	      called from within one of	the completion functions.  Any options
	      supplied will be passed to the autoload builtin; a  typical  use
	      is +X to force the function to be	loaded immediately.  Note that
	      the -U and -z flags are always added implicitly.

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

       The special contexts for	which completion functions can be defined are:

	      The right	hand side of an	array-assignment (`name=(...)')

	      The name of a parameter expansion	within braces (`${...}')

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

	      A	word in	command	position

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

	      Any word for which no other completion is	defined

	      A	word beginning with an equals sign

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

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

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

	      The word after a redirection operator.

	      The contents of a	parameter subscript.

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

	      On the right hand	side of	an assignment.

       Default implementations are supplied for	each of	 these	contexts.   In
       most  cases  the	 context  -context-  is	implemented by a corresponding
       function	_context, for example the context `-tilde-' and	 the  function

       The contexts -redirect- and -value- allow extra context-specific	infor-
       mation.	(Internally, this is handled by	the functions for each context
       calling	the function _dispatch.)  The extra information	is added sepa-
       rated by	commas.

       For the -redirect- context, the extra information is in the form	 `-re-
       direct-,op,command',  where  op is the redirection operator and command
       is the name of the command on the line.	If there is no command on  the
       line yet, the command field will	be empty.

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

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

       As an example:

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

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


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

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

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

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

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

       The  following  function	 is  defined by	compinit and may be called di-

       compdef [ -ane ]	function name ... [ -{p|P} pattern ... [ -N name ...]]
       compdef -d name ...
       compdef -k [ -an	] function style key-sequence [	key-sequence ... ]
       compdef -K [ -an	] function name	style key-seq [	name style seq ... ]
	      The first	form defines the function to call  for	completion  in
	      the given	contexts as described for the #compdef tag above.

	      Alternatively,  all  the	arguments  may have the	form `cmd=ser-
	      vice'.   Here  service  should  already  have  been  defined  by
	      `cmd1=service' lines in #compdef files, as described above.  The
	      argument for cmd will be completed in the	same way as service.

	      The function argument may	alternatively be a  string  containing
	      almost  any  shell  code.	 If the	string contains	an equal sign,
	      the above	will take precedence.  The option -e may  be  used  to
	      specify the first	argument is to be evaluated as shell code even
	      if it contains an	equal sign.  The string	will be	executed using
	      the eval builtin command to generate completions.	 This provides
	      a	way of avoiding	having to define a  new	 completion  function.
	      For  example,  to	 complete files	ending in `.h' as arguments to
	      the command foo:

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

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

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

	      The names	may also contain -p, -P	and -N	options	 as  described
	      for  the #compdef	tag.  The effect on the	argument list is iden-
	      tical, switching between	definitions  of	 patterns  tried  ini-
	      tially,  patterns	 tried	finally,  and normal commands and con-

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

	      The form with -k defines a widget	with  the  same	 name  as  the
	      function that will be called for each of the key-sequences; this
	      is like the #compdef -k tag.  The	function should	 generate  the
	      completions  needed  and	will otherwise behave like the builtin
	      widget whose name	is given as the	style argument.	  The  widgets
	      usable  for  this	 are:  complete-word, delete-char-or-list, ex-
	      pand-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 al-
	      ready 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-sequence, where the	latter two are
	      as  for  -k and the first	must be	a unique widget	name beginning
	      with an underscore.

	      Wherever applicable, the -a option makes the function  autoload-
	      able, equivalent to autoload -U function.

       The function compdef can	be used	to associate existing completion func-
       tions with new commands.	 For example,

	      compdef _pids foo

       uses the	function _pids to complete process IDs for the command foo.

       Note also the _gnu_generic function described below, which can be  used
       to complete options for commands	that understand	the `--help' option.

       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.

       When  completion	is attempted somewhere on the command line the comple-
       tion system begins building the context.	 The context represents	every-
       thing  that  the	 shell knows about the meaning of the command line and
       the significance	of the cursor position.	 This takes account of a  num-
       ber  of things including	the command word (such as `grep' or `zsh') and
       options to which	the current word may be	an argument (such as the  `-o'
       option to zsh which takes a shell option	as an argument).

       The  context  starts out	very generic ("we are beginning	a completion")
       and becomes more	specific as more is learned ("the current word is in a
       position	 that is usually a command name" or "the current word might be
       a variable name"	and so on).  Therefore the context  will  vary	during
       the same	call to	the completion system.

       This  context information is condensed into a string consisting of mul-
       tiple fields separated by colons, referred to simply as	`the  context'
       in the remainder	of the documentation.  Note that a user	of the comple-
       tion system rarely needs	to compose a context string, unless for	 exam-
       ple  a  new  function  is being written to perform completion for a new
       command.	 What a	user may need to do is compose a style pattern,	 which
       is  matched  against a context when needed to look up context-sensitive
       options that configure the completion system.

       The next	few paragraphs explain how a context is	 composed  within  the
       completion  function suite.  Following that is discussion of how	styles
       are defined.  Styles determine such things as how the matches are  gen-
       erated,	similarly  to  shell options but with much more	control.  They
       are defined with	the zstyle builtin command (see	zshmodules(1)).

       The context string always consists of a fixed set of fields,  separated
       by  colons and with a leading colon before the first.  Fields which are
       not yet known are left empty, but the surrounding colons	appear anyway.
       The  fields are always in the order :completion:function:completer:com-
       mand:argument:tag.  These have the following meaning:

       o      The literal string completion, saying that this style is used by
	      the  completion  system.	 This  distinguishes  the context from
	      those used by, for example, zle widgets and ZFTP functions.

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

       o      The completer currently active, the name of the function without
	      the  leading  underscore and with	other underscores converted to
	      hyphens.	A `completer' is in overall control of how  completion
	      is  to  be performed; `complete' is the simplest,	but other com-
	      pleters exist to perform related tasks such as correction, or to
	      modify  the  behaviour  of  a  later completer.  See the section
	      `Control Functions' below	for more information.

       o      The command or a special -context-, just at it appears following
	      the  #compdef tag	or the compdef function.  Completion functions
	      for commands that	have sub-commands usually modify this field to
	      contain the name of the command followed by a minus sign and the
	      sub-command.  For	example, the completion	function for  the  cvs
	      command  sets this field to cvs-add when completing arguments to
	      the add subcommand.

       o      The argument; this indicates which command line or option	 argu-
	      ment  we	are  completing.  For command arguments	this generally
	      takes the	form argument-n, where n is the	number	of  the	 argu-
	      ment, and	for arguments to options the form option-opt-n where n
	      is the number of the argument to option opt.  However,  this  is
	      only  the	 case  if  the	command	 line  is parsed with standard
	      UNIX-style options and arguments,	so many	completions do not set

       o      The tag.	As described previously, tags are used to discriminate
	      between the types	of matches a completion	function can  generate
	      in  a  certain context.  Any completion function may use any tag
	      name it likes, but a list	of the more common ones	is  given  be-

       The  context  is	 gradually put together	as the functions are executed,
       starting	with the main entry point, which  adds	:completion:  and  the
       function	 element  if necessary.	 The completer then adds the completer
       element.	 The contextual	completion adds	the command and	 argument  op-
       tions.	Finally,  the  tag  is	added when the types of	completion are
       known.  For example, the	context	name


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

	      dvips -o ...

       and the completion function will	generate filenames.

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

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

       When  looking  up styles	the completion system uses full	context	names,
       including the tag.  Looking up the value	of a style therefore  consists
       of two things: the context, which is matched to the most	specific (best
       fitting)	style pattern, and the name of the style itself, which must be
       matched	exactly.   The	following examples demonstrate that style pat-
       terns may be loosely defined for	 styles	 that  apply  broadly,	or  as
       tightly	defined	 as  desired for styles	that apply in narrower circum-

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

	      zstyle ':completion:*' verbose yes

       in a startup file (probably .zshrc).  This gives	the verbose style  the
       value  yes  in  every context inside the	completion system, unless that
       context has a more specific definition.	It is best to avoid giving the
       context	as  `*'	in case	the style has some meaning outside the comple-
       tion system.

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

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

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

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

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

       The  -e option to zstyle	even allows completion function	code to	appear
       as the argument to a style; this	requires some understanding of the in-
       ternals of completion functions (see see	zshcompwid(1))).  For example,

	      zstyle -e	':completion:*'	hosts 'reply=($myhosts)'

       This  forces  the value of the hosts style to be	read from the variable
       myhosts each time a host	name is	needed;	this is	useful if the value of
       myhosts	can  change  dynamically.  For another useful example, see the
       example in the description of the file-list style below.	 This form can
       be slow and should be avoided for commonly examined styles such as menu
       and list-rows-first.

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

       A good rule of thumb is that any	completion style pattern that needs to
       include more than one wildcard (*) and that does	not end	in a tag name,
       should  include	all  six  colons  (:), possibly	surrounding additional

       Style names like	those of tags are arbitrary and	depend on the  comple-
       tion  function.	 However,  the following two sections list some	of the
       most common tags	and styles.

   Standard Tags
       Some of the following are only used when	looking	up  particular	styles
       and do not refer	to a type of match.

	      used to look up the users-hosts style

	      used by the _expand completer when adding	the single string con-
	      taining all possible expansions

	      for the names of all files (as distinct from a  particular  sub-
	      set, see the globbed-files tag).

	      for arguments to a command

       arrays for names	of array parameters

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

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

	      for names	of builtin commands

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

	      for X colormap ids

       colors for color	names

	      for  names  of external commands.	 Also used by complex commands
	      such as cvs when completing names	subcommands.

	      for contexts in arguments	to the zstyle builtin command

	      used by the _approximate and _correct  completers	 for  possible

	      for cursor names used by X programs

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

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

	      for names	of device special files

	      for names	of directories -- local-directories  is	 used  instead
	      when  completing	arguments  of  cd and related builtin commands
	      when the cdpath array is set

	      for entries in the directory stack

	      for X display names

	      for network domains

	      for  email  addresses  from  the	`_email-plugin'	  backend   of

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

	      for X server extensions

	      for numbers of open file descriptors

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

       fonts  for X font names

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

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

	      for filenames when the name has been generated by	pattern	match-

       groups for names	of user	groups

	      for words	from the history

       hosts  for hostnames

	      for array	indexes

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

	      for network interfaces

	      for names	of zsh keymaps

	      for names	of X keysyms

	      for names	of system libraries

       limits for system limits

	      for names	of directories that are	subdirectories of the  current
	      working  directory  when	completing arguments of	cd and related
	      builtin commands (compare	path-directories) -- when  the	cdpath
	      array is unset, directories is used instead

	      for names	of manual pages

	      for e-mail folders

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

	      used to look up the format style for messages

	      for names	of X modifiers

	      for modules (e.g.	zsh modules)

	      used to look up the users-hosts style

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

       names  for all kinds of names

	      for USENET groups

	      for nicknames of NIS maps

	      for command options

	      used by the _approximate,	_correct and _expand  completers  when
	      offering the original string as a	match

	      used to look up the users-hosts style

	      for  the names of	any non-directory files.  This is used instead
	      of all-files when	the list-dirs-first style is in	effect.

	      for packages (e.g. rpm or	installed Debian packages)

	      for names	of parameters

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

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

       pods   for perl pods (documentation files)

       ports  for communication	ports

	      for prefixes (like those of a URL)

	      for print	queue names

	      for process identifiers

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

	      for sequences (e.g. mh sequences)

	      for sessions in the zftp function	suite

	      for signal names

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

       styles for styles used by the zstyle builtin command

	      for filename extensions

       tags   for tags (e.g. rpm tags)

	      for makefile targets

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

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

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

       users  for usernames

       values for one of a set of values in certain lists

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

	      for X visuals

	      used to look up the format style for warnings

	      for zsh widget names

	      for IDs of X windows

	      for shell	options

   Standard Styles
       Note that the values of several of these	styles represent boolean  val-
       ues.   Any  of the strings `true', `on',	`yes', and `1' can be used for
       the value `true'	and any	of the strings `false',	`off', `no',  and  `0'
       for  the	 value `false'.	 The behavior for any other value is undefined
       except where explicitly mentioned.  The default	value  may  be	either
       `true' or `false' if the	style is not set.

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

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

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

	      When  completing	pathnames (where the tag used is `paths') this
	      style accepts any	number of patterns as the value	in addition to
	      the  boolean  values.   Pathnames	matching one of	these patterns
	      will be accepted immediately even	if the command	line  contains
	      some more	partially typed	pathname components and	these match no
	      file under the directory accepted.

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

	      This  is used by filename	completion.  Unlike accept-exact it is
	      a	boolean.  By default, filename completion examines all	compo-
	      nents  of	 a path	to see if there	are completions	of that	compo-
	      nent, even if the	component matches an existing directory.   For
	      example,	when completion	after /usr/bin/, the function examines
	      possible completions to /usr.

	      When this	style is `true', any prefix of a path that matches  an
	      existing	directory  is accepted without any attempt to complete
	      it further.  Hence, in the given example,	the path /usr/bin/  is
	      accepted immediately and completion tried	in that	directory.

	      If  you  wish  to	 inhibit  this	behaviour  entirely,  set  the
	      path-completion style (see below)	to `false'.

	      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, or a slash  in  the  case	 of  directory
	      names.   If  the	value is `file', the completer will only add a
	      space to names of	existing files.	 Either	a  boolean  `true'  or
	      the value	`file' may be combined with `subst', in	which case the
	      completer	will not add a space to	words generated	from  the  ex-
	      pansion of a substitution	of the form `$(...)' or	`${...}'.

	      The  _prefix completer uses this style as	a simple boolean value
	      to decide	if a space should be inserted before the suffix.

	      This applies when	completing non-final  components  of  filename
	      paths,  in  other	 words	those with a trailing slash.  If it is
	      set, the cursor is left after  the  first	 ambiguous  component,
	      even  if	menu completion	is in use.  The	style is always	tested
	      with the paths tag.

	      When completing after an equals sign that	is being treated as an
	      assignment,  the	completion  system normally completes only one
	      filename.	 In some cases the value  may be a list	 of  filenames
	      separated	 by colons, as with PATH and similar parameters.  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 al-
	      ready contains a colon.

	      If set, this style's value will be used as the  description  for
	      options  that are	not described by the completion	functions, but
	      that have	exactly	one argument.  The sequence `%d' in the	 value
	      will  be replaced	by the description for this argument.  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.

	      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

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

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

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

	      This style is used in the	function for commands such as make and
	      ant where	calling	the command directly to	generate matches  suf-
	      fers  problems such as being slow	or, as in the case of make can
	      potentially cause	actions	in the makefile	to be executed.	If  it
	      is  set to `true'	the command is called to generate matches. The
	      default value of this style is `false'.

	      In many places, completion functions need	to call	external  com-
	      mands  to	 generate  the list of completions.  This style	can be
	      used to override the command that	is called in some such	cases.
	      The  elements of the value are joined with spaces	to form	a com-
	      mand line	to execute.  The value can also	start with  a  hyphen,
	      in  which	 case the usual	command	will be	added to the end; this
	      is most useful for putting `builtin' or `command'	 in  front  to
	      make  sure  the  appropriate version of a	command	is called, for
	      example to avoid calling a shell function	with the same name  as
	      an external command.

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

	      Note  that  the  completion  function  generally has to call the
	      specified	command	for each attempt to  generate  the  completion
	      list.   Hence care should	be taken to specify only commands that
	      take a short time	to run,	and in particular to  avoid  any  that
	      may never	terminate.

	      This  is	a  list	 of directories	to search for commands to com-
	      plete.  The default for this style is the	value of  the  special
	      parameter	path.

	      This  is	used  by  the function completing sub-commands for the
	      system initialisation scripts (residing in /etc/init.d or	 some-
	      where  not too far away from that).  Its values give the default
	      commands to complete for those commands for which	the completion
	      function isn't able to find them out automatically.  The default
	      for this style are the two strings `start' and `stop'.

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

	      This  is	used  by  the  completer for cd, chdir and pushd.  For
	      these commands a - is used to introduce a	directory stack	 entry
	      and  completion  of these	is far more common than	completing op-
	      tions.  Hence unless the value of	this style is  `true'  options
	      will  not	 be  completed,	 even  after  an  initial -.  If it is
	      `true', options will be completed	 after	an  initial  -	unless
	      there is a preceding -- on the command line.

	      The  strings  given as the value of this style provide the names
	      of the completer functions to use. The available completer func-
	      tions are	described in the section `Control Functions' below.

	      Each  string may be either the name of a completer function or a
	      string of	the form `function:name'.  In the first	case the  com-
	      pleter  field  of	 the context will contain the name of the com-
	      pleter without the leading underscore and	with all other	under-
	      scores  replaced by hyphens.  In the second case the function is
	      the name of the completer	to call, but the context will  contain
	      the user-defined name in the completer field of the context.  If
	      the name starts with a hyphen, the string	for the	 context  will
	      be build from the	name of	the completer function as in the first
	      case with	the name appended to it.  For example:

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

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

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

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

	      This style is used when adding a delimiter for use with  history
	      modifiers	 or glob qualifiers that have delimited	arguments.  It
	      is an array of preferred delimiters to add.  Non-special charac-
	      ters are preferred as the	completion system may otherwise	become
	      confused.	 The default list is :,	+, /, -, %.  The list  may  be
	      empty to force a delimiter to be typed.

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

	      A	 list  of names	of network domains for completion.  If this is
	      not set, domain names will  be  taken  from  the	file  /etc/re-

	      The environ style	is used	when completing	for `sudo'.  It	is set
	      to an array of `VAR=value' assignments to	be exported  into  the
	      local  environment  before the completion	for the	target command
	      is invoked.
	      zstyle ':completion:*:sudo::' environ \
		PATH="/sbin:/usr/sbin:$PATH" HOME="/root"

       expand This style is used when completing strings consisting of	multi-
	      ple parts, such as path names.

	      If one of	its values is the string `prefix', the partially typed
	      word from	the line will be expanded as far as possible  even  if
	      trailing parts cannot be completed.

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

       fake   This  style may be set for any completion	context.  It specifies
	      additional strings that will always be completed	in  that  con-
	      text.  The form of each string is	`value:description'; the colon
	      and description may be omitted, but any literal colons in	 value
	      must  be	quoted	with a backslash.  Any description provided is
	      shown alongside the value	in completion listings.

	      It is important to use a sufficiently restrictive	 context  when
	      specifying  fake	strings.   Note	that the styles	fake-files and
	      fake-parameters  provide	additional  features  when  completing
	      files or parameters.

	      This  works  identically	to  the	fake style except that the ig-
	      nored-patterns style is not applied to it.  This makes it	possi-
	      ble  to  override	a set of matches completely by setting the ig-
	      nored patterns to	`*'.

	      The following shows a way	of supplementing any  tag  with	 arbi-
	      trary  data,  but	 having	 it behave for display purposes	like a
	      separate tag.  In	this  example  we  use	the  features  of  the
	      tag-order	 style	to  divide  the	named-directories tag into two
	      when performing completion with the standard completer  complete
	      for  arguments  of cd.  The tag named-directories-normal behaves
	      as normal, but the tag named-directories-mine contains  a	 fixed
	      set  of  directories.   This  has	the effect of adding the match
	      group `extra directories'	with the given completions.

		     zstyle ':completion::complete:cd:*' tag-order \
		       'named-directories:-mine:extra\ directories
		       named-directories:-normal:named\	directories *'
		     zstyle ':completion::complete:cd:*:named-directories-mine'	\
		       fake-always mydir1 mydir2
		     zstyle ':completion::complete:cd:*:named-directories-mine'	\
		       ignored-patterns	'*'

	      This style is used when completing files and looked up without a
	      tag.   Its values	are of the form	`dir:names...'.	 This will add
	      the names	(strings separated by spaces) as possible matches when
	      completing  in  the  directory dir, even if no such files	really
	      exist.  The dir may be a pattern;	pattern	characters  or	colons
	      in  dir  should  be quoted with a	backslash to be	treated	liter-

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

	      The  pattern  form can be	used to	add a certain `magic' entry to
	      all directories on a particular file system.

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

	      This  style  controls whether files completed using the standard
	      builtin mechanism	are to be listed with a	long list  similar  to
	      ls  -l.	Note  that this	feature	uses the shell module zsh/stat
	      for file information; this loads the builtin stat	which will re-
	      place any	external stat executable.  To avoid this the following
	      code can be included in an initialization	file:

		     zmodload -i zsh/stat
		     disable stat

	      The style	may either be set to a `true' value (or	`all'),	or one
	      of  the  values `insert' or `list', indicating that files	are to
	      be listed	in long	format in all circumstances, or	when  attempt-
	      ing  to  insert  a file name, or when listing file names without
	      attempting to insert one.

	      More generally, the value	may be an array	of any	of  the	 above
	      values, optionally followed by =num.  If num is present it gives
	      the maximum number of matches for	which long listing style  will
	      be used.	For example,

		     zstyle ':completion:*' file-list list=20 insert=10

	      specifies	 that  long  format will be used when listing up to 20
	      files or inserting a file	with up	 to  10	 matches  (assuming  a
	      listing  is to be	shown at all, for example on an	ambiguous com-
	      pletion),	else short format will be used.

		     zstyle -e ':completion:*' file-list \
			    '((	${+NUMERIC} )) && reply=(true)'

	      specifies	that long format will be used any time a numeric argu-
	      ment is supplied,	else short format.

	      This  is used by the standard function for completing filenames,
	      _files.  If the style is unset up	to  three  tags	 are  offered,
	      `globbed-files',`directories'  and `all-files', depending	on the
	      types of files  expected by the caller of	_files.	 The first two
	      (`globbed-files'	and  `directories')  are  normally offered to-
	      gether to	make it	easier to complete files in sub-directories.

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

	      The  pattern  is	a pattern that is to be	used to	generate file-
	      names.  Any occurrence of	the sequence `%p' is replaced  by  any
	      pattern(s) passed	by the function	calling	_files.	 Colons	in the
	      pattern must be preceded by a backslash  to  make	 them  distin-
	      guishable	 from the colon	before the tag.	 If more than one pat-
	      tern is needed, the patterns can be given	inside	braces,	 sepa-
	      rated by commas.

	      The  tags	 of all	strings	in the value will be offered by	_files
	      and used when looking up other styles.  Any  tags	 in  the  same
	      word  will  be  offered at the same time and before later	words.
	      If no `:tag' is given the	`files'	tag will be used.

	      The tag may also be followed by an optional second colon	and  a
	      description, which will be used for the `%d' in the value	of the
	      format style (if that is set) instead of the default description
	      supplied	by  the	completion function.  If the description given
	      here contains itself a `%d', that	is replaced with the  descrip-
	      tion supplied by the completion function.

	      For example, to make the rm command first	complete only names of
	      object files and then the	names of all  files  if	 there	is  no
	      matching object file:

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

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

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

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

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

	      The  standard filename completion	function uses this style with-
	      out a tag	to determine  in  which	 order	the  names  should  be
	      listed;  menu completion will cycle through them in the same or-
	      der.  The	possible values	are: `size' to sort by the size	of the
	      file; `links' to sort by the number of links to the file;	`modi-
	      fication'	(or `time' or `date') to sort by the last modification
	      time;  `access' to sort by the last access time; and `inode' (or
	      `change')	to sort	by the last inode change time.	If  the	 style
	      is set to	any other value, or is unset, files will be sorted al-
	      phabetically by name.  If	the value  contains  the  string  `re-
	      verse',  sorting	is  done  in the opposite order.  If the value
	      contains the string `follow', timestamps are associated with the
	      targets  of symbolic links; the default is to use	the timestamps
	      of the links themselves.

       filter The ldap plugin of  email	 address  completion  (see  _email_ad-
	      dresses)	uses  this  style  to  specify the attributes to match
	      against when filtering entries.  So for example, if the style is
	      set  to  `sn', matching is done against surnames.	 Standard LDAP
	      filtering	is used	so normal completion matching is bypassed.  If
	      this style is not	set, the LDAP plugin is	skipped.  You may also
	      need to set the command style to specify how to connect to  your
	      LDAP server.

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

	      This style is tested for the default tag as well as for each tag
	      valid for	the current completion.	  Hence	 the  listing  can  be
	      forced only for certain types of match.

       format If  this is set for the descriptions tag,	its value is used as a
	      string to	display	above matches in completion  lists.   The  se-
	      quence  `%d'  in	this  string will be replaced with a short de-
	      scription	of what	these matches are.  This string	may also  con-
	      tain the following sequences to specify output attributes	as de-
	      scribed in the section EXPANSION OF  PROMPT  SEQUENCES  in  zsh-
	      misc(1): `%B', `%S', `%U', `%F', `%K' and	their lower case coun-
	      terparts,	as well	as `%{...%}'.  `%F', `%K' and  `%{...%}'  take
	      arguments	 in  the same form as prompt expansion.	 Note that the
	      sequence `%G' is not available; an argument to  `%{'  should  be
	      used instead.

	      The  style is tested with	each tag valid for the current comple-
	      tion before it is	tested for the descriptions tag.   Hence  dif-
	      ferent  format  strings  can  be	defined	for different types of

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

	      Some completion functions	display	 messages  that	 may  be  cus-
	      tomised  by  setting this	style for the messages tag.  Here, the
	      `%d' is replaced with a message given by	the  completion	 func-

	      Finally,	the  format string is looked up	with the warnings tag,
	      for use 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.  The  sequence	 `%D'  is  re-
	      placed with the same descriptions	separated by newlines.

	      It  is  possible to use printf-style field width specifiers with
	      `%d' and similar escape sequences.  This is handled by the zfor-
	      mat  builtin  command  from  the	zsh/zutil  module, see zshmod-

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

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

	      The completion system can	 group	different  types  of  matches,
	      which  appear in separate	lists.	This style can be used to give
	      the names	of groups for particular tags.	For example,  in  com-
	      mand  position  the completion system generates names of builtin
	      and external commands, names of aliases, shell functions and pa-
	      rameters	and  reserved  words as	possible completions.  To have
	      the external commands and	shell functions	listed separately:

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

	      As a consequence,	any match with the same	tag will be  displayed
	      in the same group.

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

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

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

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

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

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

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

       hidden If this is set to	`true',	matches	for the	given context will not
	      be listed, although any description for the matches set with the
	      format style will	be shown.  If it is set	to `all', not even the
	      description will be displayed.

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

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

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

	      This is tested for each tag valid	for  the  current  completion.
	      If  it  is  set to `true', none of the words that	are already on
	      the line will be considered as possible completions.  If	it  is
	      set  to `current', the word the cursor is	on will	not be consid-
	      ered as a	possible completion.   The  value  `current-shown'  is
	      similar but only applies if the list of completions is currently
	      shown on the screen.  Finally, if	the style is set  to  `other',
	      all  words  on  the  line	except for the current one will	be ex-
	      cluded from the possible completions.

	      The values `current' and `current-shown' are a bit like the  op-
	      posite  of  the  accept-exact  style:  only strings with missing
	      characters will be completed.

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

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

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

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

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

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

		     Ignore the	specified directories only when	names  of  di-
		     rectories	are  completed,	 not  when completing names of

	      Excluded values act in a similar fashion to values  of  the  ig-
	      nored-patterns  style,  so they can be restored to consideration
	      by the _ignored completer.

	      If set, the completion listing is	more verbose at	the cost of  a
	      probable	decrease  in completion	speed.	Completion performance
	      will suffer if this style	is set to `true'.

	      A	list of	patterns; any trial completion	matching  one  of  the
	      patterns will be excluded	from consideration.  The _ignored com-
	      pleter can appear	in the list of completers to restore  the  ig-
	      nored matches.  This is a	more configurable version of the shell
	      parameter	$fignore.

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

       insert This style is used  by  the  _all_matches	 completer  to	decide
	      whether  to  insert  the list of all matches unconditionally in-
	      stead of adding the list as another match.

	      When completing process IDs, for example	as  arguments  to  the
	      kill and wait builtins the name of a command may be converted to
	      the appropriate process ID.  A problem arises when  the  process
	      name  typed  is not unique.  By default (or if this style	is set
	      explicitly to `menu') the	name will be converted immediately  to
	      a	 set  of  possible IDs,	and menu completion will be started to
	      cycle through them.

	      If the value of the style	is `single', the shell will wait until
	      the user has typed enough	to make	the command unique before con-
	      verting the name to an ID; attempts at completion	will be	unsuc-
	      cessful  until  that  point.   If	the value is any other string,
	      menu completion will be started when the	string	typed  by  the
	      user is longer than the common prefix to the corresponding IDs.

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

	      The  value  may  also contain the	substrings `pending' or	`pend-
	      ing=val'.	 In this case, the typed character  will  be  inserted
	      instead  of  starting completion when there is unprocessed input
	      pending.	If a val is given, completion  will  not  be  done  if
	      there  are  at  least that many characters of unprocessed	input.
	      This is often useful when	pasting	characters  into  a  terminal.
	      Note  however,  that it relies on	the $PENDING special parameter
	      from the zsh/zle module being set	properly which is not  guaran-
	      teed on all platforms.

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

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

	      In  the  case of the _approximate	completer, the completer field
	      in the context will already have been set	to one of  correct-num
	      or  approximate-num, where num is	the number of errors that were

	      In the case of the _match	completer, the style may also  be  set
	      to  the  string `pattern'.  Then the pattern on the line is left
	      unchanged	if it does not match unambiguously.

	      If set to	true, this style enables the use of commands like sudo
	      or doas to gain extra privileges when retrieving information for
	      completion. This is only done when a command such	 as  sudo  ap-
	      pears  on	the command-line. To force the use of, e.g. sudo or to
	      override any prefix that might be	added due to  gain-privileges,
	      the  command  style  can be used with a value that begins	with a

	      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.  Hence,  for	 example,  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 forces the prefix to be expanded unconditionally.

	      The  behaviour  of _expand when this style is `true' is to cause
	      _expand to give up when a	single	expansion  with	 the  restored
	      prefix  is  the  same  as	the original; hence any	remaining com-
	      pleters may be called.

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

	      This  style  should  contain  a list of files to search for host
	      names and	(if the	use-ip style is	set) IP	addresses in a	format
	      compatible  with	ssh  known_hosts files.	 If it is not set, the
	      files /etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts are	used.

       list   This style is used by the	_history_complete_word	bindable  com-
	      mand.  If	it is set to `true' it has no effect.  If it is	set to
	      `false' matches will not be listed.  This	overrides the  setting
	      of  the  options	controlling  listing  behaviour, in particular
	      AUTO_LIST.  The context  always  starts  with  `:completion:his-

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

	      If  this	style  is  set for the default tag, the	strings	in the
	      value are	taken as specifications	that are  to  be  used	every-
	      where.  If it is set for other tags, the specifications are used
	      only for matches of the type described by	the tag.  For this  to
	      work best, the group-name	style must be set to an	empty string.

	      In addition to setting styles for	specific tags, it is also pos-
	      sible to use group names specified explicitly by the  group-name
	      tag together with	the `(group)' syntax allowed by	the ZLS_COLORS
	      and ZLS_COLOURS parameters and simply using the default tag.

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

		     zstyle ':completion:*:default' list-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.

	      This is used by file completion.	If set,	directories to be com-
	      pleted are listed	separately  from  and  before  completion  for
	      other  files,  regardless	of tag ordering.  In addition, the tag
	      other-files is used in place  of	all-files  for	the  remaining
	      files,  to  indicate that	no directories are presented with that

	      If this style is `true' (the  default),  the  completion	system
	      will  try	 to  make  certain completion listings more compact by
	      grouping matches.	 For example, options for commands  that  have
	      the  same	 description  (shown  when the verbose style is	set to
	      `true') will appear as a single entry.  However, menu  selection
	      can be used to cycle through all the matches.

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

	      If this style is set for the default tag,	completion lists  that
	      don't  fit on the	screen can be scrolled (see the	description of
	      the zsh/complist module in zshmodules(1)).  The  value,  if  not
	      the  empty  string,  will	be displayed after every screenful and
	      the shell	will prompt for	a key press; if	the style  is  set  to
	      the empty	string,	a default prompt will be used.

	      The  value may contain the escape	sequences: `%l'	or `%L', which
	      will be replaced by the number of	the last  line	displayed  and
	      the total	number of lines; `%m' or `%M', the number of the  last
	      match shown and the total	number of matches; and `%p' and	 `%P',
	      `Top'  when  at  the beginning of	the list, `Bottom' when	at the
	      end and the position shown as a percentage of the	 total	length
	      otherwise.  In each case the form	with the uppercase letter will
	      be replaced by a string of fixed width,  padded  to  the	 right
	      with  spaces,  while  the	 lowercase  form will be replaced by a
	      variable width string.  As in other prompt strings,  the	escape
	      sequences	 `%S',	`%s',  `%B', `%b', `%U', `%u' for entering and
	      leaving the display modes	 standout,  bold  and  underline,  and
	      `%F',  `%f',  `%K',  `%k'	for changing the foreground background
	      colour, are also available, as is	the form `%{...%}' for enclos-
	      ing escape sequences which display with zero (or,	with a numeric
	      argument,	some other) width.

	      After deleting this prompt the variable LISTPROMPT should	be un-
	      set for the removal to take effect.

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

	      This style is used by the	function that completes	filenames.  If
	      it is `true', and	completion is attempted	on a string containing
	      multiple partially typed pathname	components, all	ambiguous com-
	      ponents will be shown.  Otherwise, completion stops at the first
	      ambiguous	component.

	      The  value  of this style	is used	in completion listing to sepa-
	      rate the string to complete from	a  description	when  possible
	      (e.g.  when  completing  options).  It defaults to `--' (two hy-

       local  This is for use with functions that complete URLs	for which  the
	      corresponding files are available	directly from the 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:

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

	      Completion after `http://toast/stuff/' will look	for  files  in
	      the  directory  /var/http/public/toast/stuff,   while completion
	      after `http://toast/~yousir/' will look for files	in the	direc-
	      tory ~yousir/public_html.

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

	      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  `*'  in-
	      serted.	If  it	is  unset or set to the	empty string, matching
	      will only	be performed with the `*' inserted.

	      This style is tested separately for each tag valid in  the  cur-
	      rent  context.   Its value is placed before any match specifica-
	      tions given by the matcher-list style so can override  them  via
	      the use of an x: specification.  The value should	be in the form
	      described	in the section `Completion Matching Control'  in  zsh-
	      compwid(1).   For	 examples  of this, see	the description	of the
	      tag-order	style.

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

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

	      By  default  each	 specification replaces	the previous one; how-
	      ever, if a specification is prefixed with	+, it is added to  the
	      existing list.  Hence it is possible to create increasingly gen-
	      eral specifications without repetition:

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

	      It is possible to	create match specifications valid for particu-
	      lar  completers  by  using the third field of the	context.  This
	      applies  only   to   completers	that   override	  the	global
	      matcher-list, which as of	this writing includes only _prefix and
	      _ignored.	 For example, to  use  the  completers	_complete  and
	      _prefix  but  allow  case-insensitive completion only with _com-

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

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

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

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

	      If  there	 is  no	current	matcher	or it is empty,	and the	option
	      NO_CASE_GLOB is in effect, the matching for files	 is  performed
	      case-insensitively  in  any case.	 However, any matcher must ex-
	      plicitly specify case-insensitive	matching if that is required.

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

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

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

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

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

	      If one of	the values is explicitly set to	`false', menu  comple-
	      tion will	be explicitly turned off, overriding the MENU_COMPLETE
	      option and other settings.

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

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

	      The value	of this	widget also controls menu selection, as	imple-
	      mented by	the zsh/complist module.  The following	values may ap-
	      pear either alongside or instead of the values above.

	      If the value contains the	string `select', menu  selection  will
	      be started unconditionally.

	      In the form `select=num',	menu selection will only be started if
	      there are	at least num matches.  If the values for more than one
	      tag provide a number, the	smallest number	is taken.

	      Menu  selection can be turned off	explicitly by defining a value
	      containing the string`no-select'.

	      It is also possible to start menu	selection only if the list  of
	      matches  does  not  fit  on  the	screen by using	the value `se-
	      lect=long'.  To start menu selection even	if the current	widget
	      only performs listing, use the value `select=long-list'.

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

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

       muttrc If  set,	gives the location of the mutt configuration file.  It
	      defaults to `~/.muttrc'.

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

	      This is used by the _oldlist completer.  If it is	 set  to  `al-
	      ways',  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  un-
	      set,  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 al-
	      ready generated.

	      As another example consider the _match completer:	with  the  in-
	      sert-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.

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

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

	      This is used by the _oldlist completer.  It  controls  how  menu
	      completion  behaves  when	a completion has already been inserted
	      and the user types a standard completion key such	as  TAB.   The
	      default  behaviour  of  _oldlist	is that	menu completion	always
	      continues	with the existing list of completions.	If this	 style
	      is  set  to `false', however, a new 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

	      This is used by the _approximate and _correct completers to  de-
	      cide  if	the original string should be added as a possible com-
	      pletion.	Normally, this is done only if there are at least  two
	      possible	corrections, but if this style is set to `true', it is
	      always added.  Note that the style will  be  examined  with  the
	      completer	 field	in  the	context	name set to correct-num	or ap-
	      proximate-num, where num is the number of	errors that  were  ac-

	      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.

	      This is used by filename completion.  By default,	filename  com-
	      pletion  examines	 all  components of a path to see if there are
	      completions of that component.  For example, /u/b/z can be  com-
	      pleted  to  /usr/bin/zsh.	  Explicitly  setting  this  style  to
	      `false' inhibits this behaviour for path components up to	the  /
	      before  the  cursor;  this  overrides  the setting of accept-ex-

	      Even with	the style set to `false', it is	still possible to com-
	      plete  multiple paths by setting the option COMPLETE_IN_WORD and
	      moving the cursor	back to	the first component in the path	to  be
	      completed.  For example, /u/b/z can be completed to /usr/bin/zsh
	      if the cursor is after the /u.

	      If set, specifies	the directory containing PINE  mailbox	files.
	      There  is	no default, since recursively searching	this directory
	      is inconvenient for anyone who doesn't use PINE.

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

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

	      The default value	for this style is `false'.

	      This style is also relevant for matches with  a  common  prefix.
	      If  it  is set to	`true' this common prefix must be typed	by the
	      user to generate the matches.

	      The style	is applicable to the  options,	signals,  jobs,	 func-
	      tions, and parameters completion tags.

	      For  command  options,  this means that the initial `-', `+', or
	      `--' must	be typed explicitly before option names	will  be  com-

	      For signals, an initial `-' is required before signal names will
	      be completed.

	      For jobs,	an initial `%' is required before job  names  will  be

	      For  function  and parameter names, an initial `_' or `.'	is re-
	      quired before function or	parameter names	 starting  with	 those
	      characters will be completed.

	      The default value	for this style is `false' for function and pa-
	      rameter completions, and	`true' otherwise.

	      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  ex-
	      ample,  on some Unices an	initial	`//' (double slash) has	a spe-
	      cial meaning; setting this style to the string  `//'  will  pre-
	      serve it.	 As another example, setting this style	to `?:/' under
	      Cygwin would allow completion after `a:/...' and so on.

       range  This is used by the _history  completer  and  the	 _history_com-
	      plete_word bindable command to decide which words	should be com-

	      If it is a single	number,	only the last N	words from the history
	      will be completed.

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

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

	      If  this	style  is set, its value is an array of	patterns to be
	      tested against `$PWD/': note the trailing	 slash,	 which	allows
	      directories  in the pattern to be	delimited unambiguously	by in-
	      cluding slashes on both sides.  If an ordinary  file  completion
	      fails  and  the word on the command line does not	yet have a di-
	      rectory part to its name,	the style is retrieved using the  same
	      tag  as  for  the	 completion  just attempted, then the elements
	      tested against $PWD/ in turn.  If	one matches,  then  the	 shell
	      reattempts completion by prepending the word on the command line
	      with each	directory in the expansion of **/*(/) in turn.	 Typi-
	      cally the	elements of the	style will be set to restrict the num-
	      ber of directories beneath the current one to a manageable  num-
	      ber, for example `*/.git/*'.

	      For example,

		     zstyle ':completion:*' recursive-files '*/zsh/*'

	      If  the  current	directory is /home/pws/zsh/Src,	then zle_trTAB
	      can be completed to Zle/zle_tricky.c.

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

       rehash If  this	is set when completing external	commands, the internal
	      list (hash) of commands will be updated for each search by issu-
	      ing the rehash command.  There is	a speed	penalty	for this which
	      is only likely to	be noticeable when  directories	 in  the  path
	      have slow	file access.

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

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

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

	      If this is set for the default tag, its value will be  displayed
	      during  menu  selection (see the menu style above) when the com-
	      pletion list does	not fit	on the screen as a  whole.   The  same
	      escapes as for the list-prompt style are understood, except that
	      the numbers refer	to the match or	line the mark is  on.	A  de-
	      fault prompt is used when	the value is the empty string.

	      This  style  is  tested for the default tag and determines how a
	      completion list is scrolled during a  menu  selection  (see  the
	      menu  style  above) when the completion list does	not fit	on the
	      screen as	a whole.  If the value is  `0'	(zero),	 the  list  is
	      scrolled	by  half-screenfuls;  if it is a positive integer, the
	      list is scrolled by the given number of lines; if	it is a	 nega-
	      tive number, the list is scrolled	by a screenful minus the abso-
	      lute value of the	given number of	 lines.	  The  default	is  to
	      scroll by	single lines.

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

	      If  the zsh/complist module is loaded, this style	can be used to
	      highlight	the first ambiguous character in completion lists. The
	      value  is	 either	 a color indication such as those supported by
	      the list-colors style or,	with a value of	`true',	a  default  of
	      underlining is selected. The highlighting	is only	applied	if the
	      completion display strings correspond to the actual matches.

	      Tested whenever a	new completer is tried.	 If it is `true',  the
	      completion system	outputs	a progress message in the listing area
	      showing what completer is	being  tried.	The  message  will  be
	      overwritten  by any output when completions are found and	is re-
	      moved after completion is	finished.

	      This is used by the _ignored completer when there	 is  only  one
	      match.   If  its	value is `show', the single match will be dis-
	      played but not inserted.	If the value is	`menu',	then the  sin-
	      gle  match and the original string are both added	as matches and
	      menu completion is started, making it easy to select  either  of

       sort   Many  completion	widgets	 call _description at some point which
	      decides whether the matches are added sorted or unsorted	(often
	      indirectly  via  _wanted	or _requested).	 This style can	be set
	      explicitly to one	of the usual `true' or `false'	values	as  an
	      override.	 If it is not set for the context, the standard	behav-
	      iour of the calling widget is used.

	      The style	is tested first	against	the full context including the
	      tag,  and	 if  that fails	to produce a value against the context
	      without the tag.

	      If the calling widget explicitly requests	unsorted matches, this
	      is  usually honoured.  However, the default (unsorted) behaviour
	      of completion for	the command history may	be overridden by  set-
	      ting the style to	`true'.

	      In the _expand completer,	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 but not in the string  containing	 all  possible	expan-

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

	      The following example sets special-dirs to `..' when the current
	      prefix is	empty, is a single `.',	or consists only of a path be-
	      ginning with `../'.  Otherwise the value is `false'.

		     zstyle -e ':completion:*' special-dirs \
			'[[ $PREFIX = (../)#(|.|..) ]] && reply=(..)'

	      If set to	`true',	sequences of slashes in	 filename  paths  (for
	      example  in `foo//bar') will be treated as a single slash.  This
	      is the usual behaviour of	UNIX paths.  However, by  default  the
	      file  completion function	behaves	as if there were a `*' between
	      the slashes.

       stop   If set to	`true',	the  _history_complete_word  bindable  command
	      will  stop  once	when reaching the beginning or end of the his-
	      tory.  Invoking _history_complete_word will then wrap around  to
	      the  opposite  end  of  the  history.   If  this style is	set to
	      `false' (the default), _history_complete_word will loop  immedi-
	      ately as in a menu completion.

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

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

	      The default for this style is `false'.

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

	      The default is `true'.

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

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

	      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 first offers ex-
	      ternal commands and shell	functions.   Remaining	tags  will  be
	      tried if no completions are found.

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

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

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

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

		     If	 the  label starts with	a hyphen, the tag is prepended
		     to	the label to form the name used	for lookup.  This  can
		     be	 used  to make the completion system try a certain tag
		     more than once, supplying different  style	 settings  for
		     each attempt; see below for an example.

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

	      In any of	the forms above	the tag	may be a  pattern  or  several
	      patterns	in the form `{pat1,pat2...}'.  In this case all	match-
	      ing tags will be used except for any  given  explicitly  in  the
	      same string.

	      One use of these features	is to try one tag more than once, set-
	      ting other styles	differently on each attempt, but still to  use
	      all the other tags without having	to repeat them all.  For exam-
	      ple, to make completion of function names	 in  command  position
	      ignore  all the completion functions starting with an underscore
	      the first	time completion	is tried:

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

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

	      The matches for one tag can be split into	different groups.  For

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

	      With the group-names style set, options beginning	with `--', op-
	      tions beginning with a single `-'	or `+' but containing multiple
	      characters, and single-letter options will be displayed in sepa-
	      rate groups with different descriptions.

	      Another use of patterns is to try	multiple match	specifications
	      one after	another.  The matcher-list style offers	something sim-
	      ilar, but	it is tested very early	in the completion  system  and
	      hence  can't  be	set  for single	commands nor for more specific
	      contexts.	 Here is how to	 try  normal  completion  without  any
	      match specification and, if that generates no matches, try again
	      with case-insensitive matching, restricting the effect to	 argu-
	      ments of the command foo:

		     zstyle ':completion:*:*:foo:*:*' tag-order	'*' '*:-case'
		     zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}'

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

	      It  is  possible to use the -e option of the zstyle builtin com-
	      mand to specify conditions for the use of	particular tags.   For

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

	      Completion  in  command  position	 will be attempted only	if the
	      string typed so far is not empty.	 This is tested	using the PRE-
	      FIX  special  parameter; see zshcompwid for a description	of pa-
	      rameters which are special inside	completion  widgets.   Setting
	      reply to an empty	array provides the default behaviour of	trying
	      all tags at once;	setting	it to an array containing only	a  hy-
	      phen disables the	use of all tags	and hence of all completions.

	      If  no  tag-order	 style	has  been  defined  for	a context, the
	      strings `(|*-)argument-*	(|*-)option-*  values'	and  `options'
	      plus all tags offered by the completion function will be used to
	      provide  a  sensible  default  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 urls tag by functions  completing

	      If  the  value  consists of more than one	string,	or if the only
	      string does not name a file or directory,	the strings  are  used
	      as the URLs to complete.

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

	      Finally,	if the only string in the value	names a	directory, the
	      directory	hierarchy rooted at this directory gives  the  comple-
	      tions.   The  top	 level	directory  should  be  the file	access
	      method, such as `http', `ftp', `bookmark'	and so	on.   In  many
	      cases the	next level of directories will be a filename.  The di-
	      rectory hierarchy	can descend as deep as necessary.

	      For example,

		     zstyle ':completion:*' urls ~/.urls
		     mkdir -p ~/.urls/ftp/

	      allows  completion  of   all   the   components	of   the   URL after suitable commands such as `netscape'
	      or `lynx'.  Note,	however, that access  methods  and  files  are
	      completed	 separately, so	if the hosts style is set hosts	can be
	      completed	without	reference to the urls style.

	      See the description in the function _urls	itself for more	infor-
	      mation (e.g. `more $^fpath/_urls(N)').

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

	      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 un-
	      set, this	is done	only if	the zsh/compctl	module is loaded.  The
	      string may also contain the substring `first' to use completions
	      defined with `compctl -T', and the substring  `default'  to  use
	      the completion defined with `compctl -D'.

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

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

       use-ip By default, the function _hosts that completes host names	strips
	      IP  addresses  from entries read from host databases such	as NIS
	      and ssh files.  If this style is `true',	the  corresponding  IP
	      addresses	 can  be  completed as well.  This style is not	use in
	      any context where	the hosts style	is set;	note also it  must  be
	      set  before  the cache of	host names is generated	(typically the
	      first completion attempt).

       users  This may be set to a list	of usernames to	be completed.	If  it
	      is  not set all usernames	will be	completed.  Note that if it is
	      set only that list of users will be completed; this  is  because
	      on some systems querying all users can take a prohibitive	amount
	      of time.

	      The values of this style should be of the	 form  `user@host'  or
	      `user:host'.  It	is  used for commands that need	pairs of user-
	      and hostnames.  These commands will complete usernames from this
	      style  (only),  and will restrict	subsequent hostname completion
	      to hosts paired with that	user in	 one  of  the  values  of  the

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

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

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

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

       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 status of the  completer	 func-
       tions  to  decide  if other completers should be	called.	 If the	return
       status 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,
       although	users may write	their own.  Note that in contexts the  leading
       underscore  is  stripped,  for example basic completion is performed in
       the context `:completion::complete:...'.

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

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

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

	      Note  that  this does not	generate completions by	itself:	 first
	      use any of the standard ways of generating  a  list  of  comple-
	      tions, then use ^Xa to show all matches.	It is possible instead
	      to add a standard	completer to the list  and  request  that  the
	      list of all matches should be directly inserted:

		     zstyle ':completion:all-matches::::' completer \
			    _all_matches _complete
		     zstyle ':completion:all-matches:*'	insert true

	      In this case the old-matches style should	not be set.

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

		     zstyle ':completion:*' completer _complete	_approximate

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

	      This  completer uses the tags corrections	and original when gen-
	      erating the possible corrections and the original	 string.   The
	      format style for the former may contain the additional sequences
	      `%e' and `%o' which will be replaced by the number of errors ac-
	      cepted  to generate the corrections and the original string, re-

	      The completer progressively increases the	number of  errors  al-
	      lowed  up	 to the	limit by the max-errors	style, hence if	a com-
	      pletion is found with one	error, no completions with two	errors
	      will be shown, and so on.	 It modifies the completer name	in the
	      context to indicate the number of	errors	being  tried:  on  the
	      first  try  the completer	field contains `approximate-1',	on the
	      second try `approximate-2', and so on.

	      When _approximate	is called from another function, the number of
	      errors to	accept may be passed with the -a option.  The argument
	      is in the	same format  as	 the  max-errors  style,  all  in  one

	      Note  that  this completer (and the _correct completer mentioned
	      below) can be quite expensive to call, especially	when  a	 large
	      number  of  errors are allowed.  One way to avoid	this is	to set
	      up the completer style using the -e option  to  zstyle  so  that
	      some  completers	are  only  used	when completion	is attempted a
	      second time on the same string, e.g.:

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

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

       _canonical_paths	[ -A var ] [ -N	] [ -MJV12nfX ]	tag descr [ paths  ...
	      This  completion	function  completes all	paths given to it, and
	      also tries to offer completions which point to the same file  as
	      one  of  the paths given (relative path when an absolute path is
	      given, and vice versa; when ..'s are present in the word	to  be
	      completed; and some paths	got from symlinks).

	      -A, if specified,	takes the paths	from the array variable	speci-
	      fied. Paths can also be specified	on the command line  as	 shown
	      above.   -N,  if	specified,  prevents  canonicalizing the paths
	      given before using them for completion, in case they are already
	      so.  The	options	 -M,  -J, -V, -1, -2, -n, -F, -X are passed to

	      See _description for a description of tag	and descr.

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

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

	      Before  trying  to find a	function for a specific	context, _com-
	      plete checks if the  parameter  `compcontext'  is	 set.  Setting
	      `compcontext'  allows  the  usual	 completion  dispatching to be
	      overridden which is useful in places such	 as  a	function  that
	      uses vared for input. If it is set to an array, the elements are
	      taken to be the possible matches which will be  completed	 using
	      the tag `values' and the description `value'. If it is set to an
	      associative array, the keys are used as the possible completions
	      and  the	values (if non-empty) are used as descriptions for the
	      matches.	If `compcontext' is set	to a string containing colons,
	      it  should  be of	the form `tag:descr:action'.  In this case the
	      tag and descr give the tag and description to use	and the	action
	      indicates	 what should be	completed in one of the	forms accepted
	      by the _arguments	utility	function described below.

	      Finally, if `compcontext'	is set to a string without colons, the
	      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).  This	is not
	      used  by the completion system itself but	is nonetheless handled
	      when explicitly called.

	      Generate corrections, but	not completions, for the current word;
	      this is similar to _approximate but will not allow any number of
	      extra characters at the cursor as	that completer does.  The  ef-
	      fect is similar to spell-checking.  It is	based on _approximate,
	      but the completer	field in the context name is correct.

	      For example, with:

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

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

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

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

	      This  completer function does not	really perform completion, but
	      instead checks if	the word on the	command	line is	 eligible  for
	      expansion	 and,  if  it is, gives	detailed control over how this
	      expansion	is done.  For this to happen,  the  completion	system
	      needs  to	 be invoked with complete-word,	not expand-or-complete
	      (the default binding for TAB), as	otherwise the string  will  be
	      expanded by the shell's internal mechanism before	the completion
	      system is	started.  Note also this completer  should  be	called
	      before the _complete completer function.

	      The  tags	used when generating expansions	are all-expansions for
	      the string containing all	possible expansions,  expansions  when
	      adding  the  possible  expansions	as single matches and original
	      when adding the original string from the	line.	The  order  in
	      which  these strings are generated, if at	all, can be controlled
	      by the group-order and tag-order styles, as usual.

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

	      The kind of expansion to be tried	is controlled by  the  substi-
	      tute, glob and subst-globs-only styles.

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

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

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

	      If  the  cursor follows the string `*.', filename	extensions are
	      completed. The extensions	are taken from files in	current	direc-
	      tory  or	a  directory specified at the beginning	of the current
	      word. For	exact matches, completion  continues  to  allow	 other
	      completers  such	as _expand to expand the pattern. The standard
	      add-space	and prefix-hidden styles are observed.

	      Completes	current	directories of other zsh  processes  belonging
	      to the current user.

	      This  is intended	to be used via _generic, bound to a custom key
	      combination. Note	that pattern matching is enabled  so  matching
	      is performed similar to how it works with	the _match completer.

	      Complete	words  from  the  shell's command  history.  This com-
	      pleter can be controlled by the remove-all-dups, and sort	styles
	      as for the _history_complete_word	bindable command, see the sec-
	      tion `Bindable Commands' below and the section `Completion  Sys-
	      tem Configuration' above.

	      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
	      invoked is determined in the same	way as for  the	 _prefix  com-
	      pleter.  The single-ignored style	is also	available as described

       _list  This completer allows the	insertion of matches to	be delayed un-
	      til  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'

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

	      Normally completion will be performed by taking the pattern from
	      the  line,  inserting a `*' at the cursor	position and comparing
	      the resulting pattern with the possible  completions  generated.
	      This  can	 be  modified  with the	match-original style described

	      The generated matches will be offered in a menu  completion  un-
	      less  the	insert-unambiguous style is set	to `true'; see the de-
	      scription	above for other	options	for this style.

	      Note that	matcher	specifications defined globally	or used	by the
	      completion  functions (the styles	matcher-list and matcher) will
	      not be used.

       _menu  This completer was written as simple example  function  to  show
	      how  menu	 completion  can be enabled in shell code. However, it
	      has the notable effect of	disabling menu selection which can  be
	      useful  with  _generic  based  widgets. It should	be used	as the
	      first completer in the list.  Note that this is  independent  of
	      the  setting  of the MENU_COMPLETE option	and does not work with
	      the other	menu completion	widgets	such as	reverse-menu-complete,
	      or accept-and-menu-complete.

	      This  completer controls how the standard	completion widgets be-
	      have 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.

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

	      The completer style is used to decide which other	completers are
	      to be called to generate matches.	 If this style is  unset,  the
	      list  of	completers  set	for the	current	context	is used	-- ex-
	      cept, of course, the _prefix completer itself.  Furthermore,  if
	      this  completer appears more than	once in	the list of completers
	      only those completers not	already	tried by the  last  invocation
	      of _prefix will be called.

	      For example, consider this global	completer style:

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

	      Here, the	_prefix	completer tries	normal completion but ignoring
	      the suffix.  If that doesn't generate any	matches,  and  neither
	      does  the	 call to the _correct completer	after it, _prefix will
	      be called	a second time and, now only trying correction with the
	      suffix  ignored.	On the second invocation the completer part of
	      the context appears as `foo'.

	      To use _prefix as	the last resort	and try	only normal completion
	      when it is invoked:

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

	      The  add-space  style is also respected.	If it is set to	`true'
	      then _prefix will	insert a space between the  matches  generated
	      (if any) and the suffix.

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

	      This completer behaves similarly to the  _expand	completer  but
	      instead  performs	 expansions  defined  by  users.   The	styles
	      add-space	and sort styles	specific to the	_expand	completer  are
	      usable  with  _user_expand  in  addition to other	styles handled
	      more generally by	the completion system.	The tag	all-expansions
	      is also available.

	      The  expansion  depends on the array style user-expand being de-
	      fined for	the current context; remember  that  the  context  for
	      completers  is less specific than	that for contextual completion
	      as the full context has not yet been  determined.	  Elements  of
	      the array	may have one of	the following forms:


		     hash  is  the name	of an associative array.  Note this is
		     not a full	parameter expression,  merely  a  $,  suitably
		     quoted  to	 prevent  immediate expansion, followed	by the
		     name of an	associative array.   If	 the  trial  expansion
		     word  matches  a  key in hash, the	resulting expansion is
		     the corresponding value.

		     _func is the name of a shell function whose name must be-
		     gin with _	but is not otherwise special to	the completion
		     system.  The function is called with the trial word as an
		     argument.	 If  the  word is to be	expanded, the function
		     should set	the array reply	to a list of expansions.   Op-
		     tionally, it can set REPLY	to a word that will be used as
		     a description for the set of expansions.  The return sta-
		     tus of the	function is irrelevant.
       In  addition  to	 the context-dependent completions provided, which are
       expected	to work	in an intuitively obvious way, there are a few widgets
       implementing  special  behaviour	which can be bound separately to keys.
       The following is	a list of these	and their default bindings.

	      This function is used by two  widgets,  _bash_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

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

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

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

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

	      When used	as a bindable command there is one additional  feature
	      that  can	 be  selected by setting the complete style to `true'.
	      In this case, if the word	is not the  name  of  an  alias,  _ex-
	      pand_alias tries to complete the word to a full alias name with-
	      out expanding it.	 It leaves the cursor directly after the  com-
	      pleted 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.  Be-
	      fore calling it, the function field of the  context  is  set  to

	      This  function  is  not defined as a widget and not bound	by de-
	      fault.  However, it can be used to define	a widget and will then
	      store  the  name of the widget in	the function field of the con-
	      text and call the	completion system.  This allows	custom comple-
	      tion  widgets with their own set of style	settings to be defined
	      easily.  For example, to define a	widget	that  performs	normal
	      completion and starts menu selection:

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

	      Note  in	particular that	the completer style may	be set for the
	      context in order to change the set of functions used to generate
	      possible	matches.   If _generic is called with arguments, those
	      are passed through to _main_complete as the list	of  completers
	      in place of those	defined	by the completer style.

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

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

       _next_tags (^Xn)
	      This command alters the set of matches used to that for the next
	      tag, or set of tags, either as given by the tag-order  style  or
	      as  set  by default; these matches would otherwise not be	avail-
	      able.  Successive	invocations of the command cycle  through  all
	      possible sets of tags.

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

	      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  ac-
	      cordance 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-

       _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 de-
	      pends on the information available from the completion functions
	      called, which in turn is determined by the user's	own styles and
	      other settings.

	      Unlike  other  commands  listed  here, this must be created as a
	      normal ZLE widget	rather than a completion widget	(i.e. with zle
	      -N).   It	is used	for generating help with a widget bound	to the
	      _generic widget that is described	above.

	      If this widget is	created	using the name of the function,	as  it
	      is  by  default, then when executed it will read a key sequence.
	      This is expected to be bound to a	call to	a completion  function
	      that  uses  the  _generic	widget.	 That widget will be executed,
	      and information provided in  the	same  format  that  the	 _com-
	      plete_help widget	displays for contextual	completion.

	      If  the  widget's	name contains debug, for example if it is cre-
	      ated as `zle -N _complete_debug_generic _complete_help_generic',
	      it  will	read and execute the keystring for a generic widget as
	      before, but then generate	debugging information as done by _com-
	      plete_debug for contextual completion.

	      If  the  widget's	 name  contains	 noread,  it  will  not	read a
	      keystring	but instead arrange that the next  use	of  a  generic
	      widget  run  in the same shell will have the effect as described

	      The   widget   works   by	  setting    the    shell    parameter
	      ZSH_TRACE_GENERIC_WIDGET	which  is read by _generic.  Unsetting
	      the parameter cancels any	pending	effect of the noread form.

	      For example, after executing the following:

		     zle -N _complete_debug_generic _complete_help_generic
		     bindkey '^x:' _complete_debug_generic

	      typing `C-x :' followed by the key sequence for a	generic	widget
	      will cause trace output for that widget to be saved to a file.

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

       Descriptions follow for utility functions that may be useful when writ-
       ing completion functions.  If functions are  installed  in  subdirecto-
       ries,  most of these reside in the Base subdirectory.  Like the example
       functions for commands in the distribution, the utility functions  gen-
       erating	matches	 all follow the	convention of returning	status zero if
       they generated completions and  non-zero	 if  no	 matching  completions
       could be	added.

	      This function completes external commands	as absolute paths (un-
	      like _command_names -e which  completes  their  basenames).   It
	      takes no arguments.

       _all_labels [ -x	] [ -12VJ ] tag	name descr [ command arg ... ]
	      This  is	a convenient interface to the _next_label function be-
	      low, implementing	the loop shown	in  the	 _next_label  example.
	      The  command  and	 its  arguments	 are  called  to  generate the
	      matches.	The options stored in the parameter name will automat-
	      ically  be  inserted  into the args passed to the	command.  Nor-
	      mally, they are put directly after the command, but  if  one  of
	      the  args	 is a single hyphen, they are inserted directly	before
	      that.  If	the hyphen is the last argument, it  will  be  removed
	      from  the	 argument list before the command is called.  This al-
	      lows _all_labels to be  used  in	almost	all  cases  where  the
	      matches can be generated by a single call	to the compadd builtin
	      command or by a call to one of the utility functions.

	      For example:

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

	      Will complete the	strings	from the matches parameter, using com-
	      padd  with  additional  options  which will take precedence over
	      those generated by _all_labels.

       _alternative [ -O name ]	[ -C name ] spec ...
	      This function is useful in simple	cases where multiple tags  are
	      available.   Essentially	it  implements a loop like the one de-
	      scribed for the _tags function below.

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

	      For example, the action may be a simple function call:

		     _alternative \
			 'users:user:_users' \

	      offers usernames and hostnames as	possible matches, generated by
	      the _users and _hosts functions respectively.

	      Like _arguments, this function uses _all_labels to  execute  the
	      actions,	which  will  loop over all sets	of tags.  Special han-
	      dling is only required if	there is an additional valid tag,  for
	      example inside a function	called from _alternative.

	      The  option  `-O	name' is used in the same way as by the	_argu-
	      ments function.  In other	words, the elements of the name	 array
	      will be passed to	compadd	when executing an action.

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

       _arguments [ -nswWCRS ] [ -A pat	] [ -O name ] [	-M matchspec ]
		  [ : ]	spec ...
       _arguments [ opt	... ] -- [ -i pats ] [ -s pair ] [ helpspec ...	]
	      This function can	be used	to give	a complete  specification  for
	      completion  for  a  command whose	arguments follow standard UNIX
	      option and argument conventions.

	      Options overview

	      Options to _arguments itself must	be in separate words, i.e.  -s
	      -w,  not	-sw.   The options are followed	by specs that describe
	      options and arguments of the analyzed command.  specs  that  de-
	      scribe  option flags must	precede	specs that describe non-option
	      ("positional" or "normal") arguments of the analyzed  line.   To
	      avoid  ambiguity,	 all options to	_arguments itself may be sepa-
	      rated from the spec forms	by a single colon.

	      The `--' form is used to intuit spec forms from the help	output
	      of the command being analyzed, and is described in detail	below.
	      The opts for the `--' form are otherwise the same	options	as the
	      first  form.  Note that `-s' following `--' has a	distinct mean-
	      ing from `-s' preceding `--', and	both may appear.

	      The option switches -s, -S, -A, -w, and -W affect	how _arguments
	      parses  the analyzed command line's options.  These switches are
	      useful for commands with standard	argument parsing.

	      The options of _arguments	have the following meanings:

	      -n     With this option, _arguments sets the  parameter  NORMARG
		     to	 the  position	of  the	 first	normal argument	in the
		     $words array, i.e.	the position after the end of the  op-
		     tions.  If	that argument has not been reached, NORMARG is
		     set to -1.	 The caller should declare  `integer  NORMARG'
		     if	 the  -n  option is passed; otherwise the parameter is
		     not used.

	      -s     Enable option stacking for	single-letter options, whereby
		     multiple  single-letter  options  may  be combined	into a
		     single word.  For example,	the two	options	`-x' and  `-y'
		     may  be  combined	into a single word `-xy'.  By default,
		     every word	corresponds to a single	option name (`-xy'  is
		     a single option named `xy').

		     Options  beginning	 with a	single hyphen or plus sign are
		     eligible for stacking; words beginning with  two  hyphens
		     are not.

		     Note  that	 -s after -- has a different meaning, which is
		     documented	in the segment entitled	`Deriving  spec	 forms
		     from the help output'.

	      -w     In	combination with -s, allow option stacking even	if one
		     or	more of	the options take arguments.  For  example,  if
		     -x	 takes an argument, with no -s,	`-xy' is considered as
		     a single (unhandled) option; with -s, -xy	is  an	option
		     with  the	argument  `y'; with both -s and	-w, -xy	is the
		     option -x and the option -y with arguments	to -x (and  to
		     -y,  if  it  takes	arguments) still to come in subsequent

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

	      -C     Modify the	curcontext parameter for an action of the form
		     `->state'.	 This is discussed in detail below.

	      -R     Return status 300 instead of zero when a $state is	to  be
		     handled, in the `->string'	syntax.

	      -S     Do	 not  complete	options	 after a `--' appearing	on the
		     line, and ignore the `--'.	 For example, with -S, in  the

			    foobar -x -- -y

		     the  `-x' is considered an	option,	the `-y' is considered
		     an	argument, and the `--' is considered to	be neither.

	      -A pat Do	not complete options after the first non-option	 argu-
		     ment  on the line.	 pat is	a pattern 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 opt-
		     specs, the	form is	`-A "-*"'.

	      -O name
		     Pass the elements of the array name as arguments to func-
		     tions  called  to	execute	actions.  This is discussed in
		     detail below.

	      -M matchspec
		     Use the match specification matchspec for completing  op-
		     tion names	and values.  The default matchspec allows par-
		     tial word completion after	`_' and	`-', such as  complet-
		     ing `-f-b'	to `-foo-bar'.	The default matchspec is:
		     r:|[_-]=* r:|=*

	      specs: overview

	      Each of the following forms is a spec describing individual sets
	      of options or arguments on the command line being	analyzed.

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

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

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

		     With two colons before the	message, the words special ar-
		     ray and the CURRENT special parameter are modified	to re-
		     fer only to the normal arguments when the action is  exe-
		     cuted or evaluated.  With three colons before the message
		     they are modified to refer	only to	the  normal  arguments
		     covered by	this description.

		     This  describes  an option.  The colon indicates handling
		     for one or	more arguments to the option;  if  it  is  not
		     present, the option is assumed to take no arguments.

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

			    Here optspec is one	of the remaining forms	below.
			    This  indicates  the  following optspec may	be re-
			    peated.  Otherwise if the corresponding option  is
			    already present on the command line	to the left of
			    the	cursor it will not be offered again.

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

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

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

			    The	 first	argument  of  the option must come di-
			    rectly after the option name  in  the  same	 word.
			    For	 example,  `-foo-:...' specifies that the com-
			    pleted  option  and	 argument   will   look	  like

			    The	 first	argument  may appear immediately after
			    optname in the same	word, or may appear as a sepa-
			    rate   word	  after	  the  option.	 For  example,
			    `-foo+:...'	specifies that	the  completed	option
			    and	 argument  will	 look like either `-fooarg' or
			    `-foo arg'.

			    The	argument may appear as the next	 word,	or  in
			    same  word	as the option name provided that it is
			    separated from it by an equals sign,  for  example
			    `-foo=arg' or `-foo	arg'.

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

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

			    The	 verbose  style	 is used to decide whether the
			    explanation	strings	are 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 ar-
			    gument is described	for this optspec, the value of
			    the	style is displayed, with any appearance	of the
			    sequence `%d' in it	replaced by the	message	of the
			    first optarg that follows the optspec; see below.

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

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

			    An	argument to the	option;	message	and action are
			    treated as for ordinary arguments.	In  the	 first
			    form, the argument is mandatory, and in the	second
			    form it is optional.

			    This group may be repeated for options which  take
			    multiple arguments.	 In other words, :message1:ac-
			    tion1:message2:action2 specifies that  the	option
			    takes two arguments.

			    This  describes multiple arguments.	 Only the last
			    optarg for an option taking	multiple arguments may
			    be	given  in  this	form.  If the pattern is empty
			    (i.e. :*:),	all the	remaining words	 on  the  line
			    are	 to  be	 completed as described	by the action;
			    otherwise, all the words up	 to  and  including  a
			    word  matching the pattern are to be completed us-
			    ing	the action.

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

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

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

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

	      To aid in	reuse of specifications, it is possible	to precede any
	      of  the  forms  above  with `!'; then the	form will no longer be
	      completed, although if the option	or  argument  appears  on  the
	      command  line  they will be skipped as normal.  The main use for
	      this is when the arguments are given by an array,	and _arguments
	      is  called  repeatedly  for more specific	contexts: on the first
	      call `_arguments $global_options'	is  used,  and	on  subsequent
	      calls `_arguments	!$^global_options'.

	      specs: actions

	      In each of the forms above the action determines how completions
	      should be	generated.  Except for the `->string' form below,  the
	      action  will  be executed	by calling the _all_labels function to
	      process all tag labels.  No special handling of tags  is	needed
	      unless a function	call introduces	a new one.

	      The  functions called to execute actions will be called with the
	      elements of the array named by the `-O  name'  option  as	 argu-
	      ments.   This  can be used, for example, to pass the same	set of
	      options for the compadd builtin to all actions.

	      The forms	for action are as follows.

	       (single unquoted	space)
		     This is useful where an argument is required  but	it  is
		     not  possible  or	desirable  to generate matches for it.
		     The message will be displayed but no completions  listed.
		     Note  that	 even in this case the colon at	the end	of the
		     message is	needed;	it may only be omitted when neither  a
		     message nor an action is given.

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

			    :foo:(foo bar baz)

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

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

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

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

		     Where _arguments encounters action	in the `->string' for-
		     mat,  it  will  strip all leading and trailing whitespace
		     from string and set the array state to  the  set  of  all
		     strings for which an action is to be performed.  The ele-
		     ments of the array	state_descr are	 assigned  the	corre-
		     sponding  message	field from each	optarg containing such
		     an	action.

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

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

		     A	function  calling  _arguments with at least one	action
		     containing	a `->string' must therefore declare  appropri-
		     ate local parameters:

			    local context state	state_descr line
			    typeset -A opt_args

		     to	 prevent  _arguments from altering the global environ-

		     A string in braces	is evaluated as	shell code to generate
		     matches.	If  the	eval-string itself does	not begin with
		     an	opening	parenthesis or brace it	is split into separate
		     words before execution.

	      =	action
		     If	 the  action starts with `= ' (an equals sign followed
		     by	a space), _arguments will insert the contents  of  the
		     argument  field  of  the current context as the new first
		     element in	the words  special  array  and	increment  the
		     value of the CURRENT special parameter.  This has the ef-
		     fect of inserting a dummy word onto the  completion  com-
		     mand  line	 while not changing the	point at which comple-
		     tion is taking place.

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

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

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

	      During the performance of	the action the array  `line'  will  be
	      set  to  the  normal  arguments  from the	command	line, i.e. the
	      words from the command line after	the command name excluding all
	      options and their	arguments.  Options are	stored in the associa-
	      tive array `opt_args' with option	names as keys and their	 argu-
	      ments  as	the values.  For options that have more	than one argu-
	      ment these are given as one string, separated  by	 colons.   All
	      colons  and  backslashes	in the original	arguments are preceded
	      with backslashes.

	      The parameter `context' is set when  returning  to  the  calling
	      function to perform an action of the form	`->string'.  It	is set
	      to an array of elements corresponding to the elements of $state.
	      Each  element  is	 a suitable name for the argument field	of the
	      context: either a	string of the form `option-opt-n' for the n'th
	      argument	of  the	 option	 -opt,	or a string of the form	`argu-
	      ment-n' for the n'th argument.  For `rest'  arguments,  that  is
	      those  in	 the list at the end not handled by position, n	is the
	      string `rest'.  For example, when	completing the argument	of the
	      -o option, the name is `option-o-1', while for the second	normal
	      (non-option-) argument it	is `argument-2'.

	      Furthermore, during the evaluation of  the  action  the  context
	      name  in	the curcontext parameter is altered to append the same
	      string that is stored in the context parameter.

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

		     local curcontext="$curcontext"

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

	      Specifying multiple sets of options

	      It is possible to	specify	multiple sets of options and arguments
	      with  the	 sets separated	by single hyphens.  The	specifications
	      before the first hyphen (if any) are shared by all the remaining
	      sets.  The first word in every other set provides	a name for the
	      set which	may appear in exclusion	lists in  specifications,  ei-
	      ther alone or before one of the possible values described	above.
	      In the second case a `-' should appear between this name and the

	      For example:

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

	      This  defines  two sets.	When the command line contains the op-
	      tion `-c', the `-d' option and the argument will not be  consid-
	      ered  possible  completions.   When it contains `-d' or an argu-
	      ment, the	option `-c' will not be	 considered.   However,	 after
	      `-a' both	sets will still	be considered valid.

	      If  an option in a set appears on	the command line, it is	stored
	      in the associative array `opt_args' with 'set-option' as a  key.
	      In the example above, a key `set1--c' is used if the option `-c'
	      is on the	command	line.

	      If the name given	for one	of the mutually	exclusive sets	is  of
	      the form `(name)'	then only one value from each set will ever be
	      completed; more formally,	all specifications are mutually	exclu-
	      sive  to all other specifications	in the same set.  This is use-
	      ful for defining multiple	sets of	options	which are mutually ex-
	      clusive  and  in	which  the options are aliases for each	other.
	      For example:

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

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

	      Deriving spec forms from the help	output

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

	      In addition to options, `_arguments --' will try to  deduce  the
	      types   of   arguments  available	 for  options  when  the  form
	      `--opt=val' is valid.  It	is also	possible to provide  hints  by
	      examining	 the  help  text of the	command	and adding helpspec of
	      the form `pattern:message:action'; note  that  other  _arguments
	      spec  forms  are	not  used.  The	pattern	is matched against the
	      help text	for an option, and if it matches the message  and  ac-
	      tion  are	 used  as  for other argument specifiers.  The special
	      case of `*:' means both message and action are empty, which  has
	      the  effect of causing options having no description in the help
	      output to	be ordered in listings ahead of	options	 that  have  a

	      For example:

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

	      Here,  `yes'  and	 `no' will be completed	as the argument	of op-
	      tions whose description ends in a	star; file names will be  com-
	      pleted for options that contain the substring `=FILE' in the de-
	      scription; and directories will be completed for	options	 whose
	      description  contains  `=DIR' or `=PATH'.	 The last three	are in
	      fact the default and so need not be given	 explicitly,  although
	      it is possible to	override the use of these patterns.  A typical
	      help text	which uses this	feature	is:

		       -C, --directory=DIR	    change to directory	DIR

	      so that the above	specifications will cause  directories	to  be
	      completed	after `--directory', though not	after `-C'.

	      Note also	that _arguments	tries to find out automatically	if the
	      argument for an option is	optional.  This	can be	specified  ex-
	      plicitly by doubling the colon before the	message.

	      If the pattern ends in `(-)', this will be removed from the pat-
	      tern and the action will be used only directly  after  the  `=',
	      not  in the next word.  This is the behaviour of a normal	speci-
	      fication defined with the	form `=-'.

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

		     _arguments	-- -i \

	      will  cause  completion to ignore	the options `--enable-FEATURE'
	      and `--disable-FEATURE' (this example is useful with GNU config-

	      The  `_arguments --' form	can also be followed by	the option `-s
	      pair' to describe	option aliases.	 The pair consists of  a  list
	      of alternating patterns and corresponding	replacements, enclosed
	      in parens	and quoted so that it forms a single argument word  in
	      the _arguments call.

	      For example, some	configure-script help output describes options
	      only as `--enable-foo', but the script also accepts the  negated
	      form `--disable-foo'.  To	allow completion of the	second form:

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

	      Miscellaneous notes

	      Finally,	note  that _arguments generally	expects	to be the pri-
	      mary function handling any completion for	which it is used.   It
	      may  have	side effects which change the treatment	of any matches
	      added by other functions called after it.	 To combine _arguments
	      with  other  functions,  those functions should be called	either
	      before _arguments, as an action within a spec,  or  in  handlers
	      for `->state' actions.

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

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

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

	      The  `-format'  option  takes one	argument in the	next word, de-
	      scribed as `paper	size' for which	only the strings `letter'  and
	      `A4' will	be completed.

	      The `-copy' option may appear more than once on the command line
	      and takes	two arguments.	The first is  mandatory	 and  will  be
	      completed	as a filename.	The second is optional (because	of the
	      second colon before the description `resolution')	 and  will  be
	      completed	from the strings `300' and `600'.

	      The  last	two descriptions say what should be completed as argu-
	      ments.  The first	describes the first argument as	a  `postscript
	      file' and	makes files ending in `ps' or `eps' be completed.  The
	      last description gives all other arguments the description `page
	      numbers' but does	not offer completions.

       _cache_invalid cache_identifier
	      This  function returns status zero if the	completions cache cor-
	      responding to the	given cache identifier needs  rebuilding.   It
	      determines  this	by  looking  up	the cache-policy style for the
	      current context.	This should provide a function name  which  is
	      run  with	 the  full path	to the relevant	cache file as the only


		     _example_caching_policy ()	{
			 # rebuild if cache is more than a week	old
			 local -a oldp
			 oldp=(	"$1"(Nm+7) )
			 (( $#oldp ))

       _call_function return name [ arg	... ]
	      If a function name exists, it is called with the arguments args.
	      The  return  argument gives the name of a	parameter in which the
	      return status from the function name should be stored; if	return
	      is empty or a single hyphen it is	ignored.

	      The  return status of _call_function itself is zero if the func-
	      tion name	exists and was called and non-zero otherwise.

       _call_program [ -p ] tag	string ...
	      This function provides a mechanism for the user to override  the
	      use  of an external command.  It looks up	the command style with
	      the supplied tag.	 If the	style is set, its value	is used	as the
	      command to execute.  The strings from the	call to	_call_program,
	      or from the style	if set,	are concatenated with  spaces  between
	      them  and	 the resulting string is evaluated.  The return	status
	      is the return status of the command called.

	      If the option `-p' is supplied it	 indicates  that  the  command
	      output  is  influenced by	the permissions	it is run with.	If the
	      gain-privileges style is set to true,  _call_program  will  make
	      use of commands such as sudo, if present on the command-line, to
	      match the	permissions to whatever	the final command is likely to
	      run  under.  When	 looking  up  the  gain-privileges and command
	      styles, the command component of the  zstyle  context  will  end
	      with a slash (`/') followed by the command that would be used to
	      gain privileges.

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

	      The style	name consists of field names separated by hyphens, for
	      example `users-hosts-ports'.  For	each field for a value is  al-
	      ready  known,  a spec of the form	`field=pattern'	is given.  For
	      example, if the command line so far specifies a user `pws',  the
	      argument `users=pws' should appear.

	      The  next	 argument  with	no equals sign is taken	as the name of
	      the field	for which completions should be	generated  (presumably
	      not one of the fields for	which the value	is known).

	      The matches generated will be taken from the value of the	style.
	      These should contain the possible	values for the combinations in
	      the  appropriate	order  (users,	hosts,	ports  in  the example
	      above).  The different  fields  the  values  for	the  different
	      fields  are  separated  by colons.  This can be altered with the
	      option -s	to _combination	which specifies	a pattern.   Typically
	      this  is	a  character  class, as	for example `-s	"[:@]"'	in the
	      case of the users-hosts style.	Each `field=pattern'  specifi-
	      cation  restricts	the completions	which apply to elements	of the
	      style with appropriately matching	fields.

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

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

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

       _command_names [	-e | - ]
	      This function completes words that are valid  at	command	 posi-
	      tion:  names  of	aliases, builtins, hashed commands, functions,
	      and so on.  With the -e flag,  only  hashed  commands  are  com-
	      pleted.  The - flag is ignored.

       _completers [ -p	]
	      This function completes names of completers.

	      -p     Include the leading underscore (`_') in the matches.

       _describe [-12JVx] [ -oO	| -t tag ] descr name1 [ name2 ] [ opt ... ]
		 [ -- name1 [ name2 ] [	opt ...	] ... ]
	      This  function associates	completions with descriptions.	Multi-
	      ple 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.	 This is  fol-
	      lowed  by	one or two names of arrays followed by options to pass
	      to compadd.  The array name1 contains the	 possible  completions
	      with  their  descriptions	 in the	form `completion:description'.
	      Any literal colons in completion must be	quoted	with  a	 back-
	      slash.   If  a name2 is given, it	should have the	same number of
	      elements as name1; in this case the corresponding	 elements  are
	      added  as	possible completions instead of	the completion strings
	      from name1.  The completion list will  retain  the  descriptions
	      from name1.  Finally, a set of completion	options	can appear.

	      If  the  option  `-o'  appears  before  the  first argument, the
	      matches added will be treated as names of	command	options	 (N.B.
	      not  shell  options),  typically following a `-',	`--' or	`+' on
	      the command line.	 In this case _describe	uses  the  prefix-hid-
	      den, prefix-needed and verbose styles to find out	if the strings
	      should be	added as completions and if the	descriptions should be
	      shown.   Without the `-o'	option,	only the verbose style is used
	      to decide	how descriptions are shown.  If	`-O' is	 used  instead
	      of  `-o',	 command  options are completed	as above but _describe
	      will not handle the prefix-needed	style.

	      With the -t option a tag can be specified.  The default is `val-
	      ues' or, if the -o option	is given, `options'.

	      The options -1, -2, -J, -V, -x are passed	to _next_label.

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

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

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

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

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

	      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'.  These	supply
	      escape sequence replacements for the format style: every appear-
	      ance of `%char' will be replaced by string.

	      If the -x	option is given, the description  will	be  passed  to
	      compadd  using  the  -x  option instead of the default -X.  This
	      means that the description will be displayed even	if  there  are
	      no corresponding matches.

	      The  options  placed  in	the  array  name  take	account	of the
	      group-name style,	so matches are	placed	in  a  separate	 group
	      where necessary.	The group normally has its elements sorted (by
	      passing the option -J to compadd), but  if  an  option  starting
	      with  `-V',  `-J', `-1', or `-2' is passed to _description, that
	      option will be included in the array.  Hence it is possible  for
	      the  completion  group to	be unsorted by giving the option `-V',
	      `-1V', or	`-2V'.

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

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

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

       _dir_list [ -s sep ] [ -S ]
	      Complete a list of directory names separated by colons (the same
	      format as	$PATH).

	      -s sep Use  sep  as  separator between items.  sep defaults to a
		     colon (`:').

	      -S     Add sep instead of	slash (`/') as an autoremoveable  suf-

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

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

       _email_addresses	[ -c ] [ -n plugin ]
	      Complete email addresses.	 Addresses are provided	by plugins.

	      -c     Complete bare localhost@domain.tld	addresses,  without  a
		     name  part	 or  a	comment.   Without this	option,	RFC822
		     `Firstname	Lastname <address>' strings are	completed.

	      -n plugin
		     Complete aliases from plugin.

	      The following plugins are	available by default: _email-ldap (see
	      the  filter  style),  _email-local (completes user@hostname Unix
	      addresses),  _email-mail	(completes  aliases  from  ~/.mailrc),
	      _email-mush, _email-mutt,	and _email-pine.

	      Addresses	 from  the  _email-foo	plugin are added under the tag

	      Writing plugins

	      Plugins are written as separate functions	 with  names  starting
	      with `_email-'.  They are	invoked	with the -c option and compadd
	      options.	They should either do their own	completion or set  the
	      $reply  array  to	 a list	of `alias:address' elements and	return
	      300.  New	plugins	will be	picked up and run automatically.

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

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

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

		     compdef _gnu_generic foo bar

	      after the	call to	compinit.

	      The completion system as supplied	is conservative	in its use  of
	      this  function, since it is important to be sure the command un-
	      derstands	the option `--help'.

       _guard [	options	] pattern descr
	      This function displays descr if pattern matches the string to be
	      completed.   It  is  intended  to	 be used in the	action for the
	      specifications passed to _arguments and similar functions.

	      The return status	is zero	if the message was displayed  and  the
	      word to complete is not empty, and non-zero otherwise.

	      The  pattern may be preceded by any of the options understood by
	      compadd that are passed down from	_description, namely  -M,  -J,
	      -V,  -1,	-2,  -n,  -F and -X.  All of these options will	be ig-
	      nored.  This fits	in conveniently	with the argument-passing con-
	      ventions of actions for _arguments.

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

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

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

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

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

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

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

	      The  second -e form gives	a description for completions with the
	      tag tag to be shown even if there	are no matches for  that  tag.
	      This  form is called by _arguments in the	event that there is no
	      action for an option specification.  The tag can be omitted  and
	      if so the	tag is taken from the parameter	$curtag; this is main-
	      tained by	the completion system and so is	usually	correct.  Note
	      that  if	there  are  no	matches	 at  the time this function is
	      called, compstate[insert]	is cleared, so additional matches gen-
	      erated later are not inserted on the command line.

       _multi_parts [ -i ] sep array
	      The argument sep is a separator character.  The array may	be ei-
	      ther the name of an array	parameter or a literal	array  in  the
	      form  `(foo  bar)',  a  parenthesised list of words separated by
	      whitespace.  The possible	completions are	the strings  from  the
	      array.   However,	 each chunk delimited by sep will be completed
	      separately.  For example,	the _tar function uses `_multi_parts /
	      patharray'  to  complete partial file paths from the given array
	      of complete file paths.

	      The -i option causes _multi_parts	to insert a unique match  even
	      if  that	requires  multiple separators to be inserted.  This is
	      not usually the expected behaviour with filenames,  but  certain
	      other types of completion, for example those with	a fixed	set of
	      possibilities, may be more suited	to this	form.

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

       _next_label [ -x	] [ -12VJ ] tag	name descr [ option ...	]
	      This function is used to implement the loop over	different  tag
	      labels for a particular tag as described above for the tag-order
	      style.  On each call it checks to	see if there are any more  tag
	      labels;  if there	is it returns status zero, otherwise non-zero.
	      As this function requires	a current tag to be set, it  must  al-
	      ways follow a call to _tags or _requested.

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

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

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

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

	      This is the standard function called to handle  completion  out-
	      side  any	 special -context-.  It	is called both to complete the
	      command word and also the	arguments for a	command.  In the  sec-
	      ond  case,  _normal looks	for a special completion for that com-
	      mand, and	if there is none it uses the completion	for  the  -de-
	      fault- context.

	      A	 second	 use is	to reexamine the command line specified	by the
	      $words array and the $CURRENT parameter after  those  have  been
	      modified.	  For  example,	 the  function _precommand, which com-
	      pletes after pre-command specifiers such as nohup,  removes  the
	      first  word from the words array,	decrements the CURRENT parame-
	      ter, then	calls _normal again.  The effect is  that  `nohup  cmd
	      ...' is treated in the same way as `cmd ...'.

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

	      This can be used to complete the names  of  shell	 options.   It
	      provides	a  matcher  specification that ignores a leading `no',
	      ignores underscores and allows upper-case	letters	to match their
	      lower-case   counterparts	  (for	 example,   `glob',  `noglob',
	      `NO_GLOB'	are all	completed).  Any arguments are	propagated  to
	      the compadd builtin.

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

	      Note that	you need to uncomment a	few lines  in  the  _main_com-
	      plete  function for these	functions to work properly.  The lines
	      in question are used to store the	option settings	in effect  be-
	      fore  the	 completion  widget locally sets the options it	needs.
	      Hence these functions are	not generally used by  the  completion

	      This is used to complete the names of shell parameters.

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

	      All other	arguments are passed to	the compadd builtin.

	      This function is used throughout the completion system  to  com-
	      plete  filenames.	  It  allows completion	of partial paths.  For
	      example, the string `/u/i/s/sig' may be completed	 to  `/usr/in-

	      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

	      -W paths
		     Specifies path prefixes that are to be prepended  to  the
		     string  from  the	command	line to	generate the filenames
		     but that should not be inserted as	completions nor	 shown
		     in	 completion  listings.	Here, paths may	be the name of
		     an	array parameter, a literal list	of paths  enclosed  in
		     parentheses or an absolute	pathname.

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

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

	      Finally, the _path_files function	 uses the styles  expand,  am-
	      biguous,	special-dirs,  list-suffixes  and  file-sort described

       _pick_variant [ -b builtin-label	] [ -c command ] [ -r name ]
		     label=pattern ... label [ arg ... ]
	      This function is used to resolve situations where	a single  com-
	      mand  name  requires  more than one type of handling, either be-
	      cause it has more	than one variant or because there  is  a  name
	      clash between two	different commands.

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

	      If the `-b builtin-label'	is given, the command is tested	to see
	      if it is provided	as a shell builtin,  possibly  autoloaded;  if
	      so,  the	label  builtin-label  is selected as the label for the

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

	      The  results are also cached in the _cmd_variant associative ar-
	      ray indexed by the name of the command run.

       _regex_arguments	name spec ...
	      This function generates a	completion function name which matches
	      the  specifications  specs,  a set of regular expressions	as de-
	      scribed below.  After  running  _regex_arguments,	 the  function
	      name should be called as a normal	completion function.  The pat-
	      tern to be matched is given by the contents of the  words	 array
	      up  to  the  current  cursor  position joined together with null
	      characters; no quotation is applied.

	      The arguments are	grouped	as sets	of alternatives	 separated  by
	      `|',  which  are	tried  one  after the other until one matches.
	      Each alternative consists	of a one or more specifications	 which
	      are  tried  left	to  right,  with  each	pattern	 matched being
	      stripped in turn from the	command	line being tested,  until  all
	      of  the  group  succeeds or until	one fails; in the latter case,
	      the next alternative is tried.  This structure can  be  repeated
	      to  arbitrary depth by using parentheses;	matching proceeds from
	      inside to	outside.

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

	      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 single primitive	component.  The	function tests
		     whether   the  combined  pattern  `(#b)((#B)pattern)look-
		     ahead*' matches the command line string.  If so,  `guard'
		     is	 evaluated and its return status is examined to	deter-
		     mine if the test has succeeded.  The pattern string  `[]'
		     is	 guaranteed  never  to	match.	 The  lookahead	is not
		     stripped from the command line before the next pattern is

		     The  argument  starting with : is used in the same	manner
		     as	an argument to _alternative.

		     A component is used as follows: pattern is	tested to  see
		     if	 the component already exists on the command line.  If
		     it	does, any following  specifications  are  examined  to
		     find  something  to  complete.  If	a component is reached
		     but no such pattern exists	yet on the command  line,  the
		     string  containing	the action is used to generate matches
		     to	insert at that point.

	      /pattern/+ [%lookahead%] [-guard]	[:tag:descr:action]
		     This is similar to	`/pattern/ ...'	but the	left  part  of
		     the command line string (i.e. the part already matched by
		     previous patterns)	is also	considered part	of the comple-
		     tion target.

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

	      (	spec )
		     Parentheses may be	used to	groups specs; note each	paren-
		     thesis is a single	argument to _regex_arguments.

	      spec # This allows any number of repetitions of spec.

	      spec spec
		     The two specs are to be matched one after	the  other  as
		     described above.

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

	      The  function  _regex_words  can be used as a helper function to
	      generate matches for a set of alternative	 words	possibly  with
	      their own	arguments as a command line argument.


		     _regex_arguments _tst /$'[^\0]#\0'/ \
			 /$'[^\0]#\0'/ :'compadd aaa'

	      This  generates  a  function _tst	that completes aaa as its only
	      argument.	 The tag and description  for  the  action  have  been
	      omitted for brevity (this	works but is not recommended in	normal
	      use).  The first component matches the command  word,  which  is
	      arbitrary; the second matches  any argument.  As the argument is
	      also arbitrary, any following component would not	depend on  aaa
	      being present.

		     _regex_arguments _tst /$'[^\0]#\0'/ \
			 /$'aaa\0'/ :'compadd aaa'

	      This  is	a  more	 typical use; it is similar, but any following
	      patterns would only match	if aaa was present as the first	 argu-

		     _regex_arguments _tst /$'[^\0]#\0'/ \( \
			 /$'aaa\0'/ :'compadd aaa' \
			 /$'bbb\0'/ :'compadd bbb' \) \#

	      In  this	example, an indefinite number of command arguments may
	      be completed.  Odd arguments are completed as aaa	and even argu-
	      ments  as	 bbb.	Completion fails unless	the set	of aaa and bbb
	      arguments	before the current one is matched correctly.

		     _regex_arguments _tst /$'[^\0]#\0'/ \
			 \( /$'aaa\0'/ :'compadd aaa' \| \
			 /$'bbb\0'/ :'compadd bbb' \) \#

	      This is similar, but either aaa or bbb may be completed for  any
	      argument.	 In this case _regex_words could be used to generate a
	      suitable expression for the arguments.

       _regex_words tag	description spec ...
	      This  function  can  be  used  to	 generate  arguments  for  the
	      _regex_arguments	command	 which	may  be	 inserted at any point
	      where a set of rules is expected.	 The tag and description  give
	      a	 standard  tag	and description	pertaining to the current con-
	      text.  Each spec contains	two or three arguments separated by  a
	      colon: note that there is	no leading colon in this case.

	      Each  spec  gives	one of a set of	words that may be completed at
	      this point, together with	arguments.  It is thus roughly equiva-
	      lent  to the _arguments function when used in normal (non-regex)

	      The part of the spec before the first colon is the  word	to  be
	      completed.   This	 may  contain a	*; the entire word, before and
	      after the	* is completed,	but only the text before the * is  re-
	      quired  for the context to be matched, so	that further arguments
	      may be completed after the abbreviated form.

	      The second part of spec is a description for the word being com-

	      The  optional third part of the spec describes how words follow-
	      ing the one being	completed are themselves to be completed.   It
	      will be evaluated	in order to avoid problems with	quoting.  This
	      means that typically it contains a reference to  an  array  con-
	      taining previously generated regex arguments.

	      The  option  -t term specifies a terminator for the word instead
	      of the usual space.  This	is handled as an auto-removable	suffix
	      in the manner of the option -s sep to _values.

	      The  result  of  the processing by _regex_words is placed	in the
	      array reply, which should	be made	local to the calling function.
	      If the set of words and arguments	may be matched repeatedly, a #
	      should be	appended to the	generated array	at that	point.

	      For example:

		     local -a reply
		     _regex_words mydb-commands	'mydb commands'	\
		       'add:add	an entry to mydb:$mydb_add_cmds' \
		       'show:show entries in mydb'
		     _regex_arguments _mydb "$reply[@]"
		     _mydb "$@"

	      This shows a completion function for a command mydb which	 takes
	      two  command  arguments, add and show.  show takes no arguments,
	      while the	arguments for add have already been prepared in	an ar-
	      ray   mydb_add_cmds,  quite  possibly  by	 a  previous  call  to

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

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

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

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

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

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

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

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

	      See _store_cache below for more details.

	      This function is passed alternating arrays and separators	as ar-
	      guments.	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 accepts the	 compadd  options  `-V',  `-J',	 `-1',
	      `-2',  `-n',  `-X',  `-M',  `-P',	`-S', `-r', `-R', and `-q' and
	      passes them on to	the compadd builtin used to add	the matches.

       _sequence [ -s sep ] [ -n max ] [ -d ] function [ - ] ...
	      This function is a wrapper to  other  functions  for  completing
	      items in a separated list. The same function is used to complete
	      each item	in the list. The separator is specified	 with  the  -s
	      option.  If  -s is omitted it will use `,'. Duplicate values are
	      not matched unless -d is specified. If there is a	fixed or maxi-
	      mum  number of items in the list,	this can be specified with the
	      -n option.

	      Common compadd options are passed	on to the function. It is pos-
	      sible to use compadd directly with _sequence, though _values may
	      be more appropriate in this situation.

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

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

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

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

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

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

	      The completion function may avoid	calling	 _retrieve_cache  when
	      it  already  has	the  completion	 data available	as parameters.
	      However, in that case it should  call  _cache_invalid  to	 check
	      whether  the  data  in the parameters and	in the cache are still

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

       _tags [ [ -C name ] tag ... ]
	      If  called  with	arguments,  these are taken to be the names of
	      tags valid for completions in the	current	context.   These  tags
	      are stored internally and	sorted by using	the tag-order style.

	      Next, _tags is called repeatedly without arguments from the same
	      completion function.  This successively selects the first,  sec-
	      ond,  etc. set of	tags requested by the user.  The return	status
	      is zero if at least one of the tags is  requested	 and  non-zero
	      otherwise.  To test if a particular tag is to be tried, the _re-
	      quested function should be called	(see above).

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

	      Like  _files,  but resolve leading tildes	according to the rules
	      of filename expansion, so	the suggested completions don't	 start
	      with a `~' even if the filename on the command-line does.

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

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

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

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

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

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

	      The character separating a value from its	argument  can  be  set
	      using  the  option -S (like -s, followed by the character	to use
	      as the separator in the next argument).  By default  the	equals
	      sign will	be used	as the separator between values	and arguments.


		     _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  ap-
	      pear  more  than once.  The second is described as `number', may
	      appear more than once, and  takes	 one  mandatory	 argument  de-
	      scribed as `first	count';	no action is specified,	so it will not
	      be completed.  The `(two)' at the	beginning  says	 that  if  the
	      value  `one'  is	on the line, the value `two' will no longer be
	      considered a  possible  completion.   Finally,  the  last	 value
	      (`two')  is  described as	`another number' and takes an optional
	      argument described as `second count' for which  the  completions
	      (to  appear  after  an  `=') are `1', `2', and `3'.  The _values
	      function will complete lists of these values separated  by  com-

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

	      The style	verbose	is used	to decide if the descriptions for  the
	      values (but not those for	the arguments) should be printed.

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

		     local context state state_descr line
		     typeset -A	val_args

	      when using an action of the form `->string'.  With this function
	      the context parameter will be set	to the name of the value whose
	      argument	is  to be completed.  Note that	for _values, the state
	      and state_descr are scalars rather than arrays.  Only  a	single
	      matching state is	returned.

	      Note  also  that _values normally	adds the character used	as the
	      separator	between	values as an auto-removable suffix (similar to
	      a	 `/'  after a directory).  However, this is not	possible for a
	      `->string' action	as the matches for the argument	are  generated
	      by  the calling function.	 To get	the usual behaviour, the call-
	      ing function can add the separator x as a	suffix by passing  the
	      options `-qS x' either directly or indirectly to compadd.

	      The option -C is treated in the same way as it is	by _arguments.
	      In that case the parameter curcontext should be made  local  in-
	      stead of context (as described above).

       _wanted [ -x ] [	-C name	]  [ -12VJ ] tag name descr command [ arg ...]
	      In  many	contexts,  completion can only generate	one particular
	      set of matches, usually corresponding to a single	tag.  However,
	      it  is  still  necessary	to  decide  whether  the user requires
	      matches of this type.  This function is useful in	such a case.

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

	      Hence to offer only one tag and immediately add the  correspond-
	      ing matches with the given description:

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

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

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

       _widgets	[ -g pattern ]
	      This function completes names of zle widgets  (see  the  section
	      `Widgets'	 in  zshzle(1)).   The pattern,	if present, is matched
	      against values of	the $widgets special parameter,	documented  in
	      the section `The zsh/zleparameter	Module'	in zshmodules(1).

       There  are  some	 standard variables, initialised by the	_main_complete
       function	and then used from other functions.

       The standard variables are:

	      The completion system uses setopt	to set a  number  of  options.
	      This allows functions to be written without concern for compati-
	      bility with every	possible combination of	user options. However,
	      sometimes	 completion needs to know what the user's option pref-
	      erences are. These are saved in the  _comp_caller_options	 asso-
	      ciative array. Option names, spelled in lowercase	without	under-
	      scores, are mapped to one	or  other  of  the  strings  `on'  and

		     Completion	  functions   such   as	  _sudo	 can  set  the
		     _comp_priv_prefix array to	a command prefix that may then
		     be	 used  by  _call_program  to match the privileges when
		     calling programs to generate matches.

	      Two more features	are offered by	the  _main_complete  function.
	      The  arrays  compprefuncs	and comppostfuncs may contain names of
	      functions	that are to be called immediately before or after com-
	      pletion has been tried.  A function will only be called once un-
	      less it explicitly reinserts itself into the array.

       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.   These  are not arranged hierarchically, so, for
	      example, both the	Linux and Debian directories, as well as the X
	      directory, may be	useful on your system.

zsh 5.3.1		       December	21, 2016		 ZSHCOMPSYS(1)


Want to link to this manual page? Use this URL:

home | help