NAME
    Complete::Bash - Completion module for bash shell

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

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(@args) -> 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:

  format_completion(@args) -> 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. C<foo>) and there is only a single
          possible completion (e.g. C<foo> or C<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. C</et> or C<Downloads>) and there is
          solely a single completion possible and it is a directory (e.g. C</etc> or
          C<Downloads>), the shell automatically adds the path separator character
          instead (C</etc/> or C<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 C<path_sep> option, when set, will employ a trick to mimic this behaviour.
          The trick is, if you have a completion array of C<['foo/']>, it will be changed
          to C<['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. C<com.company.product.whatever> or C<File::Spec::Unix>) you can use this
          mode (with C<path_sep> appropriately set to, e.g. C<.> or C<::>). But note that
          in the case of C<::> since colon is a word-breaking character in Bash by
          default, when typing you'll need to escape it (e.g. C<mpath File\:\:Sp<tab>>)
          or use it inside quotes (e.g. C<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(@args) -> array
    Parse shell command-line for processing by completion routines.

    Examples:

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

    The command (first word) is never included.

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

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

     parse_cmdline( cmdline => "cmd --opt=val", point => 13, word_breaks => "=");

    Result: "[["--opt", "val"], 1]". Breaking at '=' too.

     parse_cmdline( cmdline => "cmd --opt=val ", point => 14, word_breaks => "=");

    Result: "[["--opt", "val"], 2]". Breaking at '=' too (2).

     parse_cmdline( cmdline => "cmd \"--opt=val", point => 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:

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-Complet
    ion.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.

