{
    "mode": "man",
    "parameter": "zshcompsys",
    "section": "1",
    "url": "https://www.chedong.com/phpMan.php/man/zshcompsys/1/json",
    "generated": "2026-06-03T01:37:08Z",
    "sections": {
        "NAME": {
            "content": "zshcompsys - zsh completion system\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This describes the shell code for the `new' completion system, referred to as compsys.  It is\nwritten in shell functions based on the features described in zshcompwid(1).\n\nThe features are contextual, sensitive to the point at which  completion  is  started.   Many\ncompletions  are  already  provided.   For this reason, a user can perform a great many tasks\nwithout knowing any details beyond how to initialize the system, which is described below  in\nINITIALIZATION.\n\nThe context that decides what completion is to be performed may be\n•      an  argument  or  option  position: these describe the position on the command line at\nwhich completion is requested.  For example `first argument to rmdir, the  word  being\ncompleted names a directory';\n\n\n•      a  special context, denoting an element in the shell's syntax.  For example `a word in\ncommand position' or `an array subscript'.\n\n\nA full context specification contains other elements, as we shall describe.\n\nBesides commands names and contexts, the system employs two more concepts, styles  and  tags.\nThese provide ways for the user to configure the system's behaviour.\n\nTags  play a dual role.  They serve as a classification system for the matches, typically in‐\ndicating a class of object that the user may need to distinguish.  For example, when complet‐\ning  arguments of the ls command the user may prefer to try files before directories, so both\nof these are tags.  They also appear as the rightmost element in a context specification.\n\nStyles modify various operations of the completion system, such  as  output  formatting,  but\nalso  what  kinds  of  completers  are  used (and in what order), or which tags are examined.\nStyles may accept arguments and are manipulated using the zstyle  command  described  in  see\nzshmodules(1).\n\nIn  summary, tags describe what the completion objects are, and style how they are to be com‐\npleted.  At various points of execution, the completion system checks what styles and/or tags\nare defined for the current context, and uses that to modify its behavior.  The full descrip‐\ntion of context handling, which determines how tags and other elements of the context  influ‐\nence the behaviour of styles, is described below in COMPLETION SYSTEM CONFIGURATION.\n\nWhen  a  completion  is  requested,  a  dispatcher function is called; see the description of\nmaincomplete in the list of control functions below. This dispatcher decides which function\nshould  be  called  to  produce the completions, and calls it. The result is passed to one or\nmore completers, functions that implement individual completion  strategies:  simple  comple‐\ntion, error correction, completion with error correction, menu selection, etc.\n\nMore generally, the shell functions contained in the completion system are of two types:\n•      those beginning `comp' are to be called directly; there are only a few of these;\n\n\n•      those  beginning  `'  are called by the completion code.  The shell functions of this\nset, which implement completion behaviour and may be bound to keystrokes, are referred\nto as `widgets'.  These proliferate as new completions are required.\n\n",
            "subsections": []
        },
        "INITIALIZATION": {
            "content": "If  the  system  was  installed  completely,  it  should be enough to call the shell function\ncompinit from your initialization file; see the next section.  However, the function  compin‐‐\nstall can be run by a user to configure various aspects of the completion system.\n\nUsually,  compinstall  will insert code into .zshrc, although if that is not writable it will\nsave it in another file and tell you that file's location.  Note that it is up to you to make\nsure that the lines added to .zshrc are actually run; you may, for example, need to move them\nto an earlier place in the file if .zshrc usually returns early.  So long as  you  keep  them\nall together (including the comment lines at the start and finish), you can rerun compinstall\nand it will correctly locate and modify these lines.  Note, however, that any code you add to\nthis  section by hand is likely to be lost if you rerun compinstall, although lines using the\ncommand `zstyle' should be gracefully handled.\n\nThe new code will take effect next time you start the shell, or run .zshrc by hand; there  is\nalso  an  option  to  make them take effect immediately.  However, if compinstall has removed\ndefinitions, you will need to restart the shell to see the changes.\n\nTo run compinstall you will need to make sure it is in a directory mentioned  in  your  fpath\nparameter,  which  should  already be the case if zsh was properly configured as long as your\nstartup files do not remove the appropriate directories from fpath.   Then  it  must  be  au‐\ntoloaded (`autoload -U compinstall' is recommended).  You can abort the installation any time\nyou are being prompted for information, and your .zshrc will not be altered at  all;  changes\nonly take place right at the end, where you are specifically asked for confirmation.\n",
            "subsections": [
                {
                    "name": "Use of compinit",
                    "content": "This  section  describes the use of compinit to initialize completion for the current session\nwhen called directly; if you have run compinstall it will be called automatically  from  your\n.zshrc.\n\nTo  initialize  the  system,  the function compinit should be in a directory mentioned in the\nfpath parameter, and should be autoloaded (`autoload -U compinit' is recommended),  and  then\nrun simply as `compinit'.  This will define a few utility functions, arrange for all the nec‐\nessary shell functions to be autoloaded, and will then re-define all widgets that do  comple‐\ntion to use the new system.  If you use the menu-select widget, which is part of the zsh/com‐‐\nplist module, you should make sure that that module is loaded before the call to compinit  so\nthat  that widget is also re-defined.  If completion styles (see below) are set up to perform\nexpansion as well as completion by default, and the TAB key is bound  to  expand-or-complete,\ncompinit will rebind it to complete-word; this is necessary to use the correct form of expan‐\nsion.\n\nShould you need to use the original completion commands, you can still bind keys to  the  old\nwidgets by putting a `.' in front of the widget name, e.g. `.expand-or-complete'.\n\nTo  speed  up  the running of compinit, it can be made to produce a dumped configuration that\nwill be read in on future invocations; this is the default, but can be turned off by  calling\ncompinit  with  the  option  -D.   The dumped file is .zcompdump in the same directory as the\nstartup files (i.e. $ZDOTDIR or $HOME); alternatively, an explicit file name can be given  by\n`compinit -d dumpfile'.  The next invocation of compinit will read the dumped file instead of\nperforming a full initialization.\n\nIf the number of completion files changes, compinit will recognise this  and  produce  a  new\ndump  file.  However, if the name of a function or the arguments in the first line of a #com‐‐\npdef function (as described below) change, it is easiest to delete the dump file by  hand  so\nthat compinit will re-create it the next time it is run.  The check performed to see if there\nare new functions can be omitted by giving the option -C.  In this case the  dump  file  will\nonly be created if there isn't one already.\n\nThe  dumping  is  actually  done by another function, compdump, but you will only need to run\nthis yourself if you change the configuration (e.g. using compdef) and then want to dump  the\nnew one.  The name of the old dumped file will be remembered for this purpose.\n\nIf  the parameter compdir is set, compinit uses it as a directory where completion functions\ncan be found; this is only necessary if they are not already in the function search path.\n\nFor security reasons compinit also checks if the completion system would use files not  owned\nby  root or by the current user, or files in directories that are world- or group-writable or\nthat are not owned by root or by the current user.  If such files or directories  are  found,\ncompinit  will  ask if the completion system should really be used.  To avoid these tests and\nmake all files found be used without asking, use the option -u, and to make compinit silently\nignore  all insecure files and directories use the option -i.  This security check is skipped\nentirely when the -C option is given.\n\nThe security check can be retried at any time by running the function compaudit.  This is the\nsame  check  used by compinit, but when it is executed directly any changes to fpath are made\nlocal to the function so they do not persist.  The directories to be checked may be passed as\narguments; if none are given, compaudit uses fpath and compdir to find completion system di‐\nrectories, adding missing ones to fpath as necessary.  To force a check of exactly the direc‐\ntories  currently named in fpath, set compdir to an empty string before calling compaudit or\ncompinit.\n\nThe function bashcompinit provides compatibility with bash's programmable completion  system.\nWhen  run  it  will  define  the functions, compgen and complete which correspond to the bash\nbuiltins with the same names.  It will then be possible to use completion specifications  and\nfunctions written for bash.\n"
                },
                {
                    "name": "Autoloaded files",
                    "content": "The  convention for autoloaded functions used in completion is that they start with an under‐\nscore; as already mentioned, the fpath/FPATH parameter must contain the  directory  in  which\nthey  are  stored.   If zsh was properly installed on your system, then fpath/FPATH automati‐\ncally contains the required directories for the standard functions.\n\nFor incomplete installations, if compinit does not find enough files beginning with an under‐\nscore  (fewer  than twenty) in the search path, it will try to find more by adding the direc‐\ntory compdir to the search path.  If that directory has a subdirectory named Base, all  sub‐\ndirectories will be added to the path.  Furthermore, if the subdirectory Base has a subdirec‐\ntory named Core, compinit will add all subdirectories of the subdirectories to the path: this\nallows the functions to be in the same format as in the zsh source distribution.\n\nWhen  compinit  is  run,  it searches all such files accessible via fpath/FPATH and reads the\nfirst line of each of them.  This line should contain one of the tags described below.  Files\nwhose  first  line does not start with one of these tags are not considered to be part of the\ncompletion system and will not be treated specially.\n\nThe tags are:\n\n#compdef name ... [ -{p|P} pattern ... [ -N name ... ] ]\nThe file will be made autoloadable and the function defined in it will be called  when\ncompleting names, each of which is either the name of a command whose arguments are to\nbe completed or one of a number of special contexts in the  form  -context-  described\nbelow.\n\nEach name may also be of the form `cmd=service'.  When completing the command cmd, the\nfunction typically behaves as if the command (or special context)  service  was  being\ncompleted  instead.   This  provides a way of altering the behaviour of functions that\ncan perform many different completions.  It is implemented by  setting  the  parameter\n$service  when  calling the function; the function may choose to interpret this how it\nwishes, and simpler functions will probably ignore it.\n\nIf the #compdef line contains one of the options -p or -P,  the  words  following  are\ntaken  to be patterns.  The function will be called when completion is attempted for a\ncommand or context that matches one of the patterns.  The options -p and -P  are  used\nto specify patterns to be tried before or after other completions respectively.  Hence\n-P may be used to specify default actions.\n\nThe option -N is used after a list following -p or -P;  it  specifies  that  remaining\nwords  no  longer define patterns.  It is possible to toggle between the three options\nas many times as necessary.\n\n#compdef -k style key-sequence ...\nThis option creates a widget behaving like the builtin widget style and  binds  it  to\nthe  given  key-sequences,  if any.  The style must be one of the builtin widgets that\nperform completion, namely complete-word, delete-char-or-list, expand-or-complete, ex‐‐\npand-or-complete-prefix,  list-choices, menu-complete, menu-expand-or-complete, or re‐‐\nverse-menu-complete.  If the zsh/complist module is  loaded  (see  zshmodules(1))  the\nwidget menu-select is also available.\n\nWhen  one  of  the key-sequences is typed, the function in the file will be invoked to\ngenerate the matches.  Note that a key will not be re-bound if it  already  was  (that\nis, was bound to something other than undefined-key).  The widget created has the same\nname as the file and can be bound to any other keys using bindkey as usual.\n\n#compdef -K widget-name style key-sequence [ name style seq ... ]\nThis is similar to -k except that only one key-sequence argument may be given for each\nwidget-name  style  pair.   However, the entire set of three arguments may be repeated\nwith a different set of arguments.  Note in particular that the  widget-name  must  be\ndistinct  in  each  set.   If it does not begin with `' this will be added.  The wid‐\nget-name should not clash with the name of any existing widget:  names  based  on  the\nname of the function are most useful.  For example,\n\n#compdef -K foocomplete complete-word \"^X^C\" \\\nfoolist list-choices \"^X^D\"\n\n(all  on one line) defines a widget foocomplete for completion, bound to `^X^C', and\na widget foolist for listing, bound to `^X^D'.\n\n#autoload [ options ]\nFunctions with the #autoload tag are marked for  autoloading  but  are  not  otherwise\ntreated  specially.  Typically they are to be called from within one of the completion\nfunctions.  Any options supplied will be passed to the autoload builtin; a typical use\nis  +X  to force the function to be loaded immediately.  Note that the -U and -z flags\nare always added implicitly.\n\nThe # is part of the tag name and no white space is allowed after it.  The #compdef tags  use\nthe compdef function described below; the main difference is that the name of the function is\nsupplied implicitly.\n\nThe special contexts for which completion functions can be defined are:\n"
                },
                {
                    "name": "-array-value-",
                    "content": "The right hand side of an array-assignment (`name=(...)')\n"
                },
                {
                    "name": "-brace-parameter-",
                    "content": "The name of a parameter expansion within braces (`${...}')\n"
                },
                {
                    "name": "-assign-parameter-",
                    "content": "The name of a parameter in an assignment, i.e. on the left hand side of an `='\n"
                },
                {
                    "name": "-command-",
                    "content": "A word in command position\n"
                },
                {
                    "name": "-condition-",
                    "content": "A word inside a condition (`[[...]]')\n"
                },
                {
                    "name": "-default-",
                    "content": "Any word for which no other completion is defined\n"
                },
                {
                    "name": "-equal-",
                    "content": "A word beginning with an equals sign\n"
                },
                {
                    "name": "-first-",
                    "content": "This is tried before any other completion function.  The function called may  set  the\ncompskip parameter to one of various values: all: no further completion is attempted;\na string containing the substring patterns: no pattern completion  functions  will  be\ncalled; a string containing default: the function for the `-default-' context will not\nbe called, but functions defined for commands will be.\n"
                },
                {
                    "name": "-math-",
                    "content": ""
                },
                {
                    "name": "-parameter-",
                    "content": "The name of a parameter expansion (`$...')\n"
                },
                {
                    "name": "-redirect-",
                    "content": "The word after a redirection operator.\n"
                },
                {
                    "name": "-subscript-",
                    "content": "The contents of a parameter subscript.\n"
                },
                {
                    "name": "-tilde-",
                    "content": "After an initial tilde (`~'), but before the first slash in the word.\n"
                },
                {
                    "name": "-value-",
                    "content": "On the right hand side of an assignment.\n\nDefault implementations are supplied for each of these contexts.  In most cases  the  context\n-context-  is  implemented  by  a  corresponding  function  context, for example the context\n`-tilde-' and the function `tilde').\n\nThe contexts -redirect- and -value- allow extra context-specific  information.   (Internally,\nthis is handled by the functions for each context calling the function dispatch.)  The extra\ninformation is added separated by commas.\n\nFor the -redirect- context, the extra information is  in  the  form  `-redirect-,op,command',\nwhere  op is the redirection operator and command is the name of the command on the line.  If\nthere is no command on the line yet, the command field will be empty.\n\nFor the -value- context, the form is `-value-,name,command', where name is the  name  of  the\nparameter on the left hand side of the assignment.  In the case of elements of an associative\narray, for example `assoc=(key <TAB>', name is expanded to `name-key'.   In  certain  special\ncontexts,  such  as  completing  after `make CFLAGS=', the command part gives the name of the\ncommand, here make; otherwise it is empty.\n\nIt is not necessary to define fully specific completions as the functions provided  will  try\nto  generate completions by progressively replacing the elements with `-default-'.  For exam‐\nple, when completing after `foo=<TAB>', value will try the names  `-value-,foo,'  (note  the\nempty command part), `-value-,foo,-default-' and`-value-,-default-,-default-', in that order,\nuntil it finds a function to handle the context.\n\nAs an example:\n\ncompdef 'files -g \"*.log\"' '-redirect-,2>,-default-'\n\ncompletes files matching `*.log' after `2> <TAB>' for any command with no more specific  han‐\ndler defined.\n\nAlso:\n\ncompdef foo -value-,-default-,-default-\n\nspecifies  that  foo  provides completions for the values of parameters for which no special\nfunction has been defined.  This is usually handled by the function value itself.\n\nThe same lookup rules are used when looking up styles (as described below); for example\n\nzstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log'\n\nis another way to make completion after `2> <TAB>' complete files matching `*.log'.\n"
                },
                {
                    "name": "Functions",
                    "content": "The following function is defined by compinit and may be called directly.\n\ncompdef [ -ane ] function name ... [ -{p|P} pattern ... [ -N name ...]]\ncompdef -d name ...\ncompdef -k [ -an ] function style key-sequence [ key-sequence ... ]\ncompdef -K [ -an ] function name style key-seq [ name style seq ... ]\nThe first form defines the function to call for completion in the  given  contexts  as\ndescribed for the #compdef tag above.\n\nAlternatively, all the arguments may have the form `cmd=service'.  Here service should\nalready have been defined by `cmd1=service' lines  in  #compdef  files,  as  described\nabove.  The argument for cmd will be completed in the same way as service.\n\nThe  function argument may alternatively be a string containing almost any shell code.\nIf the string contains an equal sign, the above will take precedence.  The  option  -e\nmay  be used to specify the first argument is to be evaluated as shell code even if it\ncontains an equal sign.  The string will be executed using the eval builtin command to\ngenerate  completions.  This provides a way of avoiding having to define a new comple‐\ntion function.  For example, to complete files ending in `.h' as arguments to the com‐\nmand foo:\n\ncompdef 'files -g \"*.h\"' foo\n\nThe option -n prevents any completions already defined for the command or context from\nbeing overwritten.\n\nThe option -d deletes any completion defined for the command or contexts listed.\n\nThe names may also contain -p, -P and -N options as described for  the  #compdef  tag.\nThe  effect  on  the argument list is identical, switching between definitions of pat‐\nterns tried initially, patterns tried finally, and normal commands and contexts.\n\nThe parameter $compskip may be set by any function defined for a pattern context.  If\nit is set to a value containing the substring `patterns' none of the pattern-functions\nwill be called; if it is set to a value containing the substring `all', no other func‐\ntion  will be called.  Setting $compskip in this manner is of particular utility when\nusing the -p option, as otherwise the dispatcher will move on to additional  functions\n(likely  the  default one) after calling the pattern-context one, which can mangle the\ndisplay of completion possibilities if not handled properly.\n\nThe form with -k defines a widget with the same name as  the  function  that  will  be\ncalled  for each of the key-sequences; this is like the #compdef -k tag.  The function\nshould generate the completions needed and will otherwise behave like the builtin wid‐\nget  whose name is given as the style argument.  The widgets usable for this are: com‐‐\nplete-word,   delete-char-or-list,   expand-or-complete,    expand-or-complete-prefix,\nlist-choices,  menu-complete,  menu-expand-or-complete,  and reverse-menu-complete, as\nwell as menu-select if the zsh/complist module is loaded.  The option -n prevents  the\nkey being bound if it is already to bound to something other than undefined-key.\n\nThe  form  with -K is similar and defines multiple widgets based on the same function,\neach of which requires the set of three arguments name, style and key-sequence,  where\nthe latter two are as for -k and the first must be a unique widget name beginning with\nan underscore.\n\nWherever applicable, the -a option makes the function autoloadable, equivalent to  au‐‐\ntoload -U function.\n\nThe  function  compdef  can  be used to associate existing completion functions with new com‐\nmands.  For example,\n\ncompdef pids foo\n\nuses the function pids to complete process IDs for the command foo.\n\nNote also the gnugeneric function described below, which can be used  to  complete  options\nfor commands that understand the `--help' option.\n"
                }
            ]
        },
        "COMPLETION SYSTEM CONFIGURATION": {
            "content": "This  section gives a short overview of how the completion system works, and then more detail\non how users can configure how and when matches are generated.\n",
            "subsections": [
                {
                    "name": "Overview",
                    "content": "When completion is attempted somewhere on the  command  line  the  completion  system  begins\nbuilding the context.  The context represents everything that the shell knows about the mean‐\ning of the command line and the significance of the cursor position.  This takes account of a\nnumber  of  things  including the command word (such as `grep' or `zsh') and options to which\nthe current word may be an argument (such as the `-o' option to zsh which takes a  shell  op‐\ntion as an argument).\n\nThe  context  starts out very generic (\"we are beginning a completion\") and becomes more spe‐\ncific as more is learned (\"the current word is in a position that is usually a command  name\"\nor  \"the  current word might be a variable name\" and so on).  Therefore the context will vary\nduring the same call to the completion system.\n\nThis context information is condensed into a string consisting of multiple  fields  separated\nby  colons,  referred to simply as `the context' in the remainder of the documentation.  Note\nthat a user of the completion system rarely needs to compose a context string, unless for ex‐\nample  a  new function is being written to perform completion for a new command.  What a user\nmay need to do is compose a style pattern, which is matched against a context when needed  to\nlook up context-sensitive options that configure the completion system.\n\nThe  next  few  paragraphs  explain  how a context is composed within the completion function\nsuite.  Following that is discussion of how styles are defined.  Styles determine such things\nas  how  the  matches  are  generated, similarly to shell options but with much more control.\nThey are defined with the zstyle builtin command (see zshmodules(1)).\n\nThe context string always consists of a fixed set of fields, separated by colons and  with  a\nleading  colon before the first.  Fields which are not yet known are left empty, but the sur‐\nrounding colons appear anyway.  The fields are always in the order  :completion:function:com‐\npleter:command:argument:tag.  These have the following meaning:\n\n•      The  literal  string completion, saying that this style is used by the completion sys‐\ntem.  This distinguishes the context from those used by, for example, zle widgets  and\nZFTP functions.\n\n\n•      The function, if completion is called from a named widget rather than through the nor‐\nmal completion system.  Typically this is blank, but it is set by special widgets such\nas predict-on and the various functions in the Widget directory of the distribution to\nthe name of that function, often in an abbreviated form.\n\n\n•      The completer currently active, the name of the function without  the  leading  under‐\nscore  and  with  other underscores converted to hyphens.  A `completer' is in overall\ncontrol of how completion is to be performed; `complete' is the  simplest,  but  other\ncompleters  exist to perform related tasks such as correction, or to modify the behav‐\niour of a later completer.  See the section `Control Functions' below for more  infor‐\nmation.\n\n\n•      The  command  or a special -context-, just at it appears following the #compdef tag or\nthe compdef function.  Completion functions for commands that have  sub-commands  usu‐\nally modify this field to contain the name of the command followed by a minus sign and\nthe sub-command.  For example, the completion function for the cvs command  sets  this\nfield to cvs-add when completing arguments to the add subcommand.\n\n\n•      The  argument; this indicates which command line or option argument we are completing.\nFor command arguments this generally takes the form argument-n, where n is the  number\nof  the  argument,  and  for arguments to options the form option-opt-n where n is the\nnumber of the argument to option opt.  However, this is only the case if  the  command\nline  is parsed with standard UNIX-style options and arguments, so many completions do\nnot set this.\n\n\n•      The tag.  As described previously, tags are used to discriminate between the types  of\nmatches a completion function can generate in a certain context.  Any completion func‐\ntion may use any tag name it likes, but a list of the more common ones is given below.\n\n\nThe context is gradually put together as the functions are executed, starting with  the  main\nentry  point,  which  adds :completion: and the function element if necessary.  The completer\nthen adds the completer element.  The contextual completion adds the command and argument op‐\ntions.   Finally,  the tag is added when the types of completion are known.  For example, the\ncontext name\n\n:completion::complete:dvips:option-o-1:files\n\nsays that normal completion was attempted as the first argument to the option -o of the  com‐\nmand dvips:\n\ndvips -o ...\n\nand the completion function will generate filenames.\n\nUsually  completion  will  be tried for all possible tags in an order given by the completion\nfunction.  However, this can be altered by using the tag-order style.  Completion is then re‐\nstricted to the list of given tags in the given order.\n\nThe  completehelp bindable command shows all the contexts and tags available for completion\nat a particular point.  This provides an easy way of finding information  for  tag-order  and\nother styles.  It is described in the section `Bindable Commands' below.\n\nWhen  looking  up  styles  the  completion system uses full context names, including the tag.\nLooking up the value of a style therefore consists of  two  things:  the  context,  which  is\nmatched  to the most specific (best fitting) style pattern, and the name of the style itself,\nwhich must be matched exactly.  The following examples demonstrate that style patterns may be\nloosely  defined  for  styles that apply broadly, or as tightly defined as desired for styles\nthat apply in narrower circumstances.\n\nFor example, many completion functions can generate matches in a simple and  a  verbose  form\nand  use  the  verbose style to decide which form should be used.  To make all such functions\nuse the verbose form, put\n\nzstyle ':completion:*' verbose yes\n\nin a startup file (probably .zshrc).  This gives the verbose style the  value  yes  in  every\ncontext inside the completion system, unless that context has a more specific definition.  It\nis best to avoid giving the context as `*' in case the style has  some  meaning  outside  the\ncompletion system.\n\nMany such general purpose styles can be configured simply by using the compinstall function.\n\nA  more  specific  example  of the use of the verbose style is by the completion for the kill\nbuiltin.  If the style is set, the builtin lists full job texts and  process  command  lines;\notherwise it shows the bare job numbers and PIDs.  To turn the style off for this use only:\n\nzstyle ':completion:*:*:kill:*:*' verbose no\n\nFor  even more control, the style can use one of the tags `jobs' or `processes'.  To turn off\nverbose display only for jobs:\n\nzstyle ':completion:*:*:kill:*:jobs' verbose no\n\nThe -e option to zstyle even allows completion function code to appear as the argument  to  a\nstyle;  this  requires  some  understanding of the internals of completion functions (see see\nzshcompwid(1))).  For example,\n\nzstyle -e ':completion:*' hosts 'reply=($myhosts)'\n\nThis forces the value of the hosts style to be read from the variable  myhosts  each  time  a\nhost  name is needed; this is useful if the value of myhosts can change dynamically.  For an‐\nother useful example, see the example in the description of the file-list style below.   This\nform  can  be  slow  and  should  be  avoided  for  commonly examined styles such as menu and\nlist-rows-first.\n\nNote that the order in which styles are defined does not matter; the style mechanism uses the\nmost  specific  possible  match  for a particular style to determine the set of values.  More\nprecisely, strings are preferred over patterns (for example, `:completion::complete:::foo' is\nmore  specific  than  `:completion::complete:::*'),  and  longer  patterns are preferred over\nshorter patterns.\n\nA good rule of thumb is that any completion style pattern that needs to include more than one\nwildcard (*) and that does not end in a tag name, should include all six colons (:), possibly\nsurrounding additional wildcards.\n\nStyle names like those of tags are arbitrary and depend on the completion function.  However,\nthe following two sections list some of the most common tags and styles.\n"
                },
                {
                    "name": "Standard Tags",
                    "content": "Some  of  the following are only used when looking up particular styles and do not refer to a\ntype of match.\n"
                },
                {
                    "name": "accounts",
                    "content": "used to look up the users-hosts style\n"
                },
                {
                    "name": "all-expansions",
                    "content": "used by the expand completer when adding the single string  containing  all  possible\nexpansions\n"
                },
                {
                    "name": "all-files",
                    "content": "for  the  names  of  all  files  (as  distinct  from  a  particular  subset,  see  the\nglobbed-files tag).\n"
                },
                {
                    "name": "arguments",
                    "content": "for arguments to a command\n\narrays for names of array parameters\n"
                },
                {
                    "name": "association-keys",
                    "content": "for keys of associative arrays; used when completing inside a subscript to a parameter\nof this type\n"
                },
                {
                    "name": "bookmarks",
                    "content": "when completing bookmarks (e.g. for URLs and the zftp function suite)\n"
                },
                {
                    "name": "builtins",
                    "content": "for names of builtin commands\n"
                },
                {
                    "name": "characters",
                    "content": "for single characters in arguments of commands such as stty.   Also used when complet‐\ning character classes after an opening bracket\n"
                },
                {
                    "name": "colormapids",
                    "content": "for X colormap ids\n\ncolors for color names\n"
                },
                {
                    "name": "commands",
                    "content": "for names of external commands.  Also used by complex commands such as cvs  when  com‐\npleting names subcommands.\n"
                },
                {
                    "name": "contexts",
                    "content": "for contexts in arguments to the zstyle builtin command\n"
                },
                {
                    "name": "corrections",
                    "content": "used by the approximate and correct completers for possible corrections\n"
                },
                {
                    "name": "cursors",
                    "content": "for cursor names used by X programs\n"
                },
                {
                    "name": "default",
                    "content": "used  in some contexts to provide a way of supplying a default when more specific tags\nare also valid.  Note that this tag is used when only the function field of  the  con‐\ntext name is set\n"
                },
                {
                    "name": "descriptions",
                    "content": "used  when looking up the value of the format style to generate descriptions for types\nof matches\n"
                },
                {
                    "name": "devices",
                    "content": "for names of device special files\n"
                },
                {
                    "name": "directories",
                    "content": "for names of directories -- local-directories is used instead  when  completing  argu‐\nments of cd and related builtin commands when the cdpath array is set\n"
                },
                {
                    "name": "directory-stack",
                    "content": "for entries in the directory stack\n"
                },
                {
                    "name": "displays",
                    "content": "for X display names\n"
                },
                {
                    "name": "domains",
                    "content": "for network domains\n\nemail-plugin\nfor email addresses from the `email-plugin' backend of emailaddresses\n"
                },
                {
                    "name": "expansions",
                    "content": "used  by the expand completer for individual words (as opposed to the complete set of\nexpansions) resulting from the expansion of a word on the command line\n"
                },
                {
                    "name": "extensions",
                    "content": "for X server extensions\n"
                },
                {
                    "name": "file-descriptors",
                    "content": "for numbers of open file descriptors\n\nfiles  the generic file-matching tag used by functions completing filenames\n\nfonts  for X font names\n"
                },
                {
                    "name": "fstypes",
                    "content": "for file system types (e.g. for the mount command)\n"
                },
                {
                    "name": "functions",
                    "content": "names of functions -- normally shell functions, although certain commands  may  under‐\nstand other kinds of function\n"
                },
                {
                    "name": "globbed-files",
                    "content": "for filenames when the name has been generated by pattern matching\n\ngroups for names of user groups\n"
                },
                {
                    "name": "history-words",
                    "content": "for words from the history\n\nhosts  for hostnames\n"
                },
                {
                    "name": "indexes",
                    "content": "for array indexes\n\njobs   for jobs (as listed by the `jobs' builtin)\n"
                },
                {
                    "name": "interfaces",
                    "content": "for network interfaces\n"
                },
                {
                    "name": "keymaps",
                    "content": "for names of zsh keymaps\n"
                },
                {
                    "name": "keysyms",
                    "content": "for names of X keysyms\n"
                },
                {
                    "name": "libraries",
                    "content": "for names of system libraries\n\nlimits for system limits\n"
                },
                {
                    "name": "local-directories",
                    "content": "for names of directories that are subdirectories of the current working directory when\ncompleting arguments of cd and related builtin commands (compare path-directories)  --\nwhen the cdpath array is unset, directories is used instead\n"
                },
                {
                    "name": "manuals",
                    "content": "for names of manual pages\n"
                },
                {
                    "name": "mailboxes",
                    "content": "for e-mail folders\n\nmaps   for map names (e.g. NIS maps)\n"
                },
                {
                    "name": "messages",
                    "content": "used to look up the format style for messages\n"
                },
                {
                    "name": "modifiers",
                    "content": "for names of X modifiers\n"
                },
                {
                    "name": "modules",
                    "content": "for modules (e.g. zsh modules)\n"
                },
                {
                    "name": "my-accounts",
                    "content": "used to look up the users-hosts style\n"
                },
                {
                    "name": "named-directories",
                    "content": "for named directories (you wouldn't have guessed that, would you?)\n\nnames  for all kinds of names\n"
                },
                {
                    "name": "newsgroups",
                    "content": "for USENET groups\n"
                },
                {
                    "name": "nicknames",
                    "content": "for nicknames of NIS maps\n"
                },
                {
                    "name": "options",
                    "content": "for command options\n"
                },
                {
                    "name": "original",
                    "content": "used  by  the approximate, correct and expand completers when offering the original\nstring as a match\n"
                },
                {
                    "name": "other-accounts",
                    "content": "used to look up the users-hosts style\n"
                },
                {
                    "name": "other-files",
                    "content": "for the names of any non-directory files.  This is used instead of all-files when  the\nlist-dirs-first style is in effect.\n"
                },
                {
                    "name": "packages",
                    "content": "for packages (e.g. rpm or installed Debian packages)\n"
                },
                {
                    "name": "parameters",
                    "content": "for names of parameters\n"
                },
                {
                    "name": "path-directories",
                    "content": "for names of directories found by searching the cdpath array when completing arguments\nof cd and related builtin commands (compare local-directories)\n\npaths  used to look up the values of the expand, ambiguous and special-dirs styles\n\npods   for perl pods (documentation files)\n\nports  for communication ports\n"
                },
                {
                    "name": "prefixes",
                    "content": "for prefixes (like those of a URL)\n"
                },
                {
                    "name": "printers",
                    "content": "for print queue names\n"
                },
                {
                    "name": "processes",
                    "content": "for process identifiers\n"
                },
                {
                    "name": "processes-names",
                    "content": "used to look up the command style when generating the names of processes for killall\n"
                },
                {
                    "name": "sequences",
                    "content": "for sequences (e.g. mh sequences)\n"
                },
                {
                    "name": "sessions",
                    "content": "for sessions in the zftp function suite\n"
                },
                {
                    "name": "signals",
                    "content": "for signal names\n"
                },
                {
                    "name": "strings",
                    "content": "for strings (e.g. the replacement strings for the cd builtin command)\n\nstyles for styles used by the zstyle builtin command\n"
                },
                {
                    "name": "suffixes",
                    "content": "for filename extensions\n\ntags   for tags (e.g. rpm tags)\n"
                },
                {
                    "name": "targets",
                    "content": "for makefile targets\n"
                },
                {
                    "name": "time-zones",
                    "content": "for time zones (e.g. when setting the TZ parameter)\n\ntypes  for types of whatever (e.g. address types for the xhost command)\n\nurls   used to look up the urls and local styles when completing URLs\n\nusers  for usernames\n\nvalues for one of a set of values in certain lists\n"
                },
                {
                    "name": "variant",
                    "content": "used by pickvariant to look up the command to run when determining what  program  is\ninstalled for a particular command name.\n"
                },
                {
                    "name": "visuals",
                    "content": "for X visuals\n"
                },
                {
                    "name": "warnings",
                    "content": "used to look up the format style for warnings\n"
                },
                {
                    "name": "widgets",
                    "content": "for zsh widget names\n"
                },
                {
                    "name": "windows",
                    "content": "for IDs of X windows\n"
                },
                {
                    "name": "zsh-options",
                    "content": "for shell options\n"
                },
                {
                    "name": "Standard Styles",
                    "content": "Note that the values of several of these styles represent boolean values.  Any of the strings\n`true', `on', `yes', and `1' can be used for the value `true' and any of the strings `false',\n`off',  `no',  and  `0' for the value `false'.  The behavior for any other value is undefined\nexcept where explicitly mentioned.  The default value may be either `true' or `false' if  the\nstyle is not set.\n\nSome  of  these  styles  are  tested  first for every possible tag corresponding to a type of\nmatch, and if no style was found, for the default tag.  The most notable styles of this  type\nare  menu,  list-colors  and  styles  controlling  completion listing such as list-packed and\nlast-prompt.  When tested for the default tag, only the function field of the context will be\nset so that a style using the default tag will normally be defined along the lines of:\n\nzstyle ':completion:*:default' menu ...\n"
                },
                {
                    "name": "accept-exact",
                    "content": "This  is tested for the default tag in addition to the tags valid for the current con‐\ntext.  If it is set to `true' and any of the trial matches is the same as  the  string\non  the command line, this match will immediately be accepted (even if it would other‐\nwise be considered ambiguous).\n\nWhen completing pathnames (where the tag used is `paths') this style accepts any  num‐\nber  of  patterns  as the value in addition to the boolean values.  Pathnames matching\none of these patterns will be accepted immediately even if the command  line  contains\nsome more partially typed pathname components and these match no file under the direc‐\ntory accepted.\n\nThis style is also used by the expand completer to decide if words beginning  with  a\ntilde or parameter expansion should be expanded.  For example, if there are parameters\nfoo and foobar, the string `$foo' will only be expanded  if  accept-exact  is  set  to\n`true';  otherwise  the completion system will be allowed to complete $foo to $foobar.\nIf the style is set to `continue', expand will add the expansion as a match  and  the\ncompletion system will also be allowed to continue.\n"
                },
                {
                    "name": "accept-exact-dirs",
                    "content": "This  is  used  by  filename completion.  Unlike accept-exact it is a boolean.  By de‐\nfault, filename completion examines all components of a path to see if there are  com‐\npletions  of that component, even if the component matches an existing directory.  For\nexample, when completion after /usr/bin/, the function examines  possible  completions\nto /usr.\n\nWhen  this style is `true', any prefix of a path that matches an existing directory is\naccepted without any attempt to complete it further.  Hence, in the given example, the\npath /usr/bin/ is accepted immediately and completion tried in that directory.\n\nThis style is also useful when completing after directories that magically appear when\nreferenced, such as ZFS .zfs directories or NetApp .snapshot  directories.   When  the\nstyle  is  set  the shell does not check for the existence of the directory within the\nparent directory.\n\nIf you wish to inhibit this behaviour entirely, set the path-completion style (see be‐\nlow) to `false'.\n"
                },
                {
                    "name": "add-space",
                    "content": "This  style  is used by the expand completer.  If it is `true' (the default), a space\nwill be inserted after all words resulting from the expansion, or a slash in the  case\nof  directory  names.   If the value is `file', the completer will only add a space to\nnames of existing files.  Either a boolean `true' or the value `file' may be  combined\nwith `subst', in which case the completer will not add a space to words generated from\nthe expansion of a substitution of the form `$(...)' or `${...}'.\n\nThe prefix completer uses this style as a simple boolean value to decide if  a  space\nshould be inserted before the suffix.\n"
                },
                {
                    "name": "ambiguous",
                    "content": "This  applies  when  completing non-final components of filename paths, in other words\nthose with a trailing slash.  If it is set, the cursor is left after the first ambigu‐\nous component, even if menu completion is in use.  The style is always tested with the\npaths tag.\n"
                },
                {
                    "name": "assign-list",
                    "content": "When completing after an equals sign that is being treated as an assignment, the  com‐\npletion  system normally completes only one filename.  In some cases the value  may be\na list of filenames separated by colons, as with PATH and  similar  parameters.   This\nstyle can be set to a list of patterns matching the names of such parameters.\n\nThe default is to complete lists when the word on the line already contains a colon.\n"
                },
                {
                    "name": "auto-description",
                    "content": "If  set,  this  style's value will be used as the description for options that are not\ndescribed by the completion functions, but that have exactly one  argument.   The  se‐\nquence  `%d'  in the value will be replaced by the description for this argument.  De‐\npending on personal preferences, it may be useful to set this style to something  like\n`specify: %d'.  Note that this may not work for some commands.\n"
                },
                {
                    "name": "avoid-completer",
                    "content": "This  is  used by the allmatches completer to decide if the string consisting of all\nmatches should be added to the list currently being generated.  Its value is a list of\nnames  of completers.  If any of these is the name of the completer that generated the\nmatches in this completion, the string will not be added.\n\nThe default value for this style is `expand oldlist correct approximate', i.e. it\ncontains  the  completers  for  which  a  string with all matches will almost never be\nwanted.\n"
                },
                {
                    "name": "cache-path",
                    "content": "This style defines the path where any cache files containing  dumped  completion  data\nare stored.  It defaults to `$ZDOTDIR/.zcompcache', or `$HOME/.zcompcache' if $ZDOTDIR\nis not defined.  The completion cache will not be used unless the use-cache  style  is\nset.\n"
                },
                {
                    "name": "cache-policy",
                    "content": "This  style  defines the function that will be used to determine whether a cache needs\nrebuilding.  See the section on the cacheinvalid function below.\n"
                },
                {
                    "name": "call-command",
                    "content": "This style is used in the function for commands such as make and ant where calling the\ncommand directly to generate matches suffers problems such as being slow or, as in the\ncase of make can potentially cause actions in the makefile to be executed.  If  it  is\nset  to  `true'  the  command is called to generate matches. The default value of this\nstyle is `false'.\n"
                },
                {
                    "name": "command",
                    "content": "In many places, completion functions need to call external commands  to  generate  the\nlist of completions.  This style can be used to override the command that is called in\nsome such cases.  The elements of the value are joined with spaces to form  a  command\nline to execute.  The value can also start with a hyphen, in which case the usual com‐\nmand will be added to the end; this is most useful for putting `builtin' or  `command'\nin  front  to make sure the appropriate version of a command is called, for example to\navoid calling a shell function with the same name as an external command.\n\nAs an example, the completion function for process IDs uses this style with  the  pro‐‐\ncesses  tag  to  generate the IDs to complete and the list of processes to display (if\nthe verbose style is `true').  The list produced by the command should look  like  the\noutput  of  the  ps command.  The first line is not displayed, but is searched for the\nstring `PID' (or `pid') to find the position of  the  process  IDs  in  the  following\nlines.   If  the  line  does not contain `PID', the first numbers in each of the other\nlines are taken as the process IDs to complete.\n\nNote that the completion function generally has to call the specified command for each\nattempt  to  generate the completion list.  Hence care should be taken to specify only\ncommands that take a short time to run, and in particular to avoid any that may  never\nterminate.\n"
                },
                {
                    "name": "command-path",
                    "content": "This  is  a  list  of directories to search for commands to complete.  The default for\nthis style is the value of the special parameter path.\n"
                },
                {
                    "name": "commands",
                    "content": "This is used by the function completing sub-commands  for  the  system  initialisation\nscripts (residing in /etc/init.d or somewhere not too far away from that).  Its values\ngive the default commands to complete for those  commands  for  which  the  completion\nfunction  isn't  able  to find them out automatically.  The default for this style are\nthe two strings `start' and `stop'.\n"
                },
                {
                    "name": "complete",
                    "content": "This is used by the expandalias function when invoked as a bindable command.  If set\nto `true' and the word on the command line is not the name of an alias, matching alias\nnames will be completed.\n"
                },
                {
                    "name": "complete-options",
                    "content": "This is used by the completer for cd, chdir and pushd.  For these commands a - is used\nto  introduce  a directory stack entry and completion of these is far more common than\ncompleting options.  Hence unless the value of this style is `true' options  will  not\nbe completed, even after an initial -.  If it is `true', options will be completed af‐\nter an initial - unless there is a preceding -- on the command line.\n"
                },
                {
                    "name": "completer",
                    "content": "The strings given as the value of this style provide the names of the completer  func‐\ntions  to use. The available completer functions are described in the section `Control\nFunctions' below.\n\nEach string may be either the name of a completer function or a  string  of  the  form\n`function:name'.   In  the  first case the completer field of the context will contain\nthe name of the completer without the leading underscore and  with  all  other  under‐\nscores  replaced  by hyphens.  In the second case the function is the name of the com‐\npleter to call, but the context will contain the user-defined name  in  the  completer\nfield  of  the  context.  If the name starts with a hyphen, the string for the context\nwill be build from the name of the completer function as in the first  case  with  the\nname appended to it.  For example:\n\nzstyle ':completion:*' completer complete complete:-foo\n\nHere,  completion  will  call the complete completer twice, once using `complete' and\nonce using `complete-foo' in the completer field of the context.  Normally, using  the\nsame  completer  more  than  once only makes sense when used with the `functions:name'\nform, because otherwise the context name will be the same in all  calls  to  the  com‐\npleter; possible exceptions to this rule are the ignored and prefix completers.\n\nThe  default  value  for  this  style is `complete ignored': only completion will be\ndone, first using the ignored-patterns style and the $fignore array and  then  without\nignoring matches.\n"
                },
                {
                    "name": "condition",
                    "content": "This  style  is used by the list completer function to decide if insertion of matches\nshould be delayed unconditionally. The default is `true'.\n"
                },
                {
                    "name": "delimiters",
                    "content": "This style is used when adding a delimiter for use  with  history  modifiers  or  glob\nqualifiers  that  have delimited arguments.  It is an array of preferred delimiters to\nadd.  Non-special characters are preferred as the completion system may otherwise  be‐\ncome  confused.   The default list is :, +, /, -, %.  The list may be empty to force a\ndelimiter to be typed.\n"
                },
                {
                    "name": "disabled",
                    "content": "If this is set to `true', the expandalias completer and bindable command will try to\nexpand disabled aliases, too.  The default is `false'.\n"
                },
                {
                    "name": "domains",
                    "content": "A  list  of names of network domains for completion.  If this is not set, domain names\nwill be taken from the file /etc/resolv.conf.\n"
                },
                {
                    "name": "environ",
                    "content": "The environ style is used when completing for `sudo'.   It  is  set  to  an  array  of\n`VAR=value'  assignments  to be exported into the local environment before the comple‐\ntion for the target command is invoked.\nzstyle ':completion:*:sudo::' environ \\\nPATH=\"/sbin:/usr/sbin:$PATH\" HOME=\"/root\"\n\nexpand This style is used when completing strings consisting of multiple parts, such as  path\nnames.\n\nIf  one  of  its values is the string `prefix', the partially typed word from the line\nwill be expanded as far as possible even if trailing parts cannot be completed.\n\nIf one of its values is the string `suffix', matching names for components  after  the\nfirst  ambiguous  one will also be added.  This means that the resulting string is the\nlongest unambiguous string possible.  However, menu completion can be  used  to  cycle\nthrough all matches.\n\nfake   This  style  may  be  set for any completion context.  It specifies additional strings\nthat will always be completed in that context.  The form of each string is  `value:de‐\nscription';  the colon and description may be omitted, but any literal colons in value\nmust be quoted with a backslash.  Any description  provided  is  shown  alongside  the\nvalue in completion listings.\n\nIt  is  important  to  use  a  sufficiently  restrictive  context when specifying fake\nstrings.  Note that the styles fake-files and fake-parameters provide additional  fea‐\ntures when completing files or parameters.\n"
                },
                {
                    "name": "fake-always",
                    "content": "This works identically to the fake style except that the ignored-patterns style is not\napplied to it.  This makes it possible to override a set of matches completely by set‐\nting the ignored patterns to `*'.\n\nThe  following shows a way of supplementing any tag with arbitrary data, but having it\nbehave for display purposes like a separate tag.  In this example we use the  features\nof  the  tag-order  style to divide the named-directories tag into two when performing\ncompletion with the  standard  completer  complete  for  arguments  of  cd.   The  tag\nnamed-directories-normal  behaves  as  normal, but the tag named-directories-mine con‐\ntains a fixed set of directories.  This has the effect of adding the match group  `ex‐‐\ntra directories' with the given completions.\n\nzstyle ':completion::complete:cd:*' tag-order \\\n'named-directories:-mine:extra\\ directories\nnamed-directories:-normal:named\\ directories *'\nzstyle ':completion::complete:cd:*:named-directories-mine' \\\nfake-always mydir1 mydir2\nzstyle ':completion::complete:cd:*:named-directories-mine' \\\nignored-patterns '*'\n"
                },
                {
                    "name": "fake-files",
                    "content": "This  style is used when completing files and looked up without a tag.  Its values are\nof the form `dir:names...'.  This will add the names (strings separated by spaces)  as\npossible  matches  when  completing in the directory dir, even if no such files really\nexist.  The dir may be a pattern; pattern characters or colons in dir should be quoted\nwith a backslash to be treated literally.\n\nThis  can be useful on systems that support special file systems whose top-level path‐\nnames can not be listed or generated with glob patterns (but see accept-exact-dirs for\na more general way of dealing with this problem).  It can also be used for directories\nfor which one does not have read permission.\n\nThe pattern form can be used to add a certain `magic' entry to all  directories  on  a\nparticular file system.\n"
                },
                {
                    "name": "fake-parameters",
                    "content": "This  is used by the completion function for parameter names.  Its values are names of\nparameters that might not yet be set but should be completed nonetheless.   Each  name\nmay  also  be  followed  by  a colon and a string specifying the type of the parameter\n(like `scalar', `array' or `integer').  If the type is given, the name  will  only  be\ncompleted  if  parameters  of that type are required in the particular context.  Names\nfor which no type is specified will always be completed.\n"
                },
                {
                    "name": "file-list",
                    "content": "This style controls whether files completed using the standard builtin  mechanism  are\nto be listed with a long list similar to ls -l.  Note that this feature uses the shell\nmodule zsh/stat for file information; this loads the builtin stat which  will  replace\nany  external stat executable.  To avoid this the following code can be included in an\ninitialization file:\n\nzmodload -i zsh/stat\ndisable stat\n\nThe style may either be set to a `true' value (or `all'), or one of  the  values  `in‐‐\nsert'  or `list', indicating that files are to be listed in long format in all circum‐\nstances, or when attempting to insert a file name, or when listing file names  without\nattempting to insert one.\n\nMore  generally, the value may be an array of any of the above values, optionally fol‐\nlowed by =num.  If num is present it gives the maximum number  of  matches  for  which\nlong listing style will be used.  For example,\n\nzstyle ':completion:*' file-list list=20 insert=10\n\nspecifies  that  long  format  will be used when listing up to 20 files or inserting a\nfile with up to 10 matches (assuming a listing is to be shown at all, for  example  on\nan ambiguous completion), else short format will be used.\n\nzstyle -e ':completion:*' file-list \\\n'(( ${+NUMERIC} )) && reply=(true)'\n\nspecifies  that long format will be used any time a numeric argument is supplied, else\nshort format.\n"
                },
                {
                    "name": "file-patterns",
                    "content": "This is used by the standard function for completing filenames, files.  If the  style\nis  unset up to three tags are offered, `globbed-files',`directories' and `all-files',\ndepending on the types of files  expected by the caller  of  files.   The  first  two\n(`globbed-files' and `directories') are normally offered together to make it easier to\ncomplete files in sub-directories.\n\nThe file-patterns style provides alternatives to the default tags, which are not used.\nIts  value consists of elements of the form `pattern:tag'; each string may contain any\nnumber of such specifications separated by spaces.\n\nThe pattern is a pattern that is to be used to generate filenames.  Any occurrence  of\nthe sequence `%p' is replaced by any pattern(s) passed by the function calling files.\nColons in the pattern must be preceded by a backslash  to  make  them  distinguishable\nfrom  the  colon before the tag.  If more than one pattern is needed, the patterns can\nbe given inside braces, separated by commas.\n\nThe tags of all strings in the value will be offered by files and used  when  looking\nup  other  styles.  Any tags in the same word will be offered at the same time and be‐\nfore later words.  If no `:tag' is given the `files' tag will be used.\n\nThe tag may also be followed by an optional second colon and a description, which will\nbe  used for the `%d' in the value of the format style (if that is set) instead of the\ndefault description supplied by the completion function.   If  the  description  given\nhere  contains  itself  a  `%d', that is replaced with the description supplied by the\ncompletion function.\n\nFor example, to make the rm command first complete only names of object files and then\nthe names of all files if there is no matching object file:\n\nzstyle ':completion:*:*:rm:*:*' file-patterns \\\n'*.o:object-files' '%p:all-files'\n\nTo  alter  the  default behaviour of file completion -- offer files matching a pattern\nand directories on the first attempt, then all files -- to offer only  matching  files\non the first attempt, then directories, and finally all files:\n\nzstyle ':completion:*' file-patterns \\\n'%p:globbed-files' '*(-/):directories' '*:all-files'\n\nThis  works even where there is no special pattern: files matches all files using the\npattern `*' at the first step and stops when it sees this pattern.  Note also it  will\nnever try a pattern more than once for a single completion attempt.\n\nDuring  the  execution of completion functions, the EXTENDEDGLOB option is in effect,\nso the characters `#', `~' and `^' have special meanings in the patterns.\n"
                },
                {
                    "name": "file-sort",
                    "content": "The standard filename completion function uses this style without a tag  to  determine\nin  which order the names should be listed; menu completion will cycle through them in\nthe same order.  The possible values are: `size' to sort by  the  size  of  the  file;\n`links'  to  sort  by  the  number  of links to the file; `modification' (or `time' or\n`date') to sort by the last modification time; `access' to sort  by  the  last  access\ntime;  and  `inode' (or `change') to sort by the last inode change time.  If the style\nis set to any other value, or is unset, files will be sorted alphabetically  by  name.\nIf the value contains the string `reverse', sorting is done in the opposite order.  If\nthe value contains the string `follow', timestamps are associated with the targets  of\nsymbolic links; the default is to use the timestamps of the links themselves.\n"
                },
                {
                    "name": "file-split-chars",
                    "content": "A  set  of characters that will cause all file completions for the given context to be\nsplit at the point where any of the characters occurs.  A typical use is  to  set  the\nstyle to :; then everything up to and including the last : in the string so far is ig‐\nnored when completing files.  As this is quite heavy-handed, it is usually  preferable\nto update completion functions for contexts where this behaviour is useful.\n\nfilter The  ldap plugin of email address completion (see emailaddresses) uses this style to\nspecify the attributes to match against when filtering entries.  So  for  example,  if\nthe  style is set to `sn', matching is done against surnames.  Standard LDAP filtering\nis used so normal completion matching is bypassed.  If this style is not set, the LDAP\nplugin  is skipped.  You may also need to set the command style to specify how to con‐\nnect to your LDAP server.\n"
                },
                {
                    "name": "force-list",
                    "content": "This forces a list of completions to be shown at any point where listing is done, even\nin  cases  where the list would usually be suppressed.  For example, normally the list\nis only shown if there are at least two different matches.  By setting this  style  to\n`always',  the  list  will  always be shown, even if there is only a single match that\nwill immediately be accepted.  The style may also be set to a number.   In  this  case\nthe list will be shown if there are at least that many matches, even if they would all\ninsert the same string.\n\nThis style is tested for the default tag as well as for each tag valid for the current\ncompletion.  Hence the listing can be forced only for certain types of match.\n\nformat If  this  is  set  for  the descriptions tag, its value is used as a string to display\nabove matches in completion lists.  The sequence `%d' in this string will be  replaced\nwith  a short description of what these matches are.  This string may also contain the\noutput attribute sequences understood by compadd -X (see zshcompwid(1)).\n\nThe style is tested with each tag valid for the current completion before it is tested\nfor the descriptions tag.  Hence different format strings can be defined for different\ntypes of match.\n\nNote also that some completer functions define additional  `%'-sequences.   These  are\ndescribed for the completer functions that make use of them.\n\nSome  completion  functions  display  messages  that may be customised by setting this\nstyle for the messages tag.  Here, the `%d' is replaced with a message  given  by  the\ncompletion function.\n\nFinally, the format string is looked up with the warnings tag, for use when no matches\ncould be generated at all.  In this case the `%d' is replaced  with  the  descriptions\nfor the matches that were expected separated by spaces.  The sequence `%D' is replaced\nwith the same descriptions separated by newlines.\n\nIt is possible to use printf-style field width specifiers with `%d' and similar escape\nsequences.   This is handled by the zformat builtin command from the zsh/zutil module,\nsee zshmodules(1).\n\nglob   This is used by the expand completer.  If it is set to `true' (the default), globbing\nwill be attempted on the words resulting from a previous substitution (see the substi‐‐\ntute style) or else the original string from the line.\n\nglobal If this is set to `true' (the default), the expandalias completer and bindable  com‐\nmand will try to expand global aliases.\n"
                },
                {
                    "name": "group-name",
                    "content": "The  completion  system can group different types of matches, which appear in separate\nlists.  This style can be used to give the names of groups for particular  tags.   For\nexample,  in command position the completion system generates names of builtin and ex‐\nternal commands, names of aliases, shell functions and parameters and  reserved  words\nas  possible  completions.   To  have the external commands and shell functions listed\nseparately:\n\nzstyle ':completion:*:*:-command-:*:commands' \\\ngroup-name commands\nzstyle ':completion:*:*:-command-:*:functions' \\\ngroup-name functions\n\nAs a consequence, any match with the same tag will be displayed in the same group.\n\nIf the name given is the empty string the name of the tag for the matches will be used\nas  the name of the group.  So, to have all different types of matches displayed sepa‐\nrately, one can just set:\n\nzstyle ':completion:*' group-name ''\n\nAll matches for which no group name is defined will be put in a group named -default-.\n"
                },
                {
                    "name": "group-order",
                    "content": "This style is additional to the group-name style to specify the order for  display  of\nthe  groups  defined  by that style (compare tag-order, which determines which comple‐\ntions appear at all).  The groups named are shown in the given order; any other groups\nare shown in the order defined by the completion function.\n\nFor  example, to have names of builtin commands, shell functions and external commands\nappear in that order when completing in command position:\n\nzstyle ':completion:*:*:-command-:*:*' group-order \\\nbuiltins functions commands\n\ngroups A list of names of UNIX groups.  If this is not set, group names are taken from the YP\ndatabase or the file `/etc/group'.\n\nhidden If  this  is set to `true', matches for the given context will not be listed, although\nany description for the matches set with the format style will be shown.  If it is set\nto `all', not even the description will be displayed.\n\nNote  that  the  matches will still be completed; they are just not shown in the list.\nTo avoid having matches considered as possible completions at all, the tag-order style\ncan be modified as described below.\n\nhosts  A  list of names of hosts that should be completed.  If this is not set, hostnames are\ntaken from the file `/etc/hosts'.\n"
                },
                {
                    "name": "hosts-ports",
                    "content": "This style is used by commands that need or accept hostnames and network  ports.   The\nstrings in the value should be of the form `host:port'.  Valid ports are determined by\nthe presence of hostnames; multiple ports for the same host may appear.\n"
                },
                {
                    "name": "ignore-line",
                    "content": "This is tested for each tag valid for the current completion.  If it is set to `true',\nnone  of the words that are already on the line will be considered as possible comple‐\ntions.  If it is set to `current', the word the cursor is on will not be considered as\na  possible  completion.  The value `current-shown' is similar but only applies if the\nlist of completions is currently shown on the screen.  Finally, if the style is set to\n`other',  all  words  on the line except for the current one will be excluded from the\npossible completions.\n\nThe values `current' and `current-shown' are a bit like the opposite of the accept-ex‐‐\nact style:  only strings with missing characters will be completed.\n\nNote  that you almost certainly don't want to set this to `true' or `other' for a gen‐\neral context such as `:completion:*'.  This is because it  would  disallow  completion\nof,  for  example,  options multiple times even if the command in question accepts the\noption more than once.\n"
                },
                {
                    "name": "ignore-parents",
                    "content": "The style is tested without a tag by the function completing pathnames in order to de‐\ntermine  whether  to  ignore the names of directories already mentioned in the current\nword, or the name of the current working directory.  The value  must  include  one  or\nboth of the following strings:\n\nparent The  name  of  any directory whose path is already contained in the word on the\nline is ignored.  For example, when completing after foo/../, the directory foo\nwill not be considered a valid completion.\n\npwd    The name of the current working directory will not be completed; hence, for ex‐\nample, completion after ../ will not use the name of the current directory.\n\nIn addition, the value may include one or both of:\n\n..     Ignore the specified directories only when the word on the  line  contains  the\nsubstring `../'.\n\ndirectory\nIgnore  the specified directories only when names of directories are completed,\nnot when completing names of files.\n\nExcluded values act in a similar fashion to values of the ignored-patterns  style,  so\nthey can be restored to consideration by the ignored completer.\n"
                },
                {
                    "name": "extra-verbose",
                    "content": "If  set,  the completion listing is more verbose at the cost of a probable decrease in\ncompletion speed.  Completion performance will suffer if this style is set to `true'.\n"
                },
                {
                    "name": "ignored-patterns",
                    "content": "A list of patterns; any trial completion matching one of the patterns will be excluded\nfrom  consideration.   The  ignored completer can appear in the list of completers to\nrestore the ignored matches.  This is a more configurable version of the shell parame‐\nter $fignore.\n\nNote  that  the  EXTENDEDGLOB  option is set during the execution of completion func‐\ntions, so the characters `#', `~' and `^' have special meanings in the patterns.\n\ninsert This style is used by the allmatches completer to decide whether to insert the  list\nof all matches unconditionally instead of adding the list as another match.\n"
                },
                {
                    "name": "insert-ids",
                    "content": "When  completing  process  IDs, for example as arguments to the kill and wait builtins\nthe name of a command may be converted to  the  appropriate  process  ID.   A  problem\narises when the process name typed is not unique.  By default (or if this style is set\nexplicitly to `menu') the name will be converted immediately to a set of possible IDs,\nand menu completion will be started to cycle through them.\n\nIf  the  value  of the style is `single', the shell will wait until the user has typed\nenough to make the command unique before converting the name to  an  ID;  attempts  at\ncompletion  will  be unsuccessful until that point.  If the value is any other string,\nmenu completion will be started when the string typed by the user is longer  than  the\ncommon prefix to the corresponding IDs.\n"
                },
                {
                    "name": "insert-tab",
                    "content": "If  this is set to `true', the completion system will insert a TAB character (assuming\nthat was used to start completion) instead of performing completion when there  is  no\nnon-blank  character  to  the left of the cursor.  If it is set to `false', completion\nwill be done even there.\n\nThe value may also contain the substrings `pending' or `pending=val'.  In  this  case,\nthe  typed character will be inserted instead of starting completion when there is un‐\nprocessed input pending.  If a val is given, completion will not be done if there  are\nat least that many characters of unprocessed input.  This is often useful when pasting\ncharacters into a terminal.  Note however, that it relies on the $PENDING special  pa‐\nrameter  from  the  zsh/zle  module  being set properly which is not guaranteed on all\nplatforms.\n\nThe default value of this style is `true' except for completion within  vared  builtin\ncommand where it is `false'.\n"
                },
                {
                    "name": "insert-unambiguous",
                    "content": "This  is  used  by the match and approximate completers.  These completers are often\nused with menu completion since the word typed may bear little resemblance to the  fi‐\nnal  completion.  However, if this style is `true', the completer will start menu com‐\npletion only if it could find no unambiguous initial string at least as  long  as  the\noriginal string typed by the user.\n\nIn the case of the approximate completer, the completer field in the context will al‐\nready have been set to one of correct-num or approximate-num, where num is the  number\nof errors that were accepted.\n\nIn  the  case  of  the match completer, the style may also be set to the string `pat‐‐\ntern'.  Then the pattern on the line is left unchanged if it does not match  unambigu‐\nously.\n"
                },
                {
                    "name": "gain-privileges",
                    "content": "If set to true, this style enables the use of commands like sudo or doas to gain extra\nprivileges when retrieving information for completion. This is only done when  a  com‐\nmand  such  as  sudo appears on the command-line. To force the use of, e.g. sudo or to\noverride any prefix that might be added due to gain-privileges, the command style  can\nbe used with a value that begins with a hyphen.\n"
                },
                {
                    "name": "keep-prefix",
                    "content": "This  style is used by the expand completer.  If it is `true', the completer will try\nto keep a prefix containing a tilde or parameter expansion.  Hence, for  example,  the\nstring  `~/f*' would be expanded to `~/foo' instead of `/home/user/foo'.  If the style\nis set to `changed' (the default), the prefix will only be  left  unchanged  if  there\nwere  other  changes between the expanded words and the original word from the command\nline.  Any other value forces the prefix to be expanded unconditionally.\n\nThe behaviour of expand when this style is `true' is to cause expand to give up when\na single expansion with the restored prefix is the same as the original; hence any re‐\nmaining completers may be called.\n"
                },
                {
                    "name": "last-prompt",
                    "content": "This is a more flexible form of the ALWAYSLASTPROMPT option.  If it is  `true',  the\ncompletion  system  will  try  to return the cursor to the previous command line after\ndisplaying a completion list.  It is tested for all tags valid for the current comple‐\ntion,  then  the  default  tag.  The cursor will be moved back to the previous line if\nthis style is `true' for all types of match.  Note that unlike the  ALWAYSLASTPROMPT\noption this is independent of the numeric argument.\n"
                },
                {
                    "name": "known-hosts-files",
                    "content": "This  style should contain a list of files to search for host names and (if the use-ip\nstyle is set) IP addresses in a format compatible with ssh knownhosts files.   If  it\nis not set, the files /etc/ssh/sshknownhosts and ~/.ssh/knownhosts are used.\n\nlist   This  style  is  used by the historycompleteword bindable command.  If it is set to\n`true' it has no effect.  If it is set to `false' matches will not  be  listed.   This\noverrides  the  setting  of  the  options controlling listing behaviour, in particular\nAUTOLIST.  The context always starts with `:completion:history-words'.\n"
                },
                {
                    "name": "list-colors",
                    "content": "If the zsh/complist module is loaded, this style can be used to set  color  specifica‐\ntions.   This  mechanism replaces the use of the ZLSCOLORS and ZLSCOLOURS parameters\ndescribed in the section `The zsh/complist Module' in zshmodules(1), but the syntax is\nthe same.\n\nIf this style is set for the default tag, the strings in the value are taken as speci‐\nfications that are to be used everywhere.  If it is set for other tags, the specifica‐\ntions  are  used  only for matches of the type described by the tag.  For this to work\nbest, the group-name style must be set to an empty string.\n\nIn addition to setting styles for specific tags, it is  also  possible  to  use  group\nnames  specified  explicitly  by the group-name tag together with the `(group)' syntax\nallowed by the ZLSCOLORS and ZLSCOLOURS parameters and simply using the default tag.\n\nIt is possible to use any color specifications already set up for the GNU  version  of\nthe ls command:\n\nzstyle ':completion:*:default' list-colors \\\n${(s.:.)LSCOLORS}\n\nThe  default colors are the same as for the GNU ls command and can be obtained by set‐\nting the style to an empty string (i.e. '').\n"
                },
                {
                    "name": "list-dirs-first",
                    "content": "This is used by file completion.  If set, directories to be completed are listed sepa‐\nrately from and before completion for other files, regardless of tag ordering.  In ad‐\ndition, the tag other-files is used in place of all-files for the remaining files,  to\nindicate that no directories are presented with that tag.\n"
                },
                {
                    "name": "list-grouped",
                    "content": "If  this style is `true' (the default), the completion system will try to make certain\ncompletion listings more compact by grouping matches.  For example, options  for  com‐\nmands  that  have the same description (shown when the verbose style is set to `true')\nwill appear as a single entry.  However, menu selection can be used to  cycle  through\nall the matches.\n"
                },
                {
                    "name": "list-packed",
                    "content": "This  is  tested for each tag valid in the current context as well as the default tag.\nIf it is set to `true', the  corresponding  matches  appear  in  listings  as  if  the\nLISTPACKED option were set.  If it is set to `false', they are listed normally.\n"
                },
                {
                    "name": "list-prompt",
                    "content": "If  this  style  is  set  for  the default tag, completion lists that don't fit on the\nscreen can be scrolled (see the description of  the  zsh/complist  module  in  zshmod‐\nules(1)).  The value, if not the empty string, will be displayed after every screenful\nand the shell will prompt for a key press; if the style is set to the empty string,  a\ndefault prompt will be used.\n\nThe  value  may  contain the escape sequences: `%l' or `%L', which will be replaced by\nthe number of the last line displayed and the total number of lines; `%m' or `%M', the\nnumber  of  the   last match shown and the total number of matches; and `%p' and `%P',\n`Top' when at the beginning of the list, `Bottom' when at the  end  and  the  position\nshown  as  a percentage of the total length otherwise.  In each case the form with the\nuppercase letter will be replaced by a string of fixed width,  padded  to  the   right\nwith spaces, while the lowercase form will be replaced by a variable width string.  As\nin other prompt strings, the escape sequences `%S', `%s', `%B', `%b', `%U',  `%u'  for\nentering  and  leaving the display modes standout, bold and underline, and `%F', `%f',\n`%K', `%k' for changing the foreground background colour, are also  available,  as  is\nthe  form `%{...%}' for enclosing escape sequences which display with zero (or, with a\nnumeric argument, some other) width.\n\nAfter deleting this prompt the variable LISTPROMPT should be unset for the removal  to\ntake effect.\n"
                },
                {
                    "name": "list-rows-first",
                    "content": "This  style  is tested in the same way as the list-packed style and determines whether\nmatches are to be listed in a rows-first fashion as if the LISTROWSFIRST option were\nset.\n"
                },
                {
                    "name": "list-suffixes",
                    "content": "This  style  is  used  by the function that completes filenames.  If it is `true', and\ncompletion is attempted on a string containing multiple partially typed pathname  com‐\nponents,  all  ambiguous components will be shown.  Otherwise, completion stops at the\nfirst ambiguous component.\n"
                },
                {
                    "name": "list-separator",
                    "content": "The value of this style is used in completion listing to separate the string  to  com‐\nplete from a description when possible (e.g. when completing options).  It defaults to\n`--' (two hyphens).\n\nlocal  This is for use with functions that complete URLs for which  the  corresponding  files\nare  available  directly  from  the  file  system.   Its value should consist of three\nstrings: a hostname, the path to the default web pages for the server, and the  direc‐\ntory name used by a user placing web pages within their home area.\n\nFor example:\n\nzstyle ':completion:*' local toast \\\n/var/http/public/toast publichtml\n\nCompletion   after   `http://toast/stuff/'  will  look  for  files  in  the  directory\n/var/http/public/toast/stuff,  while  completion  after  `http://toast/~yousir/'  will\nlook for files in the directory ~yousir/publichtml.\n"
                },
                {
                    "name": "mail-directory",
                    "content": "If  set,  zsh  will assume that mailbox files can be found in the directory specified.\nIt defaults to `~/Mail'.\n"
                },
                {
                    "name": "match-original",
                    "content": "This is used by the match completer.  If it is set to only, match will try to gener‐\nate  matches  without  inserting  a  `*'  at the cursor position.  If set to any other\nnon-empty value, it will first try to generate matches without inserting the  `*'  and\nif that yields no matches, it will try again with the `*' inserted.  If it is unset or\nset to the empty string, matching will only be performed with the `*' inserted.\n"
                },
                {
                    "name": "matcher",
                    "content": "This style is tested separately for each tag valid in the current context.  Its  value\nis placed before any match specifications given by the matcher-list style so can over‐\nride them via the use of an x: specification.  The value should be  in  the  form  de‐\nscribed  in  the section `Completion Matching Control' in zshcompwid(1).  For examples\nof this, see the description of the tag-order style.\n\nFor notes comparing the use of this and the matcher-list style, see under the descrip‐\ntion of the tag-order style.\n"
                },
                {
                    "name": "matcher-list",
                    "content": "This  style can be set to a list of match specifications that are to be applied every‐\nwhere. Match specifications are described in the section `Completion Matching Control'\nin zshcompwid(1).  The completion system will try them one after another for each com‐\npleter selected.  For example, to try first simple completion and, if  that  generates\nno matches, case-insensitive completion:\n\nzstyle ':completion:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}'\n\nBy  default  each specification replaces the previous one; however, if a specification\nis prefixed with +, it is added to the existing list.  Hence it is possible to  create\nincreasingly general specifications without repetition:\n\nzstyle ':completion:*' matcher-list \\\n'' '+m:{a-z}={A-Z}' '+m:{A-Z}={a-z}'\n\nIt is possible to create match specifications valid for particular completers by using\nthe third field of the context.  This applies only to  completers  that  override  the\nglobal matcher-list, which as of this writing includes only prefix and ignored.  For\nexample, to use the completers complete and prefix but allow  case-insensitive  com‐\npletion only with complete:\n\nzstyle ':completion:*' completer complete prefix\nzstyle ':completion:*:complete:*:*:*' matcher-list \\\n'' 'm:{a-zA-Z}={A-Za-z}'\n\nUser-defined  names,  as explained for the completer style, are available.  This makes\nit possible to try the same completer more than once with different  match  specifica‐\ntions each time.  For example, to try normal completion without a match specification,\nthen normal completion with case-insensitive matching, then  correction,  and  finally\npartial-word completion:\n\nzstyle ':completion:*' completer \\\ncomplete correct complete:foo\nzstyle ':completion:*:complete:*:*:*' matcher-list \\\n'' 'm:{a-zA-Z}={A-Za-z}'\nzstyle ':completion:*:foo:*:*:*' matcher-list \\\n'm:{a-zA-Z}={A-Za-z} r:|[-./]=* r:|=*'\n\nIf  the  style  is  unset in any context no match specification is applied.  Note also\nthat some completers such as correct and approximate do not use the match specifica‐\ntions  at  all,  though  these  completers  will  only ever be called once even if the\nmatcher-list contains more than one element.\n\nWhere multiple specifications are useful, note that the entire completion is done  for\neach  element of matcher-list, which can quickly reduce the shell's performance.  As a\nrough rule of thumb, one to three strings will give acceptable  performance.   On  the\nother hand, putting multiple space-separated values into the same string does not have\nan appreciable impact on performance.\n\nIf there is no current matcher or it is empty, and the option NOCASEGLOB is  in  ef‐\nfect,  the  matching  for files is performed case-insensitively in any case.  However,\nany matcher must explicitly specify case-insensitive matching if that is required.\n\nFor notes comparing the use of this and the matcher style, see under  the  description\nof the tag-order style.\n"
                },
                {
                    "name": "max-errors",
                    "content": "This  is  used  by  the approximate and correct completer functions to determine the\nmaximum number of errors to allow.  The completer will try to generate completions  by\nfirst  allowing one error, then two errors, and so on, until either a match or matches\nwere found or the maximum number of errors given by this style has been reached.\n\nIf the value for this style contains the string `numeric', the completer function will\ntake any numeric argument as the maximum number of errors allowed. For example, with\n\nzstyle ':completion:*:approximate:::' max-errors 2 numeric\n\ntwo errors are allowed if no numeric argument is given, but with a numeric argument of\nsix (as in `ESC-6 TAB'), up to six errors are accepted.  Hence with a value of `0  nu‐‐\nmeric', no correcting completion will be attempted unless a numeric argument is given.\n\nIf the value contains the string `not-numeric', the completer will not try to generate\ncorrected completions when given a numeric argument, so in this case the number  given\nshould  be  greater than zero.  For example, `2 not-numeric' specifies that correcting\ncompletion with two errors will usually be performed, but if  a  numeric  argument  is\ngiven, correcting completion will not be performed.\n\nThe default value for this style is `2 numeric'.\n"
                },
                {
                    "name": "max-matches-width",
                    "content": "This  style  is  used to determine the trade off between the width of the display used\nfor matches and the width used for their descriptions when the verbose style is in ef‐\nfect.   The value gives the number of display columns to reserve for the matches.  The\ndefault is half the width of the screen.\n\nThis has the most impact when several matches have the same description and so will be\ngrouped  together.   Increasing  the  style  will allow more matches to be grouped to‐\ngether; decreasing it will allow more of the description to be visible.\n\nmenu   If this is `true' in the context of any of the tags defined for the current completion\nmenu  completion will be used.  The value for a specific tag will take precedence over\nthat for the `default' tag.\n\nIf none of the values found in this way is `true' but at least one is set  to  `auto',\nthe shell behaves as if the AUTOMENU option is set.\n\nIf  one of the values is explicitly set to `false', menu completion will be explicitly\nturned off, overriding the MENUCOMPLETE option and other settings.\n\nIn the form `yes=num', where `yes' may be any of the  `true'  values  (`yes',  `true',\n`on'  and  `1'),  menu completion will be turned on if there are at least num matches.\nIn the form `yes=long', menu completion will be turned on if the list does not fit  on\nthe  screen.  This does not activate menu completion if the widget normally only lists\ncompletions, but menu completion  can  be  activated  in  that  case  with  the  value\n`yes=long-list'  (Typically, the value `select=long-list' described later is more use‐\nful as it provides control over scrolling.)\n\nSimilarly, with any of the `false' values (as in `no=10'), menu completion will not be\nused if there are num or more matches.\n\nThe  value of this widget also controls menu selection, as implemented by the zsh/com‐‐\nplist module.  The following values may appear either alongside or instead of the val‐\nues above.\n\nIf the value contains the string `select', menu selection will be started uncondition‐\nally.\n\nIn the form `select=num', menu selection will only be started if there  are  at  least\nnum  matches.  If the values for more than one tag provide a number, the smallest num‐\nber is taken.\n\nMenu selection can be turned  off  explicitly  by  defining  a  value  containing  the\nstring`no-select'.\n\nIt  is  also possible to start menu selection only if the list of matches does not fit\non the screen by using the value `select=long'.  To start menu selection even  if  the\ncurrent widget only performs listing, use the value `select=long-list'.\n\nTo  turn  on  menu  completion  or  menu  selection when there are a certain number of\nmatches or the list of matches does not fit on the screen, both  of  `yes='  and  `se‐‐\nlect=' may be given twice, once with a number and once with `long' or `long-list'.\n\nFinally,  it  is  possible  to activate two special modes of menu selection.  The word\n`interactive' in the value causes interactive mode to be entered immediately when menu\nselection  is started; see the description of the zsh/complist module in zshmodules(1)\nfor a description of interactive mode.  Including the string `search'  does  the  same\nfor  incremental  search  mode.   To  select  backward incremental search, include the\nstring `search-backward'.\n\nmuttrc If set, gives the location of the mutt configuration file.  It  defaults  to  `~/.mut‐‐\ntrc'.\n"
                },
                {
                    "name": "numbers",
                    "content": "This  is used with the jobs tag.  If it is `true', the shell will complete job numbers\ninstead of the shortest unambiguous prefix of the job command text.  If the value is a\nnumber, job numbers will only be used if that many words from the job descriptions are\nrequired to resolve ambiguities.  For example, if the value is `1', strings will  only\nbe used if all jobs differ in the first word on their command lines.\n"
                },
                {
                    "name": "old-list",
                    "content": "This  is used by the oldlist completer.  If it is set to `always', then standard wid‐\ngets which perform listing will retain the current list of matches, however they  were\ngenerated; this can be turned off explicitly with the value `never', giving the behav‐\niour without the oldlist completer.  If the style is unset, or any other value,  then\nthe  existing  list  of  completions is displayed if it is not already; otherwise, the\nstandard completion list is generated; this is  the  default  behaviour  of  oldlist.\nHowever,  if  there  is  an old list and this style contains the name of the completer\nfunction that generated the list, then the old list will be used even if it was gener‐\nated by a widget which does not do listing.\n\nFor  example,  suppose you type ^Xc to use the correctword widget, which generates a\nlist of corrections for the word under the cursor.  Usually, typing ^D would  generate\na  standard list of completions for the word on the command line, and show that.  With\noldlist, it will instead show the list of corrections already generated.\n\nAs another example consider the match completer: with  the  insert-unambiguous  style\nset  to `true' it inserts only a common prefix string, if there is any.  However, this\nmay remove parts of the original pattern, so that  further  completion  could  produce\nmore  matches  than on the first attempt.  By using the oldlist completer and setting\nthis style to match, the list of matches generated on the first attempt will be  used\nagain.\n"
                },
                {
                    "name": "old-matches",
                    "content": "This  is used by the allmatches completer to decide if an old list of matches should\nbe used if one exists.  This is selected by one of the `true' values or by the  string\n`only'.  If the value is `only', allmatches will only use an old list and won't have\nany effect on the list of matches currently being generated.\n\nIf this style is set it is generally unwise to call the allmatches completer  uncon‐\nditionally.   One  possible  use is for either this style or the completer style to be\ndefined with the -e option to zstyle to make the style conditional.\n"
                },
                {
                    "name": "old-menu",
                    "content": "This is used by the oldlist completer.  It controls how menu completion behaves  when\na  completion  has  already been inserted and the user types a standard completion key\nsuch as TAB.  The default behaviour of oldlist is that menu completion always contin‐\nues  with the existing list of completions.  If this style is set to `false', however,\na new completion is started if the old list was generated by  a  different  completion\ncommand; this is the behaviour without the oldlist completer.\n\nFor  example, suppose you type ^Xc to generate a list of corrections, and menu comple‐\ntion is started in one of the usual ways.  Usually, or with this style set to `false',\ntyping  TAB  at  this point would start trying to complete the line as it now appears.\nWith oldlist, it instead continues to cycle through the list of corrections.\n"
                },
                {
                    "name": "original",
                    "content": "This is used by the approximate and correct completers to  decide  if  the  original\nstring should be added as a possible completion.  Normally, this is done only if there\nare at least two possible corrections, but if this style is set to `true', it  is  al‐\nways added.  Note that the style will be examined with the completer field in the con‐\ntext name set to correct-num or approximate-num, where num is  the  number  of  errors\nthat were accepted.\n"
                },
                {
                    "name": "packageset",
                    "content": "This  style  is  used when completing arguments of the Debian `dpkg' program.  It con‐\ntains an override for the default package set for a given context.  For example,\n\nzstyle ':completion:*:complete:dpkg:option--status-1:*' \\\npackageset avail\n\ncauses available packages, rather than only installed packages, to  be  completed  for\n`dpkg --status'.\n\npath   The  function  that  completes  color  names uses this style with the colors tag.  The\nvalue should be the pathname of a file containing color names in the format of an  X11\nrgb.txt  file.  If the style is not set but this file is found in one of various stan‐\ndard locations it will be used as the default.\n"
                },
                {
                    "name": "path-completion",
                    "content": "This is used by filename completion.  By default,  filename  completion  examines  all\ncomponents  of a path to see if there are completions of that component.  For example,\n/u/b/z can be completed to /usr/bin/zsh.  Explicitly setting this style to `false' in‐\nhibits  this  behaviour  for path components up to the / before the cursor; this over‐\nrides the setting of accept-exact-dirs.\n\nEven with the style set to `false', it is still possible to complete multiple paths by\nsetting  the option COMPLETEINWORD and moving the cursor back to the first component\nin the path to be completed.  For example, /u/b/z can be completed to /usr/bin/zsh  if\nthe cursor is after the /u.\n"
                },
                {
                    "name": "pine-directory",
                    "content": "If  set,  specifies the directory containing PINE mailbox files.  There is no default,\nsince recursively searching this directory is inconvenient for anyone who doesn't  use\nPINE.\n\nports  A  list  of  Internet  service names (network ports) to complete.  If this is not set,\nservice names are taken from the file `/etc/services'.\n"
                },
                {
                    "name": "prefix-hidden",
                    "content": "This is used for certain completions which share a common prefix, for example  command\noptions  beginning  with dashes.  If it is `true', the prefix will not be shown in the\nlist of matches.\n\nThe default value for this style is `false'.\n"
                },
                {
                    "name": "prefix-needed",
                    "content": "This style is also relevant for matches with a common prefix.  If it is set to  `true'\nthis common prefix must be typed by the user to generate the matches.\n\nThe  style is applicable to the options, signals, jobs, functions, and parameters com‐\npletion tags.\n\nFor command options, this means that the initial `-', `+', or `--' must be  typed  ex‐\nplicitly before option names will be completed.\n\nFor signals, an initial `-' is required before signal names will be completed.\n\nFor jobs, an initial `%' is required before job names will be completed.\n\nFor function and parameter names, an initial `' or `.' is required before function or\nparameter names starting with those characters will be completed.\n\nThe default value for this style is `false' for function  and  parameter  completions,\nand  `true' otherwise.\n"
                },
                {
                    "name": "preserve-prefix",
                    "content": "This style is used when completing path names.  Its value should be a pattern matching\nan initial prefix of the word to complete that should be left unchanged under all cir‐\ncumstances.   For example, on some Unices an initial `//' (double slash) has a special\nmeaning; setting this style to the string `//' will preserve it.  As another  example,\nsetting  this style to `?:/' under Cygwin would allow completion after `a:/...' and so\non.\n\nrange  This is used by the history completer and the historycompleteword bindable command\nto decide which words should be completed.\n\nIf it is a single number, only the last N words from the history will be completed.\n\nIf it is a range of the form `max:slice', the last slice words will be completed; then\nif that yields no matches, the slice words before those will be tried and so on.  This\nprocess  stops  either  when at least one match has been found, or max words have been\ntried.\n\nThe default is to complete all words from the history at once.\n"
                },
                {
                    "name": "recursive-files",
                    "content": "If this style is set, its value is an array of patterns to be tested against  `$PWD/':\nnote the trailing slash, which allows directories in the pattern to be delimited unam‐\nbiguously by including slashes on both sides.  If an ordinary  file  completion  fails\nand  the  word on the command line does not yet have a directory part to its name, the\nstyle is retrieved using the same tag as for the completion just attempted,  then  the\nelements tested against $PWD/ in turn.  If one matches, then the shell reattempts com‐\npletion by prepending the word on the command line with each directory in  the  expan‐\nsion  of /*(/) in turn.  Typically the elements of the style will be set to restrict\nthe number of directories beneath the current one to a manageable number, for  example\n`*/.git/*'.\n\nFor example,\n\nzstyle ':completion:*' recursive-files '*/zsh/*'\n\nIf  the  current  directory  is  /home/pws/zsh/Src, then zletrTAB can be completed to\nZle/zletricky.c.\n"
                },
                {
                    "name": "regular",
                    "content": "This style is used by the expandalias completer and bindable  command.   If  set  to\n`true'  (the  default), regular aliases will be expanded but only in command position.\nIf it is set to `false', regular aliases will never be expanded.   If  it  is  set  to\n`always', regular aliases will be expanded even if not in command position.\n\nrehash If this is set when completing external commands, the internal list (hash) of commands\nwill be updated for each search by issuing the rehash command.  There is a speed  pen‐\nalty  for this which is only likely to be noticeable when directories in the path have\nslow file access.\n"
                },
                {
                    "name": "remote-access",
                    "content": "If set to `false', certain commands will be prevented from making Internet connections\nto retrieve remote information.  This includes the completion for the CVS command.\n\nIt is not always possible to know if connections are in fact to a remote site, so some\nmay be prevented unnecessarily.\n"
                },
                {
                    "name": "remove-all-dups",
                    "content": "The historycompleteword bindable command and the history completer use this to de‐\ncide  if  all duplicate matches should be removed, rather than just consecutive dupli‐\ncates.\n"
                },
                {
                    "name": "select-prompt",
                    "content": "If this is set for the default tag, its value will be displayed during menu  selection\n(see  the  menu  style above) when the completion list does not fit on the screen as a\nwhole.  The same escapes as for the list-prompt style are understood, except that  the\nnumbers  refer to the match or line the mark is on.  A default prompt is used when the\nvalue is the empty string.\n"
                },
                {
                    "name": "select-scroll",
                    "content": "This style is tested for the default tag and  determines  how  a  completion  list  is\nscrolled  during  a menu selection (see the menu style above) when the completion list\ndoes not fit on the screen as a whole.  If the  value  is  `0'  (zero),  the  list  is\nscrolled  by half-screenfuls; if it is a positive integer, the list is scrolled by the\ngiven number of lines; if it is a negative number, the list is scrolled by a screenful\nminus  the  absolute  value of the given number of lines.  The default is to scroll by\nsingle lines.\n"
                },
                {
                    "name": "separate-sections",
                    "content": "This style is used with the manuals tag when completing names of manual pages.  If  it\nis  `true', entries for different sections are added separately using tag names of the\nform `manual.X', where X is the section number.  When the group-name style is also  in\neffect, pages from different sections will appear separately.  This style is also used\nsimilarly with the words style when completing words for the dict command.  It  allows\nwords  from  different  dictionary  databases to be added separately.  The default for\nthis style is `false'.\n"
                },
                {
                    "name": "show-ambiguity",
                    "content": "If the zsh/complist module is loaded, this style can be used to  highlight  the  first\nambiguous  character  in completion lists. The value is either a color indication such\nas those supported by the list-colors style or, with a value of `true', a  default  of\nunderlining  is  selected.  The highlighting is only applied if the completion display\nstrings correspond to the actual matches.\n"
                },
                {
                    "name": "show-completer",
                    "content": "Tested whenever a new completer is tried.  If it is `true', the completion system out‐\nputs  a  progress  message  in the listing area showing what completer is being tried.\nThe message will be overwritten by any output when completions are found  and  is  re‐\nmoved after completion is finished.\n"
                },
                {
                    "name": "single-ignored",
                    "content": "This  is used by the ignored completer when there is only one match.  If its value is\n`show', the single match will be displayed but not inserted.  If the value is  `menu',\nthen  the single match and the original string are both added as matches and menu com‐\npletion is started, making it easy to select either of them.\n\nsort   This allows the standard ordering of matches to be overridden.\n\nIf its value is `true' or `false', sorting is enabled or disabled.   Additionally  the\nvalues  associated  with the `-o' option to compadd can also be listed: match, nosort,\nnumeric, reverse.  If it is not set for the context, the  standard  behaviour  of  the\ncalling widget is used.\n\nThe  style  is  tested  first  against the full context including the tag, and if that\nfails to produce a value against the context without the tag.\n\nIn many cases where a calling widget explicitly selects a particular ordering in  lieu\nof  the  default,  a value of `true' is not honoured.  An example of where this is not\nthe case is for command history where the default of sorting  matches  chronologically\nmay be overridden by setting the style to `true'.\n\nIn the expand completer, if it is set to `true', the expansions generated will always\nbe sorted.  If it is set to `menu', then the expansions are only sorted when they  are\noffered as single strings but not in the string containing all possible expansions.\n"
                },
                {
                    "name": "special-dirs",
                    "content": "Normally,  the  completion  code  will not produce the directory names `.' and `..' as\npossible completions.  If this style is set to `true', it will add both `.'  and  `..'\nas possible completions; if it is set to `..', only `..' will be added.\n\nThe following example sets special-dirs to `..' when the current prefix is empty, is a\nsingle `.', or consists only of a path beginning with `../'.  Otherwise the  value  is\n`false'.\n\nzstyle -e ':completion:*' special-dirs \\\n'[[ $PREFIX = (../)#(|.|..) ]] && reply=(..)'\n"
                },
                {
                    "name": "squeeze-slashes",
                    "content": "If  set  to `true', sequences of slashes in filename paths (for example in `foo//bar')\nwill be treated as a single slash.  This is the usual behaviour of UNIX  paths.   How‐\never,  by  default the file completion function behaves as if there were a `*' between\nthe slashes.\n\nstop   If set to `true', the historycompleteword bindable  command  will  stop  once  when\nreaching  the  beginning  or end of the history.  Invoking historycompleteword will\nthen wrap around to the opposite end of the history.  If this style is set to  `false'\n(the default), historycompleteword will loop immediately as in a menu completion.\n"
                },
                {
                    "name": "strip-comments",
                    "content": "If set to `true', this style causes non-essential comment text to be removed from com‐\npletion matches.  Currently it is only used when completing e-mail addresses where  it\nremoves  any  display  name  from  the addresses, cutting them down to plain user@host\nform.\n"
                },
                {
                    "name": "subst-globs-only",
                    "content": "This is used by the expand completer.  If it is set to  `true',  the  expansion  will\nonly  be used if it resulted from globbing; hence, if expansions resulted from the use\nof the substitute style described below, but these were not further changed  by  glob‐\nbing, the expansions will be rejected.\n\nThe default for this style is `false'.\n"
                },
                {
                    "name": "substitute",
                    "content": "This boolean style controls whether the expand completer will first try to expand all\nsubstitutions in the string (such as `$(...)' and `${...}').\n\nThe default is `true'.\n\nsuffix This is used by the expand completer if the word starts with a tilde  or  contains  a\nparameter  expansion.   If  it  is set to `true', the word will only be expanded if it\ndoesn't have a suffix, i.e. if it is something  like  `~foo'  or  `$foo'  rather  than\n`~foo/'  or `$foo/bar', unless that suffix itself contains characters eligible for ex‐\npansion.  The default for this style is `true'.\n"
                },
                {
                    "name": "tag-order",
                    "content": "This provides a mechanism for sorting how the tags available in a  particular  context\nwill be used.\n\nThe  values for the style are sets of space-separated lists of tags.  The tags in each\nvalue will be tried at the same time; if no match is found, the next  value  is  used.\n(See the file-patterns style for an exception to this behavior.)\n\nFor example:\n\nzstyle ':completion:*:complete:-command-:*:*' tag-order \\\n'commands functions'\n\nspecifies that completion in command position first offers external commands and shell\nfunctions.  Remaining tags will be tried if no completions are found.\n\nIn addition to tag names, each string in the value  may  take  one  of  the  following\nforms:\n\n-      If  any  value  consists  of only a hyphen, then only the tags specified in the\nother values are generated.  Normally all  tags  not  explicitly  selected  are\ntried last if the specified tags fail to generate any matches.  This means that\na single value consisting only of a single hyphen turns off completion.\n\n! tags...\nA string starting with an exclamation mark specifies names of tags that are not\nto  be used.  The effect is the same as if all other possible tags for the con‐\ntext had been listed.\n\ntag:label ...\nHere, tag is one of the standard tags and label is an arbitrary name.   Matches\nare  generated as normal but the name label is used in contexts instead of tag.\nThis is not useful in words starting with !.\n\nIf the label starts with a hyphen, the tag is prepended to the  label  to  form\nthe name used for lookup.  This can be used to make the completion system try a\ncertain tag more than once, supplying different style  settings  for  each  at‐\ntempt; see below for an example.\n\ntag:label:description\nAs  before,  but  description  will replace the `%d' in the value of the format\nstyle instead of the default description supplied by the  completion  function.\nSpaces in the description must be quoted with a backslash.  A `%d' appearing in\ndescription is replaced with the description given by the completion function.\n\nIn any of the forms above the tag may be a pattern or several  patterns  in  the  form\n`{pat1,pat2...}'.   In  this  case all matching tags will be used except for any given\nexplicitly in the same string.\n\nOne use of these features is to try one tag more than once, setting other styles  dif‐\nferently on each attempt, but still to use all the other tags without having to repeat\nthem all.  For example, to make completion of function names in command  position  ig‐\nnore  all  the completion functions starting with an underscore the first time comple‐\ntion is tried:\n\nzstyle ':completion:*:*:-command-:*:*' tag-order \\\n'functions:-non-comp *' functions\nzstyle ':completion:*:functions-non-comp' \\\nignored-patterns '*'\n\nOn the first attempt, all tags will be offered but the functions tag will be  replaced\nby  functions-non-comp.   The  ignored-patterns  style  is set for this tag to exclude\nfunctions starting with an underscore.  If there are no matches, the second  value  of\nthe tag-order style is used which completes functions using the default tag, this time\npresumably including all function names.\n\nThe matches for one tag can be split into different groups.  For example:\n\nzstyle ':completion:*' tag-order \\\n'options:-long:long\\ options\noptions:-short:short\\ options\noptions:-single-letter:single\\ letter\\ options'\nzstyle ':completion:*:options-long' \\\nignored-patterns '[-+](|-|[^-]*)'\nzstyle ':completion:*:options-short' \\\nignored-patterns '--*' '[-+]?'\nzstyle ':completion:*:options-single-letter' \\\nignored-patterns '???*'\n\nWith the group-names style set, options beginning with `--', options beginning with  a\nsingle  `-'  or `+' but containing multiple characters, and single-letter options will\nbe displayed in separate groups with different descriptions.\n\nAnother use of patterns is to try multiple match  specifications  one  after  another.\nThe  matcher-list  style  offers something similar, but it is tested very early in the\ncompletion system and hence can't be set for single commands  nor  for  more  specific\ncontexts.   Here  is how to try normal completion without any match specification and,\nif that generates no matches, try again with  case-insensitive  matching,  restricting\nthe effect to arguments of the command foo:\n\nzstyle ':completion:*:*:foo:*:*' tag-order '*' '*:-case'\nzstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}'\n\nFirst,  all  the tags offered when completing after foo are tried using the normal tag\nname.  If that generates no matches, the second value  of  tag-order  is  used,  which\ntries  all  tags  again  except that this time each has -case appended to its name for\nlookup of styles.  Hence this time the value for the matcher  style  from  the  second\ncall to zstyle in the example is used to make completion case-insensitive.\n\nIt  is  possible  to use the -e option of the zstyle builtin command to specify condi‐\ntions for the use of particular tags.  For example:\n\nzstyle -e '*:-command-:*' tag-order '\nif [[ -n $PREFIX$SUFFIX ]]; then\nreply=( )\nelse\nreply=( - )\nfi'\n\nCompletion in command position will be attempted only if the string typed  so  far  is\nnot  empty.   This  is tested using the PREFIX special parameter; see zshcompwid for a\ndescription of parameters which are special inside completion widgets.  Setting  reply\nto  an  empty array provides the default behaviour of trying all tags at once; setting\nit to an array containing only a hyphen disables the use of all tags and hence of  all\ncompletions.\n\nIf  no  tag-order  style  has been defined for a context, the strings `(|*-)argument-*\n(|*-)option-* values' and `options' plus all tags offered by the  completion  function\nwill  be  used  to  provide a sensible default behavior that causes arguments (whether\nnormal command arguments or arguments of options) to be completed before option  names\nfor most commands.\n\nurls   This is used together with the urls tag by functions completing URLs.\n\nIf  the  value consists of more than one string, or if the only string does not name a\nfile or directory, the strings are used as the URLs to complete.\n\nIf the value contains only one string which is the name of a normal file the URLs  are\ntaken from that file (where the URLs may be separated by white space or newlines).\n\nFinally,  if  the  only string in the value names a directory, the directory hierarchy\nrooted at this directory gives the completions.  The top level directory should be the\nfile  access  method,  such as `http', `ftp', `bookmark' and so on.  In many cases the\nnext level of directories will be a filename.  The directory hierarchy can descend  as\ndeep as necessary.\n\nFor example,\n\nzstyle ':completion:*' urls ~/.urls\nmkdir -p ~/.urls/ftp/ftp.zsh.org/pub\n\nallows  completion  of all the components of the URL ftp://ftp.zsh.org/pub after suit‐\nable commands such as `netscape' or `lynx'.  Note, however, that  access  methods  and\nfiles  are  completed  separately, so if the hosts style is set hosts can be completed\nwithout reference to the urls style.\n\nSee the description in the function urls itself  for  more  information  (e.g.  `more\n$^fpath/urls(N)').\n"
                },
                {
                    "name": "use-cache",
                    "content": "If  this  is  set, the completion caching layer is activated for any completions which\nuse it (via the storecache, retrievecache, and cacheinvalid functions).  The di‐\nrectory containing the cache files can be changed with the cache-path style.\n"
                },
                {
                    "name": "use-compctl",
                    "content": "If  this  style  is set to a string not equal to false, 0, no, and off, the completion\nsystem may use any completion specifications defined with the compctl builtin command.\nIf  the  style  is  unset, this is done only if the zsh/compctl module is loaded.  The\nstring may also contain the substring `first' to use completions defined with `compctl\n-T', and the substring `default' to use the completion defined with `compctl -D'.\n\nNote  that this is only intended to smooth the transition from compctl to the new com‐\npletion system and may disappear in the future.\n\nNote also that the definitions from compctl will only be used if there is no  specific\ncompletion  function for the command in question.  For example, if there is a function\nfoo to complete arguments to the command foo, compctl will never be invoked for  foo.\nHowever, the compctl version will be tried if foo only uses default completion.\n\nuse-ip By default, the function hosts that completes host names strips IP addresses from en‐\ntries read from host databases such as NIS and ssh files.  If this  style  is  `true',\nthe corresponding IP addresses can be completed as well.  This style is not use in any\ncontext where the hosts style is set; note also it must be set  before  the  cache  of\nhost names is generated (typically the first completion attempt).\n\nusers  This  may  be  set to a list of usernames to be completed.  If it is not set all user‐\nnames will be completed.  Note that if it is set only that list of users will be  com‐\npleted;  this  is  because  on  some systems querying all users can take a prohibitive\namount of time.\n"
                },
                {
                    "name": "users-hosts",
                    "content": "The values of this style should be of the form `user@host' or `user:host'. It is  used\nfor  commands  that  need  pairs of user- and hostnames.  These commands will complete\nusernames from this style (only), and will restrict subsequent hostname completion  to\nhosts paired with that user in one of the values of the style.\n\nIt  is  possible to group values for sets of commands which allow a remote login, such\nas rlogin and ssh, by using the my-accounts tag.  Similarly, values for sets  of  com‐\nmands  which  usually  refer to the accounts of other people, such as talk and finger,\ncan be grouped by using the other-accounts tag.  More ambivalent commands may use  the\naccounts tag.\n"
                },
                {
                    "name": "users-hosts-ports",
                    "content": "Like  users-hosts but used for commands like telnet and containing strings of the form\n`user@host:port'.\n"
                },
                {
                    "name": "verbose",
                    "content": "If set, as it is by default, the completion listing is more  verbose.   In  particular\nmany commands show descriptions for options if this style is `true'.\n\nword   This is used by the list completer, which prevents the insertion of completions until\na second completion attempt when the line has not changed.  The normal way of  finding\nout  if  the  line has changed is to compare its entire contents between the two occa‐\nsions.  If this style is `true', the comparison is instead performed only on the  cur‐\nrent  word.   Hence if completion is performed on another word with the same contents,\ncompletion will not be delayed.\n"
                }
            ]
        },
        "CONTROL FUNCTIONS": {
            "content": "The initialization script compinit redefines all the widgets which perform completion to call\nthe  supplied  widget  function  maincomplete.  This function acts as a wrapper calling the\nso-called `completer' functions that generate matches.  If maincomplete is called with  ar‐\nguments, these are taken as the names of completer functions to be called in the order given.\nIf no arguments are given, the set of functions to try is taken  from  the  completer  style.\nFor example, to use normal completion and correction if that doesn't generate any matches:\n\nzstyle ':completion:*' completer complete correct\n\nafter  calling  compinit. The default value for this style is `complete ignored', i.e. nor‐\nmally only ordinary completion is tried, first with the effect of the ignored-patterns  style\nand  then  without  it.   The maincomplete function uses the return status of the completer\nfunctions to decide if other completers should be called.  If the return status is  zero,  no\nother completers are tried and the maincomplete function returns.\n\nIf  the  first argument to maincomplete is a single hyphen, the arguments will not be taken\nas names of completers.  Instead, the second argument gives a name to use  in  the  completer\nfield  of  the  context  and the other arguments give a command name and arguments to call to\ngenerate the matches.\n\nThe following completer functions are contained in the distribution, although users may write\ntheir  own.  Note that in contexts the leading underscore is stripped, for example basic com‐\npletion is performed in the context `:completion::complete:...'.\n\nallmatches\nThis completer can be used to add a string consisting of all other matches.  As it in‐\nfluences later completers it must appear as the first completer in the list.  The list\nof all matches is affected by the avoid-completer  and  old-matches  styles  described\nabove.\n\nIt  may be useful to use the generic function described below to bind allmatches to\nits own keystroke, for example:\n\nzle -C all-matches complete-word generic\nbindkey '^Xa' all-matches\nzstyle ':completion:all-matches:*' old-matches only\nzstyle ':completion:all-matches::::' completer allmatches\n\nNote that this does not generate completions by itself:  first use any of the standard\nways  of  generating  a  list of completions, then use ^Xa to show all matches.  It is\npossible instead to add a standard completer to the list and request that the list  of\nall matches should be directly inserted:\n\nzstyle ':completion:all-matches::::' completer \\\nallmatches complete\nzstyle ':completion:all-matches:*' insert true\n\nIn this case the old-matches style should not be set.\n\napproximate\nThis is similar to the basic complete completer but allows the completions to undergo\ncorrections.  The maximum number of errors can be specified by the  max-errors  style;\nsee  the description of approximate matching in zshexpn(1) for how errors are counted.\nNormally this completer will only be tried after the normal complete completer:\n\nzstyle ':completion:*' completer complete approximate\n\nThis will give correcting completion if and only if normal completion yields no possi‐\nble  completions.   When  corrected completions are found, the completer will normally\nstart menu completion allowing you to cycle through these strings.\n\nThis completer uses the tags corrections and original  when  generating  the  possible\ncorrections  and the original string.  The format style for the former may contain the\nadditional sequences `%e' and `%o' which will be replaced by the number of errors  ac‐\ncepted to generate the corrections and the original string, respectively.\n\nThe  completer progressively increases the number of errors allowed up to the limit by\nthe max-errors style, hence if a completion is found with one  error,  no  completions\nwith  two errors will be shown, and so on.  It modifies the completer name in the con‐\ntext to indicate the number of errors being tried: on  the  first  try  the  completer\nfield contains `approximate-1', on the second try `approximate-2', and so on.\n\nWhen  approximate is called from another function, the number of errors to accept may\nbe passed with the -a option.  The argument is in the same format  as  the  max-errors\nstyle, all in one string.\n\nNote that this completer (and the correct completer mentioned below) can be quite ex‐\npensive to call, especially when a large number of errors are  allowed.   One  way  to\navoid this is to set up the completer style using the -e option to zstyle so that some\ncompleters are only used when completion is  attempted  a  second  time  on  the  same\nstring, e.g.:\n\nzstyle -e ':completion:*' completer '\nif [[ $lasttry != \"$HISTNO$BUFFER$CURSOR\" ]]; then\nlasttry=\"$HISTNO$BUFFER$CURSOR\"\nreply=(complete match prefix)\nelse\nreply=(ignored correct approximate)\nfi'\n\nThis  uses  the HISTNO parameter and the BUFFER and CURSOR special parameters that are\navailable inside zle and completion widgets to find out if  the  command  line  hasn't\nchanged  since  the last time completion was tried.  Only then are the ignored, cor‐‐\nrect and approximate completers called.\n\ncanonicalpaths [ -A var ] [ -N ] [ -MJV12nfX ] tag descr [ paths ... ]\nThis completion function completes all paths given to it, and also tries to offer com‐\npletions which point to the same file as one of the paths given (relative path when an\nabsolute path is given, and vice versa; when ..'s are present in the word to  be  com‐\npleted; and some paths got from symlinks).\n\n-A, if specified, takes the paths from the array variable specified. Paths can also be\nspecified on the command line as shown above.  -N, if specified, prevents canonicaliz‐\ning the paths given before using them for completion, in case they are already so. The\noptions -M, -J, -V, -1, -2, -n, -F, -X are passed to compadd.\n\nSee description for a description of tag and descr.\n\ncmdambivalent\nCompletes the remaining positional arguments as an  external  command.   The  external\ncommand and its arguments are completed as separate arguments (in a manner appropriate\nfor completing /usr/bin/env) if there are two or more remaining  positional  arguments\non  the  command  line,  and as a quoted command string (in the manner of system(...))\notherwise.  See also cmdstring and precommand.\n\nThis function takes no arguments.\n\ncmdstring\nCompletes an external command as a single argument, as for system(...).\n\ncomplete\nThis completer generates all possible completions in a context-sensitive manner,  i.e.\nusing  the  settings defined with the compdef function explained above and the current\nsettings of all special parameters.  This gives the normal completion behaviour.\n\nTo complete arguments of commands, complete uses the utility function normal,  which\nis  in  turn  responsible  for finding the particular function; it is described below.\nVarious contexts of the form -context- are handled specifically. These  are  all  men‐\ntioned above as possible arguments to the #compdef tag.\n\nBefore  trying  to find a function for a specific context, complete checks if the pa‐\nrameter `compcontext' is set. Setting `compcontext' allows the usual  completion  dis‐\npatching to be overridden which is useful in places such as a function that uses vared\nfor input. If it is set to an array, the elements are taken to be the possible matches\nwhich  will  be completed using the tag `values' and the description `value'. If it is\nset to an associative array, the keys are used as the  possible  completions  and  the\nvalues  (if  non-empty) are used as descriptions for the matches.  If `compcontext' is\nset to a string containing colons, it should be of the  form  `tag:descr:action'.   In\nthis  case  the tag and descr give the tag and description to use and the action indi‐\ncates what should be completed in one of the forms accepted by the arguments  utility\nfunction described below.\n\nFinally, if `compcontext' is set to a string without colons, the value is taken as the\nname of the context to use and the function defined for that context will  be  called.\nFor this purpose, there is a special context named -command-line- that completes whole\ncommand lines (commands and their arguments).  This is not used by the completion sys‐\ntem itself but is nonetheless handled when explicitly called.\n\ncorrect\nGenerate  corrections,  but  not completions, for the current word; this is similar to\napproximate but will not allow any number of extra characters at the cursor  as  that\ncompleter  does.   The  effect is similar to spell-checking.  It is based on approxi‐‐\nmate, but the completer field in the context name is correct.\n\nFor example, with:\n\nzstyle ':completion:::::' completer \\\ncomplete correct approximate\nzstyle ':completion:*:correct:::' max-errors 2 not-numeric\nzstyle ':completion:*:approximate:::' max-errors 3 numeric\n\ncorrection will accept up to two errors.  If a numeric argument is  given,  correction\nwill  not be performed, but correcting completion will be, and will accept as many er‐\nrors as given by the numeric argument.  Without a numeric argument,  first  correction\nand  then correcting completion will be tried, with the first one accepting two errors\nand the second one accepting three errors.\n\nWhen correct is called as a function, the number of errors to  accept  may  be  given\nfollowing  the  -a  option.   The  argument is in the same form a values to the accept\nstyle, all in one string.\n\nThis completer function is intended to be used without the approximate completer  or,\nas  in the example, just before it.  Using it after the approximate completer is use‐\nless since approximate will at least generate the corrected strings generated by  the\ncorrect completer -- and probably more.\n\nexpand\nThis  completer function does not really perform completion, but instead checks if the\nword on the command line is eligible for expansion and, if it is, gives detailed  con‐\ntrol over how this expansion is done.  For this to happen, the completion system needs\nto be invoked with complete-word, not  expand-or-complete  (the  default  binding  for\nTAB),  as  otherwise the string will be expanded by the shell's internal mechanism be‐\nfore the completion system is started.  Note also this completer should be called  be‐\nfore the complete completer function.\n\nThe  tags used when generating expansions are all-expansions for the string containing\nall possible expansions, expansions when adding  the  possible  expansions  as  single\nmatches  and  original  when  adding  the original string from the line.  The order in\nwhich these strings are generated, if at all, can be controlled by the group-order and\ntag-order styles, as usual.\n\nThe  format string for all-expansions and for expansions may contain the sequence `%o'\nwhich will be replaced by the original string from the line.\n\nThe kind of  expansion  to  be  tried  is  controlled  by  the  substitute,  glob  and\nsubst-globs-only styles.\n\nIt  is  also possible to call expand as a function, in which case the different modes\nmay  be  selected  with  options:  -s  for  substitute,  -g  for  glob  and   -o   for\nsubst-globs-only.\n\nexpandalias\nIf  the  word the cursor is on is an alias, it is expanded and no other completers are\ncalled.  The types of aliases which are to be expanded  can  be  controlled  with  the\nstyles regular, global and disabled.\n\nThis function is also a bindable command, see the section `Bindable Commands' below.\n\nextensions\nIf  the  cursor follows the string `*.', filename extensions are completed. The exten‐\nsions are taken from files in current directory or a directory specified at the begin‐\nning  of the current word. For exact matches, completion continues to allow other com‐\npleters such as expand to expand the pattern. The standard add-space and  prefix-hid‐‐\nden styles are observed.\n\nexternalpwds\nCompletes current directories of other zsh processes belonging to the current user.\n\nThis is intended to be used via generic, bound to a custom key combination. Note that\npattern matching is enabled so matching is performed similar to how it works with  the\nmatch completer.\n\nhistory\nComplete words from the shell's command  history.  This completer can be controlled by\nthe remove-all-dups, and sort styles as for the historycompleteword  bindable  com‐\nmand,  see  the  section  `Bindable Commands' below and the section `Completion System\nConfiguration' above.\n\nignored\nThe ignored-patterns style can be set to a list of patterns which are compared against\npossible  completions;  matching  ones are removed.  With this completer those matches\ncan be reinstated, as if no ignored-patterns style were set.  The  completer  actually\ngenerates  its  own list of matches; which completers are invoked is determined in the\nsame way as for the prefix completer.  The single-ignored style is also available  as\ndescribed above.\n\nlist  This  completer  allows the insertion of matches to be delayed until completion is at‐\ntempted a second time without the word on the line being changed.  On  the  first  at‐\ntempt, only the list of matches will be shown.  It is affected by the styles condition\nand word, see the section `Completion System Configuration' above.\n\nmatch This completer is intended to be used after the complete completer.  It behaves simi‐\nlarly  but the string on the command line may be a pattern to match against trial com‐\npletions.  This gives the effect of the GLOBCOMPLETE option.\n\nNormally completion will be performed by taking the pattern from the line, inserting a\n`*'  at the cursor position and comparing the resulting pattern with the possible com‐\npletions generated.  This can be modified  with  the  match-original  style  described\nabove.\n\nThe generated matches will be offered in a menu completion unless the insert-unambigu‐‐\nous style is set to `true'; see the description  above  for  other  options  for  this\nstyle.\n\nNote  that matcher specifications defined globally or used by the completion functions\n(the styles matcher-list and matcher) will not be used.\n\nmenu  This completer was written as simple example function to show how menu completion  can\nbe  enabled in shell code. However, it has the notable effect of disabling menu selec‐\ntion which can be useful with generic based widgets. It should be used as  the  first\ncompleter  in the list.  Note that this is independent of the setting of the MENUCOM‐‐\nPLETE option and does not work with the other menu  completion  widgets  such  as  re‐‐\nverse-menu-complete, or accept-and-menu-complete.\n\noldlist\nThis  completer  controls  how the standard completion widgets behave when there is an\nexisting list of completions which may have been generated  by  a  special  completion\n(i.e.  a separately-bound completion command).  It allows the ordinary completion keys\nto continue to use the list of completions thus generated, instead of producing a  new\nlist  of  ordinary contextual completions.  It should appear in the list of completers\nbefore any of the widgets which generate matches.  It uses two  styles:  old-list  and\nold-menu, see the section `Completion System Configuration' above.\n\nprecommand\nComplete   an   external   command  in  word-separated  arguments,  as  for  exec  and\n/usr/bin/env.\n\nprefix\nThis completer can be used to try completion with the  suffix  (everything  after  the\ncursor)  ignored.  In other words, the suffix will not be considered to be part of the\nword to complete.  The effect is similar to the expand-or-complete-prefix command.\n\nThe completer style is used to decide which other completers are to be called to  gen‐\nerate  matches.   If  this  style is unset, the list of completers set for the current\ncontext is used -- except, of course, the prefix completer itself.   Furthermore,  if\nthis  completer appears more than once in the list of completers only those completers\nnot already tried by the last invocation of prefix will be called.\n\nFor example, consider this global completer style:\n\nzstyle ':completion:*' completer \\\ncomplete prefix correct prefix:foo\n\nHere, the prefix completer tries normal completion but ignoring the suffix.  If  that\ndoesn't  generate any matches, and neither does the call to the correct completer af‐\nter it, prefix will be called a second time and, now only trying correction with  the\nsuffix ignored.  On the second invocation the completer part of the context appears as\n`foo'.\n\nTo use prefix as the last resort and try only normal completion when it is invoked:\n\nzstyle ':completion:*' completer complete ... prefix\nzstyle ':completion::prefix:*' completer complete\n\nThe add-space style is also respected.  If it is set to `true' then prefix  will  in‐\nsert a space between the matches generated (if any) and the suffix.\n\nNote  that this completer is only useful if the COMPLETEINWORD option is set; other‐\nwise, the cursor will be moved to the end of the current word  before  the  completion\ncode is called and hence there will be no suffix.\n\nuserexpand\nThis  completer behaves similarly to the expand completer but instead performs expan‐\nsions defined by users.  The styles add-space and sort styles specific to the  expand\ncompleter are usable with userexpand in addition to other styles handled more gener‐\nally by the completion system.  The tag all-expansions is also available.\n\nThe expansion depends on the array style user-expand being  defined  for  the  current\ncontext;  remember that the context for completers is less specific than that for con‐\ntextual completion as the full context has not yet been determined.  Elements  of  the\narray may have one of the following forms:\n\n$hash\n\nhash  is  the  name of an associative array.  Note this is not a full parameter\nexpression, merely a $, suitably quoted to prevent  immediate  expansion,  fol‐\nlowed by the name of an associative array.  If the trial expansion word matches\na key in hash, the resulting expansion is the corresponding value.\nfunc\n\nfunc is the name of a shell function whose name must begin with  but  is  not\notherwise  special  to  the completion system.  The function is called with the\ntrial word as an argument.  If the word is to be expanded, the function  should\nset the array reply to a list of expansions.  Optionally, it can set REPLY to a\nword that will be used as a description for the set of expansions.  The  return\nstatus of the function is irrelevant.",
            "subsections": []
        },
        "BINDABLE COMMANDS": {
            "content": "In  addition  to the context-dependent completions provided, which are expected to work in an\nintuitively obvious way, there are a few widgets implementing special behaviour which can  be\nbound separately to keys.  The following is a list of these and their default bindings.\n\nbashcompletions\nThis  function is used by two widgets, bashcomplete-word and bashlist-choices.  It\nexists to provide compatibility with completion bindings in bash.  The last  character\nof  the  binding  determines  what  is completed: `!', command names; `$', environment\nvariables; `@', host names; `/', file names; `~' user names.   In  bash,  the  binding\npreceded  by  `\\e'  gives  completion, and preceded by `^X' lists options.  As some of\nthese bindings clash with standard zsh bindings, only `\\e~' and `^X~' are bound by de‐\nfault.   To  add  the rest, the following should be added to .zshrc after compinit has\nbeen run:\n\nfor key in '!' '$' '@' '/' '~'; do\nbindkey \"\\e$key\" bashcomplete-word\nbindkey \"^X$key\" bashlist-choices\ndone\n\nThis includes the bindings for `~' in case they were already bound to something  else;\nthe completion code does not override user bindings.\n\ncorrectfilename (^XC)\nCorrect  the  filename  path  at  the cursor position.  Allows up to six errors in the\nname.  Can also be called with an argument to correct a filename  path,  independently\nof zle; the correction is printed on standard output.\n\ncorrectword (^Xc)\nPerforms  correction of the current argument using the usual contextual completions as\npossible choices. This stores the string `correct-word' in the function field  of  the\ncontext name and then calls the correct completer.\n\nexpandalias (^Xa)\nThis  function  can  be used as a completer and as a bindable command.  It expands the\nword the cursor is on if it is an alias.  The types of  alias  expanded  can  be  con‐\ntrolled with the styles regular, global and disabled.\n\nWhen  used  as a bindable command there is one additional feature that can be selected\nby setting the complete style to `true'.  In this case, if the word is not the name of\nan  alias,  expandalias  tries to complete the word to a full alias name without ex‐\npanding it.  It leaves the cursor directly after the completed word so  that  invoking\nexpandalias once more will expand the now-complete alias name.\n\nexpandword (^Xe)\nPerforms  expansion  on the current word:  equivalent to the standard expand-word com‐\nmand, but using the expand completer.  Before calling it, the function field  of  the\ncontext is set to `expand-word'.\n\ngeneric\nThis function is not defined as a widget and not bound by default.  However, it can be\nused to define a widget and will then store the name of the  widget  in  the  function\nfield  of  the  context and call the completion system.  This allows custom completion\nwidgets with their own set of style settings to be defined easily.   For  example,  to\ndefine a widget that performs normal completion and starts menu selection:\n\nzle -C foo complete-word generic\nbindkey '...' foo\nzstyle ':completion:foo:*' menu yes select=1\n\nNote  in  particular  that  the completer style may be set for the context in order to\nchange the set of functions used to generate possible matches.  If generic is  called\nwith  arguments,  those are passed through to maincomplete as the list of completers\nin place of those defined by the completer style.\n\nhistorycompleteword (\\e/)\nComplete words from the shell's command history. This uses the list,  remove-all-dups,\nsort, and stop styles.\n\nmostrecentfile (^Xm)\nComplete  the name of the most recently modified file matching the pattern on the com‐\nmand line (which may be blank).  If given a numeric argument N, complete the Nth  most\nrecently modified file.  Note the completion, if any, is always unique.\n\nnexttags (^Xn)\nThis  command alters the set of matches used to that for the next tag, or set of tags,\neither as given by the tag-order style or as set by default; these matches would  oth‐\nerwise not be available.  Successive invocations of the command cycle through all pos‐\nsible sets of tags.\n\nreadcomp (^X^R)\nPrompt the user for a string, and use that to perform completion on the current  word.\nThere are two possibilities for the string.  First, it can be a set of words beginning\n`', for example `files -/', in which case the function with any  arguments  will  be\ncalled  to  generate  the completions.  Unambiguous parts of the function name will be\ncompleted automatically (normal completion is not available at  this  point)  until  a\nspace is typed.\n\nSecond,  any  other  string will be passed as a set of arguments to compadd and should\nhence be an expression specifying what should be completed.\n\nA very restricted set of editing commands is available when reading the string:  `DEL'\nand `^H' delete the last character; `^U' deletes the line, and `^C' and `^G' abort the\nfunction, while `RET' accepts the completion.  Note the string is used verbatim  as  a\ncommand line, so arguments must be quoted in accordance with standard shell rules.\n\nOnce  a string has been read, the next call to readcomp will use the existing string\ninstead of reading a new one.  To force a new string to be read, call readcomp  with\na numeric argument.\n\ncompletedebug (^X?)\nThis  widget performs ordinary completion, but captures in a temporary file a trace of\nthe shell commands executed by the completion system.  Each  completion  attempt  gets\nits  own file.  A command to view each of these files is pushed onto the editor buffer\nstack.\n\ncompletehelp (^Xh)\nThis widget displays information about the context names, the tags, and the completion\nfunctions  used when completing at the current cursor position. If given a numeric ar‐\ngument other than 1 (as in `ESC-2 ^Xh'), then the styles used  and  the  contexts  for\nwhich they are used will be shown, too.\n\nNote  that  the information about styles may be incomplete; it depends on the informa‐\ntion available from the completion functions called, which in turn  is  determined  by\nthe user's own styles and other settings.\n\ncompletehelpgeneric\nUnlike  other commands listed here, this must be created as a normal ZLE widget rather\nthan a completion widget (i.e. with zle -N).  It is used for generating  help  with  a\nwidget bound to the generic widget that is described above.\n\nIf  this  widget  is created using the name of the function, as it is by default, then\nwhen executed it will read a key sequence.  This is expected to be bound to a call  to\na  completion  function  that uses the generic widget.  That widget will be executed,\nand information provided in the same format that the  completehelp  widget  displays\nfor contextual completion.\n\nIf  the  widget's  name  contains debug, for example if it is created as `zle -N com‐‐\npletedebuggeneric completehelpgeneric', it will read and  execute  the  keystring\nfor  a  generic  widget  as before, but then generate debugging information as done by\ncompletedebug for contextual completion.\n\nIf the widget's name contains noread, it will not read a keystring but instead arrange\nthat  the  next  use of a generic widget run in the same shell will have the effect as\ndescribed above.\n\nThe widget works by setting the shell parameter ZSHTRACEGENERICWIDGET which is read\nby generic.  Unsetting the parameter cancels any pending effect of the noread form.\n\nFor example, after executing the following:\n\nzle -N completedebuggeneric completehelpgeneric\nbindkey '^x:' completedebuggeneric\n\ntyping `C-x :' followed by the key sequence for a generic widget will cause trace out‐\nput for that widget to be saved to a file.\n\ncompletetag (^Xt)\nThis widget completes symbol tags created by the etags or ctags programmes (note there\nis no connection with the completion system's tags) stored in a file TAGS, in the for‐\nmat used by etags, or tags, in the format created by ctags.  It will look back up  the\npath  hierarchy  for the first occurrence of either file; if both exist, the file TAGS\nis preferred.  You can specify the full path to a TAGS or tags file by setting the pa‐\nrameter  $TAGSFILE  or $tagsfile respectively.  The corresponding completion tags used\nare etags and vtags, after emacs and vi respectively.\n",
            "subsections": []
        },
        "UTILITY FUNCTIONS": {
            "content": "Descriptions follow for utility functions that may be useful when  writing  completion  func‐\ntions.  If functions are installed in subdirectories, most of these reside in the Base subdi‐\nrectory.  Like the example functions for commands in the distribution, the utility  functions\ngenerating  matches all follow the convention of returning status zero if they generated com‐\npletions and non-zero if no matching completions could be added.\n\nabsolutecommandpaths\nThis function completes external commands as absolute paths (unlike commandnames  -e\nwhich completes their basenames).  It takes no arguments.\n\nalllabels [ -x ] [ -12VJ ] tag name descr [ command arg ... ]\nThis  is  a  convenient  interface to the nextlabel function below, implementing the\nloop shown in the nextlabel example.  The command and its arguments  are  called  to\ngenerate  the matches.  The options stored in the parameter name will automatically be\ninserted into the args passed to the command.  Normally, they are put  directly  after\nthe command, but if one of the args is a single hyphen, they are inserted directly be‐\nfore that.  If the hyphen is the last argument, it will be removed from  the  argument\nlist  before  the command is called.  This allows alllabels to be used in almost all\ncases where the matches can be generated by a single call to the compadd builtin  com‐\nmand or by a call to one of the utility functions.\n\nFor example:\n\nlocal expl\n...\nif requested foo; then\n...\nalllabels foo expl '...' compadd ... - $matches\nfi\n\nWill  complete  the  strings from the matches parameter, using compadd with additional\noptions which will take precedence over those generated by alllabels.\n\nalternative [ -O name ] [ -C name ] spec ...\nThis function is useful in simple cases where multiple  tags  are  available.   Essen‐\ntially it implements a loop like the one described for the tags function below.\n\nThe  tags  to  use and the action to perform if a tag is requested are described using\nthe specs which are of the form: `tag:descr:action'.  The tags are offered using tags\nand  if the tag is requested, the action is executed with the given description descr.\nThe actions are those accepted by the arguments function (described below), excluding\nthe `->state' and `=...' forms.\n\nFor example, the action may be a simple function call:\n\nalternative \\\n'users:user:users' \\\n'hosts:host:hosts'\n\noffers usernames and hostnames as possible matches, generated by the users and hosts\nfunctions respectively.\n\nLike arguments, this function uses alllabels to execute  the  actions,  which  will\nloop  over  all  sets of tags.  Special handling is only required if there is an addi‐\ntional valid tag, for example inside a function called from alternative.\n\nThe option `-O name' is used in the same way as by the arguments function.  In  other\nwords,  the elements of the name array will be passed to compadd when executing an ac‐\ntion.\n\nLike tags this function supports the -C option to give a different name for the argu‐\nment context field.\n\n\narguments [ -nswWCRS ] [ -A pat ] [ -O name ] [ -M matchspec ]\n[ : ] spec ...\narguments [ opt ... ] -- [ -l ] [ -i pats ] [ -s pair ]\n[ helpspec ...]\nThis  function  can be used to give a complete specification for completion for a com‐\nmand whose arguments follow standard UNIX option and argument conventions.\n\nOptions Overview\n\nOptions to arguments itself must be in separate words, i.e. -s -w, not -sw.  The  op‐\ntions  are  followed by specs that describe options and arguments of the analyzed com‐\nmand.  To avoid ambiguity, all options to arguments itself may be separated from  the\nspec forms by a single colon.\n\nThe  `--'  form is used to intuit spec forms from the help output of the command being\nanalyzed, and is described in detail below.  The opts for the `--' form are  otherwise\nthe  same  options  as  the  first form.  Note that `-s' following `--' has a distinct\nmeaning from `-s' preceding `--', and both may appear.\n\nThe option switches -s, -S, -A, -w, and -W affect how arguments parses  the  analyzed\ncommand line's options.  These switches are useful for commands with standard argument\nparsing.\n\nThe options of arguments have the following meanings:\n\n-n     With this option, arguments sets the parameter NORMARG to the position of  the\nfirst  normal  argument in the $words array, i.e. the position after the end of\nthe options.  If that argument has not been reached, NORMARG is set to -1.  The\ncaller  should  declare `integer NORMARG' if the -n option is passed; otherwise\nthe parameter is not used.\n\n-s     Enable option stacking for single-letter options, whereby multiple  single-let‐\nter  options  may be combined into a single word.  For example, the two options\n`-x' and `-y' may be combined into a single word `-xy'.  By default, every word\ncorresponds to a single option name (`-xy' is a single option named `xy').\n\nOptions  beginning with a single hyphen or plus sign are eligible for stacking;\nwords beginning with two hyphens are not.\n\nNote that -s after -- has a different meaning, which is documented in the  seg‐\nment entitled `Deriving spec forms from the help output'.\n\n-w     In  combination  with  -s, allow option stacking even if one or more of the op‐\ntions take arguments.  For example, if -x takes an argument, with no -s,  `-xy'\nis  considered  as  a single (unhandled) option; with -s, -xy is an option with\nthe argument `y'; with both -s and -w, -xy is the option -x and the  option  -y\nwith arguments to -x (and to -y, if it takes arguments) still to come in subse‐\nquent words.\n\n-W     This option takes -w a stage further:  it is possible to complete single-letter\noptions  even  after an argument that occurs in the same word.  However, it de‐\npends on the action performed whether options will really be completed at  this\npoint.  For more control, use a utility function like guard as part of the ac‐\ntion.\n\n-C     Modify the curcontext parameter for an action of the form `->state'.   This  is\ndiscussed in detail below.\n\n-R     Return  status  300  instead  of  zero  when  a $state is to be handled, in the\n`->string' syntax.\n\n-S     Do not complete options after a `--' appearing on  the  line,  and  ignore  the\n`--'.  For example, with -S, in the line\n\nfoobar -x -- -y\n\nthe  `-x'  is considered an option, the `-y' is considered an argument, and the\n`--' is considered to be neither.\n\n-A pat Do not complete options after the first non-option argument on the  line.   pat\nis  a pattern matching all strings which are not to be taken as arguments.  For\nexample, to make arguments stop completing options after the first normal  ar‐\ngument,  but  ignoring  all strings starting with a hyphen even if they are not\ndescribed by one of the optspecs, the form is `-A \"-*\"'.\n\n-O name\nPass the elements of the array name as arguments to functions called to execute\nactions.  This is discussed in detail below.\n\n-M matchspec\nUse  the  match specification matchspec for completing option names and values.\nThe default matchspec allows partial word completion after `' and `-', such as\ncompleting `-f-b' to `-foo-bar'.  The default matchspec is:\nr:|[-]=* r:|=*\n\nspecs: overview\n\nEach  of  the following forms is a spec describing individual sets of options or argu‐\nments on the command line being analyzed.\n\nn:message:action\nn::message:action\nThis describes the n'th normal argument.  The message will be printed above the\nmatches  generated and the action indicates what can be completed in this posi‐\ntion (see below).  If there are two colons before the message the  argument  is\noptional.   If  the  message contains only white space, nothing will be printed\nabove the matches unless the action adds an explanation string itself.\n\n:message:action\n::message:action\nSimilar, but describes the next argument, whatever number that happens  to  be.\nIf  all  arguments  are specified in this form in the correct order the numbers\nare unnecessary.\n\n*:message:action\n*::message:action\n*:::message:action\nThis describes how arguments (usually non-option arguments, those not beginning\nwith  -  or +) are to be completed when neither of the first two forms was pro‐\nvided.  Any number of arguments can be completed in this fashion.\n\nWith two colons before the message, the words special  array  and  the  CURRENT\nspecial  parameter  are modified to refer only to the normal arguments when the\naction is executed or evaluated.  With three colons before the message they are\nmodified to refer only to the normal arguments covered by this description.\n\noptspec\noptspec:...\nThis  describes  an option.  The colon indicates handling for one or more argu‐\nments to the option; if it is not present, the option is assumed to take no ar‐\nguments.\n\nThe  following  forms are available for the initial optspec, whether or not the\noption has arguments.\n\n*optspec\nHere optspec is one of the remaining forms below.   This  indicates  the\nfollowing  optspec  may be repeated.  Otherwise if the corresponding op‐\ntion is already present on the command line to the left of the cursor it\nwill not be offered again.\n\n-optname\n+optname\nIn  the simplest form the optspec is just the option name beginning with\na minus or a plus sign, such as `-foo'.  The first argument for the  op‐\ntion (if any) must follow as a separate word directly after the option.\n\nEither  of `-+optname' and `+-optname' can be used to specify that -opt‐\nname and +optname are both valid.\n\nIn all the remaining forms, the leading `-' may be replaced by or paired\nwith `+' in this way.\n\n-optname-\nThe  first  argument  of  the option must come directly after the option\nname in the same word.  For example, `-foo-:...' specifies that the com‐\npleted option and argument will look like `-fooarg'.\n\n-optname+\nThe  first  argument  may  appear  immediately after optname in the same\nword, or may appear as a separate word after the option.   For  example,\n`-foo+:...'  specifies  that the completed option and argument will look\nlike either `-fooarg' or `-foo arg'.\n\n-optname=\nThe argument may appear as the next word, or in same word as the  option\nname  provided that it is separated from it by an equals sign, for exam‐\nple `-foo=arg' or `-foo arg'.\n\n-optname=-\nThe argument to the option must appear after an equals sign in the  same\nword, and may not be given in the next argument.\n\noptspec[explanation]\nAn  explanation  string may be appended to any of the preceding forms of\noptspec by enclosing it in brackets, as in `-q[query operation]'.\n\nThe verbose style is used to decide whether the explanation strings  are\ndisplayed with the option in a completion listing.\n\nIf  no  bracketed  explanation  string is given but the auto-description\nstyle is set and only one argument is described for  this  optspec,  the\nvalue  of  the  style  is displayed, with any appearance of the sequence\n`%d' in it replaced by the message of the first optarg that follows  the\noptspec; see below.\n\nIt  is possible for options with a literal `+' or `=' to appear, but that char‐\nacter must be quoted, for example `-\\+'.\n\nEach optarg following an optspec must take one of the following forms:\n\n:message:action\n::message:action\nAn argument to the option; message and action are treated as  for  ordi‐\nnary  arguments.   In  the first form, the argument is mandatory, and in\nthe second form it is optional.\n\nThis group may be repeated for options which  take  multiple  arguments.\nIn  other  words,  :message1:action1:message2:action2 specifies that the\noption takes two arguments.\n\n:*pattern:message:action\n:*pattern::message:action\n:*pattern:::message:action\nThis describes multiple arguments.  Only the last optarg for  an  option\ntaking  multiple arguments may be given in this form.  If the pattern is\nempty (i.e. :*:), all the remaining words on the line  are  to  be  com‐\npleted  as  described  by the action; otherwise, all the words up to and\nincluding a word matching the pattern are to be completed using the  ac‐\ntion.\n\nMultiple  colons are treated as for the `*:...' forms for ordinary argu‐\nments:  when the message is preceded by two colons,  the  words  special\narray  and  the CURRENT special parameter are modified during the execu‐\ntion or evaluation of the action to refer only to the  words  after  the\noption.   When preceded by three colons, they are modified to refer only\nto the words covered by this description.\n\nAny literal colon in an optname, message, or action must be preceded by  a  backslash,\n`\\:'.\n\nEach  of  the forms above may be preceded by a list in parentheses of option names and\nargument numbers.  If the given option is on the command line, the options  and  argu‐\nments  indicated  in  parentheses  will  not  be  offered.  For example, `(-two -three\n1)-one:...' completes the option `-one'; if this appears on the command line, the  op‐\ntions  -two and -three and the first ordinary argument will not be completed after it.\n`(-foo):...' specifies an ordinary argument completion; -foo will not be completed  if\nthat argument is already present.\n\nOther items may appear in the list of excluded options to indicate various other items\nthat should not be applied when the current specification is matched:  a  single  star\n(*) for the rest arguments (i.e. a specification of the form `*:...'); a colon (:) for\nall normal (non-option-) arguments; and a hyphen (-) for all options.  For example, if\n`(*)' appears before an option and the option appears on the command line, the list of\nremaining arguments (those shown in the above table beginning with `*:') will  not  be\ncompleted.\n\nTo  aid  in  reuse of specifications, it is possible to precede any of the forms above\nwith `!'; then the form will no longer be completed, although if the option  or  argu‐\nment  appears  on  the  command line they will be skipped as normal.  The main use for\nthis is when the arguments are given by an array, and arguments is called  repeatedly\nfor  more  specific  contexts: on the first call `arguments $globaloptions' is used,\nand on subsequent calls `arguments !$^globaloptions'.\n\nspecs: actions\n\nIn each of the forms above the action determines how completions should be  generated.\nExcept  for  the  `->string'  form  below,  the action will be executed by calling the\nalllabels function to process all tag labels.  No special handling of tags is needed\nunless a function call introduces a new one.\n\nThe  functions called to execute actions will be called with the elements of the array\nnamed by the `-O name' option as arguments.  This can be used, for  example,  to  pass\nthe same set of options for the compadd builtin to all actions.\n\nThe forms for action are as follows.\n\n(single unquoted space)\nThis  is  useful where an argument is required but it is not possible or desir‐\nable to generate matches for it.  The message will be displayed but no  comple‐\ntions  listed.  Note that even in this case the colon at the end of the message\nis needed; it may only be omitted when neither  a  message  nor  an  action  is\ngiven.\n\n(item1 item2 ...)\nOne of a list of possible matches, for example:\n\n:foo:(foo bar baz)\n\n((item1\\:desc1 ...))\nSimilar  to the above, but with descriptions for each possible match.  Note the\nbackslash before the colon.  For example,\n\n:foo:((a\\:bar b\\:baz))\n\nThe matches will be listed together with their descriptions if the  description\nstyle is set with the values tag in the context.\n\n->string\nIn  this  form, arguments processes the arguments and options and then returns\ncontrol to the calling function with parameters set to indicate  the  state  of\nprocessing; the calling function then makes its own arrangements for generating\ncompletions.  For example, functions that implement a  state  machine  can  use\nthis type of action.\n\nWhere  arguments encounters action in the `->string' format, it will strip all\nleading and trailing whitespace from string and set the array state to the  set\nof all strings for which an action is to be performed.  The elements of the ar‐\nray statedescr are assigned the corresponding message field from  each  optarg\ncontaining such an action.\n\nBy default and in common with all other well behaved completion functions, ar‐\nguments returns status zero if it was able to add matches and  non-zero  other‐\nwise. However, if the -R option is given, arguments will instead return a sta‐\ntus of 300 to indicate that $state is to be handled.\n\nIn addition to $state and $statedescr, arguments also sets the global parame‐\nters  `context',  `line'  and `optargs' as described below, and does not reset\nany changes made to the special parameters such  as  PREFIX  and  words.   This\ngives  the  calling function the choice of resetting these parameters or propa‐\ngating changes in them.\n\nA function calling arguments with at least one action containing a  `->string'\nmust therefore declare appropriate local parameters:\n\nlocal context state statedescr line\ntypeset -A optargs\n\nto prevent arguments from altering the global environment.\n\n{eval-string}\nA  string  in  braces  is  evaluated as shell code to generate matches.  If the\neval-string itself does not begin with an opening parenthesis or  brace  it  is\nsplit into separate words before execution.\n\n= action\nIf the action starts with `= ' (an equals sign followed by a space), arguments\nwill insert the contents of the argument field of the current  context  as  the\nnew  first  element  in  the words special array and increment the value of the\nCURRENT special parameter.  This has the effect of inserting a dummy word  onto\nthe completion command line while not changing the point at which completion is\ntaking place.\n\nThis is most useful with one of the specifiers that restrict the words  on  the\ncommand  line on which the action is to operate (the two- and three-colon forms\nabove).  One particular use is when an action itself causes arguments on a re‐\nstricted range; it is necessary to use this trick to insert an appropriate com‐\nmand name into the range for the second call to arguments to be able to  parse\nthe line.\n\nword...\nword...\nThis  covers  all  forms  other  than those above.  If the action starts with a\nspace, the remaining list of words will be invoked unchanged.\n\nOtherwise it will be invoked with some extra strings  placed  after  the  first\nword;  these are to be passed down as options to the compadd builtin.  They en‐\nsure that the state specified by arguments, in particular the descriptions  of\noptions  and  arguments,  is correctly passed to the completion command.  These\nadditional arguments are taken from the array parameter `expl';  this  will  be\nset up before executing the action and hence may be referred to inside it, typ‐\nically in an expansion of the form `$expl[@]' which preserves empty elements of\nthe array.\n\nDuring  the performance of the action the array `line' will be set to the normal argu‐\nments from the command line, i.e. the words from the command line  after  the  command\nname excluding all options and their arguments.  Options are stored in the associative\narray `optargs' with option names as keys and their arguments as the values.  For op‐\ntions  that  have  more  than one argument these are given as one string, separated by\ncolons.  All colons and backslashes in the original arguments are preceded with  back‐\nslashes.\n\nThe  parameter  `context'  is set when returning to the calling function to perform an\naction of the form `->string'.  It is set to an array of elements corresponding to the\nelements  of  $state.   Each  element is a suitable name for the argument field of the\ncontext: either a string of the form `option-opt-n' for the n'th argument of  the  op‐\ntion -opt, or a string of the form `argument-n' for the n'th argument.  For `rest' ar‐\nguments, that is those in the list at the end not handled by position, n is the string\n`rest'.   For example, when completing the argument of the -o option, the name is `op‐‐\ntion-o-1', while for the second normal (non-option-) argument it is `argument-2'.\n\nFurthermore, during the evaluation of the action the context name  in  the  curcontext\nparameter  is  altered to append the same string that is stored in the context parame‐\nter.\n\nThe option -C tells arguments to modify the curcontext parameter for an action of the\nform `->state'.  This is the standard parameter used to keep track of the current con‐\ntext.  Here it (and not the context array) should be made local to the  calling  func‐\ntion to avoid passing back the modified value and should be initialised to the current\nvalue at the start of the function:\n\nlocal curcontext=\"$curcontext\"\n\nThis is useful where it is not possible for multiple states to be valid together.\n\nGrouping Options\n\nOptions can be grouped to simplify exclusion lists. A group  is  introduced  with  `+'\nfollowed by a name for the group in the subsequent word. Whole groups can then be ref‐\nerenced in an exclusion list or a group name can be used to disambiguate  between  two\nforms of the same option. For example:\n\narguments \\\n'(group2--x)-a' \\\n+ group1 \\\n-m \\\n'(group2)-n' \\\n+ group2 \\\n-x -y\n\nIf the name of a group is specified in the form `(name)' then only one value from that\ngroup will ever be completed; more formally, all specifications are mutually exclusive\nto  all  other  specifications in that group. This is useful for defining options that\nare aliases for each other. For example:\n\narguments \\\n-a -b \\\n+ '(operation)' \\\n{-c,--compress}'[compress]' \\\n{-d,--decompress}'[decompress]' \\\n{-l,--list}'[list]'\n\nIf an option in a group appears on the command line, it is stored in  the  associative\narray  `optargs'  with  'group-option' as a key.  In the example above, a key `opera‐‐\ntion--c' is used if the option `-c' is present on the command line.\n\nSpecifying Multiple Sets of Arguments\n\nIt is possible to specify multiple sets of options and arguments with the  sets  sepa‐\nrated  by  single  hyphens. This differs from groups in that sets are considered to be\nmutually exclusive of each other.\n\nSpecifications before the first set and from any group are common to all sets. For ex‐\nample:\n\narguments \\\n-a \\\n- set1 \\\n-c \\\n- set2 \\\n-d \\\n':arg:(x2 y2)'\n\nThis  defines  two sets.  When the command line contains the option `-c', the `-d' op‐\ntion and the argument will not be considered possible completions.  When  it  contains\n`-d' or an argument, the option `-c' will not be considered.  However, after `-a' both\nsets will still be considered valid.\n\nAs for groups, the name of a set may appear in exclusion lists, either alone  or  pre‐\nceding a normal option or argument specification.\n\nThe completion code has to parse the command line separately for each set. This can be\nslow so sets should only be used when necessary.  A useful alternative is often an op‐\ntion  specification  with  rest-arguments  (as  in `-foo:*:...'); here the option -foo\nswallows up all remaining arguments as described by the optarg definitions.\n\nDeriving spec forms from the help output\n\nThe option `--' allows arguments to work out the names of long options  that  support\nthe  `--help'  option  which  is  standard  in many GNU commands.  The command word is\ncalled with the argument `--help' and the output examined for option names.   Clearly,\nit  can be dangerous to pass this to commands which may not support this option as the\nbehaviour of the command is unspecified.\n\nIn addition to options, `arguments --' will try to  deduce  the  types  of  arguments\navailable for options when the form `--opt=val' is valid.  It is also possible to pro‐\nvide hints by examining the help text of the command and adding helpspec of  the  form\n`pattern:message:action';  note  that  other  arguments spec forms are not used.  The\npattern is matched against the help text for an option, and if it matches the  message\nand  action are used as for other argument specifiers.  The special case of `*:' means\nboth message and action are empty, which has the effect of causing options  having  no\ndescription  in the help output to be ordered in listings ahead of options that have a\ndescription.\n\nFor example:\n\narguments -- '*\\*:toggle:(yes no)' \\\n'*=FILE*:file:files' \\\n'*=DIR*:directory:files -/' \\\n'*=PATH*:directory:files -/'\n\nHere, `yes' and `no' will be completed as the argument of  options  whose  description\nends  in  a  star; file names will be completed for options that contain the substring\n`=FILE' in the description; and directories will be completed for  options  whose  de‐\nscription  contains  `=DIR' or `=PATH'.  The last three are in fact the default and so\nneed not be given explicitly, although it is possible to override  the  use  of  these\npatterns.  A typical help text which uses this feature is:\n\n-C, --directory=DIR          change to directory DIR\n\nso  that  the above specifications will cause directories to be completed after `--di‐‐\nrectory', though not after `-C'.\n\nNote also that arguments tries to find out automatically if the argument for  an  op‐\ntion  is  optional.  This can be specified explicitly by doubling the colon before the\nmessage.\n\nIf the pattern ends in `(-)', this will be removed from the  pattern  and  the  action\nwill be used only directly after the `=', not in the next word.  This is the behaviour\nof a normal specification defined with the form `=-'.\n\nBy default, the command (with the option `--help') is run after resetting all the  lo‐\ncale  categories  (except for LCCTYPE) to `C'.  If the localized help output is known\nto work, the option `-l' can be specified after the `arguments --' so that  the  com‐\nmand is run in the current locale.\n\nThe  `arguments  --' can be followed by the option `-i patterns' to give patterns for\noptions which are not to be completed.  The patterns can be given as the  name  of  an\narray parameter or as a literal list in parentheses.  For example,\n\narguments -- -i \\\n\"(--(en|dis)able-FEATURE*)\"\n\nwill cause completion to ignore the options `--enable-FEATURE' and `--disable-FEATURE'\n(this example is useful with GNU configure).\n\nThe `arguments --' form can also be followed by the option `-s pair' to describe  op‐\ntion  aliases.   The pair consists of a list of alternating patterns and corresponding\nreplacements, enclosed in parens and quoted so that it forms a single argument word in\nthe arguments call.\n\nFor  example,  some  configure-script  help  output  describes  options only as `--en‐‐\nable-foo', but the script also accepts the negated  form  `--disable-foo'.   To  allow\ncompletion of the second form:\n\narguments -- -s \"((#s)--enable- --disable-)\"\n\nMiscellaneous notes\n\nFinally,  note  that  arguments generally expects to be the primary function handling\nany completion for which it is used.  It may have side effects which change the treat‐\nment  of  any matches added by other functions called after it.  To combine arguments\nwith other functions, those functions should be called either before arguments, as an\naction within a spec, or in handlers for `->state' actions.\n\nHere is a more general example of the use of arguments:\n\narguments '-l+:left border:' \\\n'-format:paper size:(letter A4)' \\\n'*-copy:output file:files::resolution:(300 600)' \\\n':postscript file:files -g \\*.\\(ps\\|eps\\)' \\\n'*:page number:'\n\nThis describes three options: `-l', `-format', and `-copy'.  The first takes one argu‐\nment described as `left border' for which no completion will be offered because of the\nempty action.  Its argument may come directly after the `-l' or it may be given as the\nnext word on the line.\n\nThe `-format' option takes one argument in the next word, described  as  `paper  size'\nfor which only the strings `letter' and `A4' will be completed.\n\nThe  `-copy'  option may appear more than once on the command line and takes two argu‐\nments.  The first is mandatory and will be completed as a filename.  The second is op‐\ntional  (because  of the second colon before the description `resolution') and will be\ncompleted from the strings `300' and `600'.\n\nThe last two descriptions say what should be completed as arguments.   The  first  de‐\nscribes  the  first  argument as a `postscript file' and makes files ending in `ps' or\n`eps' be completed.  The last description gives all other  arguments  the  description\n`page numbers' but does not offer completions.\n\ncacheinvalid cacheidentifier\nThis  function returns status zero if the completions cache corresponding to the given\ncache identifier needs rebuilding.  It determines this by looking up the  cache-policy\nstyle  for the current context.  This should provide a function name which is run with\nthe full path to the relevant cache file as the only argument.\n\nExample:\n\nexamplecachingpolicy () {\n# rebuild if cache is more than a week old\nlocal -a oldp\noldp=( \"$1\"(Nm+7) )\n(( $#oldp ))\n}\n\ncallfunction return name [ arg ... ]\nIf a function name exists, it is called with the arguments args.  The return  argument\ngives the name of a parameter in which the return status from the function name should\nbe stored; if return is empty or a single hyphen it is ignored.\n\nThe return status of callfunction itself is zero if the function name exists and was\ncalled and non-zero otherwise.\n\ncallprogram [ -l ] [ -p ] tag string ...\nThis  function  provides  a  mechanism for the user to override the use of an external\ncommand.  It looks up the command style with the supplied tag.  If the style  is  set,\nits  value is used as the command to execute.  The strings from the call to callpro‐‐\ngram, or from the style if set, are concatenated with spaces between them and the  re‐\nsulting  string  is  evaluated.  The return status is the return status of the command\ncalled.\n\nBy default, the command is run in an environment where all the locale categories  (ex‐\ncept  for LCCTYPE) are reset to `C' by calling the utility function complocale (see\nbelow). If the option `-l' is given, the command is run with the current locale.\n\nIf the option `-p' is supplied it indicates that the command output is  influenced  by\nthe  permissions  it  is  run  with.  If  the  gain-privileges  style  is set to true,\ncallprogram will make use of commands such as sudo, if present on the  command-line,\nto  match  the  permissions to whatever the final command is likely to run under. When\nlooking up the gain-privileges and command styles, the command component of the zstyle\ncontext will end with a slash (`/') followed by the command that would be used to gain\nprivileges.\n\ncombination [ -s pattern ] tag style spec ... field opts ...\nThis function is used to complete combinations of values,  for example pairs of  host‐\nnames  and  usernames.  The style argument gives the style which defines the pairs; it\nis looked up in a context with the tag specified.\n\nThe  style  name  consists  of  field  names  separated  by   hyphens,   for   example\n`users-hosts-ports'.   For each field for a value is already known, a spec of the form\n`field=pattern' is given.  For example, if the command line so far  specifies  a  user\n`pws', the argument `users=pws' should appear.\n\nThe next argument with no equals sign is taken as the name of the field for which com‐\npletions should be generated (presumably not one of the fields for which the value  is\nknown).\n\nThe matches generated will be taken from the value of the style.  These should contain\nthe possible values for the combinations in the appropriate order (users, hosts, ports\nin  the  example above).  The values for the different fields are separated by colons.\nThis can be altered with the option -s to  combination  which  specifies  a  pattern.\nTypically  this  is  a  character class, as for example `-s \"[:@]\"' in the case of the\nusers-hosts style.    Each `field=pattern'  specification  restricts  the  completions\nwhich apply to elements of the style with appropriately matching fields.\n\nIf  no  style  with  the  given  name  is defined for the given tag, or if none of the\nstrings in style's value match, but a function name of the required field preceded  by\nan  underscore  is defined, that function will be called to generate the matches.  For\nexample, if there is no `users-hosts-ports' or no matching hostname when a host is re‐\nquired, the function `hosts' will automatically be called.\n\nIf  the same name is used for more than one field, in both the `field=pattern' and the\nargument that gives the name of the field to be completed, the  number  of  the  field\n(starting with one) may be given after the fieldname, separated from it by a colon.\n\nAll  arguments  after  the  required  field name are passed to compadd when generating\nmatches from the style value, or to the functions for the fields if they are called.\n\ncommandnames [ -e | - ]\nThis function completes words that are valid at command position:  names  of  aliases,\nbuiltins,  hashed  commands, functions, and so on.  With the -e flag, only hashed com‐\nmands are completed.  The - flag is ignored.\n\ncomplocale\nThis function resets all the locale categories other than LCCTYPE to `C' so that  the\noutput  from  external  commands  can  be  easily  analyzed  by the completion system.\nLCCTYPE retains the current value (taking LCALL and  LANG  into  account),  ensuring\nthat non-ASCII characters in file names are still handled properly.\n\nThis function should normally be run only in a subshell, because the new locale is ex‐\nported to the environment. Typical usage would be `$(complocale; command ...)'.\n\ncompleters [ -p ]\nThis function completes names of completers.\n\n-p     Include the leading underscore (`') in the matches.\n\n\ndescribe [-12JVx] [ -oO | -t tag ] descr name1 [ name2 ] [ opt ... ]\n[ -- name1 [ name2 ] [ opt ... ] ... ]\nThis function associates completions with descriptions.  Multiple groups separated  by\n-- can be supplied, potentially with different completion options opts.\n\nThe  descr  is  taken as a string to display above the matches if the format style for\nthe descriptions tag is set.  This is followed by one or two names of arrays  followed\nby options to pass to compadd.  The array name1 contains the possible completions with\ntheir descriptions in the form `completion:description'.  Any literal colons  in  com‐\npletion must be quoted with a backslash.  If a name2 is given, it should have the same\nnumber of elements as name1; in this case the corresponding elements are added as pos‐\nsible  completions  instead of the completion strings from name1.  The completion list\nwill retain the descriptions from name1.  Finally, a set of completion options can ap‐\npear.\n\nIf  the  option  `-o'  appears  before  the  first argument, the matches added will be\ntreated as names of command options (N.B. not shell options),  typically  following  a\n`-',  `--' or `+' on the command line.  In this case describe uses the prefix-hidden,\nprefix-needed and verbose styles to find out if the strings should be added as comple‐\ntions and if the descriptions should be shown.  Without the `-o' option, only the ver‐‐\nbose style is used to decide how descriptions are shown.  If `-O' is used  instead  of\n`-o',  command  options  are completed as above but describe will not handle the pre‐‐\nfix-needed style.\n\nWith the -t option a tag can be specified.  The default is `values' or, if the -o  op‐\ntion is given, `options'.\n\nThe options -1, -2, -J, -V, -x are passed to nextlabel.\n\nIf  selected  by the list-grouped style, strings with the same description will appear\ntogether in the list.\n\ndescribe uses the alllabels function to generate the matches, so it does  not  need\nto appear inside a loop over tag labels.\n\ndescription [ -x ] [ -12VJ ] tag name descr [ spec ... ]\nThis  function  is  not  to  be confused with the previous one; it is used as a helper\nfunction for creating options to compadd.  It is buried  inside  many  of  the  higher\nlevel completion functions and so often does not need to be called directly.\n\nThe  styles  listed  below are tested in the current context using the given tag.  The\nresulting options for compadd are put into the array named name (this is traditionally\n`expl',  but  this convention is not enforced).  The description for the corresponding\nset of matches is passed to the function in descr.\n\nThe  styles  tested  are:  format,  hidden,  matcher,  ignore-line,  ignored-patterns,\ngroup-name  and sort.  The format style is first tested for the given tag and then for\nthe descriptions tag if no value was found, while the remainder are  only  tested  for\nthe  tag given as the first argument.  The function also calls setup which tests some\nmore styles.\n\nThe string returned by the format style (if any) will be modified so that the sequence\n`%d'  is  replaced  by  the  descr  given as the third argument without any leading or\ntrailing white space.  If, after removing the white space,  the  descr  is  the  empty\nstring, the format style will not be used and the options put into the name array will\nnot contain an explanation string to be displayed above the matches.\n\nIf description is called with more than three arguments, the additional specs  should\nbe  of  the form `char:str'.  These supply escape sequence replacements for the format\nstyle: every appearance of `%char' will be replaced by string.\n\nIf the -x option is given, the description will be passed to compadd using the -x  op‐\ntion  instead  of  the  default -X.  This means that the description will be displayed\neven if there are no corresponding matches.\n\nThe options placed in the array name take account of the group-name style, so  matches\nare  placed  in a separate group where necessary.  The group normally has its elements\nsorted (by passing the option -J to compadd), but if an  option  starting  with  `-V',\n`-J', `-1', or `-2' is passed to description, that option will be included in the ar‐\nray.  Hence it is possible for the completion group to be unsorted by giving  the  op‐\ntion `-V', `-1V', or `-2V'.\n\nIn most cases, the function will be used like this:\n\nlocal expl\ndescription files expl file\ncompadd \"$expl[@]\" - \"$files[@]\"\n\nNote  the  use of the parameter expl, the hyphen, and the list of matches.  Almost all\ncalls to compadd within the completion system use a similar format; this ensures  that\nuser-specified  styles  are  correctly passed down to the builtins which implement the\ninternals of completion.\n\ndirlist [ -s sep ] [ -S ]\nComplete a list of directory names separated by colons (the same format as $PATH).\n\n-s sep Use sep as separator between items.  sep defaults to a colon (`:').\n\n-S     Add sep instead of slash (`/') as an autoremoveable suffix.\n\ndispatch context string ...\nThis sets the current context to context and looks for completion functions to  handle\nthis  context by hunting through the list of command names or special contexts (as de‐\nscribed above for compdef) given as strings.  The first completion function to be  de‐\nfined for one of the contexts in the list is used to generate matches.  Typically, the\nlast string is -default- to cause the function for default completion to be used as  a\nfallback.\n\nThe  function sets the parameter $service to the string being tried, and sets the con‐\ntext/command field (the fourth) of the $curcontext parameter to the context  given  as\nthe first argument.\n\nemailaddresses [ -c ] [ -n plugin ]\nComplete email addresses.  Addresses are provided by plugins.\n\n-c     Complete bare localhost@domain.tld addresses, without a name part or a comment.\nWithout this option, RFC822 `Firstname Lastname  <address>'  strings  are  com‐\npleted.\n\n-n plugin\nComplete aliases from plugin.\n\nThe  following  plugins  are available by default: email-ldap (see the filter style),\nemail-local (completes user@hostname Unix addresses), email-mail (completes  aliases\nfrom ~/.mailrc), email-mush, email-mutt, and email-pine.\n\nAddresses from the email-foo plugin are added under the tag `email-foo'.\n\nWriting plugins\n\nPlugins  are  written  as separate functions with names starting with `email-'.  They\nare invoked with the -c option and compadd options.  They should either do  their  own\ncompletion  or  set  the $reply array to a list of `alias:address' elements and return\n300.  New plugins will be picked up and run automatically.\n\nfiles The function files is a wrapper around pathfiles. It supports all of the same func‐\ntionality,  with  some enhancements -- notably, it respects the list-dirs-first style,\nand it allows users to override the behaviour of  the  -g  and  -/  options  with  the\nfile-patterns  style.  files  should  therefore be preferred over pathfiles in most\ncases.\n\nThis function accepts the full set of options allowed by pathfiles, described below.\n\ngnugeneric\nThis function is a simple wrapper around the arguments function described above.   It\ncan  be  used  to determine automatically the long options understood by commands that\nproduce a list when passed the option `--help'.  It  is  intended  to  be  used  as  a\ntop-level completion function in its own right.  For example, to enable option comple‐\ntion for the commands foo and bar, use\n\ncompdef gnugeneric foo bar\n\nafter the call to compinit.\n\nThe completion system as supplied is conservative in its use of this  function,  since\nit is important to be sure the command understands the option `--help'.\n\nguard [ options ] pattern descr\nThis function displays descr if pattern matches the string to be completed.  It is in‐\ntended to be used in the action for the specifications passed to arguments and  simi‐\nlar functions.\n\nThe return status is zero if the message was displayed and the word to complete is not\nempty, and non-zero otherwise.\n\nThe pattern may be preceded by any of the  options  understood  by  compadd  that  are\npassed down from description, namely -M, -J, -V, -1, -2, -n, -F and -X.  All of these\noptions will be ignored.  This fits in conveniently with the argument-passing  conven‐\ntions of actions for arguments.\n\nAs  an  example,  consider a command taking the options -n and -none, where -n must be\nfollowed by a numeric value in the same word.  By using:\n\narguments '-n-: :guard \"[0-9]#\" \"numeric value\"' '-none'\n\narguments can be made to both display the message `numeric value'  and  complete  op‐\ntions  after  `-n<TAB>'.   If  the `-n' is already followed by one or more digits (the\npattern passed to guard) only the message will be displayed; if the `-n' is  followed\nby another character, only options are completed.\n\nmessage [ -r12 ] [ -VJ group ] descr\nmessage -e [ tag ] descr\nThe  descr is used in the same way as the third argument to the description function,\nexcept that the resulting string will always be shown whether or not matches were gen‐\nerated.   This  is useful for displaying a help message in places where no completions\ncan be generated.\n\nThe format style is examined with the messages tag to find a message; the  usual  tag,\ndescriptions, is used only if the style is not set with the former.\n\nIf  the  -r  option  is  given,  no style is used; the descr is taken literally as the\nstring to display.  This is most useful when the descr comes from a pre-processed  ar‐\ngument  list  which  already  contains an expanded description.  Note that this option\ndoes not disable the `%'-sequence parsing done by compadd.\n\nThe -12VJ options and the group are passed to compadd and hence  determine  the  group\nthe message string is added to.\n\nThe  second  -e  form gives a description for completions with the tag tag to be shown\neven if there are no matches for that tag.  This form is called by arguments  in  the\nevent that there is no action for an option specification.  The tag can be omitted and\nif so the tag is taken from the parameter $curtag; this is maintained by  the  comple‐\ntion  system and so is usually correct.  Note that if there are no matches at the time\nthis function is called, compstate[insert] is cleared, so additional matches generated\nlater are not inserted on the command line.\n\nmultiparts [ -i ] sep array\nThe argument sep is a separator character.  The array may be either the name of an ar‐\nray parameter or a literal array in the form `(foo  bar)',  a  parenthesised  list  of\nwords  separated by whitespace.  The possible completions are the strings from the ar‐\nray.  However, each chunk delimited by sep will be completed separately.  For example,\nthe  tar function uses `multiparts / patharray' to complete partial file paths from\nthe given array of complete file paths.\n\nThe -i option causes multiparts to insert a unique match even if that requires  mul‐\ntiple  separators  to  be  inserted.   This is not usually the expected behaviour with\nfilenames, but certain other types of completion, for example those with a  fixed  set\nof possibilities, may be more suited to this form.\n\nLike  other utility functions, this function accepts the `-V', `-J', `-1', `-2', `-n',\n`-f', `-X', `-M', `-P', `-S', `-r', `-R', and `-q' options and passes them to the com‐‐\npadd builtin.\n\nnextlabel [ -x ] [ -12VJ ] tag name descr [ option ... ]\nThis function is used to implement the loop over different tag labels for a particular\ntag as described above for the tag-order style.  On each call  it  checks  to  see  if\nthere are any more tag labels; if there is it returns status zero, otherwise non-zero.\nAs this function requires a current tag to be set, it must always  follow  a  call  to\ntags or requested.\n\nThe  -x12VJ options and the first three arguments are passed to the description func‐\ntion.  Where appropriate the tag will be replaced by a tag label in  this  call.   Any\ndescription given in the tag-order style is preferred to the descr passed to nextla‐‐\nbel.\n\nThe options given after the descr are set in the parameter given by  name,  and  hence\nare to be passed to compadd or whatever function is called to add the matches.\n\nHere is a typical use of this function for the tag foo.  The call to requested deter‐\nmines if tag foo is required at all; the loop over nextlabel handles any labels  de‐\nfined for the tag in the tag-order style.\n\nlocal expl ret=1\n...\nif requested foo; then\n...\nwhile nextlabel foo expl '...'; do\ncompadd \"$expl[@]\" ... && ret=0\ndone\n...\nfi\nreturn ret\n\nnormal [ -P | -p precommand ]\nThis  is  the  standard function called to handle completion outside any special -con‐\ntext-.  It is called both to complete the command word and also the  arguments  for  a\ncommand.  In the second case, normal looks for a special completion for that command,\nand if there is none it uses the completion for the -default- context.\n\nA second use is to reexamine the command line specified by the $words  array  and  the\n$CURRENT parameter after those have been modified.  For example, the function precom‐‐\nmand, which completes after precommand specifiers such as  nohup,  removes  the  first\nword  from  the  words array, decrements the CURRENT parameter, then calls `normal -p\n$service'.  The effect is that `nohup cmd ...' is treated in  the  same  way  as  `cmd\n...'.\n\n-P     Reset  the list of precommands. This option should be used if completing a com‐\nmand line which allows internal commands (e.g. builtins and functions)  regard‐\nless of prior precommands (e.g. `zsh -c').\n\n-p precommand\nAppend  precommand  to  the  list of precommands. This option should be used in\nnearly all cases in which -P is not applicable.\n\nIf the command name matches one of the patterns given by one of the options -p  or  -P\nto  compdef,  the  corresponding  completion function is called and then the parameter\ncompskip is checked.  If it is set completion is terminated at that point even if  no\nmatches have been found.  This is the same effect as in the -first- context.\n\noptions\nThis can be used to complete the names of shell options.  It provides a matcher speci‐\nfication that ignores a leading `no', ignores underscores and allows  upper-case  let‐\nters  to match their lower-case counterparts (for example, `glob', `noglob', `NOGLOB'\nare all completed).  Any arguments are propagated to the compadd builtin.\n\noptionsset and optionsunset\nThese functions complete only set or unset options, with the same matching  specifica‐\ntion used in the options function.\n\nNote  that  you need to uncomment a few lines in the maincomplete function for these\nfunctions to work properly.  The lines in question are used to store the  option  set‐\ntings in effect before the completion widget locally sets the options it needs.  Hence\nthese functions are not generally used by the completion system.\n\nparameters\nThis is used to complete the names of shell parameters.\n\nThe option `-g pattern' limits the completion to parameters  whose  type  matches  the\npattern.   The  type  of a parameter is that shown by `print ${(t)param}', hence judi‐\ncious use of `*' in pattern is probably necessary.\n\nAll other arguments are passed to the compadd builtin.\n\npathfiles\nThis function is used throughout the completion system to complete filenames.  It  al‐\nlows  completion  of  partial paths.  For example, the string `/u/i/s/sig' may be com‐\npleted to `/usr/include/sys/signal.h'.\n\nThe options accepted by both pathfiles and files are:\n\n-f     Complete all filenames.  This is the default.\n\n-/     Specifies that only directories should be completed.\n\n-g pattern\nSpecifies that only files matching the pattern should be completed.\n\n-W paths\nSpecifies path prefixes that are to be prepended to the string from the command\nline  to  generate the filenames but that should not be inserted as completions\nnor shown in completion listings.  Here, paths may be the name of an array  pa‐\nrameter,  a  literal list of paths enclosed in parentheses or an absolute path‐\nname.\n\n-F ignored-files\nThis behaves as for the corresponding option to the compadd builtin.  It  gives\ndirect  control  over  which filenames should be ignored.  If the option is not\npresent, the ignored-patterns style is used.\n\nBoth pathfiles and files also accept the following options which are passed to com‐‐\npadd: `-J', `-V', `-1', `-2', `-n', `-X', `-M', `-P', `-S', `-q', `-r', and `-R'.\n\nFinally,  the  pathfiles  function  uses the styles expand, ambiguous, special-dirs,\nlist-suffixes and file-sort described above.\n\n\npickvariant [ -b builtin-label ] [ -c command ] [ -r name ]\nlabel=pattern ... label [ arg ... ]\nThis function is used to resolve situations where a single command name requires  more\nthan  one  type  of  handling,  either because it has more than one variant or because\nthere is a name clash between two different commands.\n\nThe command to run is taken from the first element of the array words unless  this  is\noverridden  by  the  option -c.  This command is run and its output is compared with a\nseries of patterns.  Arguments to be passed to the command can be specified at the end\nafter  all  the  other arguments.  The patterns to try in order are given by the argu‐\nments label=pattern; if the output of `command arg ...' contains pattern,  then  label\nis  selected as the label for the command variant.  If none of the patterns match, the\nfinal command label is selected and status 1 is returned.\n\nIf the `-b builtin-label' is given, the command is tested to see if it is provided  as\na  shell  builtin,  possibly autoloaded; if so, the label builtin-label is selected as\nthe label for the variant.\n\nIf the `-r name' is given, the label picked is stored in the parameter named name.\n\nThe results are also cached in the cmdvariant associative array indexed by the  name\nof the command run.\n\nregexarguments name spec ...\nThis  function  generates  a completion function name which matches the specifications\nspecs, a set of regular expressions as described below.   After  running  regexargu‐‐\nments,  the  function name should be called as a normal completion function.  The pat‐\ntern to be matched is given by the contents of the words array up to the current  cur‐\nsor position joined together with null characters; no quotation is applied.\n\nThe  arguments  are  grouped as sets of alternatives separated by `|', which are tried\none after the other until one matches.  Each alternative consists of  a  one  or  more\nspecifications which are tried left to right, with each pattern matched being stripped\nin turn from the command line being tested, until all of the group succeeds  or  until\none  fails;  in the latter case, the next alternative is tried.  This structure can be\nrepeated to arbitrary depth by using parentheses; matching  proceeds  from  inside  to\noutside.\n\nA  special  procedure  is  applied  if no test succeeds but the remaining command line\nstring contains no null character (implying the remaining word is the  one  for  which\ncompletions  are to be generated).  The completion target is restricted to the remain‐\ning word and any actions for the corresponding patterns are executed.  In  this  case,\nnothing  is stripped from the command line string.  The order of evaluation of the ac‐\ntions can be determined by the tag-order style; the various formats supported by  al‐‐\nternative can be used in action.  The descr is used for setting up the array parameter\nexpl.\n\nSpecification arguments take one of following forms, in which metacharacters  such  as\n`(', `)', `#' and `|' should be quoted.\n\n/pattern/ [%lookahead%] [-guard] [:tag:descr:action]\nThis  is a single primitive component.  The function tests whether the combined\npattern `(#b)((#B)pattern)lookahead*' matches the command line string.  If  so,\n`guard' is evaluated and its return status is examined to determine if the test\nhas succeeded.  The pattern string `[]' is  guaranteed  never  to  match.   The\nlookahead  is not stripped from the command line before the next pattern is ex‐\namined.\n\nThe argument starting with : is used in the same manner as an argument to  al‐‐\nternative.\n\nA  component  is used as follows: pattern is tested to see if the component al‐\nready exists on the command line.  If it does, any following specifications are\nexamined  to find something to complete.  If a component is reached but no such\npattern exists yet on the command line, the string  containing  the  action  is\nused to generate matches to insert at that point.\n\n/pattern/+ [%lookahead%] [-guard] [:tag:descr:action]\nThis is similar to `/pattern/ ...' but the left part of the command line string\n(i.e. the part already matched by previous patterns) is also considered part of\nthe completion target.\n\n/pattern/- [%lookahead%] [-guard] [:tag:descr:action]\nThis  is  similar  to `/pattern/ ...' but the actions of the current and previ‐\nously matched patterns are ignored even if the following `pattern' matches  the\nempty string.\n\n( spec )\nParentheses  may be used to groups specs; note each parenthesis is a single ar‐\ngument to regexarguments.\n\nspec # This allows any number of repetitions of spec.\n\nspec spec\nThe two specs are to be matched one after the other as described above.\n\nspec | spec\nEither of the two specs can be matched.\n\nThe function regexwords can be used as a helper function to generate matches  for  a\nset of alternative words possibly with their own arguments as a command line argument.\n\nExamples:\n\nregexarguments tst /$'[^\\0]#\\0'/ \\\n/$'[^\\0]#\\0'/ :'compadd aaa'\n\nThis  generates  a function tst that completes aaa as its only argument.  The tag and\ndescription for the action have been omitted for brevity (this works but is not recom‐\nmended  in  normal use).  The first component matches the command word, which is arbi‐\ntrary; the second matches  any argument.  As the argument is also arbitrary, any  fol‐\nlowing component would not depend on aaa being present.\n\nregexarguments tst /$'[^\\0]#\\0'/ \\\n/$'aaa\\0'/ :'compadd aaa'\n\nThis is a more typical use; it is similar, but any following patterns would only match\nif aaa was present as the first argument.\n\nregexarguments tst /$'[^\\0]#\\0'/ \\( \\\n/$'aaa\\0'/ :'compadd aaa' \\\n/$'bbb\\0'/ :'compadd bbb' \\) \\#\n\nIn this example, an indefinite number of command arguments may be completed.  Odd  ar‐\nguments  are  completed as aaa and even arguments as bbb.  Completion fails unless the\nset of aaa and bbb arguments before the current one is matched correctly.\n\nregexarguments tst /$'[^\\0]#\\0'/ \\\n\\( /$'aaa\\0'/ :'compadd aaa' \\| \\\n/$'bbb\\0'/ :'compadd bbb' \\) \\#\n\nThis is similar, but either aaa or bbb may be completed for  any  argument.   In  this\ncase regexwords could be used to generate a suitable expression for the arguments.\n\nregexwords tag description spec ...\nThis function can be used to generate arguments for the regexarguments command which\nmay be inserted at any point where a set of rules is expected.  The tag  and  descrip‐\ntion give a standard tag and description pertaining to the current context.  Each spec\ncontains two or three arguments separated by a colon: note that there  is  no  leading\ncolon in this case.\n\nEach  spec  gives  one of a set of words that may be completed at this point, together\nwith arguments.  It is thus roughly equivalent to the arguments function when used in\nnormal (non-regex) completion.\n\nThe  part  of  the  spec before the first colon is the word to be completed.  This may\ncontain a *; the entire word, before and after the * is completed, but only  the  text\nbefore  the * is required for the context to be matched, so that further arguments may\nbe completed after the abbreviated form.\n\nThe second part of spec is a description for the word being completed.\n\nThe optional third part of the spec describes how words following the one  being  com‐\npleted  are  themselves to be completed.  It will be evaluated in order to avoid prob‐\nlems with quoting.  This means that typically it contains a reference to an array con‐\ntaining previously generated regex arguments.\n\nThe  option  -t  term  specifies a terminator for the word instead of the usual space.\nThis is handled as an auto-removable suffix in the manner of  the  option  -s  sep  to\nvalues.\n\nThe  result  of  the  processing  by  regexwords is placed in the array reply, which\nshould be made local to the calling function.  If the set of words and  arguments  may\nbe matched repeatedly, a # should be appended to the generated array at that point.\n\nFor example:\n\nlocal -a reply\nregexwords mydb-commands 'mydb commands' \\\n'add:add an entry to mydb:$mydbaddcmds' \\\n'show:show entries in mydb'\nregexarguments mydb \"$reply[@]\"\nmydb \"$@\"\n\nThis shows a completion function for a command mydb which takes two command arguments,\nadd and show.  show takes no arguments, while the arguments for add have already  been\nprepared in an array mydbaddcmds, quite possibly by a previous call to regexwords.\n\nrequested [ -x ] [ -12VJ ] tag [ name descr [ command [ arg ... ] ]\nThis  function is called to decide whether a tag already registered by a call to tags\n(see below) has been requested by the user and hence completion  should  be  performed\nfor  it.   It returns status zero if the tag is requested and non-zero otherwise.  The\nfunction is typically used as part of a loop over different tags as follows:\n\ntags foo bar baz\nwhile tags; do\nif requested foo; then\n... # perform completion for foo\nfi\n... # test the tags bar and baz in the same way\n... # exit loop if matches were generated\ndone\n\nNote that the test for whether matches were generated is not performed until  the  end\nof  the tags loop.  This is so that the user can set the tag-order style to specify a\nset of tags to be completed at the same time.\n\nIf name and descr are given, requested calls the description function with these ar‐\nguments together with the options passed to requested.\n\nIf command is given, the alllabels function will be called immediately with the same\narguments.  In simple cases this makes it possible to perform the test for the tag and\nthe matching in one go.  For example:\n\nlocal expl ret=1\ntags foo bar baz\nwhile tags; do\nrequested foo expl 'description' \\\ncompadd foobar foobaz && ret=0\n...\n(( ret )) || break\ndone\n\nIf the command is not compadd, it must nevertheless be prepared to handle the same op‐\ntions.\n\nretrievecache cacheidentifier\nThis function retrieves completion information from the file  given  by  cacheidenti‐\nfier,  stored  in  a  directory  specified  by  the cache-path style which defaults to\n~/.zcompcache.  The return status is zero if retrieval was successful.  It  will  only\nattempt retrieval if the use-cache style is set, so you can call this function without\nworrying about whether the user wanted to use the caching layer.\n\nSee storecache below for more details.\n\nsepparts\nThis function is passed alternating arrays and separators as  arguments.   The  arrays\nspecify  completions  for parts of strings to be separated by the separators.  The ar‐\nrays may be the names of array parameters or a quoted list of  words  in  parentheses.\nFor  example,  with  the  array  `hosts=(ftp news)' the call `sepparts '(foo bar)' @\nhosts' will complete the string  `f' to `foo' and the string `b@n' to `bar@news'.\n\nThis function accepts the compadd options `-V', `-J', `-1', `-2',  `-n',  `-X',  `-M',\n`-P', `-S', `-r', `-R', and `-q' and passes them on to the compadd builtin used to add\nthe matches.\n\nsequence [ -s sep ] [ -n max ] [ -d ] function [ - ] ...\nThis function is a wrapper to other functions for  completing  items  in  a  separated\nlist.  The  same  function is used to complete each item in the list. The separator is\nspecified with the -s option. If -s is omitted it will use `,'. Duplicate  values  are\nnot  matched unless -d is specified. If there is a fixed or maximum number of items in\nthe list, this can be specified with the -n option.\n\nCommon compadd options are passed on to the function. It is possible  to  use  compadd\ndirectly with sequence, though values may be more appropriate in this situation.\n\nsetup tag [ group ]\nThis  function  sets up the special parameters used by the completion system appropri‐\nately for the tag given as the  first  argument.   It  uses  the  styles  list-colors,\nlist-packed, list-rows-first, last-prompt, accept-exact, menu and force-list.\n\nThe optional group supplies the name of the group in which the matches will be placed.\nIf it is not given, the tag is used as the group name.\n\nThis function is called automatically from description  and  hence  is  not  normally\ncalled explicitly.\n\nstorecache cacheidentifier param ...\nThis  function, together with retrievecache and cacheinvalid, implements a caching\nlayer which can be used in any completion function.  Data obtained  by  costly  opera‐\ntions  are  stored in parameters; this function then dumps the values of those parame‐\nters to a file.  The data can then be  retrieved  quickly  from  that  file  via  re‐‐\ntrievecache, even in different instances of the shell.\n\nThe  cacheidentifier specifies the file which the data should be dumped to.  The file\nis stored in a directory specified by the cache-path style which defaults to ~/.zcomp‐‐\ncache.  The remaining params arguments are the parameters to dump to the file.\n\nThe  return  status is zero if storage was successful.  The function will only attempt\nstorage if the use-cache style is set, so you can call this function without  worrying\nabout whether the user wanted to use the caching layer.\n\nThe completion function may avoid calling retrievecache when it already has the com‐\npletion data available as parameters.  However, in that case it should call cachein‐‐\nvalid to check whether the data in the parameters and in the cache are still valid.\n\nSee  the  perlmodules  completion  function for a simple example of the usage of the\ncaching layer.\n\ntags [ [ -C name ] tag ... ]\nIf called with arguments, these are taken to be the names of tags  valid  for  comple‐\ntions  in  the  current context.  These tags are stored internally and sorted by using\nthe tag-order style.\n\nNext, tags is called repeatedly without arguments from the same completion  function.\nThis  successively  selects the first, second, etc. set of tags requested by the user.\nThe return status is zero if at least one of the tags is requested and non-zero other‐\nwise.   To  test if a particular tag is to be tried, the requested function should be\ncalled (see above).\n\nIf `-C name' is given, name is temporarily stored in the argument field (the fifth) of\nthe  context  in  the  curcontext parameter during the call to tags; the field is re‐\nstored on exit.  This allows tags to use a more specific context  without  having  to\nchange and reset the curcontext parameter (which has the same effect).\n\ntildefiles\nLike  files, but resolve leading tildes according to the rules of filename expansion,\nso the suggested completions don't start with a `~' even if the filename on  the  com‐\nmand-line does.\n\nvalues [ -O name ] [ -s sep ] [ -S sep ] [ -wC ] desc spec ...\nThis  is used to complete arbitrary keywords (values) and their arguments, or lists of\nsuch combinations.\n\nIf the first argument is the option `-O name', it will be used in the same way  as  by\nthe  arguments  function.   In  other  words,  the elements of the name array will be\npassed to compadd when executing an action.\n\nIf the first argument (or the first argument after `-O name') is `-s', the next  argu‐\nment is used as the character that separates multiple values.  This character is auto‐\nmatically added after each value in an auto-removable fashion (see below); all  values\ncompleted  by `values -s' appear in the same word on the command line, unlike comple‐\ntion using arguments.  If this option is not present, only a  single  value  will  be\ncompleted per word.\n\nNormally, values will only use the current word to determine which values are already\npresent on the command line and hence are not to be completed again.  If the -w option\nis given, other arguments are examined as well.\n\nThe first non-option argument, desc, is used as a string to print as a description be‐\nfore listing the values.\n\nAll other arguments describe the possible values and their arguments in the same  for‐\nmat  used  for the description of options by the arguments function (see above).  The\nonly differences are that no minus or plus sign is required at the  beginning,  values\ncan  have  only one argument, and the forms of action beginning with an equal sign are\nnot supported.\n\nThe character separating a value from its argument can be  set  using  the  option  -S\n(like -s, followed by the character to use as the separator in the next argument).  By\ndefault the equals sign will be used as the separator between values and arguments.\n\nExample:\n\nvalues -s , 'description' \\\n'*foo[bar]' \\\n'(two)*one[number]:first count:' \\\n'two[another number]::second count:(1 2 3)'\n\nThis describes three possible values: `foo', `one', and `two'.  The first is described\nas `bar', takes no argument and may appear more than once.  The second is described as\n`number', may appear more than once, and takes one  mandatory  argument  described  as\n`first  count';  no  action is specified, so it will not be completed.  The `(two)' at\nthe beginning says that if the value `one' is on the line, the  value  `two'  will  no\nlonger  be  considered  a possible completion.  Finally, the last value (`two') is de‐\nscribed as `another number' and takes an optional argument described as `second count'\nfor which the completions (to appear after an `=') are `1', `2', and `3'.  The values\nfunction will complete lists of these values separated by commas.\n\nLike arguments, this function temporarily adds another context name component to  the\narguments element (the fifth) of the current context while executing the action.  Here\nthis name is just the name of the value for which the argument is completed.\n\nThe style verbose is used to decide if the descriptions for the values (but not  those\nfor the arguments) should be printed.\n\nThe  associative  array  valargs  is  used to report values and their arguments; this\nworks similarly to the optargs associative array used by arguments.  Hence the func‐\ntion  calling  values  should  declare the local parameters state, statedescr, line,\ncontext and valargs:\n\nlocal context state statedescr line\ntypeset -A valargs\n\nwhen using an action of the form `->string'.  With this function the context parameter\nwill be set to the name of the value whose argument is to be completed.  Note that for\nvalues, the state and statedescr are scalars rather  than  arrays.   Only  a  single\nmatching state is returned.\n\nNote  also that values normally adds the character used as the separator between val‐\nues as an auto-removable suffix (similar to a `/' after a directory).   However,  this\nis  not possible for a `->string' action as the matches for the argument are generated\nby the calling function.  To get the usual behaviour, the calling function can add the\nseparator  x  as a suffix by passing the options `-qS x' either directly or indirectly\nto compadd.\n\nThe option -C is treated in the same way as it is by arguments.  In that case the pa‐\nrameter curcontext should be made local instead of context (as described above).\n\nwanted [ -x ] [ -C name ]  [ -12VJ ] tag name descr command [ arg ...]\nIn  many contexts, completion can only generate one particular set of matches, usually\ncorresponding to a single tag.  However, it is still necessary to decide  whether  the\nuser requires matches of this type.  This function is useful in such a case.\n\nThe  arguments  to  wanted  are the same as those to requested, i.e. arguments to be\npassed to description.  However, in this case the command is not optional;   all  the\nprocessing  of  tags, including the loop over both tags and tag labels and the genera‐\ntion of matches, is carried out automatically by wanted.\n\nHence to offer only one tag and immediately add the  corresponding  matches  with  the\ngiven description:\n\nlocal expl\nwanted tag expl 'description' \\\ncompadd matches...\n\nNote  that, as for requested, the command must be able to accept options to be passed\ndown to compadd.\n\nLike tags this function supports the -C option to give a different name for the argu‐\nment context field.  The -x option has the same meaning as for description.\n\nwidgets [ -g pattern ]\nThis function completes names of zle widgets (see the section `Widgets' in zshzle(1)).\nThe pattern, if present, is matched against values of the $widgets special  parameter,\ndocumented in the section `The zsh/zleparameter Module' in zshmodules(1).\n",
            "subsections": []
        },
        "COMPLETION SYSTEM VARIABLES": {
            "content": "There  are  some standard variables, initialised by the maincomplete function and then used\nfrom other functions.\n\nThe standard variables are:\n\ncompcalleroptions\nThe completion system uses setopt to set a number of options. This allows functions to\nbe  written  without concern for compatibility with every possible combination of user\noptions. However, sometimes completion needs to know what the  user's  option  prefer‐\nences  are.  These  are  saved  in  the compcalleroptions associative array. Option\nnames, spelled in lowercase without underscores, are mapped to one  or  other  of  the\nstrings `on' and `off'.\n\ncompprivprefix\nCompletion  functions  such  as  sudo can set the compprivprefix array to a\ncommand prefix that may then be used by callprogram to match  the  privileges\nwhen calling programs to generate matches.\n\nTwo more features are offered by the maincomplete function.  The arrays compprefuncs\nand comppostfuncs may contain names of functions that are to be called immediately be‐\nfore  or  after completion has been tried.  A function will only be called once unless\nit explicitly reinserts itself into the array.\n",
            "subsections": []
        },
        "COMPLETION DIRECTORIES": {
            "content": "In the source distribution, the files are contained in various subdirectories of the  Comple‐‐\ntion directory.  They may have been installed in the same structure, or into one single func‐\ntion directory.  The following is a description of the files found in the original  directory\nstructure.   If  you wish to alter an installed file, you will need to copy it to some direc‐\ntory which appears earlier in your fpath than the standard directory where it appears.\n\nBase   The core functions and special completion widgets automatically bound  to  keys.   You\nwill  certainly need most of these, though will probably not need to alter them.  Many\nof these are documented above.\n\nZsh    Functions for completing arguments of shell builtin commands and utility functions for\nthis.  Some of these are also used by functions from the Unix directory.\n\nUnix   Functions  for completing arguments of external commands and suites of commands.  They\nmay need modifying for your system, although in many cases some attempt is made to de‐\ncide  which  version  of  a command is present.  For example, completion for the mount\ncommand tries to determine the system it is running  on,  while  completion  for  many\nother  utilities  try  to decide whether the GNU version of the command is in use, and\nhence whether the --help option is supported.\n\nX, AIX, BSD, ...\nCompletion and utility function for commands available only on  some  systems.   These\nare  not  arranged hierarchically, so, for example, both the Linux and Debian directo‐\nries, as well as the X directory, may be useful on your system.\n\n\n\nzsh 5.8.1                                 February 12, 2022                            ZSHCOMPSYS(1)",
            "subsections": []
        }
    },
    "summary": "zshcompsys - zsh completion system",
    "flags": [],
    "examples": [],
    "see_also": []
}