NAME<\/a> MooseX::Getopt \u2212 A Moose role for processing command line options<\/p>\n version 0.74<\/p>\n ## In your class This is a role which provides an alternate constructor for creating objects using parameters passed in from the command line.<\/p>\n “new_with_options (%params)”<\/b> The special parameter “argv”, if specified should point to an array reference with an array to use instead of @ARGV.<\/p>\n If “GetOptions” in Getopt::Long fails (due to invalid arguments), “new_with_options” will throw an exception.<\/p>\n If Getopt::Long::Descriptive is installed and any of the following command line parameters are passed, the program will exit with usage information (and the option\u2019s state will be stored in the help_flag attribute). You can add descriptions for each option by including a documentation<\/b> option for each attribute to document.<\/p>\n \u2212? If you have Getopt::Long::Descriptive the “usage” parameter is also passed to “new” as the usage option.<\/p>\n “ARGV”<\/b> “extra_argv”<\/b> Important<\/b>: By default, Getopt::Long will reject unrecognized options<\/i> (that is, options that do not correspond with attributes using the “Getopt” trait). To disable this, and allow options to also be saved in “extra_argv” (for example to pass along to another class\u2019s “new_with_options”), you can either enable the “pass_through” option of Getopt::Long for your class: “use Getopt::Long qw(:config pass_through);” or specify a value for MooseX::Getopt::GLD\u2019s “getopt_conf” parameter.<\/p>\n “usage”<\/b> “help_flag”<\/b> “print_usage_text”<\/b> “meta”<\/b> “process_argv (%params)”<\/b> This module attempts to DWIM<\/small> as much as possible with the command line parameters by introspecting your class\u2019s attributes. It will use the name of your attribute as the command line option, and if there is a type constraint defined, it will configure Getopt::Long to handle the option accordingly.<\/p>\n You can use the trait MooseX::Getopt::Meta::Attribute::Trait or the attribute metaclass MooseX::Getopt::Meta::Attribute to get non-default command-line option names and aliases.<\/p>\n You can use the trait MooseX::Getopt::Meta::Attribute::Trait::NoGetopt or the attribute metaclass MooseX::Getopt::Meta::Attribute::NoGetopt to have “MooseX::Getopt” ignore your attribute in the command-line options.<\/p>\n By default, attributes which start with an underscore are not given command-line argument support, unless the attribute\u2019s metaclass is set to MooseX::Getopt::Meta::Attribute. If you don\u2019t want your accessors to have the leading underscore in their name, you can do this:<\/p>\n # for read\/write attributes This will mean that MooseX::Getopt will not handle a \u2212\u2212foo parameter, but your code can still call the “foo” method.<\/p>\n If your class also uses a configfile-loading role based on MooseX::ConfigFromFile, such as MooseX::SimpleConfig, MooseX::Getopt\u2019s “new_with_options” will load the configfile specified by the “\u2212\u2212configfile” option (or the default you\u2019ve given for the configfile attribute) for you.<\/p>\n Options specified in multiple places follow the following precedence order: command-line overrides configfile, which overrides explicit new_with_options parameters.<\/p>\n Supported Type Constraints<\/b> A Bool<\/i> type constraint is set up as a boolean option with Getopt::Long. So that this attribute description:<\/p>\n has ‘verbose’ => (is => ‘rw’, isa => ‘Bool’);<\/p>\n would translate into “verbose!” as a Getopt::Long option descriptor, which would enable the following command line options:<\/p>\n % my_script.pl \u2212\u2212verbose Int<\/i>, Float<\/i>, Str<\/i><\/p>\n These type constraints are set up as properly typed options with Getopt::Long, using the “=i”, “=f” and “=s” modifiers as appropriate.<\/p>\n ArrayRef<\/i><\/p>\n An ArrayRef<\/i> type constraint is set up as a multiple value option in Getopt::Long. So that this attribute description:<\/p>\n has ‘include’ => ( would translate into “includes=s@” as a Getopt::Long option descriptor, which would enable the following command line options:<\/p>\n % my_script.pl \u2212\u2212include \/usr\/lib \u2212\u2212include \/usr\/local\/lib<\/p>\n HashRef<\/i><\/p>\n A HashRef<\/i> type constraint is set up as a hash value option in Getopt::Long. So that this attribute description:<\/p>\n has ‘define’ => ( would translate into “define=s%” as a Getopt::Long option descriptor, which would enable the following command line options:<\/p>\n % my_script.pl \u2212\u2212define os=linux \u2212\u2212define vendor=debian<\/p>\n Custom Type Constraints<\/b> subtype ‘ArrayOfInts’ Then you register the mapping, like so:<\/p>\n MooseX::Getopt::OptionTypeMap\u2212>add_option_type_to_map( Now any attribute declarations using this type constraint will get the custom option spec. So that, this:<\/p>\n has ‘nums’ => ( Will translate to the following on the command line:<\/p>\n % my_script.pl \u2212\u2212nums 5 \u2212\u2212nums 88 \u2212\u2212nums 199<\/p>\n This example is fairly trivial, but more complex validations are easily possible with a little creativity. The trick is balancing the type constraint validations with the Getopt::Long validations.<\/p>\n Better examples are certainly welcome \ud83d\ude42<\/p>\n Inferred Type Constraints<\/b> For example, if you had the same custom “ArrayOfInts” subtype from the examples above, but did not add a new custom option type for it to the “OptionTypeMap”, it would be treated just like a normal “ArrayRef” type for Getopt purposes (that is, “=s@”).<\/p>\n More Customization Options<\/b> Note in particular that the default setting for case sensitivity has changed over time in Getopt::Long::Descriptive, so if you rely on a particular setting, you should set it explicitly, or enforce the version of Getopt::Long::Descriptive that you install.<\/p>\n
VERSION<\/a>
SYNOPSIS<\/a>
DESCRIPTION<\/a>
METHODS<\/a>
SEE ALSO<\/a>
SUPPORT<\/a>
AUTHOR<\/a>
CONTRIBUTORS<\/a>
COPYRIGHT AND LICENSE<\/a> <\/p>\n
\nNAME <\/a> <\/h2>\n
VERSION <\/a> <\/h2>\n
SYNOPSIS <\/a> <\/h2>\n
package My::App;
use Moose;
with ‘MooseX::Getopt’;
has ‘out’ => (is => ‘rw’, isa => ‘Str’, required => 1);
has ‘in’ => (is => ‘rw’, isa => ‘Str’, required => 1);
# … rest of the class here
## in your script
#!\/usr\/bin\/perl
use My::App;
my $app = My::App\u2212>new_with_options();
# … rest of the script here
## on the command line
% perl my_app_script.pl \u2212in file.input \u2212out file.dump<\/p>\nDESCRIPTION <\/a> <\/h2>\n
METHODS <\/a> <\/h2>\n
This method will take a set of default %params and then collect parameters from the command line (possibly overriding those in %params) and then return a newly constructed object.<\/p>\n
\u2212\u2212?
\u2212h
\u2212\u2212help
\u2212\u2212usage<\/p>\n
This accessor contains a reference to a copy of the @ARGV array as it originally existed at the time of “new_with_options”.<\/p>\n
This accessor contains an arrayref of leftover @ARGV elements that Getopt::Long did not parse. Note that the real @ARGV is left untouched.<\/p>\n
This accessor contains the Getopt::Long::Descriptive::Usage object (if Getopt::Long::Descriptive is used).<\/p>\n
This accessor contains the boolean state of the \u2212\u2212help, \u2212\u2212usage and \u2212\u2212? options (true if any of these options were passed on the command line).<\/p>\n
This method is called internally when the “help_flag” state is true. It prints the text from the “usage” object (see above) to “STDOUT” (and then after this method is called, the program terminates normally). You can apply a method modification (see Moose::Manual::MethodModifiers) if different behaviour is desired, for example to include additional text.<\/p>\n
This returns the role meta object.<\/p>\n
This does most of the work of “new_with_options”, analyzing the parameters and “argv”, except for actually calling the constructor. It returns a MooseX::Getopt::ProcessedArgv object. “new_with_options” uses this method internally, so modifying this method via subclasses\/roles will affect “new_with_options”.<\/p>\n
has ‘_foo’ => (accessor => ‘foo’, …);
# or for read\u2212only attributes
has ‘_bar’ => (reader => ‘bar’, …);<\/p>\n
Bool<\/i><\/p>\n
% my_script.pl \u2212\u2212noverbose<\/p>\n
is => ‘rw’,
isa => ‘ArrayRef’,
default => sub { [] }
);<\/p>\n
is => ‘rw’,
isa => ‘HashRef’,
default => sub { {} }
);<\/p>\n
It is possible to create custom type constraint to option spec mappings if you need them. The process is fairly simple (but a little verbose maybe). First you create a custom subtype, like so:<\/p>\n
=> as ‘ArrayRef’
=> where { scalar (grep { looks_like_number($_) } @$_) };<\/p>\n
‘ArrayOfInts’ => ‘=i@’
);<\/p>\n
is => ‘ro’,
isa => ‘ArrayOfInts’,
default => sub { [0] }
);<\/p>\n
If you define a custom subtype which is a subtype of one of the standard “Supported Type Constraints” above, and do not explicitly provide custom support as in “Custom Type Constraints” above, MooseX::Getopt will treat it like the parent type for Getopt purposes.<\/p>\n
See “Configuring Getopt::Long” in Getopt::Long for many other customizations you can make to how options are parsed. Simply “use Getopt::Long qw(:config other_options…)” in your class to set these.<\/p>\nSEE ALSO <\/a> <\/h2>\n