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

SYNOPSIS

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

DESCRIPTION

29       This is a role which provides an alternate constructor for creating
30       objects using parameters passed in from the command line.
31
32       This module attempts to DWIM as much as possible with the command line
33       params by introspecting your class's attributes. It will use the name
34       of your attribute as the command line option, and if there is a type
35       constraint defined, it will configure Getopt::Long to handle the option
36       accordingly.
37
38       You can use the trait MouseX::Getopt::Meta::Attribute::Trait or the
39       attribute metaclass MouseX::Getopt::Meta::Attribute to get non-default
40       commandline option names and aliases.
41
42       You can use the trait MouseX::Getopt::Meta::Attribute::Trait::NoGetopt
43       or the attribute metaclass MouseX::Getopt::Meta::Attribute::NoGetopt to
44       have "MouseX::Getopt" ignore your attribute in the commandline options.
45
46       By default, attributes which start with an underscore are not given
47       commandline argument support, unless the attribute's metaclass is set
48       to MouseX::Getopt::Meta::Attribute. If you don't want your accessors to
49       have the leading underscore in their name, you can do this:
50
51         # for read/write attributes
52         has '_foo' => (accessor => 'foo', ...);
53
54         # or for read-only attributes
55         has '_bar' => (reader => 'bar', ...);
56
57       This will mean that Getopt will not handle a --foo param, but your code
58       can still call the "foo" method.
59
60       If your class also uses a configfile-loading role based on
61       MouseX::ConfigFromFile, such as MouseX::SimpleConfig, MouseX::Getopt's
62       "new_with_options" will load the configfile specified by the
63       "--configfile" option (or the default you've given for the configfile
64       attribute) for you.
65
66       Options specified in multiple places follow the following precedence
67       order: commandline overrides configfile, which overrides explicit
68       new_with_options parameters.
69
70   Supported Type Constraints
71       Bool
72           A Bool type constraint is set up as a boolean option with
73           Getopt::Long. So that this attribute description:
74
75             has 'verbose' => (is => 'rw', isa => 'Bool');
76
77           would translate into "verbose!" as a Getopt::Long option
78           descriptor, which would enable the following command line options:
79
80             % my_script.pl --verbose
81             % my_script.pl --noverbose
82
83       Int, Float, Str
84           These type constraints are set up as properly typed options with
85           Getopt::Long, using the "=i", "=f" and "=s" modifiers as
86           appropriate.
87
88       ArrayRef
89           An ArrayRef type constraint is set up as a multiple value option in
90           Getopt::Long. So that this attribute description:
91
92             has 'include' => (
93                 is      => 'rw',
94                 isa     => 'ArrayRef',
95                 default => sub { [] }
96             );
97
98           would translate into "includes=s@" as a Getopt::Long option
99           descriptor, which would enable the following command line options:
100
101             % my_script.pl --include /usr/lib --include /usr/local/lib
102
103       HashRef
104           A HashRef type constraint is set up as a hash value option in
105           Getopt::Long. So that this attribute description:
106
107             has 'define' => (
108                 is      => 'rw',
109                 isa     => 'HashRef',
110                 default => sub { {} }
111             );
112
113           would translate into "define=s%" as a Getopt::Long option
114           descriptor, which would enable the following command line options:
115
116             % my_script.pl --define os=linux --define vendor=debian
117
118   Custom Type Constraints
119       It is possible to create custom type constraint to option spec mappings
120       if you need them. The process is fairly simple (but a little verbose
121       maybe). First you create a custom subtype, like so:
122
123         subtype 'ArrayOfInts'
124             => as 'ArrayRef'
125             => where { scalar (grep { looks_like_number($_) } @$_)  };
126
127       Then you register the mapping, like so:
128
129         MouseX::Getopt::OptionTypeMap->add_option_type_to_map(
130             'ArrayOfInts' => '=i@'
131         );
132
133       Now any attribute declarations using this type constraint will get the
134       custom option spec. So that, this:
135
136         has 'nums' => (
137             is      => 'ro',
138             isa     => 'ArrayOfInts',
139             default => sub { [0] }
140         );
141
142       Will translate to the following on the command line:
143
144         % my_script.pl --nums 5 --nums 88 --nums 199
145
146       This example is fairly trivial, but more complex validations are easily
147       possible with a little creativity. The trick is balancing the type
148       constraint validations with the Getopt::Long validations.
149
150       Better examples are certainly welcome :)
151
152   Inferred Type Constraints
153       If you define a custom subtype which is a subtype of one of the
154       standard "Supported Type Constraints" above, and do not explicitly
155       provide custom support as in "Custom Type Constraints" above,
156       MouseX::Getopt will treat it like the parent type for Getopt purposes.
157
158       For example, if you had the same custom "ArrayOfInts" subtype from the
159       examples above, but did not add a new custom option type for it to the
160       "OptionTypeMap", it would be treated just like a normal "ArrayRef" type
161       for Getopt purposes (that is, "=s@").
162
163       new_with_options (%params)
164           This method will take a set of default %params and then collect
165           params from the command line (possibly overriding those in %params)
166           and then return a newly constructed object.
167
168           The special parameter "argv", if specified should point to an array
169           reference with an array to use instead of @ARGV.
170
171           If "GetOptions" in Getopt::Long fails (due to invalid arguments),
172           "new_with_options" will throw an exception.
173
174           If Getopt::Long::Descriptive is installed and any of the following
175           command line params are passed, the program will exit with usage
176           information (and the option's state will be stored in the help_flag
177           attribute). You can add descriptions for each option by including a
178           documentation option for each attribute to document.
179
180             --?
181             --help
182             --usage
183
184           If you have Getopt::Long::Descriptive the "usage" param is also
185           passed to "new" as the usage option.
186
187       ARGV
188           This accessor contains a reference to a copy of the @ARGV array as
189           it originally existed at the time of "new_with_options".
190
191       extra_argv
192           This accessor contains an arrayref of leftover @ARGV elements that
193           Getopt::Long did not parse.  Note that the real @ARGV is left un-
194           mangled.
195
196       usage
197           This accessor contains the Getopt::Long::Descriptive::Usage object
198           (if Getopt::Long::Descriptive is used).
199
200       help_flag
201           This accessor contains the boolean state of the --help, --usage and
202           --?  options (true if any of these options were passed on the
203           command line).
204
205       meta
206           This returns the role meta object.
207

AUTHORS

209       NAKAGAWA Masaki <masaki@cpan.org>
210       FUJI Goro <gfuji@cpan.org>
211       Stevan Little <stevan@iinteractive.com>
212       Brandon L. Black <blblack@gmail.com>
213       Yuval Kogman <nothingmuch@woobling.org>
214       Ryan D Johnson <ryan@innerfence.com>
215       Drew Taylor <drew@drewtaylor.com>
216       Tomas Doran <bobtfish@bobtfish.net>
217       Florian Ragwitz <rafl@debian.org>
218       Dagfinn Ilmari Mannsaker <ilmari@ilmari.org>
219       Avar Arnfjord Bjarmason <avar@cpan.org>
220       Chris Prather <perigrin@cpan.org>
221       Mark Gardner <mjgardner@cpan.org>
222       Tokuhiro Matsuno <tokuhirom@cpan.org>
223
225       This software is copyright (c) 2012 by Infinity Interactive, Inc.
226
227       This is free software; you can redistribute it and/or modify it under
228       the same terms as the Perl 5 programming language system itself.
229
230
231
232perl v5.34.0                      2021-07-22               MouseX::Getopt(3pm)
Impressum