Getopt::Long::Complete - A drop-in replacement for Getopt::Long, with shell tab completion
This document describes version 0.316 of Getopt::Long::Complete (from Perl distribution Getopt-Long-Complete), released on 2021-08-24.
You just replace use Getopt::Long with use Getopt::Long::Complete and your program suddenly supports tab completion. This works for most/many programs (see "INCOMPATIBILITIES". For example, below is source code for delete-user.
use Getopt::Long
use Getopt::Long::Complete
delete-user
use Getopt::Long::Complete; my %opts; GetOptions( 'help|h' => sub { ... }, 'on-fail=s' => \$opts{on_fail}, 'user|U=s' => \$opts{name}, 'force' => \$opts{force}, 'verbose!' => \$opts{verbose}, );
Several shells are supported. To activate completion, see "DESCRIPTION". After activation, tab completion works:
% delete-user <tab> --force --help --noverbose --no-verbose --on-fail --user --verbose -h % delete-user --h<tab>
The previous example only provides completion for option names. To provide completion for option values as well as arguments, you need to provide more hints. Instead of GetOptions, use GetOptionsWithCompletion. It's basically the same as GetOptions but accepts an extra coderef in the first argument. The code will be invoked when completion to option value or argument is needed. Example:
GetOptions
GetOptionsWithCompletion
use Getopt::Long::Complete qw(GetOptionsWithCompletion); use Complete::Unix qw(complete_user); use Complete::Util qw(complete_array_elem); my %opts; GetOptionsWithCompletion( sub { my %args = @_; my $word = $args{word}; # the word to be completed my $type = $args{type}; # 'optname', 'optval', or 'arg' my $opt = $args{opt}; # can be an array of options if ambiguous, e.g. ['--on-fail', '--on-full'] if ($type eq 'optval' && $opt eq '--on-fail') { return complete_array_elem(array=>[qw/die warn ignore/], word=>$word); } elsif ($type eq 'optval' && ($opt eq '--user' || $opt eq '-U')) { return complete_user(word=>$word); } elsif ($type eq 'arg') { return complete_user(word=>$word); } []; }, 'help|h' => sub { ... }, 'on-fail=s' => \$opts{on_fail}, 'user=s' => \$opts{name}, 'force' => \$opts{force}, 'verbose!' => \$opts{verbose}, );
This module provides a quick and easy way to add shell tab completion feature to your scripts, including scripts already written using the venerable Getopt::Long module. Currently bash and tcsh are directly supported; fish and zsh are also supported via shcompgen.
This module is basically just a thin wrapper for Getopt::Long. Its GetOptions function just checks for COMP_LINE/COMP_POINT environment variable (in the case of bash) or COMMAND_LINE (in the case of tcsh) before passing its arguments to Getopt::Long's GetOptions. If those environment variable(s) are defined, completion reply will be printed to STDOUT and then the program will exit. Otherwise, Getopt::Long's GetOptions is called.
Getopt::Long
To keep completion quick, you should do GetOptions() or GetOptionsWithCompletion() as early as possible in your script. Preferably before loading lots of other Perl modules.
GetOptions()
GetOptionsWithCompletion()
To activate tab completion in bash, put your script somewhere in PATH and execute this in the shell or put it into your bash startup file (e.g. /etc/bash.bashrc or ~/.bashrc). Replace delete-user with the actual script name:
PATH
/etc/bash.bashrc
~/.bashrc
complete -C delete-user delete-user
For tcsh:
complete delete-user 'p/*/`delete-user`/'
For other shells (but actually for bash too) you can use shcompgen.
Because we are "bound" by providing a Getopt::Long-compatible function interface, these variables exist to allow configuring Getopt::Long::GetOptions. You can use Perl's local to localize the effect.
local
Bool. Default: 1 (or 0 if POSIXLY_CORRECT). Not exported.
Bool. Default: 0. Not exported.
Bool. Default: 1. Not exported.
Integer. Constant. Value is 0. Exported by default, to be compatible with Getopt::Long.
Integer. Constant. Value is 1. Exported by default, to be compatible with Getopt::Long.
Integer. Constant. Value is 2. Exported by default, to be compatible with Getopt::Long.
Getopt::Long::Complete (GLC) provides all the same exports as Getopt::Long (GL), for example "GetOptions" (exported by default), "GetOptionsFromArray", "Configure", etc.
Aside from GetOptions which has an extra behavior to support completion, all the other routines of GLC behave exactly the same as GL.
However, there are some incompatibilities or unsupported features:
GLC does not allow passing configure options during import
GLC's GetOptions only supports running under a specific set of modes: bundling, no_ignore_case.
bundling
no_ignore_case
Other non-default settings have not been tested and probably not supported.
Usage:
GetOptions([ \%hash, ] @spec)
Exported by default. Will call Getopt::Long's GetOptions, except when COMP_LINE environment variable is defined, in which case will print completion reply to STDOUT and exit.
Note: Will temporarily set Getopt::Long configuration as follow: bundling, no_ignore_case, gnu_compat, no_getopt_compat, permute (if POSIXLY_CORRECT environment is false). I believe this a sane default. You can turn off bundling via $opt_bundling. You can turn on/off permute explicitly by via $opt_permute. You can turn on pass_through via $opt_pass_through.
$opt_bundling
$opt_permute
$opt_pass_through
GetOptionsWithCompletion(\&completion, [ \%hash, ] @spec)
Exported on demand. Just like GetOptions, except that it accepts an extra first argument \&completion containing completion routine for completing option values and arguments. This will be passed as completion argument to Complete::Getopt::Long's complete_cli_arg. See that module's documentation on details of what is passed to the routine and what return value is expected from it.
\&completion
completion
complete_cli_arg
Exported on demand. Will just call Getopt::Long's version.
Please visit the project's homepage at https://metacpan.org/release/Getopt-Long-Complete.
Source repository is at https://github.com/perlancar/perl-Getopt-Long-Complete.
Getopt::Long::More, another drop-in replacement for Getopt::Long with tab completion support and more stuffs: default value, required value, summary in auto_help.
Complete::Getopt::Long (the backend for this module), Complete::Bash, Complete::Tcsh.
Getopt::Long::Subcommand also supports tab completion, in addition to subcommands.
Other option-processing modules featuring shell tab completion: Getopt::Complete.
Perinci::CmdLine - an alternative way to easily create command-line applications with completion feature.
shcompgen
Pod::Weaver::Section::Completion::GetoptLongComplete
perlancar <perlancar@cpan.org>
Steven Haryanto (on Asus Zenbook) <stevenharyanto@gmail.com>
To contribute, you can send patches by email/via RT, or send pull requests on GitHub.
Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:
% prove -l
If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla plugin and/or Pod::Weaver::Plugin. Any additional steps required beyond that are considered a bug and can be reported to me.
This software is copyright (c) 2021, 2020, 2017, 2016, 2015, 2014 by perlancar <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.
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Getopt-Long-Complete
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.
To install Getopt::Long::Complete, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Getopt::Long::Complete
CPAN shell
perl -MCPAN -e shell install Getopt::Long::Complete
For more information on module installation, please visit the detailed CPAN module installation guide.