Complete::Getopt::Long - Complete command-line argument using Getopt::Long specification
This document describes version 0.472 of Complete::Getopt::Long (from Perl distribution Complete-Getopt-Long), released on 2019-09-10.
See Getopt::Long::Complete for an easy way to use this module.
Usage:
complete_cli_arg(%args) -> hash|array
Complete command-line argument using Getopt::Long specification.
This routine can complete option names, where the option names are retrieved from Getopt::Long specification. If you provide completion routine in completion, you can also complete option values and arguments.
completion
Note that this routine does not use Getopt::Long (it does its own parsing) and currently is not affected by Getopt::Long's configuration. Its behavior mimics Getopt::Long under these configuration: no_ignore_case, bundling (or no_bundling if the bundling option is turned off). Which I think is the sensible default. This routine also does not currently support auto_help and auto_version, so you'll need to add those options specifically if you want to recognize --help/-? and --version, respectively.
no_ignore_case
bundling
no_bundling
auto_help
auto_version
--help/-?
--version
This function is not exported by default, but exportable.
Arguments ('*' denotes required arguments):
bundling => bool (default: 1)
If you turn off bundling, completion of short-letter options won't support bundling (e.g. -b<tab> won't add more single-letter options), but single-dash multiletter options can be recognized. Currently only those specified with a single dash will be completed. For example if you have -foo=s in your option specification, -f<tab> can complete it.
-b<tab>
-foo=s
-f<tab>
This can be used to complete old-style programs, e.g. emacs which has options like -nw, -nbc etc (but also have double-dash options like --no-window-system or --no-blinking-cursor).
-nw
-nbc
--no-window-system
--no-blinking-cursor
completion => code
Completion routine to complete option value/argument.
Completion code will receive a hash of arguments (%args) containing these keys:
%args
type (str, what is being completed, either optval, or arg)
type
optval
arg
word (str, word to be completed)
word
cword (int, position of words in the words array, starts from 0)
cword
opt (str, option name, e.g. --str; undef if we're completing argument)
opt
--str
ospec (str, Getopt::Long option spec, e.g. str|S=s; undef when completing argument)
ospec
str|S=s
argpos (int, argument position, zero-based; undef if type='optval')
argpos
nth (int, the number of times this option has seen before, starts from 0 that means this is the first time this option has been seen; undef when type='arg')
nth
seen_opts (hash, all the options seen in words)
seen_opts
words
parsed_opts (hash, options parsed the standard/raw way)
parsed_opts
as well as all keys from extras (but these won't override the above keys).
extras
and is expected to return a completion answer structure as described in Complete which is either a hash or an array. The simplest form of answer is just to return an array of strings. The various complete_* function like those in Complete::Util or the other Complete::* modules are suitable to use here.
Complete
complete_*
Complete::*
Completion routine can also return undef to express declination, in which case the default completion routine will then be consulted. The default routine completes from shell environment variables ($FOO), Unix usernames (~foo), and files/directories.
$FOO
~foo
Example:
use Complete::Unix qw(complete_user); use Complete::Util qw(complete_array_elem); complete_cli_arg( getopt_spec => { 'help|h' => sub{...}, 'format=s' => \$format, 'user=s' => \$user, }, completion => sub { my %args = @_; my $word = $args{word}; my $ospec = $args{ospec}; if ($ospec && $ospec eq 'format=s') { complete_array_elem(array=>[qw/json text xml yaml/], word=>$word); } else { complete_user(word=>$word); } }, );
cword* => int
Index in words of the word we're trying to complete.
See function parse_cmdline in Complete::Bash on how to produce this (if you're using bash).
parse_cmdline
extras => hash
Add extra arguments to completion routine.
The keys from this extras hash will be merged into the final %args passed to completion routines. Note that standard keys like type, word, and so on as described in the function description will not be overwritten by this.
getopt_spec* => hash
Getopt::Long specification.
words* => array
Command line arguments, like @ARGV.
Return value: (hash|array)
You can use format_completion function in Complete::Bash module to format the result of this function for bash.
format_completion
Please visit the project's homepage at https://metacpan.org/release/Complete-Getopt-Long.
Source repository is at https://github.com/perlancar/perl-Complete-Getopt-Long.
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Complete-Getopt-Long
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.
Getopt::Long::Complete
Complete::Bash
Other modules related to bash shell tab completion: Bash::Completion, Getopt::Complete.
Perinci::CmdLine - an alternative way to easily create command-line applications with completion feature.
perlancar <perlancar@cpan.org>
This software is copyright (c) 2019, 2017, 2016, 2015, 2014 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.
To install Complete::Getopt::Long, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Complete::Getopt::Long
CPAN shell
perl -MCPAN -e shell install Complete::Getopt::Long
For more information on module installation, please visit the detailed CPAN module installation guide.