view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME
    Complete::Bash - Completion routines for bash shell

VERSION
    This document describes version 0.337 of Complete::Bash (from Perl
    distribution Complete-Bash), released on 2022-09-08.

DESCRIPTION
    This module provides routines related to tab completion in bash shell.

  About programmable completion in bash
    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 ("-C") including, from 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

  About the routines in this module
    First of all, "parse_cmdline()" is the function to parse raw
    command-line (such as what you get from bash in "COMP_LINE" environment
    variable) into words. This makes it easy for the other functions to
    generate completion answer. See the documentation for that function for
    more details.

    "format_completion()" is what you use to format completion answer
    structure for bash.

FUNCTIONS
  format_completion
    Usage:

     format_completion($completion, $opts) -> str|array

    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 completion answer structure as described in the
    "Complete" POD. Aside from "words", this function also recognizes these
    keys:

    This function is not exported by default, but exportable.

    Arguments ('*' denotes required arguments):

    *   $completion* => *hash|array*

        Completion answer structure.

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

    *   $opts => *hash*

        Specify options.

        Known options:

        *   as

README  view on Meta::CPAN

    *   Like bash, we group non-whitespace word-breaking characters into its
        own word. By default "COMP_WORDBREAKS" is:

        "'@><=;|&(:

        So if raw command-line is:

        command --foo=bar http://example.com:80 mail@example.org Foo::Bar

        then the parse result will be:

        ["command", "--foo", "=", "bar", "http", ":", "//example.com", ":",
        "80", "Foo", "::", "Bar"]

        which is annoying sometimes. But we follow bash here so we can more
        easily accept input from a joined "COMP_WORDS" if we write
        completion bash functions, e.g. (in the example, "foo" is a Perl
        script):

        *foo () { local words=(${COMP*CWORDS[@]}) # add things to words, etc
        local point=... # calculate the new point COMPREPLY=(
        "COMP_LINE="foo ${words[@]}" COMP_POINT=$point foo" ) }

        To avoid these word-breaking characters to be split/grouped, we can
        escape them with backslash or quote them, e.g.:

        command "http://example.com:80" Foo\:\:Bar

        which bash will parse as:

        ["command", "\"http://example.com:80\"", "Foo\:\:Bar"]

        and we parse as:

        ["command", "http://example.com:80", "Foo::Bar"]

    *   Due to the way bash parses the command line (see above), the two
        below are equivalent:

        % cmd --foo=bar % cmd --foo = bar

    Because they both expand to "['--foo', '=', 'bar']". But obviously
    Getopt::Long does not regard the two as equivalent.

    This function is not exported by default, but exportable.

    Arguments ('*' denotes required arguments):

    *   $cmdline => *str*

        Command-line, defaults to COMP_LINE environment.

    *   $opts => *hash*

        Options.

        Optional. Known options:

        *   "truncate_current_word" (bool). If set to 1, will truncate
            current word to the position of cursor, for example ("^" marks
            the position of cursor): "--vers^oo" to "--vers" instead of
            "--versoo". This is more convenient when doing tab completion.

    *   $point => *int*

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

    Return value: (array)

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

    Note that COMP_LINE includes the command name. If you want the
    command-line arguments only (like in @ARGV), you need to strip the first
    element from $words and reduce $cword by 1.

  point
    Usage:

     point($cmdline, $marker) -> any

    Return line with point marked by a marker.

    This is a utility function useful for testing/debugging.
    "parse_cmdline()" expects a command-line and a cursor position ($line,
    $point). This routine expects $line with a marker character (by default
    it's the caret, "^") and return ($line, $point) to feed to
    "parse_cmdline()".

    Example:

     point("^foo") # => ("foo", 0)
     point("fo^o") # => ("foo", 2)

    This function is not exported by default, but exportable.

    Arguments ('*' denotes required arguments):

    *   $cmdline => *str*

        Command-line which contains a marker character.

    *   $marker => *str* (default: "^")

        Marker character.

    Return value: (any)

ENVIRONMENT
  COMPLETE_BASH_DEFAULT_ESC_MODE
    Str. To provide default for the "esc_mode" option in
    "format_completion".

  COMPLETE_BASH_FZF
    Bool. Whether to pass large completion answer to fzf instead of directly
    passing it to bash and letting bash page it with a simpler more-like
    internal pager. By default, large is defined as having at least 100
    items (same bash's "completion-query-items" setting). This can be
    configured via "COMPLETE_BASH_FZF_ITEMS".

    Will not pass to fzf if inside emacs ("INSIDE_EMACS" environment is
    true).

  COMPLETE_BASH_FZF_ITEMS
    Uint. Default 100. The minimum number of items to trigger passing
    completion answer to "fzf".

    A special value of -1 means to use terminal height. However, since
    terminal height (and width) normally cannot be read during tab
    completion anyway, it's better if you do something like this in your
    bash startup file:

     export COMPLETE_BASH_FZF_ITEMS=$LINES

    because without passing to "fzf", as soon as the number of completion
    answers exceeds $LINES, "bash" will start paging the answer to its
    internal pager, which is limited like "more". If you set the above, then
    as soon as the number of completion answers exceeds terminal height, you
    will avoid the bash internal pager and use the nicer "fzf".

    See also: "COMPLETE_BASH_FZF".

  COMPLETE_BASH_MAX_COLUMNS
    Uint.