NAME

Shell::Completer - Easily add tab completion to existing CLI program

VERSION

This document describes version 0.002 of Shell::Completer (from Perl distribution Shell-Completer), released on 2016-10-20.

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.

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(),

FUNCTIONS

declare_completer(%args)

HOMEPAGE

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

SOURCE

Source repository is at https://github.com/perlancar/perl-Shell-Completer.

BUGS

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

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.

SEE ALSO

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

shcompgen from App::shcompgen.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by perlancar@cpan.org.

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

cpanm Shell::Completer

perl -MCPAN -e shell
install Shell::Completer