Complete - Convention for Complete::* modules family and common settings
This document describes version 0.11 of Complete (from Perl distribution Complete), released on 2015-01-09.
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.
Complete::
This POD page gives an overview of the modules in Complete::* namespace, establishes convention, and declares common settings.
Complete::*
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).
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::Bash::*
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_*()
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:
complete_*
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.
word
words
cword
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).
ci
$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.
Complete::Util::complete_array_elem
array
Return completion answer structure
See "Completion answer structure".
Use defaults from global Complete settings, when applicable
See "SETTINGS"" in "
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
escmode => str
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
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.
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.
completion-ignore-case
$Complete::OPT_MAP_CASE
This is exactly like completion-map-case in readline/bash to treat _ and - as the same when matching.
completion-map-case
_
-
All Complete::Path-based modules (like Complete::Util's complete_file()), Complete::Module, or Complete::Riap respect this setting.
complete_file()
$Complete::OPT_EXP_IM_PATH
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.
cd /h/u/b/myscript
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
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:
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:
OPT_EXP_IM_PATH_MAX_LEN
we expand l, D, Zi, but not Plugi. So to get expansion you'll have to write:
l
D
Zi
Plugi
l/D/Zi/P/Author<tab> l/D/Zi/Pl/Author<tab>
which is usually fine.
$Complete::OPT_DIG_LEAF
(Experimental) When enabled, this option mimics what's seen on GitHub. If a directory entry only contains a single subentry, it will directly show the subentry (and subsubentry and so on) to save a number of tab presses.
Suppose you have files like this:
a b/c/d/e c
If you complete for b you will directly get b/c/d/e (the leaf).
b
b/c/d/e
This is currently experimental because if you want to complete only directories, you won't get b or b/c or b/c/d. Need to think how to solve this.
Set default for $Complete::OPT_CI.
Set default for $Complete::OPT_MAP_CASE.
Set default for $Complete::OPT_EXP_IM_PATH.
Set default for $Complete::OPT_EXP_IM_PATH_MAX_LEN.
Set default for $Complete::OPT_DIG_LEAF.
Please visit the project's homepage at https://metacpan.org/release/Complete.
Source repository is at https://github.com/perlancar/perl-Complete.
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.
perlancar <perlancar@cpan.org>
This software is copyright (c) 2015 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.
To install Complete, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Complete
CPAN shell
perl -MCPAN -e shell install Complete
For more information on module installation, please visit the detailed CPAN module installation guide.