File Coverage

blib/lib/MouseX/Getopt.pm
Criterion Covered Total %
statement 6 6 100.0
branch n/a
condition n/a
subroutine 2 2 100.0
pod n/a
total 8 8 100.0


line stmt bran cond sub pod time code
1             package MouseX::Getopt;
2             # ABSTRACT: A Mouse role for processing command line options
3              
4             our $VERSION = "0.36";
5              
6 21     21   389355 use Mouse::Role;
  21         238085  
  21         87  
7              
8             with 'MouseX::Getopt::GLD';
9              
10 21     21   4791 no Mouse::Role;
  21         31  
  21         82  
11              
12             1;
13              
14             =for stopwords metaclass commandline params configfile
15              
16             =head1 SYNOPSIS
17              
18             ## In your class
19             package My::App;
20             use Mouse;
21              
22             with 'MouseX::Getopt';
23              
24             has 'out' => (is => 'rw', isa => 'Str', required => 1);
25             has 'in' => (is => 'rw', isa => 'Str', required => 1);
26              
27             # ... rest of the class here
28              
29             ## in your script
30             #!/usr/bin/perl
31              
32             use My::App;
33              
34             my $app = My::App->new_with_options();
35             # ... rest of the script here
36              
37             ## on the command line
38             % perl my_app_script.pl -in file.input -out file.dump
39              
40             =head1 DESCRIPTION
41              
42             This is a role which provides an alternate constructor for creating
43             objects using parameters passed in from the command line.
44              
45             This module attempts to DWIM as much as possible with the command line
46             params by introspecting your class's attributes. It will use the name
47             of your attribute as the command line option, and if there is a type
48             constraint defined, it will configure Getopt::Long to handle the option
49             accordingly.
50              
51             You can use the trait L or the
52             attribute metaclass L to get non-default
53             commandline option names and aliases.
54              
55             You can use the trait L
56             or the attribute metaclass L
57             to have C ignore your attribute in the commandline options.
58              
59             By default, attributes which start with an underscore are not given
60             commandline argument support, unless the attribute's metaclass is set
61             to L. If you don't want your accessors
62             to have the leading underscore in their name, you can do this:
63              
64             # for read/write attributes
65             has '_foo' => (accessor => 'foo', ...);
66              
67             # or for read-only attributes
68             has '_bar' => (reader => 'bar', ...);
69              
70             This will mean that Getopt will not handle a --foo param, but your
71             code can still call the C method.
72              
73             If your class also uses a configfile-loading role based on
74             L, such as L,
75             L's C will load the configfile
76             specified by the C<--configfile> option (or the default you've
77             given for the configfile attribute) for you.
78              
79             Options specified in multiple places follow the following
80             precedence order: commandline overrides configfile, which
81             overrides explicit new_with_options parameters.
82              
83             =head2 Supported Type Constraints
84              
85             =over 4
86              
87             =item I
88              
89             A I type constraint is set up as a boolean option with
90             Getopt::Long. So that this attribute description:
91              
92             has 'verbose' => (is => 'rw', isa => 'Bool');
93              
94             would translate into C as a Getopt::Long option descriptor,
95             which would enable the following command line options:
96              
97             % my_script.pl --verbose
98             % my_script.pl --noverbose
99              
100             =item I, I, I
101              
102             These type constraints are set up as properly typed options with
103             Getopt::Long, using the C<=i>, C<=f> and C<=s> modifiers as appropriate.
104              
105             =item I
106              
107             An I type constraint is set up as a multiple value option
108             in Getopt::Long. So that this attribute description:
109              
110             has 'include' => (
111             is => 'rw',
112             isa => 'ArrayRef',
113             default => sub { [] }
114             );
115              
116             would translate into C as a Getopt::Long option descriptor,
117             which would enable the following command line options:
118              
119             % my_script.pl --include /usr/lib --include /usr/local/lib
120              
121             =item I
122              
123             A I type constraint is set up as a hash value option
124             in Getopt::Long. So that this attribute description:
125              
126             has 'define' => (
127             is => 'rw',
128             isa => 'HashRef',
129             default => sub { {} }
130             );
131              
132             would translate into C as a Getopt::Long option descriptor,
133             which would enable the following command line options:
134              
135             % my_script.pl --define os=linux --define vendor=debian
136              
137             =back
138              
139             =head2 Custom Type Constraints
140              
141             It is possible to create custom type constraint to option spec
142             mappings if you need them. The process is fairly simple (but a
143             little verbose maybe). First you create a custom subtype, like
144             so:
145              
146             subtype 'ArrayOfInts'
147             => as 'ArrayRef'
148             => where { scalar (grep { looks_like_number($_) } @$_) };
149              
150             Then you register the mapping, like so:
151              
152             MouseX::Getopt::OptionTypeMap->add_option_type_to_map(
153             'ArrayOfInts' => '=i@'
154             );
155              
156             Now any attribute declarations using this type constraint will
157             get the custom option spec. So that, this:
158              
159             has 'nums' => (
160             is => 'ro',
161             isa => 'ArrayOfInts',
162             default => sub { [0] }
163             );
164              
165             Will translate to the following on the command line:
166              
167             % my_script.pl --nums 5 --nums 88 --nums 199
168              
169             This example is fairly trivial, but more complex validations are
170             easily possible with a little creativity. The trick is balancing
171             the type constraint validations with the Getopt::Long validations.
172              
173             Better examples are certainly welcome :)
174              
175             =head2 Inferred Type Constraints
176              
177             If you define a custom subtype which is a subtype of one of the
178             standard L above, and do not explicitly
179             provide custom support as in L above,
180             MouseX::Getopt will treat it like the parent type for Getopt
181             purposes.
182              
183             For example, if you had the same custom C subtype
184             from the examples above, but did not add a new custom option
185             type for it to the C, it would be treated just
186             like a normal C type for Getopt purposes (that is,
187             C<=s@>).
188              
189             =over 4
190              
191             =item B
192              
193             This method will take a set of default C<%params> and then collect
194             params from the command line (possibly overriding those in C<%params>)
195             and then return a newly constructed object.
196              
197             The special parameter C, if specified should point to an array
198             reference with an array to use instead of C<@ARGV>.
199              
200             If L fails (due to invalid arguments),
201             C will throw an exception.
202              
203             If L is installed and any of the following
204             command line params are passed, the program will exit with usage
205             information (and the option's state will be stored in the help_flag
206             attribute). You can add descriptions for each option by including a
207             B option for each attribute to document.
208              
209             --?
210             --help
211             --usage
212              
213             If you have L the C param is also passed to
214             C as the usage option.
215              
216             =item B
217              
218             This accessor contains a reference to a copy of the C<@ARGV> array
219             as it originally existed at the time of C.
220              
221             =item B
222              
223             This accessor contains an arrayref of leftover C<@ARGV> elements that
224             L did not parse. Note that the real C<@ARGV> is left
225             un-mangled.
226              
227             =item B
228              
229             This accessor contains the L object (if
230             L is used).
231              
232             =item B
233              
234             This accessor contains the boolean state of the --help, --usage and --?
235             options (true if any of these options were passed on the command line).
236              
237             =item B
238              
239             This returns the role meta object.
240              
241             =back
242              
243             =head1 AUTHORS
244              
245             =over 4
246              
247             =item NAKAGAWA Masaki
248              
249             =item FUJI Goro
250              
251             =item Stevan Little
252              
253             =item Brandon L. Black
254              
255             =item Yuval Kogman
256              
257             =item Ryan D Johnson
258              
259             =item Drew Taylor
260              
261             =item Tomas Doran
262              
263             =item Florian Ragwitz
264              
265             =item Dagfinn Ilmari Mannsaker
266              
267             =item Avar Arnfjord Bjarmason
268              
269             =item Chris Prather
270              
271             =item Mark Gardner
272              
273             =item Tokuhiro Matsuno
274              
275             =back
276              
277             =head1 COPYRIGHT AND LICENSE
278              
279             This software is copyright (c) 2012 by Infinity Interactive, Inc.
280              
281             This is free software; you can redistribute it and/or modify it under
282             the same terms as the Perl 5 programming language system itself.
283              
284             =cut