Unix/Linux Go Back    

RedHat 9 (Linux i386) - man page for zshcompsys (redhat section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


       zshcompsys - zsh completion system

       This describes the shell code for the new completion system.  It consists 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'.

       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 section by hand is likely to be lost if you rerun compin-
       stall, 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 immediately.  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 mentioned 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 installation any
       time you are being prompted for information, and your .zshrc will not be altered  at  all;
       changes	only  take place right at the end, where you are specifically asked for confirma-

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

       To initialize the system, the function compinit should be in a directory mentioned in  the
       fpath  parameter,  and  should  be autoloaded (`autoload -U compinit' is recommended), and
       then run simply as `compinit'.  This will define a few utility functions, arrange for  all
       the  necessary  shell functions to be autoloaded, and will then re-define all widgets that
       do completion to use the new system.  If you use the menu-select widget, which is part  of
       the  zsh/complist  module, you should make sure that that module is loaded before the call
       to compinit so that that widget is also re-defined.  If completion styles (see below)  are
       set  up to perform expansion as well as completion by default, and the TAB key is bound to
       expand-or-complete, compinit will rebind it to complete-word; this is necessary to use the
       correct form of expansion.

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

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

       If  the number of completion files changes, compinit will recognise this and produce a new
       dump file.  However, if the name of a function or the arguments in the  first  line  of	a
       #compdef  function  (as	described below) change, it is easiest to delete the dump file by
       hand so that compinit will re-create it the next time it is run.  The check  performed  to
       see  if	there are new functions can be omitted by giving the option -C.  In this case the
       dump file will only be created if there isn't one already.

       The dumping is actually done by another function, compdump, but you will only need to  run
       this  yourself  if you change the configuration (e.g. using compdef) and then want to dump
       the new one.  The name of the old dumped file will be remembered for this purpose.

       If the parameter _compdir is set, compinit uses it as a directory where	completion  func-
       tions  can be found; this is only necessary if they are not already in the function search

       For security reasons compinit also checks if the completion system  would  use  files  not
       owned  by  root	or  by	the  current  user,  or  files	in directories that are world- or
       group-writable or that are not owned by root or by the current user.   If  such	files  or
       directories  are  found, compinit will ask if the completion system should really be used.
       To avoid these tests and make all files found be used without asking, use the  option  -u,
       and to make compinit silently ignore all insecure files and directories use the option -i.
       This security check is skipped entirely when the -C option is given.

       The security check can be retried at any time by running the function compaudit.  This  is
       the same check used by compinit, but when it is executed directly any changes to fpath are
       made local to the function so they do not persist.  The directories to be checked  may  be
       passed  as arguments; if none are given, compaudit uses fpath and _compdir to find comple-
       tion system directories, adding missing ones to fpath as necessary.  To force a	check  of
       exactly	the  directories currently named in fpath, set _compdir to an empty string before
       calling compaudit or compinit.

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

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

       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 argu-
	      ments are to be completed or one of a number of special contexts in the form  -con-
	      text- described below for the _complete function.

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

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

       #compdef -P pattern
	      Like  the previous one, but the function will be called only if no completion func-
	      tion 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  speci-
	      fied.   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-complete.  If the zsh/complist  module  is
	      loaded (see zshmodules(1)), the same happens to the menu-select widget.

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

       #compdef -K widget-name style key-sequences ...
	      This is similar to -k, with the same style and key-sequences arguments, preceded by
	      a string giving the name of a widget.  In this case only one key-sequences argument
	      may  be given, but the entire set of three arguments may be repeated with a 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  use-
	      ful.  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 immedi-
	      ately.  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 zcom-
       pile  -z to load the functions for the completion system; see zshbuiltins(1).  This forces
       the functions to be autoloaded the way zsh normally loads functions.

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

       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 complet-
	      ing for the contexts or commands whose names are given:  this is like the  #compdef
	      tag  unless  the first word contains an equal sign.  In this case all words have to
	      be of the form `cmd=service' where service is the name of a command or of a service
	      defined by an autoloaded function with the #compdef tag and an argument of the form
	      `cmd=service'.  This kind of use makes the arguments of the cmds	be  completed  as
	      those for the services.

	      If  the  -n  option is given, any existing completion behaviour for particular con-
	      texts 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 com-
	      mands 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 _comp-
	      skip 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 func-
	      tion 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-com-
	      plete-prefix,    list-choices,	menu-complete,	  menu-expand-or-complete,    and
	      reverse-menu-complete, 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  func-
	      tion,  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 beginning with an underscore.

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

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

	      compdef _pids foo

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

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

       When completion is attempted somewhere on 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 completing an argument, and possibly  also	the  name  of  an
       option when completing 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  pos-
       sible  to  build the whole context string in advance, completion functions may modify some
       of the fields and hence the context used for lookup may vary during the same call  to  the
       completion system.

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

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

       o      The  function; in many cases this field will be blank, but when the completion sys-
	      tem is called from other functions, like predict-on or one of the functions in  the
	      Command  directory  of the distribution, this field contains the name of that func-
	      tion, often in an abbreviated form.

       o      The completer currently active, which is the name of the function without the lead-
	      ing  underscore.	 A  `completer'  is in overall control of how completion is to be
	      performed; `complete' is the basic one for ordinary completion, but completers  may
	      perform  various	related  tasks	such  as correction, or modify the behaviour of a
	      later completer (see the section `Control Functions' below for more information).

       o      The context or command.  This is either one of the special context  names  such  as
	      -condition- as explained for the _complete completer below, or the name of the com-
	      mand 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  com-
	      mand  sets  this	field  to  strings  such  as  cvs-add when completing for the add

       o      The argument, describing which argument we are completing.  Normally 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

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

       As an example, the context name


       says that normal completion was attempted on an argument of the dvips command  (more  pre-
       cisely:	completion  was attempted on the first argument after the -o option) and the com-
       pletion function will generate filenames for this context.

       In many of the possible contexts the completion system can generate matches, often  multi-
       ple  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  possibilities	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 particular completion in

       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 informa-
       tion 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 completion), 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

       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

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

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

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

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

       Note that the order in which styles are defined does not matter; the style mechanism  uses
       the  most  specific  possible match for a particular style to determine the set of values.
       More precisely, strings are  preferred  over  patterns  (for  example,  `:completion::com-
       plete: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 com-
       plete  list.  However, the following two sections list those tags and styles that are used
       in many places of the completion 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 particular type of match.

	      used to look up the users-hosts style

	      used by the _expand completer when adding the single string containing all possible

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

	      when an argument of a command may be completed

       arrays for names of array parameters

	      for keys of associative arrays; used when completing inside a subscript of a param-
	      eter of this type

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

	      for names of builtin commands

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

	      for X colormap ids

       colors for color names

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

	      for contexts used by the zstyle builtin command

	      used by the _approximate and _correct completers for the possible corrections

	      for cursor names used by X programs

	      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

	      used when looking up the value of the format style for descriptions

	      for names of device special files

	      for names of directories

	      for entries in the directory stack

	      for X display names

	      for network domains

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

	      for X server extensions

	      for the numbers of open file descriptors

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

       fonts  used for X font names

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

	      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

	      for words from the history

       hosts  for hostnames

	      used for array indexes

       jobs   used for jobs

	      for names of zsh keymaps

	      for names of X keysyms

	      for names of system libraries

       limits for system limits

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

	      for names of manual pages

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

	      used to look up the format style for messages

	      for names of X modifiers

	      for modules (e.g. zsh modules)

	      used to look up the users-hosts style

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

       names  for all kinds of names

	      for nicknames of NIS maps

	      for command options

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

	      used to look up the users-hosts style

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

	      for names of parameters

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

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

       pods   for perl pods (documentation files)

       ports  for communication ports

	      for prefixes (like those of a URL)

	      for printer names

	      for process identifiers

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

	      for sequences (e.g. mh sequences)

	      for sessions in the zftp function suite

	      for signal names

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

       styles for styles used by the zstyle builtin command

       tags   for tags (e.g. rpm tags)

	      for makefile targets

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

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

       users  for usernames

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

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

	      used to look up the format style for warnings

	      for zsh widget names

	      for IDs of X windows

	      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	undefined
       unless the description for the particular style mentions other possible values; in partic-
       ular, 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 func-
       tion field of the context will be set up, so the default value will normally be set like:

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

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

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

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

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

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

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

	      When completing after an equals sign, the completion system normally completes only
	      one filename.  In some cases, particularly for certain parameters such as  PATH,	a
	      list of filenames separated 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

	      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.
	      Depending on personal preferences, it may be useful to set this style to	something
	      like `specify: %d'.  Note that this may not work for some commands.

	      This  is	used  by the _all_matches completer to decide if the string consisting of
	      all matches should be added to the list currently being generated.  Its value is	a
	      list  of	names  of  completers.	If any of these is the name of the completer that
	      generated the matches in this completion, the string will not be added.

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

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

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

	      In many places, completion functions need to call external commands 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  command line to execute.  The value can also start with a hyphen, in which
	      case the usual command will be added to the end; this is most  useful  for  putting
	      `builtin'  or  `command' in front to make sure the appropriate version of a command
	      is called, for example to avoid calling a shell function with the same name  as  an
	      external command.

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

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

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

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

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

	      Each  string may be the name of a completer function or a string of the form `func-
	      tion: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 con-
	      text.  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  `func-
	      tions: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

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

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

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

	      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

	      If set, gives the names of network domains that should be completed.   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 multiple parts, such as
	      path names.  If one of its values is the string `prefix', the partially typed  word
	      from  the line will be expanded as far as possible even if trailing parts cannot be
	      completed.  If one of its values is the string `suffix', matching names for  compo-
	      nents  after  the  first	ambiguous  one	will  also be added.  This means that the
	      resulting string is the longest unambiguous string possible, but if menu completion
	      is  started on the list of matches generated this way, this will also cycle through
	      the names of the files in pathname components after the first ambiguous one.

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

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

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

	      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', depend-
	      ing 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  contain  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  specifica-
	      tions  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  sup-
	      plied  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

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

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

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

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

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

	      The  completion  function  that  generates  filenames as possible matches uses this
	      style without a tag to determine in which order the names should be listed and com-
	      pleted  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 decreasing order.

	      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 sin-
	      gle  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 listing on for certain types of matches.

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

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

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

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

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

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

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

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

	      The  completion system can put different types of matches in different 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 com-
	      mands,  names of aliases, shell functions and parameters and reserved words as pos-
	      sible completions.  To have the external commands and shell functions listed  sepa-
	      rately, 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

	      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 com-
	      mands 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 completed. 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 possible 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.

	      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.

	      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 pos-
	      sible completions.  If it is set to `current', the word the cursor is on	will  not
	      be  considered  a  possible  completion.	 The  same  happens if the value is `cur-
	      rent-shown', but only if the list of completions is currently shown on the  screen.
	      Finally,	if it is set to `other' all words except the current one will not be con-
	      sidered to be a possible completion.

	      The  values  `current'  and  `current-shown'  are  a  bit  like  the  opposite   of
	      accept-exact.  They  mean  that  only  strings with missing characters will be com-

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

	      The style is tested by the function completing pathnames without a tag to determine
	      whether to ignore the names of directories already mentioned in the  current  word,
	      or  the  name of the 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

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

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

		     Ignore  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

	      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 possibilities.  The _ignored completer can appear in the
	      list of completers to produce a list which includes these matches once more.   This
	      is a more configurable version of the shell parameter $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  pat-

	      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 possible IDs, and menu completion
	      will be started to cycle through them.  If the value of the style is `single', how-
	      ever,  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 char-
	      acters 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  corre-
	      sponding IDs.

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

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

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

	      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 _approxi-
	      mate completer uses it after setting the completer field in the context name to one
	      of  correct-num  or  approximate-num,  where  num is the number of errors that were

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

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

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

	      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 cursor
	      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 command.  If it is set to
	      `true'  it  has  no  effect,  but  if  it is set to `false' the matches will not be
	      listed, overriding the setting of the options that control listing behaviour, espe-
	      cially AUTO_LIST. Use the context prefix `:completion:history-words'.

	      If  the zsh/complist module is used, this style can be used to set color specifica-
	      tions as with the ZLS_COLORS and ZLS_COLOURS parameters, which will not be  honored
	      under  this completion system (see the section `The zsh/complist Module' in zshmod-

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

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

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

	      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.

	      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  zshmod-
	      ules(1)).   The  value,  if  not	the  empty  string, will be displayed after every
	      screenful and the shell will prompt for a key press; if the style  is  set  to  the
	      empty  string,  a  default  prompt  will be used.  The value may contain the escape
	      sequences `%l' or `%L', which will be replaced by the number of the last line  dis-
	      played  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 leav-
	      ing the display modes standout, bold and underline are also available.

	      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 fashion, as for the LIST_ROWS_FIRST

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

       local  This  style is used by completion functions which generate URLs as possible matches
	      to add suitable matches when a URL points to a local web server, that is, one whose
	      files are available directly on the local file system.  Its value should consist of
	      three strings: a hostname, the path to the default web pages for the server and the
	      directory  name used by a user placing web pages within their home area.	For exam-
	      ple, 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  com-

	      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 `*'

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

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

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

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

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

	      The style allows even finer control by specifying a particular  completer,  without
	      the leading underscore, in the third field of the completion context.  For example,
	      if one uses the completers _complete and _prefix but wants to try  case-insensitive
	      completion 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  partial-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 _approximate do not use the	match  specifica-
	      tions 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 specifica-
	      tions will only ever be called once, rather than once per specification.

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

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

	      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 exam-
	      ple, 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 gen-
	      erate corrected completions when given a numeric argument, so in this case the num-
	      ber 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	behaviour
	      will  be	as for the AUTO_MENU option.  Finally, if one of the values is explicitly
	      set to false, menu completion will be turned off even  if  it  would  otherwise  be
	      active (for example, with the MENU_COMPLETE option).

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

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

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

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

	      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 differ in the first word on  their  com-
	      mand lines.

	      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 completion list is generated; this is the default behaviour
	      of  _oldlist.  However, if there is an old list and this style contains 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 widget, which generates
	      a list of corrections for the word under the cursor.  Usually, typing ^D would gen-
	      erate  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  gener-

	      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
	      produce more matches than on the first attempt.  By using  the  _oldlist	completer
	      and  setting  this  style  to  _match,  the  list of matches generated on the first
	      attempt will be used again.

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

	      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 comple-
	      tion key type such as TAB.  The default behaviour of _oldlist is that menu  comple-
	      tion  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 com-

	      For example, suppose you type ^Xc to generate a list of corrections, and menu  com-
	      pletion  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 correc-

	      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 com-
	      pleter field in the context name to correct-num or approximate-num,  where  num  is
	      the number of errors that were accepted.

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

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

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

       path   The  function  that completes color names uses this style with the colors tag.  The
	      value should be the pathname of a file 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.

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

	      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 completed at all.

	      The default value for this style is `true'.

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

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

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

	      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

	      If this is set for the default tag, its value will be displayed during menu  selec-
	      tion (see the menu style above) when the completion 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.

	      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 negative).  The default is to scroll by single

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

	      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 comple-
	      tion 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 pos-
	      sible  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).

	      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 completions; if it is set to `..', only `..' will be added.

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

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

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

	      The default for this style is `false'.

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

	      The default is `true'.

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

	      This provides a mechanism for sorting how the tags available in a  particular  con-
	      text 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-patterns 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 immediately.

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

	      -      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 con-
		     text 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 certain tag more than once, supply-
		     ing different style settings for each attempt, see below for an example.

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

       In each of the cases above, the tag may also be a pattern or more than one pattern  inside
       braces  and  separated  by commas.  In this case all of the offered tags matching the pat-
       tern(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
       underscore 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 possible 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 func-
       tions 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 completion system and hence can't be set for  single  commands
       nor  for  more  specific contexts.  Here is how to try normal completion without any match
       specification and, if that generates no matches, try again with case-insensitive matching,
       restricting the effect to arguments of the command foo:
	      zstyle ':completion:*:*:foo:*' tag-order '*' '*:-case'
	      zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}'

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

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

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

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

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

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

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

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

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

	      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 com-
	      mand.  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  spe-
	      cific completion function for the command in question.  For example, while complet-
	      ing arguments to the command foo, if this was handled by a command  function  _foo,
	      compctl would never be tried, while if it was handled by _default, compctl would be

       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.

	      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

	      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.

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

	      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 insertion 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 performed on another word with the same
	      contents, completion will not be delayed.

       The initialization script compinit redefines all the widgets which perform  completion  to
       call the supplied widget function _main_complete.  This function acts as a wrapper calling
       the so-called `completer' functions that generate matches.  If  _main_complete  is  called
       with  arguments,  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 completion 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  com-
       pleter  functions  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  arguments  will  not  be
       taken as names of completers. Instead, the second argument gives a name to use in the com-
       pleter field of the context and the other arguments give a command name and  arguments  to
       call to generate the matches.

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

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

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

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

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

	      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 num-
	      ber 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 completer by setting:

		     zstyle ':completion:*' completer _complete _approximate

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

	      This  completer uses the tags corrections and original when generating 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.
	      _approximate 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 sec-
	      ond try `approximate-2', and so on.

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

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

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

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

	      This  completer  generates  all possible completions in a context-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 be-

	      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:

		     for completion on the right hand side of an array-assignment (`foo=(...)').

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

		     for completing in a command position.

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

		     for generating completions when no special completion function is used.

		     for completion of words beginning with an equals sign

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

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

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

		     for completion after a redirection operator.

		     for completion inside subscripts.

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

		     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, _complete  checks  if  the
	      parameter  `compcontext'	is set.  If it is set to an array, the elements are taken
	      to be the possible matches which will be completed using the tag `values'  and  the
	      description  `value'.    If it is set to an associative array, the keys are used as
	      the possible completions and the values (if non-empty) are used as descriptions for
	      the  matches.   If `compcontext' is set to a string containing colons, it should be
	      of the form `tag:descr:action'.  In this case the tag and descr give  the  tag  and
	      description to use and the action says what should be completed in one of the forms
	      described for the _arguments utility function below.

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

	      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	_approxi-
	      mate 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, correc-
	      tion will not be performed, but correcting completion 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 accept-
	      ing 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.

	      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 contain-
	      ing all possible expansions, expansions when adding the possible expansions as sin-
	      gle  matches  and original when adding the original string from the line.  In which
	      order these strings are generated and which of these strings are generated  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  contain  the  sequence
	      `%o' which will be replaced by the original string from the line.

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

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

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

	      This  function  is  also	a  bindable  command, see the section `Bindable Commands'

	      Complete words  from  the  shell's  command   history.   This  completer	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 Sys-
	      tem Configuration' above.

	      The  ignored-patterns  style  can  be  set to a list of patterns which are compared
	      against possible completions; matching ones are removed.	With this completer those
	      matches can be reinstated, 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 generated.	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 con-
	      dition and word, see the section `Completion System Configuration' above.

       _match This  completer is intended to be used after the _complete completer. 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 resulting pattern with the possible comple-
	      tions 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-unam-
	      biguous style is set to `true'.  In this case menu completion will only be  started
	      if  no unambiguous string could be generated that is at least as long as the origi-
	      nal string.  The style may also be set to the string `pattern'.  This will keep the
	      pattern  on  the	line intact as long as there isn't an unambiguous completion with
	      which it could be replaced.

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

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

	      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	separately-bound  completion command).	It allows the ordinary completion
	      keys to continue to use the list of completions thus generated, instead of  produc-
	      ing a new list of ordinary contextual 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 System Configuration' above.

	      This  completer can be used to try completion with the suffix (everything after the
	      cursor) ignored.	In other words, the suffix 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 generate matches.  If this
	      style  is  unset,  the  list  of	completers set for the current context is used --
	      except, of course, the _prefix completer itself.	Furthermore,  if  this	completer
	      appears  more than once in the list of 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 com-
	      pleter after it, _prefix will be called a second time and, now only trying  correc-
	      tion  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; oth-
	      erwise, the cursor will be moved to the end of the current word before the  comple-
	      tion code is called and hence there will be no suffix.

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

	      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;  `$',
	      environment  variables; `@', host names; `/', file names; `~' user names.  In bash,
	      the binding preceded by `\e' gives completion, and preceded by `^X' lists  options.
	      As  some	of  these bindings clash with standard zsh bindings, only `\e~' and `^X~'
	      are bound by default.  To add the rest, the following should  be	added  to  .zshrc
	      after compinit has been run:

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

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

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

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

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

	      When used as a bindable command  there  is  one  additional  feature  that  can  be
	      selected	by setting the complete style to `true'.  In this case, if the word isn't
	      the name of an alias, _expand_alias tries to complete the word to a full alias name
	      without  expanding  it (but leaving the cursor directly after the completed word so
	      that invoking _expand_alias once more will expand the now-complete alias name).

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

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

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

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

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

       _next_tags (^Xn)
	      This command alters the set of matches used to that for the next	tag,  or  set  of
	      tags,  either  as  given by the tag-order style or as set by default; these matches
	      would otherwise not be available.  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  func-
	      tion  name  will	be completed automatically (normal 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 argument.

       _complete_debug (^X?)
	      This  widget performs ordinary completion, but captures in a temporary file a trace
	      of the shell commands executed by the completion system.	Each  completion  attempt
	      gets its own file.  A command to view each of these files is pushed onto the editor
	      buffer stack.

       _complete_help (^Xh)
	      This widget displays information about the context names, the tags, and the comple-
	      tion  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 infor-
	      mation available from the completion functions called, which in turn is  determined
	      by the user's own styles and other settings.

       _complete_tag (^Xt)
	      This  widget  completes  symbol tags created by the etags or ctags programmes (note
	      there is no connection with the completion system'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 $TAGSFILE or $tagsfile  respectively.   The  corresponding
	      completion tags used are etags and vtags, after emacs and vi respectively.

       Descriptions follow for utility functions that may be useful when writing completion func-
       tions.  Most of these reside in the Base subdirectory. Like the example functions for com-
       mands in the distribution, the utility functions generating matches all follow the conven-
       tion of returning zero if they generated completions and non-zero if no	matching  comple-
       tions could be added.

       When  writing  completion functions or other ZLE widgets that call completion, 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 functions  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 auto-
	      matically be inserted into the args given to the command.  Normally, they  are  put
	      directly	after  the  command,  but if one of the args is a single hyphen, they are
	      inserted directly before that. If the hyphen is the last	argument,  that  will  be
	      removed  from  the  argument  list  before  the  command	is  called.  This  allows
	      _all_labels to be used in almost all cases where the matches can be generated by	a
	      single call to the compadd builtin command or by a call to one of the utility func-

	      For example:

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

	      Will complete the strings from the matches parameter, using compadd 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.  Essen-
	      tially, 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 _arguments 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' \

	      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 different name for the
	      argument context field.

       _arguments [ -ACS ] [ -O name ] [ -M matchspec ] spec ...
	      This function can be used to complete words on the line by describing  the  options
	      and arguments which may be passed to the command for which completion is being per-
	      formed.  The description is given as arguments to this  function,  with  each  spec
	      describing  one option or normal argument of the command.  The forms of spec under-
	      stood are:

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

		     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.

		     This describes how arguments (usually non-option arguments, those not begin-
		     ning  with  -  or +) are to be completed when no description with one of the
		     first two forms was given. This also means that any number of arguments  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 message
		     they are modified to refer only to the  normal  arguments	covered  by  this

	      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 brackets are not themselves part of
		     this format.  If brackets are used,  they	are  part  of  the  optspec;  see

		     In  the descriptions below, the option names represented by optname are nor-
		     mally taken to be multi-character names, and a word from the line is consid-
		     ered  to  contain	only  one  option  (or none).  By giving the -s option to
		     _arguments before the first spec, each optname is considered 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-letter options together  with  such  long
		     option names.

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

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

		     The forms of optspec are:

			    If the option may be given more than once, a star (`*') must be added
			    in front of one of the following 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.

			    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

			    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.

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

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

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

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

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

			    The  verbose  style  is  used  to decide 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 fol-
			    lows 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 following forms:

		     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 generated (unless it contains only white space, see  above)  and
		     the action says what can be completed in this position.

		     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  completed  using  the

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

		     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  pre-
       ceded by a backslash, as `\:'.

       Each of the six forms of spec (yes, there are six, keep track of the nestings) may be pre-
       ceded by a list of option names and argument numbers 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 specification of the form `*:...')  should  not
       be  used,  a colon (:) to specify that the descriptions for all normal (non-option-) argu-
       ments should not be used and a hyphen (-) to specify that the descriptions for all options
       should not be used.  This paragraph desperately needs rewriting.

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

       In every case above, the action determines how the possible completions should  be  gener-
       ated.   In places where no sensible matches can be generated, 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 explic-
       itly 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 com-
       plete 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 trailing spaces and tabs	removed)  of  all
       actions	that  have  to	be  used  will be stored in the global array state.  The function
       returns with a non-zero return value if the cursor is not in a position where options  can
       be  completed  or  if the current word could not be completed to an option.  But if the -R
       option is given to _arguments, the function will instead return with a return value of 300
       (to  make it distinguishable from other return values) after setting the global `context',
       `line' and `opt_args' parameters as described below, and  without  resetting  any  changes
       made  to  the special parameters such as PREFIX and words.  This enables wrapper functions
       around _arguments to be able to find out if they have to make sure that the  special  com-
       pletion parameters are not reset when they return.

       Note  that this means that a function calling _arguments with at least one action contain-
       ing 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 parameters.

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

       If  the	action	starts	with  `=  ' (an equals sign followed by a space), _arguments will
       insert the contents of the argument field of the current 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 modify 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 element 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 second _argu-
       ments) to be the command name and hence ignored.

       During the evaluation or execution of the action the array `line' will be set to the  com-
       mand  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, separated 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  cre-
       ated context names. These are either strings of the form `option-opt-n' for the n'th argu-
       ment 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 completing 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 curcontext 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  sepa-
       rated  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

       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 completions. 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 specifications in the same set. This is useful for defining mul-
       tiple 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)' \

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

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

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

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

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

	      local curcontext="$curcontext"

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

       For  such automatically found options that get an argument after an `=', the function also
       tries to automatically find out what should be completed 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 `pat-
       tern:message:action'.  The  message  and the action have the same format 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 descriptions contain-
       ing `=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 argument 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 speci-
       fication as described above using `=-'.

       The option `-i patterns' (which must be given after the `--') can be used to give patterns
       for options which should not be completed. The patterns can be given as	the  name  of  an
       array parameter or as a literal list in parentheses. E.g. `-i "(--(en|dis)able-FEATURE*)"'
       will make the options `--enable-FEATURE' and `--disable-FEATURE' be  ignored.  The  option
       `-s  pairs' (again, after the `--') can be used to describe option aliases. Each pair con-
       sists 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-)"'.


	      _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  argu-
       ment  described	as  `left  border' for which no completion 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 possible completions.

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


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

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

       _call_program tag string ...
	      This function is used in places where a command is called, making 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  exe-

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

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

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

	      The matches generated will be taken from the value  of  the  style.   These  values
	      should  contain  the  possible values for the combinations 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 character
	      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 arguments.

	      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 compadd when generating
	      matches from the style value, or to the  functions  for  the  fields  if	they  are

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

       _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 elements as the first one and the corre-
	      sponding elements are added as  possible	completions  instead  of  the  completion
	      strings  from  the  first  array.  The completion list will retain the descriptions
	      from the first array.  Finally, a set of completion options can appear.

	      If the option `-o' appears before the first argument, the  matches  added  will  be
	      treated  as  option  names  (typically  following 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 com-
	      padd); 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  descrip-
	      tion  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 modified so that the
	      sequence `%d' is replaced by the descr given as  the  third  argument  without  any
	      leading  or trailing white space.  If, after removing the white space, the descr is
	      the empty string, the format style will not be used and the options  put	into  the
	      name  array  will  not  contain  an  explanation	string	to be displayed above the
	      matches.	If _description is called with more than three arguments, the  additional
	      specs  should be of the form `char:str' and every appearance of `%char' in the for-
	      mat string will be replaced by string.

	      The options placed in the array will also make sure that the matches are placed  in
	      a  separate  group,  depending  on  the  value of the group-name style.  Normally a
	      sorted group will be used for this (with the `-J' option), but if an option  start-
	      ing  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  system  use	a  similar  format;  this
	      ensures  that user-specified styles are correctly passed down to the builtins which
	      implement the internals of completion.

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

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

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

		     compdef _gnu_generic foo bar

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

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

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

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

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

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


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

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

       _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 gener-
	      ated automatically.

	      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

	      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 argument 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	parenthe-
	      ses).   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  function,	by  using
	      `_multi_parts / patharray'.

	      If the -i option is present, then any time there is a unique match it will  immedi-
	      ately  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

	      The -12JV options and the first three arguments are given to the _description func-
	      tion 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
	      function 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  func-

	      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
		     return ret

	      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

	      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 specifiers 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 function.  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.

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

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

	      Note  that  you  need  to  uncomment a few lines in the _main_complete 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.

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

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

	      The options accepted by both _path_files and _files are:

	      -f     Complete all filenames.  This is the default.

	      -/     Specifies that only directories should be completed.

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

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

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

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

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

       _regex_arguments name specs ...
	      This function is a compiler to generate a completion function.  The first  argument
	      specifies  the name of the generated function while the remaining arguments specify
	      a completion as a set of regular expressions with actions.  The generated  function
	      has  the	structure  of a finite-state machine whose states correspond to the state
	      (i.e. the context) of the completion. This state machine uses a command line, which
	      comes  from  the concatenation of the words array up to the current cursor position
	      using null characters as separators with no extra quotation.  This is 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 matches, `guard'  is  evaluated  and
		     its  return status is examined; if this is successful, the state is entered,
		     otherwise the test fails and other candidates 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,  pro-
		     ceeding 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  com-
		     mand  line  string  and  actions for the target are executed.  In this case,
		     nothing is actually removed from the command line string so that any  previ-
		     ous  or  neighbouring state may also have actionss.  actionss evaluation are
		     ordered by the tag-order style and specified tag by _alternative.	 So,  the
		     various  formats  supported by _alternative can be used in action.  descr is
		     used for setting up the array parameter expl.

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

	      /pattern/- [%lookahead%] [-guard] [:tag:descr:action]
		     This is similar to `/pattern/ ...' but the actions of the current and previ-
		     ous states are ignored even if the following 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 registered by a call to
	      _tags (see below) is requested and hence completion should be performed for it;  it
	      returns status zero if the tag is requested and non-zero otherwise.  This will usu-
	      ally be done in a loop such as the following:

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

	      Note that the test for whether matches were generated is not  performed  until  the
	      end  of  the  _tags loop.  This is so that the user can 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,  get-
	      ting 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

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

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

	      See _store_cache below for more details.

	      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	parenthe-
	      ses.   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

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

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

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

	      Note that this function is called automatically from _description so that one  nor-
	      mally doesn't have to call it explicitly.

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

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

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

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

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

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

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

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

       _values specs ...
	      This is used to complete values (strings) and their arguments or lists of such val-
	      ues.  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 arguments in the same
	      format used for the description of options by the _arguments function (see  above).
	      The  only  differences are that no minus or plus sign is required at the beginning,
	      that values can have only one argument and that those forms  of  actions	beginning
	      with an equal sign are not supported.

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


		     _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
	      anymore.	 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 arguments, although otherwise this is the
	      same  as	the  opt_args  association  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 param-
	      eter will be set to the name of the value whose argument is to be completed.

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

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

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

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

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

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

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

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

       In  the source distribution, the files are contained in various subdirectories of the Com-
       pletion directory.  They may have been installed in the same structure, or into one single
       function  directory.   The  following  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

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

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

       Unix   Functions  for  completing  arguments  of external commands and suites of commands.
	      They may need modifying for your system, although in many  cases	some  attempt  is
	      made  to decide which version of a command is present.  For example, completion for
	      the mount command tries to determine the system it is running on, while  completion
	      for many other utilities try to decide whether the GNU version of the command is in
	      use, and hence whether the --help option is supported..

       X, AIX, BSD, ...
	      Completion and utility function for commands available only on some systems.

zsh 4.0.6				 August 14, 2002			    ZSHCOMPSYS(1)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 11:07 AM.