NAME
    Complete - Convention for Complete::* modules family

VERSION
    This document describes version 0.202 of Complete (from Perl
    distribution Complete), released on 2020-01-28.

DESCRIPTION
    The namespace "Complete::" is used for the family of modules that deal
    with completion (including, but not limited to, shell tab completion,
    tab completion feature in other CLI-based application, web autocomplete,
    completion in GUI, etc). These modules try to have a clear separation
    between general completion routine and shell-/environment specific ones,
    for more reusability.

    This POD page establishes convention and gives an overview of the
    modules in "Complete::*".

  Modules
   Common/shared settings and other stuffs
    Complete::Common

   Generic (non-environment-specific) modules
    Modules usually are named after the type of completion answer they
    provide. For example: Complete::Unix completes username/group name,
    Complete::Getopt::Long completes from Getopt::Long specification,
    Complete::Module completes Perl module names, and so on. A current
    exception is Complete::Util which contains several generic routines, the
    main one is "complete_array_elem()" which is used by most other
    completion routines.

   Environment-specific modules
    "Complete::Bash::*" modules are specific to bash shell. See
    Complete::Bash on some of the ways to do bash tab completion with Perl.
    Other shells are also supported. For shell-specific information, please
    refer to Complete::Zsh, Complete::Tcsh, Complete::Fish, as well as their
    submodules.

    "Complete::*" modules for non-shell environment (like browser or GUI)
    have not been developed. Please check again from time to time in the
    future.

  "complete_*()" functions
    The main functions that do the actual completion are the "complete_*()"
    functions. These functions are generic completion routines: they accept
    the word to be completed, zero or more other arguments, and return a
    completion answer structure (see "Completion answer structure").

     use Complete::Util qw(complete_array_elem);
     my $ary = complete_array_elem(array=>[qw/apple apricot banana/], word=>'ap');
     # -> ['apple', 'apricot']

    Convention for "complete_*" function:

    *   Accept a hash argument

        Example:

         complete_array_elem(%args)

        Required arguments: "word" (the word to be completed). Sometimes,
        for lower-level functions, you can accept "words" and "cword"
        instead of "word", For example, in function
        "Complete::Getopt::Long::complete_cli_arg".

        You can define more arguments as you see fit. Often there is at
        least one argument to specify or customize the source of completion,
        for example for the function "Complete::Util::complete_array_elem"
        there is an "array" argument to specify the source array.

    *   Observe settings specified in Complete::Common

        Example settings in Complete::Common include whether search should
        be case-insensitive, whether fuzzy searching should be done, etc.
        See the module's documentation for more details.

    *   Return completion answer structure

        See "Completion answer structure".

  Completion answer structure
    "complete_*()" functions return completion answer structure. This
    structure contains the completion entries as well as extra metadata to
    give hints to formatters/tools.

   Hash form
    It is a DefHash which can contain the following keys:

    *   words => array|hash

        Required (unless "message" is present). Its value is an array of
        completion entries. A completion entry can be a string or a hashref
        (a DefHash). Example:

         ['apple', 'apricot'] # array of strings

         [{word=>'apple', summary=>'A delicious fruit with thousands of varieties'},
          {word=>'apricot', summary=>'Another delicious fruit'},] # array of hashes

        As you can see from the above, each entry specifies the word and can
        also contain additional information: summary (str, short one-line
        description about the entry, can be displayed alongside the entry),
        is_partial (bool, specify whether this is a partial completion which
        means the word is not the full entry).

         # example of digit-by-digit completion
         [
           {word=>'11', is_partial=>1},
           {word=>'12', is_partial=>1},
           ...
           {word=>'19', is_partial=>1},
         ],

    *   is_partial => bool

        Optional. If set to true, specifies that the entries in words are
        partial completion entries. This is equivalent to setting
        "is_partial => 1" to all the entries.

    *   path_sep => str

        Optional. If set, express that the completion should be done in
        "path mode", useful for completing/drilling-down path.

        In shells like bash, for example, when completing filename (e.g.
        "foo") and there is only a single possible completion (e.g. "foo" or
        "foo.txt"), the shell will display the completion in the buffer and
        automatically add a space so the user can move to the next argument.
        This is also true when completing other values like variables or
        program names.

        However, when completing directory (e.g. "/et" or "Downloads") and
        there is solely a single completion possible and it is a directory
        (e.g. "/etc" or "Downloads"), instead of adding a space, the shell
        will automatically add the path separator character ("/etc/" or
        "Downloads/"). The user can press Tab again to complete for
        files/directories inside that directory, and so on. This is
        obviously more convenient compared to when shell adds a space
        instead.

        Path mode is not restricted to completing filesystem paths. Anything
        path-like can use it. For example when you are completing Java or
        Perl module name (e.g. "com.company.product.whatever" or
        "File::Spec::Unix") you can use this mode (with "path_sep"
        appropriately set to, e.g. "." or "::").

    *   static => bool

        Optional. Specifies that completion is "static", meaning that it
        does not depend on external state (like filesystem) or a custom code
        which can return different answer everytime completion is requested.

        This can be useful for code that wants to generate completion code,
        like bash completion or fish completion. Knowing that completion for
        an option value is static means that completion for that option can
        be answered from an array instead of having to call code/program
        (faster).

    *   message => string

        Optional. Instead of returning completion entries ("words"), a
        completion answer can also opt to request showing a message (i.e.
        error message, or informational message) to the user.

    Implementations that want to observe more information can do so in the
    "x.NAME.WHATEVER" attribute, as per recommended by DefHash. For example:

     {
      words => ["foo", "bar"],
      'x.bash.escape_dollar' => 1,
     }

   Array form
    As a shortcut, completion answer can also be an arrayref (just the
    "words") without any metadata.

    Examples:

     # hash form
     {words=>[qw/apple apricot/]}

     # another hash form. type=env instructs formatter not to escape '$'
     {words=>[qw/$HOME $ENV/], type=>'env'}

     # array form
     ['apple', 'apricot']

     # another array form, each entry is a hashref to include description
     [{word=>'apple', summary=>'A delicious fruit with thousands of varieties'},
      {word=>'apricot', summary=>'Another delicious fruit'},] # array of hashes

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/Complete>.

SOURCE
    Source repository is at <https://github.com/perlancar/perl-Complete>.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=Complete>

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2020, 2019, 2018, 2015, 2014 by
    perlancar@cpan.org.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

