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 trait MooseX::Getopt::Meta::Attribute::Trait or the
42 attribute metaclass MooseX::Getopt::Meta::Attribute to get non-default
43 commandline option names and aliases.
44 You can use the trait MooseX::Getopt::Meta::Attribute::Trait::NoGetopt
46 or the attribute metaclass MooseX::Getopt::Meta::Attribute::NoGetopt to
47 have "MooseX::Getopt" ignore your attribute in the commandline options.
48 By default, attributes which start with an underscore are not given
50 commandline argument support, unless the attribute's metaclass is set
51 to MooseX::Getopt::Meta::Attribute. If you don't want your accessors to
52 have the leading underscore in their name, you can do this:
53 # for read/write attributes
55 has '_foo' => (accessor => 'foo', ...);
56 # or for read-only attributes
58 has '_bar' => (reader => 'bar', ...);
59 This will mean that Getopt will not handle a --foo param, but your code
61 can still call the "foo" method.
62 If your class also uses a configfile-loading role based on
64 MooseX::ConfigFromFile, such as MooseX::SimpleConfig, MooseX::Getopt's
65 "new_with_options" will load the configfile specified by the
66 "--configfile" option (or the default you've given for the configfile
67 attribute) for you.
68 Options specified in multiple places follow the following precendence
70 order: commandline overrides configfile, which overrides explicit
71 new_with_options parameters.
72 Supported Type Constraints
74 Bool
75 A Bool type constraint is set up as a boolean option with
76 Getopt::Long. So that this attribute description:
77 has 'verbose' => (is => 'rw', isa => 'Bool');
79 would translate into "verbose!" as a Getopt::Long option
81 descriptor, which would enable the following command line options:
82 % my_script.pl --verbose
84 % my_script.pl --noverbose
85 Int, Float, Str
87 These type constraints are set up as properly typed options with
88 Getopt::Long, using the "=i", "=f" and "=s" modifiers as
89 appropriate.
90 ArrayRef
92 An ArrayRef type constraint is set up as a multiple value option in
93 Getopt::Long. So that this attribute description:
94 has 'include' => (
96 is => 'rw',
97 isa => 'ArrayRef',
98 default => sub { [] }
99 );
100 would translate into "includes=s@" as a Getopt::Long option
102 descriptor, which would enable the following command line options:
103 % my_script.pl --include /usr/lib --include /usr/local/lib
105 HashRef
107 A HashRef type constraint is set up as a hash value option in
108 Getopt::Long. So that this attribute description:
109 has 'define' => (
111 is => 'rw',
112 isa => 'HashRef',
113 default => sub { {} }
114 );
115 would translate into "define=s%" as a Getopt::Long option
117 descriptor, which would enable the following command line options:
118 % my_script.pl --define os=linux --define vendor=debian
120 Custom Type Constraints
122 It is possible to create custom type constraint to option spec mappings
123 if you need them. The process is fairly simple (but a little verbose
124 maybe). First you create a custom subtype, like so:
125 subtype 'ArrayOfInts'
127 => as 'ArrayRef'
128 => where { scalar (grep { looks_like_number($_) } @$_) };
129 Then you register the mapping, like so:
131 MooseX::Getopt::OptionTypeMap->add_option_type_to_map(
133 'ArrayOfInts' => '=i@'
134 );
135 Now any attribute declarations using this type constraint will get the
137 custom option spec. So that, this:
138 has 'nums' => (
140 is => 'ro',
141 isa => 'ArrayOfInts',
142 default => sub { [0] }
143 );
144 Will translate to the following on the command line:
146 % my_script.pl --nums 5 --nums 88 --nums 199
148 This example is fairly trivial, but more complex validations are easily
150 possible with a little creativity. The trick is balancing the type
151 constraint validations with the Getopt::Long validations.
152 Better examples are certainly welcome :)
154 Inferred Type Constraints
156 If you define a custom subtype which is a subtype of one of the
157 standard "Supported Type Constraints" above, and do not explicitly
158 provide custom support as in "Custom Type Constraints" above,
159 MooseX::Getopt will treat it like the parent type for Getopt purposes.
160 For example, if you had the same custom "ArrayOfInts" subtype from the
162 examples above, but did not add a new custom option type for it to the
163 "OptionTypeMap", it would be treated just like a normal "ArrayRef" type
164 for Getopt purposes (that is, "=s@").
165
167 new_with_options (%params)
168 This method will take a set of default %params and then collect
169 params from the command line (possibly overriding those in %params)
170 and then return a newly constructed object.
171 The special parameter "argv", if specified should point to an array
173 reference with an array to use instead of @ARGV.
174 If "GetOptions" in Getopt::Long fails (due to invalid arguments),
176 "new_with_options" will throw an exception.
177 If Getopt::Long::Descriptive is installed and any of the following
179 command line params are passed, the program will exit with usage
180 information. You can add descriptions for each option by including
181 a documentation option for each attribute to document.
182 --?
184 --help
185 --usage
186 If you have Getopt::Long::Descriptive the "usage" param is also
188 passed to "new".
189 ARGV
191 This accessor contains a reference to a copy of the @ARGV array as
192 it originally existed at the time of "new_with_options".
193 extra_argv
195 This accessor contains an arrayref of leftover @ARGV elements that
196 Getopt::Long did not parse. Note that the real @ARGV is left un-
197 mangled.
198 meta
200 This returns the role meta object.
201
203 All complex software has bugs lurking in it, and this module is no
204 exception. If you find a bug please either email me, or add the bug to
205 cpan-RT.
206
208 Stevan Little <stevan@iinteractive.com>
209 Brandon L. Black, <blblack@gmail.com>
211 Yuval Kogman, <nothingmuch@woobling.org>
213
215 Ryan D Johnson, <ryan@innerfence.com>
216 Drew Taylor, <drew@drewtaylor.com>
218 Tomas Doran, (t0m) "<bobtfish@bobtfish.net>"
220
222 Copyright 2007-2008 by Infinity Interactive, Inc.
223 <http://www.iinteractive.com>
225 This library is free software; you can redistribute it and/or modify it
227 under the same terms as Perl itself.
228perl v5.12.0 2010-03-01 MooseX::Getopt(3)