1MooseX::Getopt(3) User Contributed Perl Documentation MooseX::Getopt(3)
2
6 MooseX::Getopt - A Moose role for processing command line options
7
9 ## In your class
10 package My::App;
11 use Moose;
12 with 'MooseX::Getopt';
14 has 'out' => (is => 'rw', isa => 'Str', required => 1);
16 has 'in' => (is => 'rw', isa => 'Str', required => 1);
17 # ... rest of the class here
19 ## in your script
21 #!/usr/bin/perl
22 use My::App;
24 my $app = My::App->new_with_options();
26 # ... rest of the script here
27 ## on the command line
29 % perl my_app_script.pl -in file.input -out file.dump
30
32 This is a role which provides an alternate constructor for creating
33 objects using parameters passed in from the command line.
34 This module attempts to DWIM as much as possible with the command line
36 params by introspecting your class's attributes. It will use the name
37 of your attribute as the command line option, and if there is a type
38 constraint defined, it will configure Getopt::Long to handle the option
39 accordingly.
40 You can use the attribute metaclass MooseX::Getopt::Meta::Attribute to
42 get non-default commandline option names and aliases.
43 By default, attributes which start with an underscore are not given
45 commandline argument support, unless the attribute's metaclass is set
46 to MooseX::Getopt::Meta::Attribute. If you don't want you accessors to
47 have the leading underscore in thier name, you can do this:
48 # for read/write attributes
50 has '_foo' => (accessor => 'foo', ...);
51 # or for read-only attributes
53 has '_bar' => (reader => 'bar', ...);
54 This will mean that Getopt will not handle a --foo param, but your code
56 can still call the "foo" method.
57 Supported Type Constraints
59 Bool
61 A Bool type constraint is set up as a boolean option with
62 Getopt::Long. So that this attribute description:
63 has 'verbose' => (is => 'rw', isa => 'Bool');
65 would translate into "verbose!" as a Getopt::Long option descrip‐
67 tor, which would enable the following command line options:
68 % my_script.pl --verbose
70 % my_script.pl --noverbose
71 Int, Float, Str
73 These type constraints are set up as properly typed options with
74 Getopt::Long, using the "=i", "=f" and "=s" modifiers as appropri‐
75 ate.
76 ArrayRef
78 An ArrayRef type constraint is set up as a multiple value option in
79 Getopt::Long. So that this attribute description:
80 has 'include' => (
82 is => 'rw',
83 isa => 'ArrayRef',
84 default => sub { [] }
85 );
86 would translate into "includes=s@" as a Getopt::Long option
88 descriptor, which would enable the following command line options:
89 % my_script.pl --include /usr/lib --include /usr/local/lib
91 HashRef
93 A HashRef type constraint is set up as a hash value option in
94 Getopt::Long. So that this attribute description:
95 has 'define' => (
97 is => 'rw',
98 isa => 'HashRef',
99 default => sub { {} }
100 );
101 would translate into "define=s%" as a Getopt::Long option descrip‐
103 tor, which would enable the following command line options:
104 % my_script.pl --define os=linux --define vendor=debian
106 Custom Type Constraints
108 It is possible to create custom type constraint to option spec mappings
110 if you need them. The process is fairly simple (but a little verbose
111 maybe). First you create a custom subtype, like so:
112 subtype 'ArrayOfInts'
114 => as 'ArrayRef'
115 => where { scalar (grep { looks_like_number($_) } @$_) };
116 Then you register the mapping, like so:
118 MooseX::Getopt::OptionTypeMap->add_option_type_to_map(
120 'ArrayOfInts' => '=i@'
121 );
122 Now any attribute declarations using this type constraint will get the
124 custom option spec. So that, this:
125 has 'nums' => (
127 is => 'ro',
128 isa => 'ArrayOfInts',
129 default => sub { [0] }
130 );
131 Will translate to the following on the command line:
133 % my_script.pl --nums 5 --nums 88 --nums 199
135 This example is fairly trivial, but more complex validations are easily
137 possible with a little creativity. The trick is balancing the type con‐
138 straint validations with the Getopt::Long validations.
139 Better examples are certainly welcome :)
141 Inferred Type Constraints
143 If you define a custom subtype which is a subtype of one of the stan‐
145 dard "Supported Type Constraints" above, and do not explicitly provide
146 custom support as in "Custom Type Constraints" above, MooseX::Getopt
147 will treat it like the parent type for Getopt purposes.
148 For example, if you had the same custom "ArrayOfInts" subtype from the
150 examples above, but did not add a new custom option type for it to the
151 "OptionTypeMap", it would be treated just like a normal "ArrayRef" type
152 for Getopt purposes (that is, "=s@").
153
155 new_with_options (%params)
156 This method will take a set of default %params and then collect
157 params from the command line (possibly overriding those in %params)
158 and then return a newly constructed object.
159 If "GetOptions" in Getopt::Long fails (due to invalid arguments),
161 "new_with_options" will throw an exception.
162 ARGV
164 This accessor contains a reference to a copy of the @ARGV array as
165 it originally existed at the time of "new_with_options".
166 extra_argv
168 This accessor contains an arrayref of leftover @ARGV elements that
169 Getopt::Long did not parse. Note that the real @ARGV is left
170 un-mangled.
171 meta
173 This returns the role meta object.
174
176 All complex software has bugs lurking in it, and this module is no
177 exception. If you find a bug please either email me, or add the bug to
178 cpan-RT.
179
181 Stevan Little <stevan@iinteractive.com>
182 Brandon L. Black, <blblack@gmail.com>
184
186 Copyright 2007 by Infinity Interactive, Inc.
187 <http://www.iinteractive.com>
189 This library is free software; you can redistribute it and/or modify it
191 under the same terms as Perl itself.
192perl v5.8.8 2007-08-10 MooseX::Getopt(3)