NAME
    Complete::Util - Shell completion routines

VERSION
    This document describes version 0.07 of Complete::Util (from Perl
    distribution Complete-Util), released on 2014-06-26.

DESCRIPTION
    This module provides routines for doing programmable shell tab
    completion. Currently this module is geared towards bash, but support
    for other shells might be added in the future (e.g. zsh, fish).

    The "complete_*()" routines are used to complete from a specific data
    source or for a specific type. They are the lower-level functions.

FUNCTIONS
  break_cmdline_into_words(%args) -> [status, msg, result, meta]
    Break command-line string into words.

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

        "'@><=;|&(:

    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*

    Return value:

    Returns an enveloped result (an array).

    First element (status) is an integer containing HTTP status code (200
    means OK, 4xx caller error, 5xx function error). Second element (msg) is
    a string containing error message, or 'OK' if status is 200. Third
    element (result) is optional, the actual result. Fourth element (meta)
    is called result metadata and is optional, a hash that contains extra
    information.

  complete_array(%args) -> array
    Complete from array.

    Arguments ('*' denotes required arguments):

    *   array* => *array*

    *   ci => *bool* (default: 0)

    *   word => *str* (default: "")

    Return value:

  complete_env(%args) -> array
    Complete from environment variables.

    On Windows, environment variable names are all converted to uppercase.
    You can use case-insensitive option ("ci") to match against original
    casing.

    Arguments ('*' denotes required arguments):

    *   ci => *bool* (default: 0)

    *   word => *str* (default: "")

    Return value:

  complete_file(%args) -> array
    Complete file and directory from local filesystem.

    Arguments ('*' denotes required arguments):

    *   d => *bool* (default: 1)

        Whether to include directory.

    *   f => *bool* (default: 1)

        Whether to include file.

    *   word => *str* (default: "")

    Return value:

  complete_hash_key(%args) -> array
    Complete from hash keys.

    Arguments ('*' denotes required arguments):

    *   ci => *bool* (default: 0)

    *   hash* => *hash*

    *   word => *str* (default: "")

    Return value:

  complete_program(%args) -> array
    Complete program name found in PATH.

    Windows is supported, on Windows PATH will be split using /;/ instead of
    /:/.

    Arguments ('*' denotes required arguments):

    *   word => *str* (default: "")

    Return value:

  format_shell_completion(%args) -> str
    Format completion for output to shell.

    Usually, like in bash, we just need to output the entries one line at a
    time, with some special characters in the entry escaped using
    backslashes so it's not interpreted by the shell.

    Arguments ('*' denotes required arguments):

    *   shell_completion* => *hash*

        Result of shell completion.

        A hash containing list of completions and other metadata. For
        example:

            {
                completion => ['f1', 'f2', 'f3.txt', 'foo:bar.txt'],
                type => 'filename',
            }

    Return value:

  mimic_shell_dir_completion(%args) -> array
    Make completion of paths behave more like shell.

    This function employs a trick to make directory/path completion work
    more like shell's own. In shell, when completing directory, the sole
    completion for "foo/" is "foo/", the cursor doesn't automatically add a
    space (like the way it does when there is only a single completion
    possible). Instead it stays right after the "/" to allow user to
    continue completing further deeper in the tree ("foo/bar" and so on).

    To make programmable completion work like shell's builtin dir
    completion, the trick is to add another completion alternative "foo/"
    (with an added space) so shell won't automatically add a space because
    there are now more than one completion possible ("foo/" and "foo/").

    Arguments ('*' denotes required arguments):

    *   completion* => *array*

    Return value:

  parse_shell_cmdline(@args) -> hash
    Parse shell command-line for processing by completion routines.

    Currently only supports bash.

    Returns hash with the following keys: "words" (array of str, equivalent
    to "COMP_WORDS" provided by shell to completion routine), "cword" (int,
    equivalent to shell-provided "COMP_CWORD").

    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.

    Return value:

DEVELOPER'S NOTES
    We want to future-proof the API so future features won't break the API
    (too hardly). Below are the various notes related to that.

    In fish, aside from string, each completion alternative has some extra
    metadata. For example, when completing filenames, fish might show each
    possible completion filename with type (file/directory) and file size.
    When completing options, it can also display a summary text for each
    option. So instead of an array of strings, array of hashrefs will be
    allowed in the future:

     ["word1", "word2", "word3"]
     [ {word=>"word1", ...},
       {word=>"word2", ...},
       {word=>"word3", ...}, ]

    fish also supports matching not by prefix only, but using wildcard. For
    example, if word if "b??t" then "bait" can be suggested as a possible
    completion. fish also supports fuzzy matching (e.g. "house" can bring up
    "horse" or "hose"). There is also spelling-/auto-correction feature in
    some shells. This feature can be added later in the various
    "complete_*()" routines. Or there could be helper routines for this. In
    general this won't pose a problem to the API.

    fish supports autosuggestion (autocomplete). When user types, without
    she pressing Tab, the shell will suggest completion (not only for a
    single token, but possibly for the entire command). If the user wants to
    accept the suggestion, she can press the Right arrow key. This can be
    supported later by a function e.g. "shell_complete()" which accepts the
    command line string.

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/Complete-Util>.

SOURCE
    Source repository is at
    <https://github.com/sharyanto/perl-Complete-Util>.

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

    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.

