-
-
25 Aug 2021 00:05:14 UTC
- Distribution: Getopt-Long-Subcommand
- Module version: 0.104
- Source (raw)
- Browse (raw)
- Changes
- Homepage
- How to Contribute
- Repository
- Issues (0)
- Testers (790 / 0 / 1)
- Kwalitee
Bus factor: 1- 55.95% Coverage
- License: perl_5
- Perl: v5.10.1
- Activity
24 month- Tools
- Download (22.83KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
++ed by:1 non-PAUSE user- NAME
- VERSION
- SYNOPSIS
- DESCRIPTION
- FUNCTIONS
- FAQ
- HOMEPAGE
- SOURCE
- BUGS
- CAVEATS
- SEE ALSO
- AUTHOR
- COPYRIGHT AND LICENSE
NAME
Getopt::Long::Subcommand - Process command-line options, with subcommands and completion
VERSION
This document describes version 0.104 of Getopt::Long::Subcommand (from Perl distribution Getopt-Long-Subcommand), released on 2021-05-30.
SYNOPSIS
use Getopt::Long::Subcommand; # exports GetOptions my %opts; my $res = GetOptions( summary => 'Summary about your program ...', # common options recognized by all subcommands options => { 'help|h|?' => { summary => 'Display help message', handler => sub { my ($cb, $val, $res) = @_; if ($res->{subcommand}) { say "Help message for $res->{subcommand} ..."; } else { say "General help message ..."; } exit 0; }, 'version|v' => { summary => 'Display program version', handler => sub { say "Program version $main::VERSION"; exit 0; }, 'verbose' => { handler => \$opts{verbose}, }, }, # list your subcommands here subcommands => { subcmd1 => { summary => 'The first subcommand', # subcommand-specific options options => { 'foo=i' => { handler => \$opts{foo}, }, }, }, subcmd1 => { summary => 'The second subcommand', options => { 'bar=s' => \$opts{bar}, 'baz' => \$opts{baz}, }, }, }, # tell how to complete option value and arguments. see # Getopt::Long::Complete for more details, the arguments are the same # except there is an additional 'subcommand' that gives the subcommand # name. completion => sub { my %args = @_; ... }, ); die "GetOptions failed!\n" unless $res->{success}; say "Running subcommand $res->{subcommand} ...";
To run your script:
% script Missing subcommand % script --help General help message ... % script subcmd1 Running subcommand subcmd1 ... % script subcmd1 --help Help message for subcmd1 ... % script --verbose subcmd2 --baz --bar val Running subcommand subcmd2 ... % script subcmd3 Unknown subcommand 'subcmd3' GetOptions failed!
DESCRIPTION
This module extends Getopt::Long with subcommands and tab completion ability.
How parsing works: First we call
Getopt::Long::GetOptions
with the top-level options, passing through unknown options if we have subcommands. Then, subcommand name is taken from the first argument. If subcommand has options, the process is repeated. SoGetopt::Long::GetOptions
is called once at every level.Completion: Scripts using this module can complete themselves. Just put your script somewhere in your
PATH
and run something like this in your bash shell:complete -C script-name script-name
. See also shcompgen to manage completion scripts for multiple applications easily.How completion works: Environment variable
COMP_LINE
orCOMMAND_LINE
(for tcsh) is first checked. If it exists, we are in completion mode and@ARGV
is parsed/formed from it. We then perform parsing to get subcommand names. Finally we hand it off to Complete::Getopt::Long.FUNCTIONS
GetOptions(%cmdspec) => hash
Exported by default.
Process options and/or subcommand names specified in
%cmdspec
, and remove them from@ARGV
(thus modifying it). Will warn to STDERR on errors. Actual command-line options parsing will be done using Getopt::Long.Return hash structure, with these keys:
success
(bool, false if parsing options failed e.g. unknown option/subcommand, illegal option value, etc),subcommand
(array of str, subcommand name, if there is any; nested subcommands will be listed in order, e.g.["sub1", "subsub1"]
).Arguments:
summary => str
Used by autohelp (not yet implemented).
options => hash
A hash of option names and its specification. The specification is the same as what you would feed to Getopt::Long's
GetOptions
.subcommands => hash
A hash of subcommand name and its specification. The specification looks like
GetOptions
argument, with keys likesummary
,options
,subcommands
(for nested subcommands).default_subcommand => str
Default subcommand to use if no subcommand name is set. Subcommand can be set using the first argument, or your option handler can also set the subcommand using:
$_[2]{subcommand_name} = 'something';
configure => arrayref
Custom Getopt::Long configuration. The default is:
['no_ignore_case', 'no_getopt_compat', 'gnu_compat', 'bundling']
Note that even though you use custom configuration here, the tab completion (performed by Complete::Getopt::Long only supports
no_ignore_case
,gnu_compat
, andno_getopt_compat
.
Differences with
Getopt::Long
'sGetOptions
:Accept a command/subcommand specification (
%cmdspec
) instead of just options specification (%ospec
) like inGetopt::Long
).This module's function returns hash instead of bool.
Coderefs in
options
will receive an extra argument$res
which is the result hash (being built). So the arguments that the coderefs get is:($callback, $value, $res)
FAQ
How to avoid modifying @ARGV? How to process from another array, like Getopt::Long's GetOptionsFromArray?
Instead of adding another function, you can use
local
.{ local @ARGV = ['--some', 'value']; GetOptions(...); } # the original @ARGV is restored
HOMEPAGE
Please visit the project's homepage at https://metacpan.org/release/Getopt-Long-Subcommand.
SOURCE
Source repository is at https://github.com/perlancar/perl-Getopt-Long-Subcommand.
BUGS
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Getopt-Long-Subcommand
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.
CAVEATS
Common options take precedence over subcommand options
Common options (e.g.
--help
) are parsed and removed from the command-line first. This is done for convenience so you can do something likecmd subc --help
orcmd --help subc
to get help. The consequence is you cannot have a subcommand option with the same name as common option.Similarly, options for a subcommand takes precedence over its sub-subcommand, and so on.
SEE ALSO
Perinci::CmdLine - a more full featured command-line application framework, also with subcommands and completion.
Pod::Weaver::Section::Completion::GetoptLongSubcommand
AUTHOR
perlancar <perlancar@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2021, 2019, 2017, 2016, 2015 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.
Module Install Instructions
To install Getopt::Long::Subcommand, copy and paste the appropriate command in to your terminal.
cpanm Getopt::Long::Subcommand
perl -MCPAN -e shell install Getopt::Long::Subcommand
For more information on module installation, please visit the detailed CPAN module installation guide.