1MooX::Options(3) User Contributed Perl Documentation MooX::Options(3)
2
6 MooX::Options - Explicit Options eXtension for Object Class
7
9 In myOptions.pm :
10 package myOptions;
12 use Moo;
13 use MooX::Options;
14 option 'show_this_file' => (
16 is => 'ro',
17 format => 's',
18 required => 1,
19 doc => 'the file to display'
20 );
21 1;
22 In myTool.pl :
24 use myOptions;
26 use Path::Class;
27 my $opt = myOptions->new_with_options;
29 print "Content of the file : ",
31 file($opt->show_this_file)->slurp;
32 To use it :
34 perl myTool.pl --show_this_file=myFile.txt
36 Content of the file: myFile content
37 The help message :
39 perl myTool.pl --help
41 USAGE: myTool.pl [-h] [long options...]
42 --show_this_file: String
44 the file to display
45 -h --help:
47 show this help message
48 --man:
50 show the manual
51 The usage message :
53 perl myTool.pl --usage
55 USAGE: myTool.pl [ --show_this_file=String ] [ --usage ] [ --help ] [ --man ]
56 The manual :
58 perl myTool.pl --man
60
62 Create a command line tool with your Moo, Moose objects.
63 Everything is explicit. You have an "option" keyword to replace the
65 usual "has" to explicitly use your attribute into the command line.
66 The "option" keyword takes additional parameters and uses
68 Getopt::Long::Descriptive to generate a command line tool.
69
71 Enhancing existing attributes
72 One can now convert an existing attribute into an option for obvious
73 reasons.
74 package CommonRole;
76 use Moo::Role;
78 has attr => (is => "ro", ...);
80 sub common_logic { ... }
82 1;
84 package Suitable::Cmd::CLI;
86 use Moo;
88 use MooX::Cmd;
89 use MooX::Options;
90 with "CommonRole";
92 option '+attr' => (format => 's', repeatable => 1);
94 sub execute { shift->common_logic }
96 1;
98 package Suitable::Web::Request::Handler;
100 use Moo;
102 with "CommonRole";
104 sub all_suits { shift->common_logic }
106 1;
108 package Suitable::Web;
110 use Dancer2;
112 use Suitable::Web::Request::Handler;
113 set serializer => "JSON";
115 get '/suits' => sub {
117 $my $reqh = Suitable::Web::Request::Handler->new( attr => config->{suit_attr} );
118 $reqh->all_suits;
119 };
120 dance;
122 1;
124 Of course there more ways to to it, Jedi or Catalyst shall be fine,
126 either.
127 Rename negativable into negatable
129 Since users stated that "negativable" is not a reasonable word, the
130 flag is renamed into negatable. Those who will 2020 continue use
131 negativable might or might not be warned about soon depreciation.
132 Replace Locale::TextDomain by MooX::Locale::Passthrough
134 Locale::TextDomain is broken (technically and functionally) and causes
135 a lot of people to avoid "MooX::Options" or hack around. Both is
136 unintened.
137 So introduce MooX::Locale::Passthrough to allow any vendor to add
139 reasonable localization, eg. by composing MooX::Locale::TextDomain::OO
140 into it's solution and initialize the localization in a reasonable way.
141 Make lazy loaded features optional
143 Since some features aren't used on a regular basis, their dependencies
144 have been downgraded to "recommended" or "suggested". The optional
145 features are:
146 autosplit
148 This feature allowes one to split option arguments at a defined
149 character and always return an array (implicit flag "repeatable").
150 option "search_path" => ( is => "ro", required => 1, autosplit => ":", format => "s" );
152 However, this feature requires following modules are provided:
154 • Data::Record
156 • Regexp::Common
158 json format
160 This feature allowes one to invoke a script like
161 $ my-tool --json-attr '{ "gem": "sapphire", "color": "blue" }'
163 It might be a reasonable enhancement to handles.
165 Handling JSON formatted arguments requires any of those modules are
167 loded:
168 • JSON::MaybeXS
170 • JSON::PP (in Core since 5.14).
172 Decouple autorange and autosplit
174 Until 4.023, any option which had autorange enabled got autosplit
175 enabled, too. Since autosplit might not work correctly and for a
176 reasonable amount of users the fact of
177 $ my-tool --range 1..5
179 is all they desire, autosplit will enabled only when the dependencies
181 of autosplit are fulfilled.
182
184 The list of the methods automatically imported into your class.
185 new_with_options
187 It will parse your command line params and your inline params, validate
188 and call the "new" method.
189 myTool --str=ko
191 t->new_with_options()->str # ko
193 t->new_with_options(str => 'ok')->str #ok
194 option
196 The "option" keyword replaces the "has" method and adds support for
197 special options for the command line only.
198 See "OPTION PARAMETERS" for the documentation.
200 options_usage | --help
202 It displays the usage message and returns the exit code.
203 my $t = t->new_with_options();
205 my $exit_code = 1;
206 my $pre_message = "str is not valid";
207 $t->options_usage($exit_code, $pre_message);
208 This method is also automatically fired if the command option "--help"
210 is passed.
211 myTool --help
213 options_man | --man
215 It displays the manual.
216 my $t = t->new_with_options();
218 $t->options_man();
219 This is automatically fired if the command option "--man" is passed.
221 myTool --man
223 options_short_usage | --usage
225 It displays a short version of the help message.
226 my $t = t->new_with_options();
228 $t->options_short_usage($exit_code);
229 This is automatically fired if the command option "--usage" is passed.
231 myTool --usage
233
235 The list of parameters supported by MooX::Options.
236 flavour
238 Passes extra arguments for Getopt::Long::Descriptive. It is useful if
239 you want to configure Getopt::Long.
240 use MooX::Options flavour => [qw( pass_through )];
242 Any flavour is passed to Getopt::Long as a configuration, check the doc
244 to see what is possible.
245 protect_argv
247 By default, @ARGV is protected. If you want to do something else on it,
248 use this option and it will change the real @ARGV.
249 use MooX::Options protect_argv => 0;
251 skip_options
253 If you have Role with options and you want to deactivate some of them,
254 you can use this parameter. In that case, the "option" keyword will
255 just work like an "has".
256 use MooX::Options skip_options => [qw/multi/];
258 prefer_commandline
260 By default, arguments passed to "new_with_options" have a higher
261 priority than the command line options.
262 This parameter will give the command line an higher priority.
264 use MooX::Options prefer_commandline => 1;
266 with_config_from_file
268 This parameter will load MooX::Options in your module. The config
269 option will be used between the command line and parameters.
270 myTool :
272 use MooX::Options with_config_from_file => 1;
274 In /etc/myTool.json
276 {"test" : 1}
278 with_locale_textdomain_oo
280 This Parameter will load MooX::Locale::TextDomain::OO into your module
281 as well as into MooX::Options::Descriptive::Usage.
282 No further action is taken, no language is chosen - everything keep in
284 control.
285 Please read Locale::TextDomain::OO carefully how to enable the desired
287 translation setup accordingly.
288
290 This parameter is passed to
291 Getopt::Long::Descriptive::describe_options() as the first parameter.
292 It is a "sprintf"-like string that is used in generating the first line
294 of the usage message. It's a one-line summary of how the command is to
295 be invoked. The default value is "USAGE: %c %o".
296 %c will be replaced with what Getopt::Long::Descriptive thinks is the
298 program name (it's computed from $0, see "prog_name").
299 %o will be replaced with a list of the short options, as well as the
301 text "[long options...]" if any have been defined.
302 The rest of the usage description can be used to summarize what
304 arguments are expected to follow the program's options, and is entirely
305 free-form.
306 Literal "%" characters will need to be written as "%%", just like with
308 "sprintf".
309 spacer
311 This indicate the char to use for spacer. Please only use 1 char
312 otherwize the text will be too long.
313 The default char is " ".
315 use MooX::Options space => '+'
317 Then the "spacer_before" and "spacer_after" will use it for "man" and
319 "help" message.
320 option 'x' => (is => 'ro', spacer_before => 1, spacer_after => 1);
322
324 The keyword "option" extend the keyword "has" with specific parameters
325 for the command line.
326 doc | documentation
328 Documentation for the command line option.
329 long_doc
331 Documentation for the man page. By default the "doc" parameter will be
332 used.
333 See also Man parameters to get more examples how to build a nice man
335 page.
336 required
338 This attribute indicates that the parameter is mandatory. This
339 attribute is not really used by MooX::Options but ensures that
340 consistent error message will be displayed.
341 format
343 Format of the params, same as Getopt::Long::Descriptive.
344 • i : integer
346 • i@: array of integer
348 • s : string
350 • s@: array of string
352 • f : float value
354 By default, it's a boolean value.
356 Take a look of available formats with Getopt::Long::Descriptive.
358 You need to understand that everything is explicit here. If you use
360 Moose and your attribute has "isa => 'Array[Int]'", that will not imply
361 the format "i@".
362 format json : special format support
364 The parameter will be treated like a json string.
365 option 'hash' => (is => 'ro', json => 1);
367 You can also use the json format
369 option 'hash' => (is => 'ro', format => "json");
371 myTool --hash='{"a":1,"b":2}' # hash = { a => 1, b => 2 }
373 negatable
375 It adds the negative version for the option.
376 option 'verbose' => (is => 'ro', negatable => 1);
378 myTool --verbose # verbose = 1
380 myTool --no-verbose # verbose = 0
381 The former name of this flag, negativable, is discouraged - since it's
383 not a word.
384 repeatable
386 It appends to the "format" the array attribute "@".
387 I advise to add a default value to your attribute to always have an
389 array. Otherwise the default value will be an undefined value.
390 option foo => (is => 'rw', format => 's@', default => sub { [] });
392 myTool --foo="abc" --foo="def" # foo = ["abc", "def"]
394 autosplit
396 For repeatable option, you can add the autosplit feature with your
397 specific parameters.
398 option test => (is => 'ro', format => 'i@', default => sub {[]}, autosplit => ',');
400 myTool --test=1 --test=2 # test = (1, 2)
402 myTool --test=1,2,3 # test = (1, 2, 3)
403 It will also handle quoted params with the autosplit.
405 option testStr => (is => 'ro', format => 's@', default => sub {[]}, autosplit => ',');
407 myTool --testStr='a,b,"c,d",e,f' # testStr ("a", "b", "c,d", "e", "f")
409 autorange
411 For another repeatable option you can add the autorange feature with
412 your specific parameters. This allows you to pass number ranges instead
413 of passing each individual number.
414 option test => (is => 'ro', format => 'i@', default => sub {[]}, autorange => 1);
416 myTool --test=1 --test=2 # test = (1, 2)
418 myTool --test=1,2,3 # test = (1, 2, 3)
419 myTool --test=1,2,3..6 # test = (1, 2, 3, 4, 5, 6)
420 It will also handle quoted params like "autosplit", and will not
422 rangify them.
423 option testStr => (is => 'ro', format => 's@', default => sub {[]}, autorange => 1);
425 myTool --testStr='1,2,"3,a,4",5' # testStr (1, 2, "3,a,4", 5)
427 "autosplit" will be set to ',' if undefined. You may set "autosplit" to
429 a different delimiter than ',' for your group separation, but the range
430 operator '..' cannot be changed.
431 option testStr => (is => 'ro', format => 's@', default => sub {[]}, autorange => 1, autosplit => '-');
433 myTool --testStr='1-2-3-5..7' # testStr (1, 2, 3, 5, 6, 7)
435 short
437 Long option can also have short version or aliased.
438 option 'verbose' => (is => 'ro', short => 'v');
440 myTool --verbose # verbose = 1
442 myTool -v # verbose = 1
443 option 'account_id' => (is => 'ro', format => 'i', short => 'a|id');
445 myTool --account_id=1
447 myTool -a=1
448 myTool --id=1
449 You can also use a shorter option without attribute :
451 option 'account_id' => (is => 'ro', format => 'i');
453 myTool --acc=1
455 myTool --account=1
456 order
458 Specifies the order of the attribute. If you want to push some
459 attributes at the end of the list. By default all options have an
460 order set to 0, and options are sorted by their names.
461 option 'at_the_end' => (is => 'ro', order => 999);
463 hidden
465 Hide option from doc but still an option you can use on command line.
466 option 'debug' => (is => 'ro', doc => 'hidden');
468 Or
470 option 'debug' => (is => 'ro', hidden => 1);
472 spacer_before, spacer_after
474 Add spacer before or after or both the params
475 option 'myoption' => (is => 'ro', spacer_before => 1, spacer_after => 1);
477
479 MooX::Options and Mo
480 "MooX::Options" is implemented as a frontend loader class and the real
481 magic provided by a role composed into the caller by
482 "MooX::Options::import".
483 Since some required features ("with", "around") isn't provided by Mo,
485 Class::Method::Modifiers must be loaded by any "Mo" class using
486 "MooX::Options", Role::Tiny::With is needed to inject the
487 MooX::Options::Role and finally in the target package the private
488 accessors to options_config and options_data are missing.
489 Concluding a reasonable support for Mo based classes is beyond the goal
491 of this module. It's neither forbidden nor actively prevented, but
492 won't be covered by any test nor actively supported.
493 If someome wants contribute guides how to use "MooX::Options" together
495 with "Mo" or provide patches to solve this limitation - any support
496 will granted.
497
499 • Man parameters
500 • Using namespace::clean
502 • Manage your tools with MooX::Cmd
504
506 • Slide3D about MooX::Options
507 <http://perltalks.celogeek.com/slides/2012/08/moox-options-
508 slide3d.html>
509
511 Translation is now supported.
512 Use the dzil command to update the pot and merge into the po files.
514 • dzil msg-init
516 Create a new language po
518 • dzil msg-scan
520 Scan and generate or update the pot file
522 • dzil msg-merge
524 Update all languages using the pot file
526 THANKS
528 • sschober
529 For implementation and German translation.
531
533 • Matt S. Trout (mst) <mst@shadowcat.co.uk>
534 For his patience and advice.
536 • Tomas Doran (t0m) <bobtfish@bobtfish.net>
538 To help me release the new version, and using it :)
540 • Torsten Raudssus (Getty)
542 to use it a lot in DuckDuckGo <http://duckduckgo.com> (go to see
544 MooX module also)
545 • Jens Rehsack (REHSACK)
547 Use with PkgSrc <http://www.pkgsrc.org/>, and many really good idea
549 (MooX::Cmd, MooX::Options, and more to come I'm sure)
550 • All contributors
552 For improving and add more feature to MooX::Options
554
556 You can find documentation for this module with the perldoc command.
557 perldoc MooX::Options
559 You can also look for information at:
561 • RT: CPAN's request tracker (report bugs here)
563 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=MooX-Options>
565 • AnnoCPAN: Annotated CPAN documentation
567 <http://annocpan.org/dist/MooX-Options>
569 • CPAN Ratings
571 <http://cpanratings.perl.org/d/MooX-Options>
573 • Search CPAN
575 <http://search.cpan.org/dist/MooX-Options/>
577
579 celogeek <me@celogeek.com>
580
582 This software is copyright (c) 2013 by celogeek <me@celogeek.com>.
583 This software is copyright (c) 2017 by Jens Rehsack.
585 This is free software; you can redistribute it and/or modify it under
587 the same terms as the Perl 5 programming language system itself.
588perl v5.34.0 2021-07-22 MooX::Options(3)