NAME
Complete::Getopt::Long - Complete command-line argument using
Getopt::Long specification
VERSION
This document describes version 0.479 of Complete::Getopt::Long (from
Perl distribution Complete-Getopt-Long), released on 2020-04-16.
SYNOPSIS
See Getopt::Long::Complete for an easy way to use this module.
DESCRIPTION
FUNCTIONS
complete_cli_arg
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*.
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.
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.
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").
* completion => *code*
Completion routine to complete option value/argument.
Completion code will receive a hash of arguments (%args) containing
these keys:
* "type" (str, what is being completed, either "optval", or "arg")
* "word" (str, word to be completed)
* "cword" (int, position of words in the words array, starts from
0)
* "opt" (str, option name, e.g. "--str"; undef if we're completing
argument)
* "ospec" (str, Getopt::Long option spec, e.g. "str|S=s"; undef
when completing argument)
* "argpos" (int, argument position, zero-based; undef if
type='optval')
* "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')
* "seen_opts" (hash, all the options seen in "words")
* "parsed_opts" (hash, options parsed the standard/raw way)
as well as all keys from "extras" (but these won't override the
above keys).
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.
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.
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).
* 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* => *array*
Getopt::Long specification.
* words* => *array*
Command line arguments, like @ARGV.
See function "parse_cmdline" in Complete::Bash on how to produce
this (if you're using bash).
Return value: (hash|array)
You can use "format_completion" function in Complete::Bash module to
format the result of this function for bash.
ENVIRONMENT
COMPLETE_GETOPT_LONG_TRACE
Bool. If set to true, will generated more log statements for debugging
(at the trace level).
COMPLETE_GETOPT_LONG_DEFAULT_ENV
Bool. Default true. Can be set to false to disable completing from
environment variable in default completion.
COMPLETE_GETOPT_LONG_DEFAULT_FILE
Bool. Default true. Can be set to false to disable completing from
filesystem (file and directory names) in default completion.
HOMEPAGE
Please visit the project's homepage at
<https://metacpan.org/release/Complete-Getopt-Long>.
SOURCE
Source repository is at
<https://github.com/perlancar/perl-Complete-Getopt-Long>.
BUGS
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.
SEE ALSO
Getopt::Long::Complete
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.
AUTHOR
perlancar <perlancar@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2020, 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.