ZSHCOMPSYS man page on Tru64

Printed from http://www.polarhome.com/service/man/?qf=ZSHCOMPSYS&af=0&tf=2&of=Tru64

ZSHCOMPSYS(1)							 ZSHCOMPSYS(1)

NAME
       zshcompsys - zsh completion system

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

INITIALIZATION
       If the system was installed completely, it should be enough to call the
       shell  function	compinit  from	your initialization file; see the next
       section.	 However, the function compinstall can be run  by  a  user  to
       configure various aspects of the completion system.

       Usually,	 compinstall will insert code into .zshrc, although if that is
       not writable it will save it in another file and tell you  that	file's
       location.   Note that it is up to you to make sure that the lines added
       to .zshrc are actually run; you may, for example, need to move them  to
       an  earlier place in the file if .zshrc usually returns early.  So long
       as you keep them all together (including the comment lines at the start
       and finish), you can rerun compinstall and it will correctly locate and
       modify these lines.  Note, however, that any code you add to this  sec‐
       tion  by	 hand  is likely to be lost if you rerun compinstall, although
       lines using the command `zstyle' should be gracefully handled.

       The new code will take effect next time you start  the  shell,  or  run
       .zshrc  by hand; there is also an option to make them take effect imme‐
       diately.	 However, if compinstall has  removed  definitions,  you  will
       need to restart the shell to see the changes.

       To run compinstall you will need to make sure it is in a directory men‐
       tioned in your $fpath parameter, which should already be	 the  case  if
       zsh was properly configured as long as your startup files do not remove
       the appropriate directories from $fpath.	 Then it  must	be  autoloaded
       (`autoload  -U compinstall' is recommended).  You can abort the instal‐
       lation any time you are being prompted for information, and your .zshrc
       will  not  be altered at all; changes only take place right at the end,
       where you are specifically asked for confirmation.

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

       To initialize the system, the function compinit should be in  a	direc‐
       tory  mentioned	in  the	 $fpath	 variable,  and	 should	 be autoloaded
       (`autoload -U  compinit'	 is  recommended),  and	 then  run  simply  as
       `compinit'.   This will define a few utility functions, arrange for all
       the necessary shell functions to be autoloaded, and will	 then  re-bind
       all  keys  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
       to make sure that that widget is also re-bound.

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

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

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

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

   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.   Furthermore, if the directory in question ends in the path seg‐
       ment Core, or has a subdirectory named Core, compinit will add all sub‐
       directories of the directory where Core is to the path: this allows the
       functions to be in the same format as in the zsh source distribution.

       When compinit is	 run,  it  searches  all  such	files  accessible  via
       fpath/FPATH and reads the first line of each of them.  This line should
       contain one of the tags described below.	 Files whose first  line  does
       not  start  with one of these tags are not considered to be part of the
       completion system and will not be treated specially.

       The tags are:

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

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

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

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

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

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

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

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

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

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

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

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

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

       compdef [ -an ] function names...
       compdef -d names...
       compdef -p [ -a ] function pattern
       compdef -P [ -a ] function pattern
       compdef -k [ -an ] function style key-sequences...
       compdef -K [ -an ] function name style key-sequences ...
	      The  first  form	tells  the completion system to call the given
	      function when completing for  the	 contexts  or  commands	 whose
	      names  are  given:   this	 is  like the #compdef tag.  If the -n
	      option is given, any existing completion behaviour for  particu‐
	      lar contexts or commands will not be altered.  These definitions
	      can be deleted by giving the -d option as in the second form.

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

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

	      The  form	 with  -k  defines  a widget with the same name as the
	      function which will be called for	 each  of  the	key-sequences;
	      this  is like the #compdef -k tag.  The function should generate
	      the completions  needed  and  will  otherwise  behave  like  the
	      builtin  widget  whose  name is given as the style argument. The
	      widgets usable for this are: complete-word, delete-char-or-list,
	      expand-or-complete,   expand-or-complete-prefix,	 list-choices,
	      menu-complete,  menu-expand-or-complete,	and  reverse-menu-com‐
	      plete,  as  well	as  menu-select	 if the zsh/complist module is
	      loaded.  The option -n prevents the key being  bound  if	it  is
	      already to bound to something other than undefined-key.

	      The  form	 with -K is similar and defines multiple widgets based
	      on the same function, each of which requires the	set  of	 three
	      arguments	 name,	style  and key-sequences, where the latter two
	      are as for -k and the first must be a unique widget name	begin‐
	      ning with an underscore.

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

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

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

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

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

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

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

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

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

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

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

       As an example, the context name

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

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

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

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

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

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

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

	      zstyle ':completion:*' verbose yes

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

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

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

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

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

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

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

   Standard Tags
       Here  are  the  tags  currently used by the completion system.  Some of
       them are only used when looking up styles and do not refer to a partic‐
       ular type of match.

       accounts
	      used to look up the users-hosts style

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

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

       arguments
	      when an argument of a command may be completed

       arrays for names of array parameters

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

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

       builtins
	      for names of builtin commands

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

       colors for color names

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

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

       cursors
	      for cursor names used by X programs

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

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

       devices
	      for names of device special files

       directories
	      for names of directories

       directory-stack
	      for entries in the directory stack

       displays
	      for X display names

       domains
	      for network domains

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

       extensions
	      for X server extensions

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

       fonts  used for X font names

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

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

       groups used when completing names of user groups

       history-words
	      for words from the history

       hosts  for hostnames

       indexes
	      used for array indexes

       jobs   used for jobs

       keymaps
	      for names of zsh keymaps

       keysyms
	      for names of X keysyms

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

       libraries
	      for names of system libraries

       limits for system limits

       manuals
	      for names of manual pages

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

       messages
	      used to look up the format style for messages

       modifiers
	      for names of X modifiers

       modules
	      for modules (e.g. zsh modules)

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

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

       names  for all kinds of names

       nicknames
	      for nicknames of NIS maps

       options
	      for command options

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

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

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

       parameters
	      for names of parameters

       path-directories
	      for names of directories found by	 searching  the	 cdpath	 array
	      when completing for the cd and related builtin commands

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

       pods   for perl pods (documentation files)

       ports  for communication ports

       prefixes
	      for prefixes (like those of an URL)

       printers
	      for printer names

       processes
	      for process identifiers

       processes-list
	      used to look up the command style when generating	 the  list  to
	      display for process identifiers

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

       sequences
	      for sequences (e.g. mh sequences)

       sessions
	      for sessions in the zftp function suite

       signals
	      for signal names

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

       tags   for tags (e.g. rpm tags)

       targets
	      for makefile targets

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

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

       users  for usernames

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

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

       warnings
	      used to look up the format style for warnings

       widgets
	      for zsh widget names

       windows
	      for IDs of X windows

       zsh-options
	      for shell options

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

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

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

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

       add-space
	      This  style  is  used by the _expand completer.  If it is `true'
	      (the default), a space will be inserted after all words  result‐
	      ing  from	 the expansion (except for directory names which get a
	      slash).

	      It is also used by the _prefix completer to decide  if  a	 space
	      should be inserted before the suffix.

       ambiguous
	      This  applies  when  completing non-final components of filename
	      paths.  If it is set, the cursor is left after the first ambigu‐
	      ous  component, even if menu completion is in use.  It is tested
	      with the paths tag.

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

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

       auto-description
	      If  set,	this style's value will be used as the description for
	      options which are not described by the completion functions, but
	      that  have exactly one argument.	The sequence `%d' in the value
	      will be replaced by the description for this argument.   Depend‐
	      ing  on personal preferences, it may be useful to set this style
	      to something like `specify: %d'.	Note that this	may  not  work
	      for some commands.

       break-keys
	      This  style  is  used  by	 the  incremental-complete-word widget
	      (found in the Functions/Zle directory of the distribution).  Its
	      value  should  be	 a  pattern and all keys matching this pattern
	      will cause the widget to stop incremental completion without the
	      key having any further effect.

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

	      As an example, the function generating process  IDs  as  matches
	      uses  this  style	 with the processes tag to generate the IDs to
	      complete and when the verbose style  is  `true',	it  uses  this
	      style  with  the	processes-list	tag to generate the strings to
	      display.	When using different values for	 these	two  tags  one
	      should  ensure  that the process IDs appear in the same order in
	      both lists.

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

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

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

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

	      Note  that  the widget functions from the distribution that call
	      the completion code (namely, the	incremental-complete-word  and
	      the  predict-on  widgets)	 set  up  their top-level context name
	      before calling completion.  This allows one to define  different
	      sets  of completer functions for normal completion and for these
	      widgets.	For example, to use completion, approximation and cor‐
	      rection  for  normal  completion,	 completion and correction for
	      incremental completion and only completion  for  prediction  one
	      could use:

		     zstyle ':completion:*' completer _complete _correct _approximate
		     zstyle ':completion:incremental:*' completer _complete _correct
		     zstyle ':completion:predict:*' completer _complete

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

       completions
	      This style is used by the _expand completer function.

	      If this is set to an non-empty string it should be an expression
	      usable  inside  a	 `$((...))'  arithmetical expression. The com‐
	      pleter function evaluates this expression and if the  result  is
	      `1',  no	expansions  will be generated, but instead the comple‐
	      tions will be generated as  normal  and  all  of	them  will  be
	      inserted into the command line.

       condition
	      This style is used by the _list completer function.

	      If  it  is  not set or set to the empty string, the insertion of
	      matches will be delayed unconditionally.	 If  it	 is  set,  the
	      value should be an expression usable inside a `$((...))'	arith‐
	      metical expression.  In this case, delaying will be done if  the
	      expression evaluates to `1'. For example, with

		     zstyle ':completion:*:list:::' condition '${NUMERIC:-1} != 1'

	      delaying will be done only if given an explicit numeric argument
	      other than `1'.

       cursor The predict-on widget uses this style to decide where  to	 place
	      the cursor after completion has been tried.  Values are:

	      complete
		     The cursor is left where it was when completion finished,
		     but only if it is after a character equal to the one just
		     inserted  by the user.  If it is after another character,
		     this value is the same as `key'.

	      key    The cursor is left after the nth occurrence of the	 char‐
		     acter  just inserted, where n is the number of times that
		     character appeared in  the	 word  before  completion  was
		     attempted.	  In short, this has the effect of leaving the
		     cursor after the character just typed even if the comple‐
		     tion  code	 found out that no other characters need to be
		     inserted at that position.

	      Any other value for this style unconditionally leaves the cursor
	      at the position where the completion code left it.

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

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

       expand This  style is used when completing strings consisting of multi‐
	      ple parts, such as path names.  If its value contains the string
	      `prefix',	 the  partially	 typed	word  from  the	 line  will be
	      expanded as far as possible even if  trailing  parts  cannot  be
	      completed.   If  it  contains  the  string  `suffix'  and normal
	      (non-menu-) completion is used, matching	names  for  components
	      after  the  first	 ambiguous one will also be added.  This means
	      that the resulting string is the longest unambiguous string pos‐
	      sible,  but if menu completion is started on the list of matches
	      generated this way (e.g. due to the option AUTO_MENU being set),
	      this  will also cycle through the names of the files in pathname
	      components after the first ambiguous one.

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

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

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

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

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

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

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

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

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

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

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

	      For  the	same  purpose, this style is also tested with the tags
	      used when matches are generated before  it  is  tested  for  the
	      descriptions  tag.  This gives the possibility to define differ‐
	      ent format strings for different types of matches.

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

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

	      Finally, when set with the warnings tag, the  format  string  is
	      printed when no matches could be generated at all.  In this case
	      the `%d' is replaced with the descriptions for the matches  that
	      were expected.  If the value does not contain a `%d', then those
	      descriptions are added in the same way  as  matches  are	added,
	      i.e.  they  appear below the value for the format style laid out
	      in columns.  The descriptions are added as if for the tag	 warn‐
	      ings  so	that you can use the list-colors style for that tag to
	      highlight them.

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

       glob   Like completions, this is used by the _expand completer.

	      The  value is used like the one for completions and if it evalu‐
	      ates to `1', globbing will be attempted on the  words  resulting
	      from  substitution  (see	the  substitute style) or the original
	      string from the line.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       ignore-line
	      This  style is tested for the tags used when generating matches.
	      If it is set to `true', then none of the words that are  already
	      on the line will be considered possible completions.

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

       ignore-parents
	      The style is tested for the files tag 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,	 so  that,  for	 example, completion after ../
		     will not use the name of the current directory.

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

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

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

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

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

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

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

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

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

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

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

       list   This  style  is used by the _history_complete_word bindable com‐
	      mand (using the context prefix `:completion:history-words')  and
	      by  the incremental-complete-word widget (using the context pre‐
	      fix `:completion:incremental).

	      The _history_complete_word bindable command uses this  style  to
	      decide if the available matches should be shown.

	      When using the incremental-complete-word widget, this style says
	      if the matches should be listed on every key press (if they  fit
	      on the screen).

	      The  predict-on  widget uses this style to decide if the comple‐
	      tion should be shown even if there is only one possible  comple‐
	      tion.  This  is  done  if	 the value of this style is the string
	      always.

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

	      If  this	style  is  set for the default tag, the strings in the
	      value are taken as specifications that are  to  be  used	every‐
	      where.  If it is set for other tags, the specifications are used
	      only for matches of the type described by the tag.  For this  to
	      work,  the  group-name style must be set to an empty string.  If
	      the group-name tag specifies other  names	 for  the  groups  the
	      matches  in  these  groups  can  be colored by using these names
	      together	with  the  `(group)...'	  syntax  described  for   the
	      ZLS_COLORS  and ZLS_COLOURS parameters and adding the specifica‐
	      tions to the value for this style with the default tag.

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

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

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

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

       list-prompt
	      If  this style is set for the default tag, completion lists that
	      don't fit on the screen can be scrolled (see the description  of
	      the  zsh/complist	 module	 in zshmodules(1)).  The value, if not
	      the empty string, will be displayed after	 every	screenful  and
	      the  shell will prompt for a key press; if the style is unset, a
	      default prompt will be used.  The value may contain  the	escape
	      sequences	 `%l' or `%L', which will be replaced by the number of
	      the last line displayed and the total number of lines;  `%m'  or
	      `%M',  which  will  be replaced by the number of the  last match
	      shown and the total number of matches; and `%p' and `%P',	 which
	      will  be	replaced  by  `Top' when at the beginning of the list,
	      `Bottom' when at the end and the position shown  in  percent  of
	      the  total  length  otherwise.   In each of these cases the form
	      with the uppercase letter is  replaced  by  a  string  of	 fixed
	      width,  padded  to  the	right with spaces.  As in other prompt
	      strings, the escape sequences  `%S',  `%s',  `%B',  `%b',	 `%U',
	      `%u',  and  `%{...%}' for entering and leaving the display modes
	      standout, bold and underline are also available.

	      Note that this style has a default value.	 If you don't want  to
	      use scrolling, set this style to an empty string.

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

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

       match-original
	      This  is	used  by  the _match completer.	 If it is set to only,
	      _match will try to generate matches without inserting a  `*'  at
	      the  cursor  position.   If set to any other non-empty value, it
	      will first try to generate matches without inserting the `*' and
	      if  that	yields	no  matches,  it  will	try again with the `*'
	      inserted.	 If it is unset or set to the empty  string,  matching
	      will only be done with the `*' inserted.

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

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

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

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

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

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

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

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

       max-errors
	      This  is	used  by the _approximate and _correct completer func‐
	      tions to determine the maximum number of errors to  allow.   The
	      completer will try to generate completions by first allowing one
	      error, then two errors, and so  on,  until  either  a  match  or
	      matches  wer found or the maximum number of errors given by this
	      style has been reached.

	      If the value for this style contains the string  `numeric',  the
	      completer function will take any numeric argument as the maximum
	      number of errors allowed. For example, with

		     zstyle ':completion:*:approximate:::' max-errors 2 numeric

	      two errors are allowed if no numeric argument is given, but with
	      a	 numeric argument of six (as in `ESC-6 TAB'), up to six errors
	      are accepted.  Hence with a value of `0 numeric', no  correcting
	      completion will be attempted unless a numeric argument is given.

	      If  the  value  contains the string `not-numeric', the completer
	      will not try to generate	corrected  completions	when  given  a
	      numeric  argument,  so  in  this case the number given should be
	      greater than zero.  For example, `2 not-numeric' specifies  that
	      correcting completion with two errors will usually be performed,
	      but if a numeric argument is given, correcting  completion  will
	      not be performed.

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

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

	      In  addition  to	(or  instead  of) the above possibilities, the
	      value may contain the string `select', optionally followed by an
	      equal  sign  and	a  number.   In	 this  case menu-selection (as
	      defined by the zsh/complist module) will	be  started.   Without
	      the optional number, it will be started unconditionally and with
	      a number it will be started only if at least that	 many  matches
	      are  generated;  if  the	values for more than one tag provide a
	      number, the smallest number is taken.   Menu  selection  can  be
	      turned  off explicitly by defining a value containing the string
	      `no-select'.

	      It is also possible to start menu-selection only if the list  of
	      matches	does  not  fit	on  the	 screen	 by  using  the	 value
	      `select=long'.  This will only start menu-selection if the  wid‐
	      get  invoked  does  completion,  not  simply  listing as done by
	      delete-char-or-list; to start menu-selection even here, use  the
	      value `select=long-list'.

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

       old-list
	      This  is	used  by  the  _oldlist	 completer.   If  it is set to
	      `always', then  standard	widgets	 which	perform	 listing  will
	      retain the current list of matches, however they were generated;
	      this can be turned off explicitly with the value `never', giving
	      the  behaviour  without the _oldlist completer.  If the style is
	      unset, or any other value, then the existing list of completions
	      is  displayed if it is not already; otherwise, the standard com‐
	      pletion list is generated; this  is  the	default	 behaviour  of
	      _oldlist.	  However, if there is an old list and this style con‐
	      tains the name of the  completer	function  that	generated  the
	      list, then the old list will be used even if it was generated by
	      a widget which does not do listing.

	      For example, suppose you type ^Xc to use the _correct_word  wid‐
	      get,  which  generates  a list of corrections for the word under
	      the cursor.  Usually, typing ^D would generate a	standard  list
	      of  completions for the word on the command line, and show that.
	      With _oldlist, it will instead  show  the	 list  of  corrections
	      already generated.

	      As  another  example  consider  the  _match  completer: with the
	      insert-unambiguous style set to `true' it inserts only a	common
	      prefix  string, if there is any.	However, this may remove parts
	      of the original pattern, so that further completion  could  pro‐
	      duce  more  matches  than	 on  the  first attempt.  By using the
	      _oldlist completer and setting this style to _match, the list of
	      matches generated on the first attempt will be used again.

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

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

       original
	      This  is	used  by  the  _approximate and _correct completers to
	      decide if the original string should be added  as	 one  possible
	      completion.   Normally,  this is done only if there are at least
	      two possible corrections, but if this style is set to `true', it
	      is  always  added.   Note	 that  these completers use this style
	      after setting the completer field in the context	name  to  cor‐
	      rect-num	or  approximate-num, where num is the number of errors
	      that were accepted.

       packageset
	      This style is used  when	completing  arguments  of  the	Debian
	      `dpkg' program.  It contains an override for the default package
	      set for a given context.	For example,

		     zstyle ':completion:*:complete:dpkg:option--status-1:*' \
				    packageset avail

	      causes available packages, rather than only installed  packages,
	      to be completed for `dpkg --status'.

       path   This  is used together with the the urls tag by completion func‐
	      tions that generate URLs as possible matches.  It should be  set
	      to  the  path  of	 a  directory containing sub-directories named
	      after the retrieval methods which occur as the first part	 of  a
	      URL,   i.e.   `http',  `ftp',  `bookmark',  and  so  on.	 These
	      sub-directories should contain files and	other  sub-directories
	      whose  pathnames	are  possible  completions  after  the initial
	      `http://', `ftp://', etc. See the description in the file	 _urls
	      in  the  User  sub-directory  of	the completion system for more
	      information.

	      The function that completes color names  also  uses  this	 style
	      with  the colors tag.  Here, the value should be the pathname of
	      a file containing color names in the format of  an  X11  rgb.txt
	      file.   If the style is not set but this file is found in one of
	      various standard locations it will be used as the default.

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

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

	      The default value for this style is `false'.

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

	      The default style for this style is `true'.

       prompt The incremental-complete-word widget shows  the  value  of  this
	      style  in	 the  status  line during incremental completion.  The
	      string value may contain any of the following substrings in  the
	      manner of the PS1 and other prompt parameters:

	      %c     Replaced  by the name of the completer function that gen‐
		     erated the matches (without the leading underscore).

	      %l     When the list style is set, replaced by `...' if the list
		     of	 matches  is too long to fit on the screen and with an
		     empty string otherwise.  If the list style is `false'  or
		     not set, `%l' is always removed.

	      %n     Replaced by the number of matches generated.

	      %s     Replaced  by  `-no	 match-',  `-no	 prefix-', or an empty
		     string if there is no completion matching the word on the
		     line, if the matches have no common prefix different from
		     the word on the line, or if there is such a  common  pre‐
		     fix, respectively.

	      %u     Replaced by the unambiguous part of all matches, if there
		     is any, and if it is different from the word on the line.

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

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

       select-scroll
	      This  style  is  tested for the default tag and determines how a
	      completion list is scrolled during  a  menu-selection  (see  the
	      menu  style  above) when the completion list does not fit on the
	      screen as a whole.  Its value should be `0' (zero) to scroll  by
	      half-screenfuls, a positive integer to scroll by that many lines
	      and a negative number to scroll by the number of	lines  of  the
	      screen  minus that number (or plus the number, since it is nega‐
	      tive).  The default is to scroll by single lines.

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

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

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

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

       squeeze-slashes
	      If set to `true', sequences of slashes (as in  `foo//bar')  will
	      be  treated as if they were only one slash when completing path‐
	      names.  This is the usual behaviour of UNIX paths.  However,  by
	      default  the file completion function behaves as if there were a
	      `*' between the slashes.

       stop   If set to `true', the  _history_complete_word  bindable  command
	      will  always  insert  matches as if menu completion were started
	      and will stop when the last match is inserted.  If this style is
	      set to `verbose' a message will be displayed when the last match
	      is reached.

       stop-keys
	      This style is used by the incremental-complete-word widget.  Its
	      value  is treated similarly to the one for the break-keys style.
	      However, in this case all keys matching the pattern given as its
	      value  will  stop	 incremental  completion and will then execute
	      their usual function.

       subst-globs-only
	      This is used by the _expand completer.  As for the  glob	style,
	      the  value should be a value usable in a `$((...))' arithmetical
	      expression.  If it evaluates to `1', 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.

       substitute
	      This style controls whether the _expand completer will first try
	      to expand all substitutions in the string (such as `$(...)'  and
	      `${...}').  It should be set to a number or an non-empty	string
	      which  is	 an expression usable inside a `$((...))' arithmetical
	      expression.  Expansion of substitutions  will  be	 done  if  the
	      expression evaluates to `1'. For example, with

		     zstyle ':completion:*:expand:::' substitute '${NUMERIC:-1} != 1'

	      substitution will be performed only if given an explicit numeric
	      argument other than `1', as by typing `ESC 2 TAB'.

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

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

	      For example:

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

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

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

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

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

	      tag:label ...
		     In	 strings  not starting with an exclamation mark, it is
		     also possible to specify tag labels instead of only tags,
		     where  tag	 is  one of the tags offered by the completion
		     function for the current context and  label  is  a	 name.
		     For  this,	 the completion function will generate matches
		     in the same way as for the tag but it will use the	 label
		     in	 place of the tag in the context names used to look up
		     styles.  If the label starts with a hyphen,  the  tag  is
		     prepended	to the label to form the name used for lookup.
		     This can be used to make the completion system try a cer‐
		     tain  tag	more than once, supplying different style set‐
		     tings for each attempt.  For example,

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

		     This makes completion in command position first try  only
		     names  of	shell  functions  that don't match the pattern
		     `_*'. If that generates no matches, the default of trying
		     all  the  other  things  that can be completed in command
		     position is used, including the names of all shell	 func‐
		     tions.

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

	      func() The function func is called, which can  then  define  the
		     order  in	which  tags are to be used based on additional
		     context information.  See the _sort_tags  function	 below
		     for  a  description  of  how such functions can be imple‐
		     mented.  The return value of  the	function  is  used  to
		     decide  if	 the  following values for the style should be
		     used.  If it  is  zero,  they  are	 used  and  if	it  is
		     non-zero, they are not used.  For example:

			    non-empty() { [[ -n $PREFIX ]] }
			    zstyle ':completion:*:*:-command-:*' tag-order 'non-empty()'

		     Makes  completion	in command position happen only if the
		     string on the line is not empty.  This  is	 tested	 using
		     the  PREFIX parameter which is special in completion wid‐
		     gets; see zshcompwid for a description of	these  special
		     parameters.

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

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

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

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

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

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

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

       The second interesting use of patterns is the case where one  wants  to
       try  multiple match specifications one after another.  The matcher-list
       style offers something similar, but it is tested very early in the com‐
       pletion	system and hence can't be set for single commands nor for more
       specific contexts.  Here is how to try normal  completion  without  any
       match  specification  and, if that generates no matches, try again with
       case-insensitive matching, restricting the effect to arguments  of  the
       command foo:
	      zstyle ':completion:*:*:foo:*' tag-order '*' '*:-case'
	      zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}'

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

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

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

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

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

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

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

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

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

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

	      The default value for this style is `true'.

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

CONTROL FUNCTIONS
       The initialization script compinit redefines all the widgets which per‐
       form completion to call the supplied  widget  function  _main_complete.
       This function acts as a wrapper calling the so-called `completer' func‐
       tions that generate matches.  If _main_complete is  called  with	 argu‐
       ments, these are taken as the names of completer functions to be called
       in the order given.  If no arguments are given, the set of functions to
       try is taken from the completer style.  For example, to use normal com‐
       pletion and correction if that doesn't generate any matches:

	      zstyle ':completion:*' completer _complete _correct

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

       If the first argument to _main_complete is a single hyphen,  the	 argu‐
       ments  will  not	 be  taken as names of completers. Instead, the second
       argument gives a name to use in the completer field of the context  and
       the other arguments give a command anme and arguments to call to gener‐
       ate the matches.

       The following completer functions are  contained	 in  the  distribution
       (users may write their own):

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

		     zstyle ':completion:*' completer _complete _approximate

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

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

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

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

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

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

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

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

	      -command-
		     for completing in a command position.

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

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

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

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

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

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

	      -redirect-
		     for completion after a redirection operator.

	      -subscript-
		     for completion inside subscripts.

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

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

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

	      Before trying to find a function for a specific  context,	 _com‐
	      plete  checks  if	 the  parameter	 `compcontext'	is  set	 to  a
	      non-empty value.	If it is, the value is taken as	 the  name  of
	      the  context  to	use  and the function defined for that context
	      will be called.  For this purpose, there is  a  special  context
	      named  -command-line-  that  completes whole command lines (com‐
	      mands and their arguments) and is not  used  by  the  completion
	      system itself, but has a function handling completion for it.

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

	      For example, with:

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

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

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

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

       _expand
	      This  completer  function	 does  not  really  do completion, but
	      instead checks if the word on the command line is	 eligible  for
	      expansion	 and,  if  it is, gives detailed control over how this
	      expansion is done.  When using this,  one	 should	 not  use  the
	      expand-or-complete  widget,  but	instead	 use complete-word, as
	      expand-or-complete will expand the string on the line before the
	      completion  widget  is  called.	Also, this completer should be
	      called before the _complete completer function.

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

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

	      Which kind of expansion is tried is controlled  by  the  substi‐
	      tute, glob and subts-globs-only styles.  Note that none of these
	      has a default value so that they have to be set to make  _expand
	      generate any expansions at all.

	      There  is	 another  style,  completions, which allows _expand to
	      display or insert all completions generated for the string.  The
	      use  of  this is that the tags expansions and all-expansions are
	      available, unlike with _complete.

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

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

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

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

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

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

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

	      The  generated  matches  will  be	 offered  in a menu completion
	      unless the insert-unambiguous style is set to `true'.   In  this
	      case  menu  completion  will  only  be started if no unambiguous
	      string could be generated that is at least as long as the origi‐
	      nal string.

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

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

       _oldlist
	      This completer controls  how  the	 standard  completion  widgets
	      behave  when  there is an existing list of completions which may
	      have been generated  by  a  special  completion  (i.e.  a	 sepa‐
	      rately-bound  completion	command).  It allows the ordinary com‐
	      pletion keys to continue to use the  list	 of  completions  thus
	      generated,  instead  of producing a new list of ordinary contex‐
	      tual completions.	 It should appear in the  list	of  completers
	      before  any  of the widgets which generate matches.  It uses two
	      styles: old-list and old-menu, see the section `Completion  Sys‐
	      tem Configuration' above.

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

	      For example, consider this global completer style:

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

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

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

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

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

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

       _bash_completions
	      This function is used by two  widgets,  _bash_complete-word  and
	      _bash_list-choices.   It	exists	to  provide compatibility with
	      completion bindings in bash.  The last character of the  binding
	      determines  what is completed: `!', command names; `$', environ‐
	      ment variables; `@', host	 names;	 `/',  file  names;  `~'  user
	      names.  In bash, the binding preceeded by `\e' gives completion,
	      and preceeded by `^X' lists options.  As some of these  bindings
	      clash with standard zsh bindings, only `\e~' and `^X~' are bound
	      by default.  To add the rest, the following should be  added  to
	      .zshrc after compinit has been run:

		     for key in '!' '$' '@' '/' '~'; do
		       bindkey "\e$key" _bash_complete-word
		       bindkey "^X$key" _bash_list-choices
		     done

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

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

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

       _expand_word (^Xe)
	      Performs expansion on the current word:  equivalent to the stan‐
	      dard expand-word	command,  but  using  the  _expand  completer.
	      Before calling it, the function field is set to `expand-word'.

	      Unlike  _expand  this  uses a `1' (one) as the default value for
	      the substitute and glob styles, so both types of expansion  will
	      normally be performed.

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

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

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

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

	      Second, any other string will be passed as a set of arguments to
	      compadd and should hence be an expression specifying what should
	      be completed.

	      A very restricted set of	editing	 commands  is  available  when
	      reading  the  string:  `DEL' and `^H' delete the last character;
	      `^U' deletes the line, and `^C' and  `^G'	 abort	the  function,
	      while  `RET'  accepts  the  completion.  Note the string is used
	      verbatim as a command line,  so  arguments  must	be  quoted  in
	      accordance with standard shell rules.

	      Once  a  string  has been read, the next call to _read_comp will
	      use the existing string instead of reading a new one.  To	 force
	      a	 new  string  to be read, call _read_comp with a numeric argu‐
	      ment.

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

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

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

UTILITY FUNCTIONS
       Descriptions follow for utility functions that may be useful when writ‐
       ing completion functions.  Most of these reside in the  Core  subdirec‐
       tory.  Like the example functions for commands in the distribution, the
       utility functions generating  matches  all  follow  the	convention  of
       returning  zero if they generated completions and non-zero if no match‐
       ing completions could be added.

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

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

	      For example:

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

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

       _alternative [ -C name ] specs ...
	      This  function is useful in simple cases where multiple tags are
	      available.  Essentially, it  implements  a  loop	like  the  one
	      described for the _tags function above.

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

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

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

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

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

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

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

	      n:message:action
	      n::message:action
		     This describes the n'th  normal  argument.	  The  message
		     will  be  printed	above  the  matches  generated and the
		     action says what can be completed in this	position  (see
		     below).  If there are two colons before the message, this
		     describes an optional argument.

	      :message:action
	      ::message:action
		     Like the previous one, but describing the next  argument.
		     I.e.  if you want to describe all arguments a command can
		     get, you can leave out the numbers in the description and
		     just  use this form to describe them one after another in
		     the order they have to appear on the line.

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

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

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

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

		     The forms of optspec are:

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

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

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

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

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

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

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

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

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

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

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

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

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

	      :message:action
	      ::message:action
		     Describes a mandatory argument  with  one	colon,	or  an
		     optional  argument with two colons.  As in other forms of
		     spec, the message will be printed above the matches  gen‐
		     erated  and the action says what can be completed in this
		     position.

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

		     When  the	message	 is  preceded by two colons, the words
		     special array and the CURRENT special parameter are modi‐
		     fied  during the execution or evaluation of the action to
		     refer only to the words after the option.	When  preceded
		     by	 three	colons, they are modified to refer only to the
		     words covered by this description.

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

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

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

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

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

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

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

	      :foo:(foo bar baz)

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

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

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

       An action of the form `->string' is used by functions that implement  a
       state machine. In this case, the `string's (with all leading and trail‐
       ing spaces and tabs removed) of all actions that have to be  used  will
       be  stored  in  the  global array state and the function returns with a
       return value of 300 (to make it distinguishable from other return  val‐
       ues)  after setting the global `context', `line' and `opt_args' parame‐
       ters as described below, and without resetting any changes made to  the
       special parameters such as PREFIX and words.

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

	      local context state line
	      typeset -A opt_args

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

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

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

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

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

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

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

       For example:

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

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

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

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

       To  simplify the specifications for commands with standard option pars‐
       ing, the options -A and -S may be given. With -A	 no  options  will  be
       completed  after the first non-option argument on the line. With -S, no
       option will be completed after a `--' on the  line  and	this  argument
       will otherwise be ignored.

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

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

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

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

	      local curcontext="$curcontext"

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

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

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

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

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

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

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

       Example:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

	      The descr is taken as a string to display above the  matches  if
	      the  format  style  for the descriptions tag is set.  After this
	      come one or two names of arrays followed by options to  pass  to
	      compadd.	The first array contains the possible completions with
	      their descriptions in the form `completion:description'.	 If  a
	      second  array  is	 given, it should have the same number of ele‐
	      ments as the first one and the corresponding elements are	 added
	      as  possible  completions instead of the completion strings from
	      the first array.	The completion list will retain	 the  descrip‐
	      tions  from  the	first  array.	Finally,  a  set of completion
	      options can appear.

	      If the option  `-o'  appears  before  the	 first	argument,  the
	      matches added will be treated as option names (typically follow‐
	      ing a `-', `--'  or  `+'	on  the	 command  line).   This	 makes
	      _describe	 use  the  prefix-hidden,  prefix-needed  and  verbose
	      styles to find out if the strings should be added at all and  if
	      the descriptions should be shown.	 Without the `-o' option, only
	      the verbose style is used.

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

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

	      The string returned by the format style (if any) will  be	 modi‐
	      fied so that the sequence `%d' is replaced by the descr given as
	      the third argument.  If _description is called  with  more  than
	      three  arguments,	 the  additional  specs	 should be of the form
	      `char:str' and every appearance of `%char' in the format	string
	      will be replaced by string.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       _parameters
	      This  should be used to complete parameter names.	 All arguments
	      are passed unchanged to the compadd builtin.

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

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

	      The options accepted by both _path_files and _files are:

	      -f     Complete all filenames.  This is the default.

	      -/     Specifies that only directories should be completed.

	      -g pattern
		     Specifies that only files matching the pattern should  be
		     completed.

	      -W paths
		     Specifies	path  prefixes that are to be prepended to the
		     string from the line to generate the filenames  but  that
		     should  not be inserted in the line or shown in a comple‐
		     tion listing.  Here, paths may be the name	 of  an	 array
		     parameter,	 a literal list of paths enclosed in parenthe‐
		     ses or an absolute pathname.

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

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

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

       _options
	      This  can	 be used to complete option names.  It uses a matching
	      specification that ignores a leading `no',  ignores  underscores
	      and  allows the user to type upper-case letters which will match
	      their lower-case counterparts.  All  arguments  passed  to  this
	      function are propagated unchanged to the compadd builtin.

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

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

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

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

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

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

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

	      ( spec )
		     This groups specs.

	      spec # This allows any number of repetitions of spec.

	      spec spec
		     This represents the concatenation of two specs.

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

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

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

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

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

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

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

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

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

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

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

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

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

       _sort_tags tag ...
	      No such function is actually used by the completion  system;  as
	      mentioned	 above for the tag-order style, it is only provided to
	      show how functions that sort tags can be implemented.

	      Inside such functions the name of the  current  context  can  be
	      accessed using the curcontext parameter.	For example, the func‐
	      tion used in command position  (called  _command_names)  in  the
	      completion  can generate names of external and builtin commands,
	      names of shell functions, aliases and  parameters	 and  reserved
	      words.

	      Example:

		     _sort_tags() {
		       case $curcontext in
		       (*:-command-:*)
			 comptry commands functions
			 comptry builtins aliases
			 ;;
		       (*)
			 .comptry "$@"
			 ;;
		       esac
		       return 1
		     }

	      Every call to the comptry builtin command gives a set of tags to
	      use; as soon as the completion system produces matches  for  one
	      set,  subsequent sets have no effect.  Hence in the example this
	      means that in command position on the first attempt  only	 names
	      of  external commands and shell functions will be generated (the
	      first call to comptry).  If none of those names match the string
	      from  the	 command  line	the  completion function will generate
	      names of builtin commands and aliases as possible	 matches  (the
	      second call to comptry).

	      For  all other context names the second case-pattern matches, so
	      that  normally  the  completion  functions  will	try  all  tags
	      offered.	The  return  value  means  that	 the calling function,
	      _tags, will not use all offered tags as a	 default,  so  in  the
	      first  case names or parameters and reserved words will never be
	      completed.

	      In any context the function may call comptry as often as	neces‐
	      sary.   Also, any string may be given as an argument, even if no
	      tag with that name was offered by the completion function.  This
	      allows one to give a preferred ordering for some common tag sets
	      without having to worry  about  sensible	patterns  for  context
	      names.  For example, many completion functions can generate both
	      arguments and option names for commands.	These  functions  nor‐
	      mally  use  the  tags  like  argument-num,  option-name-num  and
	      options.	Depending on your preference you  may  write  in  your
	      sorting function:

		     _sort_tags() {
		       comptry -m '(|*-)argument-* (|*-)option-* options'
		       case $curcontext in
		       ...
		       esac
		     }

	      or

		     _sort_tags() {
		       comptry -m '(|*-)argument-* (|*-)option-*'
		       comptry options
		       case $curcontext in
		       ...
		       esac
		     }

	      The former always adds both the matches for the argument and the
	      option names as possible matches.	 The latter forces matches for
	      the  arguments  to  be preferred.	 In this case option names are
	      only generated as matches if the string on the line produces  no
	      possible	completion  for	 arguments; normally you would have to
	      type the hyphen the option names start with yourself in order to
	      see the list of option names that can be completed.

	      With  the	 -s option, each tag given to comptry will be put in a
	      separate set. With the -m option, the arguments are  treated  in
	      the  same	 way as the the values for the tag-order style (except
	      for the `!...', `-' and `foo()' forms).

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

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

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

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

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

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

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

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

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

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

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

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

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

	      Example:

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

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

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

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

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

		     local context state line
		     typeset -A val_args

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

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

COMPLETION DIRECTORIES
       In  the	source distribution, the files are contained in various subdi‐
       rectories of the Completion directory.  They may have been installed in
       the same structure, or into one single function directory.  The follow‐
       ing is a description of the  files  found  in  the  original  directory
       structure.   If	you  wish to alter an installed file, you will need to
       copy it to some directory which appears earlier in your fpath than  the
       standard directory where it appears.

       Core   The  core scripts and functions.	You will certainly need these,
	      though will probably not need to alter them.  Many of these  are
	      documented above.

       Base   Other  functions you will almost certainly want if you are going
	      to use any of the standard completion functions.	You  may  want
	      to edit some of these files.

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

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

       Commands
	      Functions which implement special	 types	of  completion	to  be
	      bound to keystrokes rather than called by context.

zsh 3.1.9			 June 5, 2000			 ZSHCOMPSYS(1)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Tru64

List of man pages available for Tru64

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

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

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