/ 
Getopt-Long-Subcommand-0.102
++
 / Getopt::Long::Subcommand
perlancar

NAME

Getopt::Long::Subcommand - Process command-line options, with subcommands and completion

VERSION

This document describes version 0.102 of Getopt::Long::Subcommand (from Perl distribution Getopt-Long-Subcommand), released on 2017-08-12.

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. So Getopt::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 or COMMAND_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.

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 like cmd subc --help or cmd --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.

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 like summary, 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, and no_getopt_compat.

Differences with Getopt::Long's GetOptions:

  • Accept a command/subcommand specification (%cmdspec) instead of just options specification (%ospec) like in Getopt::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.

SEE ALSO

Getopt::Long

Getopt::Long::Complete

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) 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.