MooseX::Getopt(3pm)

1MooseX::Getopt(3pm)   User Contributed Perl Documentation  MooseX::Getopt(3pm)
2
3
4

NAME

6       MooseX::Getopt - A Moose role for processing command line options
7

VERSION

9       version 0.74
10

SYNOPSIS

12         ## In your class
13         package My::App;
14         use Moose;
15
16         with 'MooseX::Getopt';
17
18         has 'out' => (is => 'rw', isa => 'Str', required => 1);
19         has 'in'  => (is => 'rw', isa => 'Str', required => 1);
20
21         # ... rest of the class here
22
23         ## in your script
24         #!/usr/bin/perl
25
26         use My::App;
27
28         my $app = My::App->new_with_options();
29         # ... rest of the script here
30
31         ## on the command line
32         % perl my_app_script.pl -in file.input -out file.dump
33

DESCRIPTION

35       This is a role which provides an alternate constructor for creating
36       objects using parameters passed in from the command line.
37

METHODS

39   "new_with_options (%params)"
40       This method will take a set of default %params and then collect
41       parameters from the command line (possibly overriding those in %params)
42       and then return a newly constructed object.
43
44       The special parameter "argv", if specified should point to an array
45       reference with an array to use instead of @ARGV.
46
47       If "GetOptions" in Getopt::Long fails (due to invalid arguments),
48       "new_with_options" will throw an exception.
49
50       If Getopt::Long::Descriptive is installed and any of the following
51       command line parameters are passed, the program will exit with usage
52       information (and the option's state will be stored in the help_flag
53       attribute). You can add descriptions for each option by including a
54       documentation option for each attribute to document.
55
56         -?
57         --?
58         -h
59         --help
60         --usage
61
62       If you have Getopt::Long::Descriptive the "usage" parameter is also
63       passed to "new" as the usage option.
64
65   "ARGV"
66       This accessor contains a reference to a copy of the @ARGV array as it
67       originally existed at the time of "new_with_options".
68
69   "extra_argv"
70       This accessor contains an arrayref of leftover @ARGV elements that
71       Getopt::Long did not parse.  Note that the real @ARGV is left
72       untouched.
73
74       Important: By default, Getopt::Long will reject unrecognized options
75       (that is, options that do not correspond with attributes using the
76       "Getopt" trait). To disable this, and allow options to also be saved in
77       "extra_argv" (for example to pass along to another class's
78       "new_with_options"), you can either enable the "pass_through" option of
79       Getopt::Long for your class:  "use Getopt::Long qw(:config
80       pass_through);" or specify a value for MooseX::Getopt::GLD's
81       "getopt_conf" parameter.
82
83   "usage"
84       This accessor contains the Getopt::Long::Descriptive::Usage object (if
85       Getopt::Long::Descriptive is used).
86
87   "help_flag"
88       This accessor contains the boolean state of the --help, --usage and --?
89       options (true if any of these options were passed on the command line).
90
91   "print_usage_text"
92       This method is called internally when the "help_flag" state is true.
93       It prints the text from the "usage" object (see above) to "STDOUT" (and
94       then after this method is called, the program terminates normally).
95       You can apply a method modification (see
96       Moose::Manual::MethodModifiers) if different behaviour is desired, for
97       example to include additional text.
98
99   "meta"
100       This returns the role meta object.
101
102   "process_argv (%params)"
103       This does most of the work of "new_with_options", analyzing the
104       parameters and "argv", except for actually calling the constructor. It
105       returns a MooseX::Getopt::ProcessedArgv object. "new_with_options" uses
106       this method internally, so modifying this method via subclasses/roles
107       will affect "new_with_options".
108
109       This module attempts to DWIM as much as possible with the command line
110       parameters by introspecting your class's attributes. It will use the
111       name of your attribute as the command line option, and if there is a
112       type constraint defined, it will configure Getopt::Long to handle the
113       option accordingly.
114
115       You can use the trait MooseX::Getopt::Meta::Attribute::Trait or the
116       attribute metaclass MooseX::Getopt::Meta::Attribute to get non-default
117       command-line option names and aliases.
118
119       You can use the trait MooseX::Getopt::Meta::Attribute::Trait::NoGetopt
120       or the attribute metaclass MooseX::Getopt::Meta::Attribute::NoGetopt to
121       have "MooseX::Getopt" ignore your attribute in the command-line
122       options.
123
124       By default, attributes which start with an underscore are not given
125       command-line argument support, unless the attribute's metaclass is set
126       to MooseX::Getopt::Meta::Attribute. If you don't want your accessors to
127       have the leading underscore in their name, you can do this:
128
129         # for read/write attributes
130         has '_foo' => (accessor => 'foo', ...);
131
132         # or for read-only attributes
133         has '_bar' => (reader => 'bar', ...);
134
135       This will mean that MooseX::Getopt will not handle a --foo parameter,
136       but your code can still call the "foo" method.
137
138       If your class also uses a configfile-loading role based on
139       MooseX::ConfigFromFile, such as MooseX::SimpleConfig, MooseX::Getopt's
140       "new_with_options" will load the configfile specified by the
141       "--configfile" option (or the default you've given for the configfile
142       attribute) for you.
143
144       Options specified in multiple places follow the following precedence
145       order: command-line overrides configfile, which overrides explicit
146       new_with_options parameters.
147
148   Supported Type Constraints
149       Bool
150           A Bool type constraint is set up as a boolean option with
151           Getopt::Long. So that this attribute description:
152
153             has 'verbose' => (is => 'rw', isa => 'Bool');
154
155           would translate into "verbose!" as a Getopt::Long option
156           descriptor, which would enable the following command line options:
157
158             % my_script.pl --verbose
159             % my_script.pl --noverbose
160
161       Int, Float, Str
162           These type constraints are set up as properly typed options with
163           Getopt::Long, using the "=i", "=f" and "=s" modifiers as
164           appropriate.
165
166       ArrayRef
167           An ArrayRef type constraint is set up as a multiple value option in
168           Getopt::Long. So that this attribute description:
169
170             has 'include' => (
171                 is      => 'rw',
172                 isa     => 'ArrayRef',
173                 default => sub { [] }
174             );
175
176           would translate into "includes=s@" as a Getopt::Long option
177           descriptor, which would enable the following command line options:
178
179             % my_script.pl --include /usr/lib --include /usr/local/lib
180
181       HashRef
182           A HashRef type constraint is set up as a hash value option in
183           Getopt::Long. So that this attribute description:
184
185             has 'define' => (
186                 is      => 'rw',
187                 isa     => 'HashRef',
188                 default => sub { {} }
189             );
190
191           would translate into "define=s%" as a Getopt::Long option
192           descriptor, which would enable the following command line options:
193
194             % my_script.pl --define os=linux --define vendor=debian
195
196   Custom Type Constraints
197       It is possible to create custom type constraint to option spec mappings
198       if you need them. The process is fairly simple (but a little verbose
199       maybe). First you create a custom subtype, like so:
200
201         subtype 'ArrayOfInts'
202             => as 'ArrayRef'
203             => where { scalar (grep { looks_like_number($_) } @$_)  };
204
205       Then you register the mapping, like so:
206
207         MooseX::Getopt::OptionTypeMap->add_option_type_to_map(
208             'ArrayOfInts' => '=i@'
209         );
210
211       Now any attribute declarations using this type constraint will get the
212       custom option spec. So that, this:
213
214         has 'nums' => (
215             is      => 'ro',
216             isa     => 'ArrayOfInts',
217             default => sub { [0] }
218         );
219
220       Will translate to the following on the command line:
221
222         % my_script.pl --nums 5 --nums 88 --nums 199
223
224       This example is fairly trivial, but more complex validations are easily
225       possible with a little creativity. The trick is balancing the type
226       constraint validations with the Getopt::Long validations.
227
228       Better examples are certainly welcome :)
229
230   Inferred Type Constraints
231       If you define a custom subtype which is a subtype of one of the
232       standard "Supported Type Constraints" above, and do not explicitly
233       provide custom support as in "Custom Type Constraints" above,
234       MooseX::Getopt will treat it like the parent type for Getopt purposes.
235
236       For example, if you had the same custom "ArrayOfInts" subtype from the
237       examples above, but did not add a new custom option type for it to the
238       "OptionTypeMap", it would be treated just like a normal "ArrayRef" type
239       for Getopt purposes (that is, "=s@").
240
241   More Customization Options
242       See "Configuring Getopt::Long" in Getopt::Long for many other
243       customizations you can make to how options are parsed. Simply "use
244       Getopt::Long qw(:config other_options...)" in your class to set these.
245
246       Note in particular that the default setting for case sensitivity has
247       changed over time in Getopt::Long::Descriptive, so if you rely on a
248       particular setting, you should set it explicitly, or enforce the
249       version of Getopt::Long::Descriptive that you install.
250

SUPPORT

258       Bugs may be submitted through the RT bug tracker
259       <https://rt.cpan.org/Public/Dist/Display.html?Name=MooseX-Getopt> (or
260       bug-MooseX-Getopt@rt.cpan.org <mailto:bug-MooseX-Getopt@rt.cpan.org>).
261
262       There is also a mailing list available for users of this distribution,
263       at <http://lists.perl.org/list/moose.html>.
264
265       There is also an irc channel available for users of this distribution,
266       at "#moose" on "irc.perl.org" <irc://irc.perl.org/#moose>.
267

AUTHOR

269       Stevan Little <stevan@iinteractive.com>
270

CONTRIBUTORS

272       ·   Karen Etheridge <ether@cpan.org>
273
274       ·   Tomas Doran <bobtfish@bobtfish.net>
275
276       ·   Stevan Little <stevan.little@iinteractive.com>
277
278       ·   Yuval Kogman <nothingmuch@woobling.org>
279
280       ·   Florian Ragwitz <rafl@debian.org>
281
282       ·   Brandon L Black <blblack@gmail.com>
283
284       ·   Shlomi Fish <shlomif@cpan.org>
285
286       ·   Hans Dieter Pearcey <hdp@weftsoar.net>
287
288       ·   Olaf Alders <olaf@wundersolutions.com>
289
290       ·   Nelo Onyiah <nelo.onyiah@gmail.com>
291
292       ·   Ryan D Johnson <ryan@innerfence.com>
293
294       ·   Dave Rolsky <autarch@urth.org>
295
296       ·   Ricardo SIGNES <rjbs@cpan.org>
297
298       ·   AEvar Arnfjoerd` Bjarmason <avarab@gmail.com>
299
300       ·   Hinrik Oern Sigurd`sson <hinrik.sig@gmail.com>
301
302       ·   Damien Krotkine <dkrotkine@weborama.com>
303
304       ·   Todd Hepler <thepler@employees.org>
305
306       ·   Devin Austin <dhoss@cpan.org>
307
308       ·   Jose Luis Martinez <jlmartinez@capside.com>
309
310       ·   Gregory Oschwald <goschwald@maxmind.com>
311
312       ·   Chris Prather <chris@prather.org>
313
314       ·   Jonathan Swartz <swartz@pobox.com>
315
316       ·   Andreas Koenig <Andreas.Koenig.extern@telecolumbus.de>
317
318       ·   Dagfinn Ilmari Mannsaaker <ilmari@ilmari.org>
319
320       ·   Damyan Ivanov <dmn@debian.org>
321
322       ·   Drew Taylor <drew@drewtaylor.com>
323
324       ·   Gordon Irving <goraxe@goraxe.me.uk>
325
326       ·   Jesse Luehrs <doy@tozt.net>
327
328       ·   John Goulah <jgoulah@cpan.org>
329
330       ·   Andreas Koenig <andk@cpan.org>
331
332       ·   Justin Hunter <justin.d.hunter@gmail.com>
333
334       ·   Michael Schout <mschout@gkg.net>
335
336       ·   Shlomi Fish <shlomif@shlomifish.org>
337
338       ·   Stevan Little <stevan.little@gmail.com>
339
340       ·   Stuart A Johnston <saj_git@thecommune.net>
341

COPYRIGHT AND LICENSE

343       This software is copyright (c) 2007 by Infinity Interactive, Inc.
344
345       This is free software; you can redistribute it and/or modify it under
346       the same terms as the Perl 5 programming language system itself.
347
348
349
350perl v5.32.0                      2020-07-28               MooseX::Getopt(3pm)