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). This (family of) modules try 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, establishes convention, and declares common settings.

 Modules

  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 routines to complete
    from common/generic sources (array, hash, file, environment).

  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.

      Optional common arguments: ci (bool, whether the matching should be
      case-insensitive, if unspecified should default to
      $Complete::OPT_CI).

      Other arguments: you can define more arguments as you 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.

      * Return completion answer structure

      See "Completion answer structure".

      * Use defaults from global Complete settings, when applicable

      See "SETTINGS"" in "

 Completion answer structure

    complete_*() functions return completion answer structure. Completion
    answer contains the completion entries as well as extra metadata to
    give hints to formatters/tools. It is a hashref which can contain the
    following keys:

      * words => array

      This key is required. Its value is an array of completion entries. A
      completion entry can be a string or a hashref. 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 can contain description
      (can be displayed in shells that support them, like fish and zsh).

      * type => str

      See Complete::Bash.

      * path_sep => str

      See Complete::Bash.

      * escmode => str

      See Complete::Bash.

      * static => bool

      Specify 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).

    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

SETTINGS

    This module also defines some configuration variable. Complete::*
    modules should use the default from these settings, to make it
    convenient for users to change some behavior globally.

    The defaults are optimized for convenience and laziness for user typing
    and might change from release to release.

 $Complete::OPT_CI => bool (default: from COMPLETE_OPT_CI or 1)

    If set to 1, matching is done case-insensitively. This setting should
    be consulted as the default for all ci arguments in the complete_*
    functions. But users can override this setting by providing value to ci
    argument.

    In bash/readline, this is akin to setting completion-ignore-case.

 $Complete::OPT_MAP_CASE => bool (default: from COMPLETE_OPT_MAP_CASE or 1)

    This is exactly like completion-map-case in readline/bash to treat _
    and - as the same when matching.

    All Complete::Path-based modules (like Complete::Util's
    complete_file()), Complete::Module, or Complete::Riap respect this
    setting.

 $Complete::OPT_EXP_IM_PATH => bool (default: from COMPLETE_OPT_EXP_IM_PATH
 or 1)

    Whether to "expand intermediate paths". What is meant by this is
    something like zsh: when you type something like cd /h/u/b/myscript it
    can be completed to cd /home/ujang/bin/myscript.

    All Complete::Path-based modules (like Complete::Util's
    complete_file()), Complete::Module, or Complete::Riap respect this
    setting.

 $Complete::OPT_EXP_IM_PATH_MAX_LEN => int (default: from
 COMPLETE_OPT_EXP_IM_PATH_MAX_LEN or 2)

    Wehn OPT_EXP_IM_PATH is active, because of the way bash does completion
    (it cuts current word to the shortest common denominator of all
    completion candidates), in some cases this can be annoying because it
    prevents completion to be done the way we want. For example:

     l/D/Zi/Plugi/Author<tab>

    if we have:

     lib/Dist/Zilla/Plugin/Author/
     lib/Dist/Zilla/PluginBundle/Author/

    the completion candidates are both the above, and bash cuts our word at
    the buffer to:

     lib/Dist/Zilla/Plugin

    even if we type / and then Tab like this:

     lib/Dist/Zilla/Plugin/<tab>

    bash will again cuts the buffer to become:

     lib/Dist/Zilla/Plugin

    To work around (or compromise around) this, the setting
    OPT_EXP_IM_PATH_MAX_LEN is introduced. The default is 2. So if a path
    element is over 2 characters long, expand will not be done. This means
    in this path:

     l/D/Zi/Plugi/Author<tab>

    we expand l, D, Zi, but not Plugi. So to get expansion you'll have to
    write:

     l/D/Zi/P/Author<tab>
     l/D/Zi/Pl/Author<tab>

    which is usually fine.

ENVIRONMENT

 COMPLETE_OPT_CI => bool

    Set default for $Complete::OPT_CI.

 COMPLETE_OPT_MAP_CASE => bool

    Set default for $Complete::OPT_MAP_CASE.

 COMPLETE_OPT_EXP_IM_PATH => bool

    Set default for $Complete::OPT_EXP_IM_PATH.

 COMPLETE_OPT_EXP_IM_PATH_MAX_LEN => int

    Set default for $Complete::OPT_EXP_IM_PATH_MAX_LEN.

TODO

    COMPLETE_OPT_MAX_RESULT?

SEE ALSO