Utility Functions
=================

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

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

_all_labels [ -12VJ ] TAG NAME DESCR [ COMMAND ARGS ... ]
     This is a convenient interface to the _next_label function below,
     implementing the loop shown in the _next_label example.  The
     COMMAND is the one that should be called to generate the matches.
     The options stored in the parameter NAME will automatically be
     inserted into the ARGS given to the COMMAND.  Normally, they are
     put directly after the COMMAND, but if one of the ARGS is a single
     hyphen, they are inserted directly before that. If the hyphen is
     the last argument, that will be removed from the argument list
     before the COMMAND is called. This allows _all_labels to be used
     in almost all cases where the matches can be generated by a single
     call to the compadd builtin command or by a call to one of the
     utility functions.

     For example:

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

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

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

     The tags to use and the action to perform if a tag is requested are
     described using the SPECS which are of the form:
     `TAG:DESCR:ACTION'. The TAGs are offered using _tags and if the
     tag is requested, the ACTION is executed with the given
     description DESCR.  The ACTIONs supported are those used by the
     _arguments function (described below), without the `->STATE' and
     `=...' forms.

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

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

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

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

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

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

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

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

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

          With two colons before the MESSAGE, the words special array
          and the CURRENT special parameter are modified to refer only
          to the normal arguments when the ACTION is executed or
          evaluated.  With three colons before the MESSAGE they are
          modified to refer only to the normal arguments covered by
          this description.

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

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

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

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

          The forms of OPTSPEC are:

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

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

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

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

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

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

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

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

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

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

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

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

          Each DESCRIPTION following an OPTSPEC must take one of the
          following forms:

         :MESSAGE:ACTION
         ::MESSAGE:ACTION
               Describes a mandatory argument with one colon, or an
               optional argument with two colons.  As in other forms of
               SPEC, the MESSAGE will be printed above the matches
               generated (unless it contains only white space, see
               above) and the ACTION says what can be completed in this
               position.

         :*PATTERN:MESSAGE:ACTION
         :*PATTERN::MESSAGE:ACTION
         :*PATTERN:::MESSAGE:ACTION
               This describes multiple arguments.  Only the _last_
               description may be given in this form.  If the PATTERN
               is empty (i.e., :*:), all following words on the line
               are to be completed as described by the ACTION;
               otherwise, all words up to a word matching the PATTERN
               are to be completed using the ACTION.

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

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

     To include a colon in any OPTNAME, MESSAGE, or ACTION anywhere
     above, it has to be preceded by a backslash, as `\:'.

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

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

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

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

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

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

          :foo:(foo bar baz)

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

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

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

     An ACTION of the form `->STRING' is used by functions that
     implement a state machine. In this case, the `STRING's (with all
     leading and trailing spaces and tabs removed) of all actions that
     have to be used will be stored in the global array state.  The
     function returns with a non-zero return value if the cursor is not
     in a position where options can be completed or if the current
     word could not be completed to an option.  But if the -R option is
     given to _arguments, the function will instead return with a return
     value of 300 (to make it distinguishable from other return values)
     after setting the global `context', `line' and `opt_args'
     parameters as described below, and without resetting any changes
     made to the special parameters such as PREFIX and words.  This
     enables wrapper functions around _arguments to be able to find out
     if they have to make sure that the special completion parameters
     are not reset when they return.

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

          local context state line
          typeset -A opt_args

     This will ensure that _arguments does not create unused global
     parameters.

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

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

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

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

     Also, during the evaluation of the ACTION, the context name in the
     curcontext parameter is changed by appending the same string that
     is stored in the context parameter.

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

     For example:

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

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

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

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

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

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

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

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

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

          local curcontext="$curcontext"

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

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

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

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

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

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

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

     Example:

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

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

     The last two descriptions say what should be completed as
     arguments. The first one describes the first argument as a
     `POSTSCRIPT FILE' and makes files ending in `ps' or `eps' be
     completed. The last description says that all other arguments are
     `PAGE NUMBERS' but does not give possible completions.

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

     Example:

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

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

_call_program TAG STRING ...
     This function is used in places where a command is called, making
     it possible for the user to override the default command call.  It
     looks up the command style with the supplied TAG.  If the style is
     set, its value is used as the command to execute.

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

_combination [ -s PATTERN ] TAG STYLE SPECS ... FIELD OPTS ...
     This function is used to complete combinations of values such as
     pairs of hostnames and usernames.  The possible values will be
     taken from the STYLE whose name is given as the second argument.
     The first argument is the TAG to use to do the lookup.

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

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

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

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

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

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

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

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

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

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

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

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

     The string returned by the format style (if any) will be modified
     so that the sequence `%d' is replaced by the DESCR given as the
     third argument without any leading or trailing white space.  If,
     after removing the white space, the DESCR is the empty string, the
     format style will not be used and the options put into the NAME
     array will not contain an explanation string to be displayed above
     the matches.  If _description is called with more than three
     arguments, the additional SPECS should be of the form `CHAR:STR'
     and every appearance of `%CHAR' in the format string will be
     replaced by STRING.

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

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

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

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

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

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

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

          compdef _gnu_generic foo bar

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

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

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

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

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

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

     or

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     The options accepted by both _path_files and _files are:

    -f
          Complete all filenames.  This is the default.

    -/
          Specifies that only directories should be completed.

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

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

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

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

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

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

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

    /PATTERN/ [%LOOKAHEAD%] [-GUARD] [:TAG:DESCR:ACTION]
          This is a primitive element, corresponding to one state of
          the compiled state machine.  The state is entered if
          `(#b)((#B)PATTERN)(#B)LOOKAHEAD*' matches the command line
          string.  If it matches, `GUARD' is evaluated and its return
          status is examined; if this is successful, the state is
          entered, otherwise the test fails and other candidates are
          tried.  The PATTERN string `[]' is guaranteed never to match.

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

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

    /PATTERN/+ [%LOOKAHEAD%] [-GUARD] [:TAG:DESCR:ACTION]
          This is similar to `/PATTERN/ ...' but the left part of the
          command line string is also considered as part of the
          completion target.

    /PATTERN/- [%LOOKAHEAD%] [-GUARD] [:TAG:DESCR:ACTION]
          This is similar to `/PATTERN/ ...' but the ACTIONs of the
          current and previous states are ignored even if the following
          state's `PATTERN' matches the empty string.

    ( SPEC )
          This groups SPECs.

    SPEC #
          This allows any number of repetitions of SPEC.

    SPEC SPEC
          This represents the concatenation of two SPECs.

    SPEC | SPEC
          Either of the two SPECs can be matched.

_requested [ -12VJ ] TAG [ NAME DESCR [ COMMAND ARGS ... ] ]
     This function is called to decide whether a tag already registered
     by a call to _tags (see below) is requested and hence completion
     should be performed for it; it returns status zero if the tag is
     requested and non-zero otherwise.  This will usually be done in a
     loop such as the following:

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

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

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

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

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

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

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

     See _store_cache below for more details.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     Example:

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

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

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

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

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

          local context state line
          typeset -A val_args

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

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

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

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

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

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

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

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

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