SYNOPSIS

   Suppose you have a CLI named process-users that accepts some
   command-line options and arguments. To add tab completion for
   process-users, write _process-users as follows:

    #!/usr/bin/env perl
    use Shell::Completer;
    declare_completer(
        options => {
            'help|h'     => undef,               # no completion, no option value
            'verbose!'   => undef,               #
            'on-fail=s'  => ['skip', 'die'],     # complete from a list of words
            'template=s' => _file(file_ext_filter=>['tmpl', 'html']),
                                                 # complete from *.tmpl or *.html files
            '<>'         => _user(),             # complete from list of users
        },
    );

   Install it (on bash):

    % complete -C _process-users process-users

   or use shcompgen.

   Now you can do completion for process-users:

    % process-users -on<tab>
    % process-users --on-fail _

    % process-users --on-fail <tab>
    die     skip
    % process-users --on-fail s<tab>
    % process-users --on-fail skip _

    % process-users b<tab>
    bob     bobby

DESCRIPTION

   EARLY RELEASE, EXPERIMENTAL.

   This module lets you easily add shell tab completion to an existing CLI
   program.

FUNCTIONS

declare_completer(%args)

COMPLETION FUNCTIONS

   All these functions accept a hash argument.

_dir

   Complete from directories. See Complete::File's complete_dir for more
   details.

_file

   Complete from files. See Complete::File's complete_file for more
   details.

_gid

   Complete from list of Unix GID's. See Complete::Unix's complete_gid for
   more details.

_group

   Complete from list of Unix group names. See Complete::Unix's
   complete_group for more details.

_uid

   Complete from list of Unix UID's. See Complete::Unix's complete_uid for
   more details.

_pid

   Complete from list of running PID's. See Complete::Unix's complete_pid
   for more details.

_user

   Complete from list of Unix user names. See Complete::Unix's
   complete_user for more details.

TODOS AND IDEAS

   Add more completion functions.

   Override | operator to combine answers, e.g.:

    'user|U=s' => _user() | _uid(),

SEE ALSO

   Getopt::Long::Complete if you want to write a CLI program that can
   complete itself.

   shcompgen from App::shcompgen.