2 package MooseX::Getopt;
7 use MooseX::Getopt::OptionTypeMap;
8 use MooseX::Getopt::Meta::Attribute;
10 our $VERSION = '0.06';
11 our $AUTHORITY = 'cpan:STEVAN';
13 has ARGV => (is => 'rw', isa => 'ArrayRef');
14 has extra_argv => (is => 'rw', isa => 'ArrayRef');
16 sub new_with_options {
17 my ($class, %params) = @_;
19 my %processed = $class->_parse_argv(
21 $class->_attrs_to_options( %params )
26 ARGV => $processed{argv_copy},
27 extra_argv => $processed{argv},
28 %params, # explicit params to ->new
29 %{ $processed{params} }, # params from CLI
34 my ( $class, %params ) = @_;
36 local @ARGV = @{ $params{argv} || \@ARGV };
38 my ( @options, %name_to_init_arg, %options );
40 foreach my $opt ( @{ $params{options} } ) {
41 push @options, $opt->{opt_string};
42 $name_to_init_arg{ $opt->{name} } = $opt->{init_arg};
45 # Get a clean copy of the original @ARGV
46 my $argv_copy = [ @ARGV ];
49 local $SIG{__WARN__} = sub { die $_[0] };
50 Getopt::Long::GetOptions(\%options, @options);
53 # Get a copy of the Getopt::Long-mangled @ARGV
54 my $argv_mangled = [ @ARGV ];
57 argv_copy => $argv_copy,
58 argv => $argv_mangled,
61 $name_to_init_arg{$_} => $options{$_}
67 sub _attrs_to_options {
72 foreach my $attr ($class->meta->compute_all_applicable_attributes) {
73 my $name = $attr->name;
77 if ($attr->isa('MooseX::Getopt::Meta::Attribute')) {
78 $name = $attr->cmd_flag if $attr->has_cmd_flag;
79 $aliases = $attr->cmd_aliases if $attr->has_cmd_aliases;
82 next if $name =~ /^_/;
85 my $opt_string = $aliases
86 ? join(q{|}, $name, @$aliases)
89 if ($attr->has_type_constraint) {
90 my $type_name = $attr->type_constraint->name;
91 if (MooseX::Getopt::OptionTypeMap->has_option_type($type_name)) {
92 $opt_string .= MooseX::Getopt::OptionTypeMap->get_option_type($type_name);
98 init_arg => $attr->init_arg,
99 opt_string => $opt_string,
100 required => $attr->is_required,
101 ( $attr->has_documentation ? ( doc => $attr->documentation ) : () ),
116 MooseX::Getopt - A Moose role for processing command line options
124 with 'MooseX::Getopt';
126 has 'out' => (is => 'rw', isa => 'Str', required => 1);
127 has 'in' => (is => 'rw', isa => 'Str', required => 1);
129 # ... rest of the class here
136 my $app = My::App->new_with_options();
137 # ... rest of the script here
139 ## on the command line
140 % perl my_app_script.pl -in file.input -out file.dump
144 This is a role which provides an alternate constructor for creating
145 objects using parameters passed in from the command line.
147 This module attempts to DWIM as much as possible with the command line
148 params by introspecting your class's attributes. It will use the name
149 of your attribute as the command line option, and if there is a type
150 constraint defined, it will configure Getopt::Long to handle the option
153 You can use the attribute metaclass L<MooseX::Getopt::Meta::Attribute>
154 to get non-default commandline option names and aliases.
156 By default, attributes which start with an underscore are not given
157 commandline argument support, unless the attribute's metaclass is set
158 to L<MooseX::Getopt::Meta::Attribute>. If you don't want you accessors
159 to have the leading underscore in thier name, you can do this:
161 # for read/write attributes
162 has '_foo' => (accessor => 'foo', ...);
164 # or for read-only attributes
165 has '_bar' => (reader => 'bar', ...);
167 This will mean that Getopt will not handle a --foo param, but your
168 code can still call the C<foo> method.
170 =head2 Supported Type Constraints
176 A I<Bool> type constraint is set up as a boolean option with
177 Getopt::Long. So that this attribute description:
179 has 'verbose' => (is => 'rw', isa => 'Bool');
181 would translate into C<verbose!> as a Getopt::Long option descriptor,
182 which would enable the following command line options:
184 % my_script.pl --verbose
185 % my_script.pl --noverbose
187 =item I<Int>, I<Float>, I<Str>
189 These type constraints are set up as properly typed options with
190 Getopt::Long, using the C<=i>, C<=f> and C<=s> modifiers as appropriate.
194 An I<ArrayRef> type constraint is set up as a multiple value option
195 in Getopt::Long. So that this attribute description:
200 default => sub { [] }
203 would translate into C<includes=s@> as a Getopt::Long option descriptor,
204 which would enable the following command line options:
206 % my_script.pl --include /usr/lib --include /usr/local/lib
210 A I<HashRef> type constraint is set up as a hash value option
211 in Getopt::Long. So that this attribute description:
216 default => sub { {} }
219 would translate into C<define=s%> as a Getopt::Long option descriptor,
220 which would enable the following command line options:
222 % my_script.pl --define os=linux --define vendor=debian
226 =head2 Custom Type Constraints
228 It is possible to create custom type constraint to option spec
229 mappings if you need them. The process is fairly simple (but a
230 little verbose maybe). First you create a custom subtype, like
233 subtype 'ArrayOfInts'
235 => where { scalar (grep { looks_like_number($_) } @$_) };
237 Then you register the mapping, like so:
239 MooseX::Getopt::OptionTypeMap->add_option_type_to_map(
240 'ArrayOfInts' => '=i@'
243 Now any attribute declarations using this type constraint will
244 get the custom option spec. So that, this:
248 isa => 'ArrayOfInts',
249 default => sub { [0] }
252 Will translate to the following on the command line:
254 % my_script.pl --nums 5 --nums 88 --nums 199
256 This example is fairly trivial, but more complex validations are
257 easily possible with a little creativity. The trick is balancing
258 the type constraint validations with the Getopt::Long validations.
260 Better examples are certainly welcome :)
262 =head2 Inferred Type Constraints
264 If you define a custom subtype which is a subtype of one of the
265 standard L</Supported Type Constraints> above, and do not explicitly
266 provide custom support as in L</Custom Type Constraints> above,
267 MooseX::Getopt will treat it like the parent type for Getopt
270 For example, if you had the same custom C<ArrayOfInts> subtype
271 from the examples above, but did not add a new custom option
272 type for it to the C<OptionTypeMap>, it would be treated just
273 like a normal C<ArrayRef> type for Getopt purposes (that is,
280 =item B<new_with_options (%params)>
282 This method will take a set of default C<%params> and then collect
283 params from the command line (possibly overriding those in C<%params>)
284 and then return a newly constructed object.
286 If L<Getopt::Long/GetOptions> fails (due to invalid arguments),
287 C<new_with_options> will throw an exception.
291 This accessor contains a reference to a copy of the C<@ARGV> array
292 as it originally existed at the time of C<new_with_options>.
296 This accessor contains an arrayref of leftover C<@ARGV> elements that
297 L<Getopt::Long> did not parse. Note that the real C<@ARGV> is left
302 This returns the role meta object.
308 All complex software has bugs lurking in it, and this module is no
309 exception. If you find a bug please either email me, or add the bug
314 Stevan Little E<lt>stevan@iinteractive.comE<gt>
316 Brandon L. Black, E<lt>blblack@gmail.comE<gt>
318 =head1 COPYRIGHT AND LICENSE
320 Copyright 2007 by Infinity Interactive, Inc.
322 L<http://www.iinteractive.com>
324 This library is free software; you can redistribute it and/or modify
325 it under the same terms as Perl itself.