Commit | Line | Data |
5dac17c3 |
1 | package MooseX::Getopt; |
669588e2 |
2 | # ABSTRACT: A Moose role for processing command line options |
5dac17c3 |
3 | |
669588e2 |
4 | use Moose::Role 0.56; |
75a6449b |
5 | |
75434e78 |
6 | with 'MooseX::Getopt::GLD'; |
5dac17c3 |
7 | |
669588e2 |
8 | no Moose::Role; |
5dac17c3 |
9 | |
669588e2 |
10 | 1; |
5dac17c3 |
11 | |
12 | =head1 SYNOPSIS |
13 | |
4e086633 |
14 | ## In your class |
5dac17c3 |
15 | package My::App; |
16 | use Moose; |
4e086633 |
17 | |
5dac17c3 |
18 | with 'MooseX::Getopt'; |
4e086633 |
19 | |
5dac17c3 |
20 | has 'out' => (is => 'rw', isa => 'Str', required => 1); |
21 | has 'in' => (is => 'rw', isa => 'Str', required => 1); |
4e086633 |
22 | |
5dac17c3 |
23 | # ... rest of the class here |
4e086633 |
24 | |
5dac17c3 |
25 | ## in your script |
26 | #!/usr/bin/perl |
4e086633 |
27 | |
5dac17c3 |
28 | use My::App; |
4e086633 |
29 | |
5dac17c3 |
30 | my $app = My::App->new_with_options(); |
31 | # ... rest of the script here |
4e086633 |
32 | |
5dac17c3 |
33 | ## on the command line |
34 | % perl my_app_script.pl -in file.input -out file.dump |
35 | |
36 | =head1 DESCRIPTION |
37 | |
4e086633 |
38 | This is a role which provides an alternate constructor for creating |
39 | objects using parameters passed in from the command line. |
8034a232 |
40 | |
4e086633 |
41 | This module attempts to DWIM as much as possible with the command line |
42 | params by introspecting your class's attributes. It will use the name |
43 | of your attribute as the command line option, and if there is a type |
8034a232 |
44 | constraint defined, it will configure Getopt::Long to handle the option |
3899e5df |
45 | accordingly. |
46 | |
2814de27 |
47 | You can use the trait L<MooseX::Getopt::Meta::Attribute::Trait> or the |
48 | attribute metaclass L<MooseX::Getopt::Meta::Attribute> to get non-default |
49 | commandline option names and aliases. |
3899e5df |
50 | |
2814de27 |
51 | You can use the trait L<MooseX::Getopt::Meta::Attribute::Trait::NoGetopt> |
52 | or the attribute metaclass L<MooseX::Getopt::Meta::Attribute::NoGetopt> |
0f8232b6 |
53 | to have C<MooseX::Getopt> ignore your attribute in the commandline options. |
54 | |
3899e5df |
55 | By default, attributes which start with an underscore are not given |
56 | commandline argument support, unless the attribute's metaclass is set |
7f5f3d94 |
57 | to L<MooseX::Getopt::Meta::Attribute>. If you don't want your accessors |
58 | to have the leading underscore in their name, you can do this: |
3d9a716d |
59 | |
60 | # for read/write attributes |
61 | has '_foo' => (accessor => 'foo', ...); |
4e086633 |
62 | |
3d9a716d |
63 | # or for read-only attributes |
4e086633 |
64 | has '_bar' => (reader => 'bar', ...); |
3d9a716d |
65 | |
4e086633 |
66 | This will mean that Getopt will not handle a --foo param, but your |
67 | code can still call the C<foo> method. |
8034a232 |
68 | |
ee69c4ba |
69 | If your class also uses a configfile-loading role based on |
70 | L<MooseX::ConfigFromFile>, such as L<MooseX::SimpleConfig>, |
71 | L<MooseX::Getopt>'s C<new_with_options> will load the configfile |
b4a79051 |
72 | specified by the C<--configfile> option (or the default you've |
73 | given for the configfile attribute) for you. |
74 | |
75 | Options specified in multiple places follow the following |
fe01c3e8 |
76 | precedence order: commandline overrides configfile, which |
b4a79051 |
77 | overrides explicit new_with_options parameters. |
ee69c4ba |
78 | |
8034a232 |
79 | =head2 Supported Type Constraints |
80 | |
81 | =over 4 |
82 | |
83 | =item I<Bool> |
84 | |
4e086633 |
85 | A I<Bool> type constraint is set up as a boolean option with |
8034a232 |
86 | Getopt::Long. So that this attribute description: |
87 | |
88 | has 'verbose' => (is => 'rw', isa => 'Bool'); |
89 | |
4e086633 |
90 | would translate into C<verbose!> as a Getopt::Long option descriptor, |
8034a232 |
91 | which would enable the following command line options: |
92 | |
93 | % my_script.pl --verbose |
4e086633 |
94 | % my_script.pl --noverbose |
95 | |
8034a232 |
96 | =item I<Int>, I<Float>, I<Str> |
97 | |
4e086633 |
98 | These type constraints are set up as properly typed options with |
8034a232 |
99 | Getopt::Long, using the C<=i>, C<=f> and C<=s> modifiers as appropriate. |
100 | |
101 | =item I<ArrayRef> |
102 | |
103 | An I<ArrayRef> type constraint is set up as a multiple value option |
104 | in Getopt::Long. So that this attribute description: |
105 | |
106 | has 'include' => ( |
4e086633 |
107 | is => 'rw', |
108 | isa => 'ArrayRef', |
8034a232 |
109 | default => sub { [] } |
110 | ); |
111 | |
4e086633 |
112 | would translate into C<includes=s@> as a Getopt::Long option descriptor, |
8034a232 |
113 | which would enable the following command line options: |
114 | |
115 | % my_script.pl --include /usr/lib --include /usr/local/lib |
116 | |
117 | =item I<HashRef> |
118 | |
119 | A I<HashRef> type constraint is set up as a hash value option |
120 | in Getopt::Long. So that this attribute description: |
121 | |
122 | has 'define' => ( |
4e086633 |
123 | is => 'rw', |
124 | isa => 'HashRef', |
8034a232 |
125 | default => sub { {} } |
126 | ); |
127 | |
4e086633 |
128 | would translate into C<define=s%> as a Getopt::Long option descriptor, |
8034a232 |
129 | which would enable the following command line options: |
130 | |
131 | % my_script.pl --define os=linux --define vendor=debian |
132 | |
133 | =back |
134 | |
135 | =head2 Custom Type Constraints |
136 | |
4e086633 |
137 | It is possible to create custom type constraint to option spec |
8034a232 |
138 | mappings if you need them. The process is fairly simple (but a |
4e086633 |
139 | little verbose maybe). First you create a custom subtype, like |
8034a232 |
140 | so: |
141 | |
142 | subtype 'ArrayOfInts' |
143 | => as 'ArrayRef' |
144 | => where { scalar (grep { looks_like_number($_) } @$_) }; |
145 | |
146 | Then you register the mapping, like so: |
147 | |
148 | MooseX::Getopt::OptionTypeMap->add_option_type_to_map( |
149 | 'ArrayOfInts' => '=i@' |
150 | ); |
151 | |
4e086633 |
152 | Now any attribute declarations using this type constraint will |
8034a232 |
153 | get the custom option spec. So that, this: |
154 | |
155 | has 'nums' => ( |
156 | is => 'ro', |
157 | isa => 'ArrayOfInts', |
158 | default => sub { [0] } |
159 | ); |
160 | |
161 | Will translate to the following on the command line: |
162 | |
163 | % my_script.pl --nums 5 --nums 88 --nums 199 |
164 | |
4e086633 |
165 | This example is fairly trivial, but more complex validations are |
8034a232 |
166 | easily possible with a little creativity. The trick is balancing |
167 | the type constraint validations with the Getopt::Long validations. |
168 | |
169 | Better examples are certainly welcome :) |
170 | |
f63e6310 |
171 | =head2 Inferred Type Constraints |
172 | |
173 | If you define a custom subtype which is a subtype of one of the |
174 | standard L</Supported Type Constraints> above, and do not explicitly |
175 | provide custom support as in L</Custom Type Constraints> above, |
176 | MooseX::Getopt will treat it like the parent type for Getopt |
177 | purposes. |
178 | |
179 | For example, if you had the same custom C<ArrayOfInts> subtype |
180 | from the examples above, but did not add a new custom option |
181 | type for it to the C<OptionTypeMap>, it would be treated just |
182 | like a normal C<ArrayRef> type for Getopt purposes (that is, |
183 | C<=s@>). |
184 | |
669588e2 |
185 | =method B<new_with_options (%params)> |
5dac17c3 |
186 | |
4e086633 |
187 | This method will take a set of default C<%params> and then collect |
8034a232 |
188 | params from the command line (possibly overriding those in C<%params>) |
189 | and then return a newly constructed object. |
190 | |
035b1668 |
191 | The special parameter C<argv>, if specified should point to an array |
0e3f178a |
192 | reference with an array to use instead of C<@ARGV>. |
193 | |
f63e6310 |
194 | If L<Getopt::Long/GetOptions> fails (due to invalid arguments), |
195 | C<new_with_options> will throw an exception. |
196 | |
47a89a8d |
197 | If L<Getopt::Long::Descriptive> is installed and any of the following |
2557b526 |
198 | command line params are passed, the program will exit with usage |
81b19ed8 |
199 | information (and the option's state will be stored in the help_flag |
200 | attribute). You can add descriptions for each option by including a |
47a89a8d |
201 | B<documentation> option for each attribute to document. |
202 | |
fa8dcd69 |
203 | -? |
47a89a8d |
204 | --? |
8d396d8a |
205 | -h |
47a89a8d |
206 | --help |
207 | --usage |
208 | |
b766829d |
209 | If you have L<Getopt::Long::Descriptive> the C<usage> param is also passed to |
81b19ed8 |
210 | C<new> as the usage option. |
fad5da09 |
211 | |
669588e2 |
212 | =method B<ARGV> |
3899e5df |
213 | |
214 | This accessor contains a reference to a copy of the C<@ARGV> array |
f63e6310 |
215 | as it originally existed at the time of C<new_with_options>. |
216 | |
669588e2 |
217 | =method B<extra_argv> |
f63e6310 |
218 | |
219 | This accessor contains an arrayref of leftover C<@ARGV> elements that |
220 | L<Getopt::Long> did not parse. Note that the real C<@ARGV> is left |
221 | un-mangled. |
3899e5df |
222 | |
faf7d951 |
223 | B<Important>: By default, L<Getopt::Long> will reject unrecognized I<options> |
224 | (that is, options that do not correspond with attributes using the Getopt |
edd79c6f |
225 | trait). To disable this, and allow options to also be saved in C<extra_argv> (for example to pass along to another class's C<new_with_options>), you can either enable the |
226 | C<pass_through> option of L<Getopt::Long> for your class: C<< use Getopt::Long |
227 | qw(:config pass_through); >> or specify a value for for L<MooseX::Getopt::GLD>'s C<getopt_conf> parameter. |
449f0087 |
228 | |
81b19ed8 |
229 | =method B<usage> |
230 | |
231 | This accessor contains the L<Getopt::Long::Descriptive::Usage> object (if |
232 | L<Getopt::Long::Descriptive> is used). |
233 | |
234 | =method B<help_flag> |
235 | |
236 | This accessor contains the boolean state of the --help, --usage and --? |
237 | options (true if any of these options were passed on the command line). |
238 | |
83446b78 |
239 | =method B<print_usage_text> |
240 | |
241 | This method is called internally when the C<help_flag> state is true. |
242 | It prints the text from the C<usage> object (see above) to stdout and then the |
243 | program terminates normally. You can apply a method modification (see |
244 | L<Moose::Manual::MethodModifiers>) if different behaviour is desired, for |
245 | example to include additional text. |
246 | |
669588e2 |
247 | =method B<meta> |
5dac17c3 |
248 | |
8034a232 |
249 | This returns the role meta object. |
250 | |
f3615693 |
251 | =method B<process_argv (%params)> |
252 | |
253 | This does most of the work of C<new_with_options>, analyzing the parameters |
254 | and argv, except for actually calling the constructor. It returns a |
255 | L<MooseX::Getopt::ProcessedArgv> object. C<new_with_options> uses this |
256 | method internally, so modifying this method via subclasses/roles will affect |
257 | C<new_with_options>. |
258 | |
449f0087 |
259 | =head2 More Customization Options |
260 | |
772e216b |
261 | See L<Getopt::Long/Configuring Getopt::Long> for many other customizations you |
449f0087 |
262 | can make to how options are parsed. Simply C<use Getopt::Long qw(:config |
263 | other_options...)> in your class to set these. |
264 | |
5dac17c3 |
265 | =cut |
cdb3fe1f |
266 | |