NAME
    Complete - Completion modules family

VERSION
    This document describes version 0.04 of Complete (from Perl distribution
    Complete), released on 2014-11-27.

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). Compared to other modules, this (family of)
    module(s) tries to have a clear separation between general completion
    routine and shell-/environment specific ones, for more reusability.

    This POD page gives an overview of the modules in "Complete::*"
    namespace.

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

    Other modules usually are named after the type of completion answer they
    provide. For example: Complete::Unix completes username/group name,
    Complete::Util completes from several generic sources:
    "complete_array_elem" completes from an array, "complete_env" from a
    list of environment variables, "complete_file" from files/directories on
    the filesystem.

    "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']

  Completion answer structure
    "complete_*()" functions can return an arrayref or hashref. An example
    of the arrayref form:

     ['apple', 'apricot']

    That is, the completion answer is simply an array of words. However,
    each element can also be a hashref to give metadata to each entry, for
    example:

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

    The "summary" can be used, e.g. by the fish shell which displays a
    description beside each completion. Or by other environments as they see
    fit. Other metadata can also be added to each entry's hashref.

    The second form of completion answer structure is hashref. It must
    contain the main key "words" which is the same structure as the arrayref
    above. Aside from "words", the hashref can contain extra metadata which
    can give hints to the formatter on how to better format/display the
    answer: "type", "path_sep", "escmode" etc (see Complete::Bash for
    example on what hints it understands).

     {words=>[qw/apple apricot/]}
     {words=>[qw/$HOME $ENV/], type=>'env'}

    In the second example, "Complete::Bash::format_completion()" can be
    instructed to produce the final result like this:

     $HOME
     $ENV

    However, given one of these:

     [qw/$HOME $ENV/]
     {words=>[qw/$HOME $ENV/], type=>'filename'}

    then "format_completion()" will produce:

     \$HOME
     \$ENV

    the difference is the escaping backslash for the "$" character.

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

SOURCE
    Source repository is at <https://github.com/sharyanto/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) 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.