.. zsh-module-meta::
   :name: zsh/computil
   :summary: A module with utility builtins needed for the shell function based completion system.

.. index:: single: completion, utility; Command

The ``zsh/computil`` module adds several builtin commands that are used by
some of the completion functions in the completion system based on shell
functions (see :manpage:`zshcompsys`).
Except for ``compquote`` these builtin commands are very
specialised and thus not very interesting when writing your own
completion functions.  In summary, these builtin commands are:

.. index:: single: comparguments; Function

``comparguments``
    
    This is used by the ``_arguments`` function to do the argument and
    command line parsing.  Like ``compdescribe`` it has an option ``-i`` to 
    do the parsing and initialize some internal state and various options
    to access the state information to decide what should be completed.
    

.. index:: single: compdescribe; Function

``compdescribe``
    
    This is used by the ``_describe`` function to build the displays for
    the matches and to get the strings to add as matches with their
    options.  On the first call one of the options ``-i`` or ``-I`` should be
    supplied as the first argument.  In the first case, display strings without
    the descriptions will be generated, in the second case, the string used to
    separate the matches from their descriptions must be given as the
    second argument and the descriptions (if any) will be shown.  All other 
    arguments are like the definition arguments to ``_describe`` itself.
    
    Once ``compdescribe`` has been called with either the ``-i`` or the
    ``-I`` option, it can be repeatedly called with the ``-g`` option and
    the names of four parameters as its arguments.  This will step through
    the different sets of matches and store the value of ``compstate[list]``
    in the first scalar, the options for ``compadd`` in the second array,
    the matches in the third array, and the strings to be displayed in the
    completion listing in the fourth array.  The arrays may then be directly
    given to ``compadd`` to register the matches with the completion code.
    

.. index:: single: compfiles; Function

``compfiles``
    
    Used by the ``_path_files`` function to optimize complex recursive
    filename generation (globbing).  It does three things.  With the
    ``-p`` and ``-P`` options it builds the glob patterns to use,
    including the paths already handled and trying to optimize the
    patterns with respect to the prefix and suffix from the line and the
    match specification currently used.  The ``-i`` option does the
    directory tests for the ``ignore-parents`` style and the ``-r`` option 
    tests if a component for some of the matches are equal to the string
    on the line and removes all other matches if that is true.
    

.. index:: single: compgroups; Function

``compgroups``
    
    Used by the ``_tags`` function to implement the internals of the
    ``group-order`` style.  This only takes its arguments as names of
    completion groups and creates the groups for it (all six types: sorted 
    and unsorted, both without removing duplicates, with removing all
    duplicates and with removing consecutive duplicates).
    

.. index:: single: compquote; Function

``compquote`` [ ``-p`` ] :var:`names` ...
    
    There may be reasons to write completion functions that have to add
    the matches using the ``-Q`` option to ``compadd`` and perform quoting
    themselves.  Instead of interpreting the first character of the
    ``all_quotes`` key of the ``compstate`` special association and using
    the ``q`` flag for parameter expansions, one can use this builtin
    command.  The arguments are the names of scalar or array parameters
    and the values of these parameters are quoted as needed for the
    innermost quoting level.  If the ``-p`` option is given, quoting is
    done as if there is some prefix before the values of the parameters,
    so that a leading equal sign will not be quoted.
    
    The return status is non-zero in case of an error and zero otherwise.
    

.. index:: single: comptags; Function

.. index:: single: comptry; Function

``comptags``

``comptry``
    
    These implement the internals of the tags mechanism.
    

.. index:: single: compvalues; Function

``compvalues``
    
    Like ``comparguments``, but for the ``_values`` function.
    

