.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Getopt::ArgParse 3pm"
.TH Getopt::ArgParse 3pm "2022-06-14" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Getopt::ArgParse \- Parsing command line arguments with a richer and
more user\-friendly API interface, similar to Python's argparse but with
perlish extras.
.PP
In particular, the modules provides the following features:
.PP
.Vb 8
\&  \- generating usage messages
\&  \- storing parsed arg values in an object, which can be also used to
\&    load configuration values from files and therefore the ability for
\&    applications to combine configurations in a single interface
\&  \- A more user\-friendly interface to specify arguments, such as
\&    argument types, argument values split, etc.
\&  \- Subcommand parsing, such svn <command>
\&  \- Supporting both flag based named arguments and positional arguments
.Ve
.SH "VERSION"
.IX Header "VERSION"
version 1.0.6
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Getopt::ArgParse;
\&
\& $ap = Getopt::ArgParse\->new_parser(
\&        prog        => \*(AqMyProgramName\*(Aq,
\&        description => \*(AqThis is a program\*(Aq,
\&    epilog      => \*(AqThis appears at the bottom of usage\*(Aq,
\& );
\&
\& # Parse an option: \*(Aq\-\-foo value\*(Aq or \*(Aq\-f value\*(Aq
\& $ap\->add_arg(\*(Aq\-\-foo\*(Aq, \*(Aq\-f\*(Aq, required => 1);
\&
\& # Parse a boolean: \*(Aq\-\-bool\*(Aq or \*(Aq\-b\*(Aq using a different name from
\& # the option
\& $ap\->add_arg(\*(Aq\-\-bool\*(Aq, \*(Aq\-b\*(Aq, type => \*(AqBool\*(Aq, dest => \*(Aqboo\*(Aq);
\&
\& # Parse a positonal option.
\& # But in this case, better using subcommand. See below
\& $ap\->add_arg(\*(Aqcommand\*(Aq, required => 1);
\&
\& # $ns is also accessible via $ap\->namespace
\& $ns = $ap\->parse_args(split(\*(Aq \*(Aq, \*(Aqtest \-f 1 \-b\*(Aq));
\&
\& say $ns\->command; # \*(Aqtest\*(Aq
\& say $ns\->foo;     # false
\& say $ns\->boo;     # false
\& say $ns\->no_boo;   # true \- \*(Aqno_\*(Aq is added for boolean options
\&
\& # You can continue to add arguments and parse them again
\& # $ap\->namespace is accumulatively populated
\&
\& # Parse an Array type option and split the value into an array of values
\& $ap\->add_arg(\*(Aq\-\-emails\*(Aq, type => \*(AqArray\*(Aq, split => \*(Aq,\*(Aq);
\& $ns = $ap\->parse_args(split(\*(Aq \*(Aq, \*(Aq\-\-emails a@perl.org,b@perl.org,c@perl.org\*(Aq));
\& # Because this is an array option, this also allows you to specify the
\& # option multiple times and splitting
\& $ns = $ap\->parse_args(split(\*(Aq \*(Aq, \*(Aq\-\-emails a@perl.org,b@perl.org \-\-emails c@perl.org\*(Aq));
\&
\& # Below will print: a@perl.org|b@perl.org|c@perl.org|a@perl.org|b@perl.org|c@perl.org
\& # Because Array types are appended
\& say join(\*(Aq|\*(Aq, $ns\->emails);
\&
\& # Parse an option as key,value pairs
\& $ap\->add_arg(\*(Aq\-\-param\*(Aq, type => \*(AqPair\*(Aq, split => \*(Aq,\*(Aq);
\& $ns = $ap\->parse_args(split(\*(Aq \*(Aq, \*(Aq\-\-param a=1,b=2,c=3\*(Aq));
\&
\& say $ns\->param\->{a}; # 1
\& say $ns\->param\->{b}; # 2
\& say $ns\->param\->{c}; # 3
\&
\& # You can use choice to restrict values
\& $ap\->add_arg(\*(Aq\-\-env\*(Aq, choices => [ \*(Aqdev\*(Aq, \*(Aqprod\*(Aq ],);
\&
\& # or use case\-insensitive choices
\& # Override the previous option with reset
\& $ap\->add_arg(\*(Aq\-\-env\*(Aq, choices_i => [ \*(Aqdev\*(Aq, \*(Aqprod\*(Aq ], reset => 1);
\&
\& # or use a coderef
\& # Override the previous option
\& $ap\->add_args(
\&        \*(Aq\-\-env\*(Aq,
\&        choices => sub {
\&                die "\-\-env invalid values" if $_[0] !~ /^(dev|prod)$/i;
\&        },
\&    reset => 1,
\& );
\&
\& # subcommands
\& $ap\->add_subparsers(title => \*(Aqsubcommands\*(Aq); # Must be called to initialize subcommand parsing
\& $list_parser = $ap\->add_parser(
\&         \*(Aqlist\*(Aq,
\&         help => \*(AqList directory entries\*(Aq,
\&         description => \*(AqA multiple paragraphs long description.\*(Aq,
\& );
\&
\& $list_parser\->add_args(
\&   [
\&     \*(Aq\-\-verbose\*(Aq, \*(Aq\-v\*(Aq,
\&      type => \*(AqCount\*(Aq,
\&      help => \*(AqVerbosity\*(Aq,
\&   ],
\&   [
\&     \*(Aq\-\-depth\*(Aq,
\&      help => \*(Aqdepth\*(Aq,
\&   ],
\& );
\&
\& $ns = $ap\->parse_args(split(\*(Aq \*(Aq, \*(Aqlist \-v\*(Aq));
\&
\& say $ns\->current_command(); # current_command stores list,
\&                             # Don\*(Aqt use this name for your own option
\&
\& $ns =$ap\->parse_args(split(\*(Aq \*(Aq, \*(Aqhelp list\*(Aq)); # This will print the usage for the list command
\& # help subcommand is automatically added for you
\& say $ns\->help_command(); # list
\&
\& # Copy parsing
\& $common_args = Getopt::ArgParse\->new_parser();
\& $common_args\->add_args(
\&   [
\&     \*(Aq\-\-dry\-run\*(Aq,
\&      type => \*(AqBool\*(Aq,
\&      help => \*(AqDry run\*(Aq,
\&   ],
\& );
\&
\& $sp = $ap\->add_parser(
\&   \*(Aqremove\*(Aq,
\&   aliases => [qw(rm)],           # prog remove or prog rm
\&   parents => [ $command_args ],  # prog rm \-\-dry\-run
\& );
\&
\& # Or copy explicitly
\& $sp = $ap\->add_parser(
\&   \*(Aqcopy\*(Aq,
\&   aliases => [qw(cp)],           # prog remove or prog rm
\& );
\&
\& $sp\->copy_args($command_parser); # You can also copy_parsers() but in this case
\&                                  # $common_parser doesn\*(Aqt have subparsers
.Ve
.SH "DESCRIPTIOIN"
.IX Header "DESCRIPTIOIN"
Getopt::ArgParse, Getopt::ArgParse::Parser and related classes
together aim to provide user-friendly interfaces for writing
command-line interfaces. A user should be able to use it without
looking up the document most of the time. It allows applications to
define argument specifications and it will parse them out of \f(CW@AGRV\fR by
default or a command line if provided. It implements both named
arguments, using Getopt::Long for parsing, and positional
arguments. The class also generates help and usage messages.
.PP
The parser has a namespace property, which is an object of
ArgParser::Namespace. The parsed argument values are stored in this
namespace property. Moreover, the values are stored accumulatively
when \fBparse_args()\fR is called multiple times.
.PP
Though inspired by Python's argparse and names and ideas are borrowed
from it, there is a lot of difference from the Python one.
.SS "Getopt::ArgParser::Parser"
.IX Subsection "Getopt::ArgParser::Parser"
This is the underlying parser that does the heavylifting.
.PP
Getopt::ArgParse::Parser is a Moo class.
.PP
\fIConstructor\fR
.IX Subsection "Constructor"
.PP
.Vb 4
\&  my $parser = Getopt::ArgParse\->new_parser(
\&    help        => \*(Aqshort description\*(Aq,
\&    description => \*(Aqlong description\*(Aq,
\&  );
.Ve
.PP
The former calls Getopt::ArgParser::Parser\->new to create a parser
object. The parser constructor accepts the following parameters.
.PP
All parsers are created with a predefined Bool option \-\-help|\-h. The
program can choose to reset it, though.
.IP "\(bu" 8
prog
.Sp
The program's name. Default \f(CW$0\fR.
.IP "\(bu" 8
help
.Sp
A short description of the program.
.IP "\(bu" 8
description
.Sp
A long description of the program.
.IP "\(bu" 8
namespace
.Sp
An object of Getopt::ArgParse::Namespace. An empty namespace is created if
not provided. The parsed values are stored in it, and they can be
refered to by their argument names as the namespace's properties,
e.g. \f(CW$parser\fR\->namespace\->boo. See also Getopt::ArgParse::Namespace
.IP "\(bu" 8
parser_configs
.Sp
The Getopt::Long configurations. See also Getopt::Long
.IP "\(bu" 8
parents
.Sp
Parent parsents, whose argument and subparser specifications the new
parser will copy. See \fBcopy()\fR below
.IP "\(bu" 8
error_prefix
.Sp
Customize the message prefixed to error messages thrown by
Getop::ArgParse, default to 'Getopt::ArgParse: '
.IP "\(bu" 8
print_usage_if_help
.Sp
Set this to false to not display usage messages even if \-\-help is on
or the subcommand help is called. The default behavior is to display
usage messages if help is set.
.PP
\fIadd_arg, add_argument, add_args, and add_arguments\fR
.IX Subsection "add_arg, add_argument, add_args, and add_arguments"
.PP
.Vb 4
\&  $parser\->add_args(
\&    [ \*(Aq\-\-foo\*(Aq, required => 1, type => \*(AqArray\*(Aq, split => \*(Aq,\*(Aq ],
\&    [ \*(Aqboo\*(Aq, required => 1, nargs => \*(Aq+\*(Aq ],
\&  );
.Ve
.PP
The object method, arg_arg or the longer version add_argument, defines
the specification of an argument. It accepts the following parameters.
.PP
add_args or \fBadd_arguments()\fR is to add multiple multiple arguments.
.IP "\(bu" 8
name or flags
.Sp
Either a name or a list of option strings, e.g. foo or \-f, \-\-foo.
.Sp
If dest is not specified, the name or the first option without leading
dashes will be used as the name for retrieving values. If a name is
given, this argument is a positional argument. Otherwise, it's an
option argument.
.Sp
Hyphens can be used in names and flags, but they will be replaced with
underscores '_' when used as option names. For example:
.Sp
.Vb 3
\&    $parser\->add_argument( [ \*(Aq\-\-dry\-run\*(Aq, type => \*(AqBool\*(Aq ]);
\&    # command line: prog \-\-dry\-run
\&    $parser\->namespace\->dry_run; # The option\*(Aqs name is dry_run
.Ve
.Sp
A name or option strings are following by named parameters.
.IP "\(bu" 8
dest
.Sp
The name of the attribute to be added to the namespace populated by
\&\fBparse_args()\fR.
.IP "\(bu" 8
type => \f(CW$type\fR
.Sp
Specify the type of the argument. It can be one of the following values:
.RS 8
.IP "\(bu" 8
Scalar
.Sp
The option takes a scalar value.
.IP "\(bu" 8
Array
.Sp
The option takes a list of values. The option can appear multiple
times in the command line. Each value is appended to the list. It's
stored in an arrayref in the namespace.
.IP "\(bu" 8
Pair
.Sp
The option takes a list of key-value pairs separated by the equal sign
\&'='. It's stored in a hashref in the namespace.
.IP "\(bu" 8
Bool
.Sp
The option does not take an argument. It's set to true if the option
is present or false otherwise. A 'no_bool' option is also available,
which is the negation of \fBbool()\fR.
.Sp
For example:
.Sp
.Vb 1
\&    $parser\->add_argument(\*(Aq\-\-dry\-run\*(Aq, type => \*(AqBool\*(Aq);
\&
\&    $ns = $parser\->parse_args(split(\*(Aq \*(Aq, \*(Aq\-\-dry\-run\*(Aq));
\&
\&    print $ns\->dry_run; # true
\&    print $ns\->no_dry_run; # false
.Ve
.IP "\(bu" 8
Count
.Sp
The option does not take an argument and its value will be incremented
by 1 every time it appears on the command line.
.RE
.RS 8
.RE
.IP "\(bu" 8
split
.Sp
split should work with types 'Array' and 'Pair' only.
.Sp
split specifies a string by which to split the argument string e.g. if
split => ',', a,b,c will be split into [ 'a', 'b', 'c' ].When split
works with type 'Pair', the parser will split the argument string and
then parse each of them as pairs.
.IP "\(bu" 8
choices or choices_i
.Sp
choices specifies a list of the allowable values for the argument or a
subroutine that validates input values.
.Sp
choices_i specifies a list of the allowable values for the argument,
but case insenstive, and it doesn't allow one to use a subroutine for
validation.
.Sp
Either choices or chioces_i can be present or completely omitted, but
not both at the same time.
.IP "\(bu" 8
default
.Sp
The value produced if the argument is absent from the command line.
.Sp
Only one value is allowed for scalar argument types: Scalar, Count, and Bool.
.IP "\(bu" 8
required
.Sp
Whether or not the command-line option may be omitted (optionals
only). This has no effect on types 'Bool' and 'Count'. An named
option is marked by the question mark ? in the generated usage, e.g.
    \-\-help, \-h             ? show this help message and exit
.Sp
This parameter is ignored for Bool and Count types for they will
already have default values.
.IP "\(bu" 8
help
.Sp
A brief description of what the argument does.
.IP "\(bu" 8
metavar
.Sp
A name for the argument in usage messages.
.IP "\(bu" 8
reset
.Sp
Set reset to override the existing definition of an option. This will
clear the value in the namspace as well.
.IP "\(bu" 8
nargs \- Positional option only
.Sp
This only instructs how many arguments the parser consumes. The
program still needs to specify the right type to achieve the desired
result.
.RS 8
.IP "\(bu" 8
n
.Sp
1 if not specified
.IP "\(bu" 8
?
.Sp
1 or 0
.IP "\(bu" 8
+
.Sp
1 or more
.IP "\(bu" 8
*
.Sp
0 or many. This will consume the rest of arguments.
.RE
.RS 8
.RE
.PP
\fIparse_args\fR
.IX Subsection "parse_args"
.PP
.Vb 1
\&  $namespace = $parser\->parse_args(@command_line);
.Ve
.PP
This object method accepts a list of arguments or \f(CW@ARGV\fR if
unspecified, parses them for values, and stores the values in the
namespace object.
.PP
A few things may be worth noting about \fBparse_args()\fR.
.PP
First, parsing for Named Arguments is done by Getopt::Long
.PP
Second, parsing for positional arguments takes place after that for
named arguments. It will consume what's still left in the command
line.
.PP
Finally, the Namespace object is accumulatively poplulated. If
\&\fBparse_args()\fR is called multiple times to parse a number of command
lines, the same namespace object is accumulatively populated.  For
Scalar and Bool options, this means the previous value will be
overwrittend. For Pair and Array options, values will be appended. And
for a Count option, it will add on top of the previous value.
.PP
In face, the program can choose to pass a already populated namespace
when creating a parser object. This is to allow the program to pre-load
values to a namespace from conf files before parsing the command line.
.PP
And finally, it does \s-1NOT\s0 display usage messages if the argument list
is empty. This may be contrary to many other implementations of
argument parsing.
.PP
\fIargv\fR
.IX Subsection "argv"
.PP
.Vb 1
\&  @argv = $parser\->argv; # called after parse_args
.Ve
.PP
Call this after \fBparse_args()\fR is invoked to get the unconsumed
arguments. It's up to the application to decide what to do if there is
a surplus of arguments.
.PP
\fIThe Namespace Object\fR
.IX Subsection "The Namespace Object"
.PP
The parsed values are stored in a namespace object. Any class with the
following three methods:
.PP
.Vb 3
\&  * A constructor new()
\&  * set_attr(name => value)
\&  * get_attr(name)
.Ve
.PP
can be used as the Namespace class.
.PP
The default one is Getopt::ArgParse::Namespace. It uses autoload to
provide a readonly accessor method using dest names to access parsed
values. However, this is not required for user-defined namespace. So
within the implementation, \f(CW$namespace\fR\->get_attr($dest) should always
be used.
.SS "Subcommand Support"
.IX Subsection "Subcommand Support"
Note only one level of subcommand parsing is supported. Subcommands
cannot have subcommands.
.PP
Call \fBadd_subparsers()\fR first to initialize the current parser for
subcommand support. A help subcommand is created as part of the
initialization. The help subcommand has the following options:
.Sp
.RS 4
required positional arguments:
     \s-1COMMAND\s0      ? Show the usage for this command
optional named arguments:
    \-\-help, \-h     ? show this help message and exit
    \-\-all, \-a      ? Show the full usage
.RE
.PP
Call \fBadd_parser()\fR to add a subparser for each subcommand. Use the
parser object returned by \fBadd_parser()\fR to add the options to the
subcommand.
.PP
Once subcommand support is on, if the first argument is not a flag,
i.e. starting with a dash '\-', the parser's \fBparse_args()\fR will treat it
as a subcommand. Otherwise, the parser parses for the defined
arguments.
.PP
The namespace's \fBcurrent_command()\fR will contain the subcommand after
parsing successfully.
.PP
Unlike arguments, subparsers cannot be reset.
.PP
\fIadd_subparsers\fR
.IX Subsection "add_subparsers"
.PP
.Vb 4
\&  $parser\->add_subparsers(
\&    title       => \*(AqSubcommands\*(Aq,
\&    description => \*(Aqdescription about providing subcommands\*(Aq,
\&  );
.Ve
.PP
add_subparsers must be called to initialize subcommand support.
.IP "\(bu" 8
title
.Sp
A title message to mark the beginning of subcommand usage in the usage
message
.IP "\(bu" 8
description
.Sp
A general description appearing about the title
.PP
\fIadd_parser\fR
.IX Subsection "add_parser"
.PP
.Vb 8
\&  $subparser = $parser\->add_parser(
\&     \*(Aqlist\*(Aq,
\&     aliases     => [qw(ls)],
\&     help        => \*(Aqshort description\*(Aq,
\&     description => \*(Aqa long one\*(Aq,
\&     parents => [ $common_args ], # inherit common args from
\&                                  # $common_args
\&  );
.Ve
.IP "\(bu" 8
\&\f(CW$command\fR
.Sp
The first argument is the name of the new command.
.IP "\(bu" 8
help
.Sp
A short description of the subcommand.
.IP "\(bu" 8
description
.Sp
A long description of the subcommand.
.IP "\(bu" 8
aliases
.Sp
An array reference containing a list of command aliases.
.IP "\(bu" 8
parents
.Sp
An array reference containing a list of parsers whose specification
will be copied by the new parser.
.SS "get_parser"
.IX Subsection "get_parser"
.Vb 1
\&   $subparser = $parser\->get_parser(\*(Aqls\*(Aq);
.Ve
.PP
Return the parser for parsing the \f(CW$alias\fR command if exsist.
.SS "Copying Parsers"
.IX Subsection "Copying Parsers"
A parser can copy argument specification or subcommand specifciation
for existing parsers. A use case for this is that the program wants all
subcommands to have a command set of arguments.
.PP
\fIcopy_args\fR
.IX Subsection "copy_args"
.PP
.Vb 1
\&   $parser\->copy_args($common_args_parser);
.Ve
.PP
Copy argument specification from the \f(CW$parent\fR parser
.PP
\fIcopy_parsers\fR
.IX Subsection "copy_parsers"
.PP
.Vb 1
\&   $parser\->copy_parsers($common_args_parser);
.Ve
.PP
Copy parser specification for subcommands from the \f(CW$parent\fR parser
.PP
\fIcopy\fR
.IX Subsection "copy"
.PP
.Vb 1
\&   $parser\->copy($common_args_parser);
.Ve
.PP
Copy both arguments and subparsers.
.SS "Usage Messages and Related Methods"
.IX Subsection "Usage Messages and Related Methods"
\fIformat_usage\fR
.IX Subsection "format_usage"
.PP
.Vb 1
\&  $usage = $parser\->format_usage;
.Ve
.PP
Return the formatted usage message for the whole program in an array
reference.
.PP
\fIprint_usage\fR
.IX Subsection "print_usage"
.PP
.Vb 1
\&   $parser\->print_usage;
.Ve
.PP
Print the usage message returned by \fBformat_usage()\fR.
.PP
\fIformat_command_usage\fR
.IX Subsection "format_command_usage"
.PP
.Vb 1
\&  $usage = $parser\->format_command_usage($subcommand);
.Ve
.PP
Return the formatted usage message for the command in an array
reference.
.PP
\fIprint_command_usage\fR
.IX Subsection "print_command_usage"
.PP
.Vb 1
\&  $parser\->print_command_usage($subcommand);
.Ve
.PP
Print the usage message returned by \fBformat_command_usage()\fR. If
\&\f(CW$command\fR is not given, it will first try to use
\&\f(CW$self\fR\->namespace\->help_command, which will be present for the help
subcommand, and then \f(CW$self\fR\->namespace\->current_command.
.PP
\fI\fR
.IX Subsection ""
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Getopt::Long
Python's argparse
.SH "AUTHOR"
.IX Header "AUTHOR"
Mytram <mytram2@gmail.com> (original author)
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Robbin Bonthond (rbonthond@github)
Adam Pfeiffer (apinco@github)
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2015 by Mytram.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Artistic License 2.0 (GPL Compatible)
.Ve