NAME
MooseX::Getopt - A Moose role for processing command line options
SYNOPSIS
## In your class
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->new_with_options();
# ... rest of the script here
## on the command line
% perl my_app_script.pl -in file.input -out file.dump
DESCRIPTION
This is a role which provides an alternate constructor for creating objects using parameters passed in from the command line.
This module attempts to DWIM as much as possible with the command line params by introspecting your class's 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.
Supported Type Constraints
- Bool
-
A Bool type constraint is set up as a boolean option with Getopt::Long. So that this attribute description:
has 'verbose' => (is => 'rw', isa => 'Bool');
would translate into
verbose!
as a Getopt::Long option descriptor, which would enable the following command line options:% my_script.pl --verbose % my_script.pl --noverbose
- Int, Float, Str
-
These type constraints are set up as properly typed options with Getopt::Long, using the
=i
,=f
and=s
modifiers as appropriate. - ArrayRef
-
An ArrayRef type constraint is set up as a multiple value option in Getopt::Long. So that this attribute description:
has 'include' => ( is => 'rw', isa => 'ArrayRef', default => sub { [] } );
would translate into
includes=s@
as a Getopt::Long option descriptor, which would enable the following command line options:% my_script.pl --include /usr/lib --include /usr/local/lib
- HashRef
-
A HashRef type constraint is set up as a hash value option in Getopt::Long. So that this attribute description:
has 'define' => ( is => 'rw', isa => 'HashRef', default => sub { {} } );
would translate into
define=s%
as a Getopt::Long option descriptor, which would enable the following command line options:% my_script.pl --define os=linux --define vendor=debian
Custom Type Constraints
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:
subtype 'ArrayOfInts'
=> as 'ArrayRef'
=> where { scalar (grep { looks_like_number($_) } @$_) };
Then you register the mapping, like so:
MooseX::Getopt::OptionTypeMap->add_option_type_to_map(
'ArrayOfInts' => '=i@'
);
Now any attribute declarations using this type constraint will get the custom option spec. So that, this:
has 'nums' => (
is => 'ro',
isa => 'ArrayOfInts',
default => sub { [0] }
);
Will translate to the following on the command line:
% my_script.pl --nums 5 --nums 88 --nums 199
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.
Better examples are certainly welcome :)
METHODS
- new_with_options (%params)
-
This method will take a set of default
%params
and then collect params from the command line (possibly overriding those in%params
) and then return a newly constructed object. - meta
-
This returns the role meta object.
BUGS
All complex software has bugs lurking in it, and this module is no exception. If you find a bug please either email me, or add the bug to cpan-RT.
AUTHOR
Stevan Little <stevan@iinteractive.com>
COPYRIGHT AND LICENSE
Copyright 2007 by Infinity Interactive, Inc.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.