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

VERSION
   This document describes version 0.103 of Getopt::Long::Subcommand (from
   Perl distribution Getopt-Long-Subcommand), released on 2019-02-27.

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-Subcomman
   d>

   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 <[email protected]>

COPYRIGHT AND LICENSE
   This software is copyright (c) 2019, 2017, 2016, 2015 by
   [email protected].

   This is free software; you can redistribute it and/or modify it under
   the same terms as the Perl 5 programming language system itself.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.