NAME

Complete - Convention for Complete::* modules family

VERSION

This document describes version 0.201 of Complete (from Perl distribution Complete), released on 2019-06-26.

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

• message => string

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

• words => array

  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 specify the word and can also contain additional information: summary (str, short one-line description, can be displayed e.g. in shells that support them, like fish and zsh), is_partial (bool, specify whether this is a partial completion).

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

• is_partial => bool

  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.

• type => str

  See Complete::Bash.

• path_sep => str

  See Complete::Bash.

• esc_mode => 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

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

cpanm Complete

perl -MCPAN -e shell
install Complete