/ 
Complete-Bash-0.08
River stage three • 26 direct dependents • 616 total dependents
/ Complete::Bash

NAME

Complete::Bash - Completion module for bash shell

VERSION

This document describes version 0.08 of Complete::Bash (from Perl distribution Complete-Bash), released on 2014-07-23.

DESCRIPTION

Bash allows completion to come from various sources. The simplest is from a list of words (-W):

% complete -W "one two three four" somecmd
% somecmd t<Tab>
two  three

Another source is from a bash function (-F). The function will receive input in two variables: COMP_WORDS (array, command-line chopped into words) and COMP_CWORD (integer, index to the array of words indicating the cursor position). It must set an array variable COMPREPLY that contains the list of possible completion:

% _foo()
{
  local cur
  COMPREPLY=()
  cur=${COMP_WORDS[COMP_CWORD]}
  COMPREPLY=($( compgen -W '--help --verbose --version' -- $cur ) )
}
% complete -F _foo foo
% foo <Tab>
--help  --verbose  --version

And yet another source is an external command (including, a Perl script). The command receives two environment variables: COMP_LINE (string, raw command-line) and COMP_POINT (integer, cursor location). Program must split COMP_LINE into words, find the word to be completed, complete that, and return the list of words one per-line to STDOUT. An example:

% cat foo-complete
#!/usr/bin/perl
use Complete::Bash qw(parse_cmdline format_completion);
use Complete::Util qw(complete_array_elem);
my ($words, $cword) = parse_cmdline();
my $res = complete_array_elem(array=>[qw/--help --verbose --version/], word=>$words->[$cword]);
print format_completion($res);

% complete -C foo-complete foo
% foo --v<Tab>
--verbose --version

This module provides routines for you to be doing the above.

Instead of being called by bash as an external command every time user presses Tab, you can also use Perl to generate bash complete scripts for you. See Complete::BashGen.

FUNCTIONS

break_cmdline_into_words($cmdline, $word_breaks) -> array

Break command-line string into words.

Note to users: this is an internal function. Normally you only need to use parse_cmdline.

The first step of shell completion is to break the command-line string (e.g. from COMP_LINE in bash) into words.

Bash by default split using these characters (from COMP_WORDBREAKS):

COMP_WORDBREAKS=$' \t\n"\'@><=;|&(:'

We don't necessarily want to split using default bash's rule, for example in Perl we might want to complete module names which contain colons (e.g. Module::Path).

By default, this routine splits by spaces and tabs and takes into account backslash and quoting. Unclosed quotes won't generate error.

Arguments ('*' denotes required arguments):

  • cmdline* => str

  • word_breaks => str

Return value:

(array)

format_completion($shell_completion) -> array|str

Format completion for output (for shell).

Bash accepts completion reply in the form of one entry per line to STDOUT. Some characters will need to be escaped. This function helps you do the formatting, with some options.

This function accepts an array (the result of a complete_* function), or a hash (which contains the completion array from a complete_* function as well as other metadata for formatting hints). Known keys:

  • completion (array): The completion array. You can put the result of complete_* function here.

  • as (str): Either string (the default) or array (to return array of lines instead of the lines joined together). Returning array is useful if you are doing completion inside Term::ReadLine, for example, where the library expects an array.

  • escmode (str): Escaping mode for entries. Either default (most nonalphanumeric characters will be escaped), shellvar (like default, but dollar sign $ will not be escaped, convenient when completing environment variables for example), filename (currently equals to default), option (currently equals to default), or none (no escaping will be done).

  • path_sep (str): If set, will enable "path mode", useful for completing/drilling-down path. Below is the description of "path mode".

    In shell, 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), the shell automatically adds the path separator character instead (/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.

    The path_sep option, when set, will employ a trick to mimic this behaviour. The trick is, if you have a completion array of ['foo/'], it will be changed to ['foo/', 'foo/ '] (the second element is the first element with added space at the end) to prevent bash from adding a space automatically.

    Path mode is not restricted to completing filesystem paths. Anything path-like can use it. For example when you are completing Java or Perl package 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 ::). But note that in the case of :: since colon is a word-breaking character in Bash by default, when typing you'll need to escape it (e.g. mpath File\:\:Sp<tab>) or use it inside quotes (e.g. mpath "File::Sp<tab>).

Arguments ('*' denotes required arguments):

  • shell_completion* => array|hash

    Result of shell completion.

    Either an array or hash. See function description for more details.

Return value:

Formatted string (or array, if `as` is set to `array`) (any)

parse_cmdline($cmdline, $point, $word_breaks) -> array

Parse shell command-line for processing by completion routines.

Examples:

parse_cmdline("cmd ", 4); # -> [[], 0]

The command (first word) is never included.

parse_cmdline("cmd -", 5); # -> [["-"], 0]
parse_cmdline("cmd - ", 6); # -> [["-"], 1]
parse_cmdline("cmd --opt val", 6); # -> [["--", "val"], 0]
parse_cmdline("cmd --opt val", 9); # -> [["--opt", "val"], 0]
parse_cmdline("cmd --opt val", 10); # -> [["--opt"], 1]
parse_cmdline("cmd --opt val", 13); # -> [["--opt", "val"], 1]
parse_cmdline("cmd --opt val ", 14); # -> [["--opt", "val"], 2]
parse_cmdline("cmd --opt=val", 13); # -> [["--opt=val"], 0]

Other word-breaking characters (other than whitespace) is not used by default.

parse_cmdline("cmd --opt=val", 13, "="); # -> [["--opt", "=", "val"], 2]

Breaking at '=' too.

parse_cmdline("cmd --opt=val ", 14, "="); # -> [["--opt", "=", "val"], 3]

Breaking at '=' too (2).

parse_cmdline("cmd \"--opt=val", 13, "="); # -> [["--opt=va"], 0]

Double quote protects word-breaking characters.

Currently only supports bash.

Arguments ('*' denotes required arguments):

  • cmdline => str

    Command-line, defaults to COMP_LINE environment.

  • point => int

    Point/position to complete in command-line, defaults to COMP_POINT.

  • word_breaks => str

    Extra characters to break word at.

    In addition to space and tab.

    Example: =:.

    Note that the characters won't break words if inside quotes or escaped.

Return value:

(array)

Return a 2-element array: `[$words, $cword]`. `$words` is array of str, equivalent to `COMP_WORDS` provided by shell to bash function. `$cword` is an integer, equivalent to shell-provided `COMP_CWORD` variable to bash function. The word to be completed is at `$words->[$cword]`.

TODOS

Accept regex for path_sep.

SEE ALSO

Complete

Complete::BashGen

Other modules related to bash shell tab completion: Bash::Completion, Getopt::Complete. Term::Bash::Completion::Generator

Programmable Completion section in Bash manual: https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Complete-Bash.

SOURCE

Source repository is at https://github.com/sharyanto/perl-Complete-Bash.

BUGS

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

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

Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Steven Haryanto.

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