Getopt::Long::More - Like Getopt::Long, but with more stuffs
This document describes version 0.007 of Getopt::Long::More (from Perl distribution Getopt-Long-More), released on 2020-04-08.
use Getopt::Long::More; # imports GetOptions as well as optspec; you can also # explicitly import Configure, GetOptionsFromArray, # GetOptionsFromString my %opts; GetOptions( # just like in Getopt::Long 'foo=s' => \$opts{foo}, 'bar' => sub { ... }, # but if you want to specify extra stuffs... 'baz' => optspec( # will be passed to Getopt::Long destination => \$opts{baz}, # specify that this option is required required => 1, # specify this for default value default => 10, # specify this if you want nicer usage message summary => 'Blah blah blah', # specify longer (multiparagraphs) of text for POD, in POD format description => <<'_', Blah blah ... blah Blah blah ... blah blah _ # provide completion from a list of strings # completion => [qw/apple apricot banana/], # provide more advanced completion routine completion => sub { require Complete::Util; my %args = @_; Complete::Util::complete_array_elem( word => $args{word}, array => [ ... ], ); }, # other properties: x or x.* or _* are allowed 'x.debug' => 'blah', _app_code => {foo=>1}, ), );
This module is a wrapper and drop-in replacement for Getopt::Long. It provides the same interface as Getopt::Long and, unlike other wrappers like Getopt::Long::Complete or Getopt::Long::Modern it does not change default configuration and all Getopt::Long configuration are supported. In fact, Getopt::Long::More behaves much like Getopt::Long until you start to use optspec object as one or more option destinations.
In addition to using scalarref, arrayref, hashref, or coderef as the option destination as Getopt::Long allows, Getopt::Long::More also allows using optspec object as the destination. This enables you to specify more stuffs.
Optspec object is created using the optspec function which accepts a list of property name-property value pairs:
optspec
'--fruit=s' => optspec( destination => \$opts{fruit}, default => 'apple', summary => 'Supply name of fruit to order', completion => [qw/apple apricot banana/], ... )
All properties are optional.
The destination property, if present, will be passed to Getopt::Long when parsing options.
destination
Note that, in previous versions of this module, destination was referred to as handler, which is now deprecated. At this time handler is still being accepted as an alias for destination, but do NOT count on that forever. The name handler will be discontinued at one point. You have been warned.
handler
In addition to destination, these other properties are also recognized:
Set this to 1 to specify that the option is required.
Provide default for the option.
Provide a short summary message for the option. This is used when generating usage/help message.
Provide a longer (multiparagraph) text, in POD format. Will be used to generate POD.
Provide completion routine. Can also be a simple array of strings.
Completion routine will be passed a hash argument, with at least the following keys: word (str, the word to be completed). It is expected to return a completion answer structure (see Complete for mor edetails) which is usually just an array of strings.
word
You are allowed to have properties named x or anything that begins with x. or _. These are ignored by Getopt::Long::More. You can use store comments or whatever additional information here.
x
x.
_
See Getopt::Long documentation.
Will print a usage/help message and exit. Sample result:
myapp [options] Options: --fruit=s Supply name of fruit to order (default: apple) --debug Enable debug mode --help|? Print help message and exit --version Print usage message and exit
Will generate a POD containing list of options. The text will be taken from the summary and description properties of optspec objects. Example result:
summary
description
=head1 OPTIONS =head2 --fruit|f=s Supply name of fruit to order. Blah blah blah blah blah ... =head2 --debug =head2 --version Display program version and exit. =head2 --help Display help message and exit.
Create optspec object. See "OPTSPEC OBJECT".
Getopt::Long::Mode supports shell tab completion. To activate tab completion, put your script (e.g. myapp.pl) in PATH and in bash shell type:
myapp.pl
PATH
% complete -C myapp.pl myapp.pl
You can then complete option names (or option values or command-line arguments too, if you provide completion properties). You can also use shcompgen to activate shell completion; shcompgen supports several shells and various modules.
completion
Tab completion functionality is provided by Complete::Getopt::Long. Note that this module assumes no_ignore_case and does not support things like getopt_compat (starting option with + instead of --).
no_ignore_case
getopt_compat
+
--
Use the option spec <>:
<>
GetOptions( ... '<>' => optspec( destination => \&process, completion => sub { ... }, ), );
Please visit the project's homepage at https://metacpan.org/release/Getopt-Long-More.
Source repository is at https://github.com/perlancar/perl-Getopt-Long-More.
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Getopt-Long-More
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
Other Getopt::Long wrappers that provide extra features: Getopt::Long::Complete, Getopt::Long::Descriptive.
If you want less features instead of more: Getopt::Long::Less, Getopt::Long::EvenLess.
perlancar <perlancar@cpan.org>
This software is copyright (c) 2020, 2019, 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.
To install Getopt::Long::More, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Getopt::Long::More
CPAN shell
perl -MCPAN -e shell install Getopt::Long::More
For more information on module installation, please visit the detailed CPAN module installation guide.