1MooX::Options(3)      User Contributed Perl Documentation     MooX::Options(3)
2
3
4

NAME

6       MooX::Options - Explicit Options eXtension for Object Class
7

SYNOPSIS

9       In myOptions.pm :
10
11         package myOptions;
12         use Moo;
13         use MooX::Options;
14
15         option 'show_this_file' => (
16             is => 'ro',
17             format => 's',
18             required => 1,
19             doc => 'the file to display'
20         );
21         1;
22
23       In myTool.pl :
24
25         use myOptions;
26         use Path::Class;
27
28         my $opt = myOptions->new_with_options;
29
30         print "Content of the file : ",
31              file($opt->show_this_file)->slurp;
32
33       To use it :
34
35         perl myTool.pl --show_this_file=myFile.txt
36         Content of the file: myFile content
37
38       The help message :
39
40         perl myTool.pl --help
41         USAGE: myTool.pl [-h] [long options...]
42
43             --show_this_file: String
44                 the file to display
45
46             -h --help:
47                 show this help message
48
49             --man:
50                 show the manual
51
52       The usage message :
53
54         perl myTool.pl --usage
55         USAGE: myTool.pl [ --show_this_file=String ] [ --usage ] [ --help ] [ --man ]
56
57       The manual :
58
59         perl myTool.pl --man
60

DESCRIPTION

62       Create a command line tool with your Moo, Moose objects.
63
64       Everything is explicit. You have an "option" keyword to replace the
65       usual "has" to explicitly use your attribute into the command line.
66
67       The "option" keyword takes additional parameters and uses
68       Getopt::Long::Descriptive to generate a command line tool.
69

IMPORTANT CHANGES IN 4.100

71   Enhancing existing attributes
72       One can now convert an existing attribute into an option for obvious
73       reasons.
74
75         package CommonRole;
76
77         use Moo::Role;
78
79         has attr => (is => "ro", ...);
80
81         sub common_logic { ... }
82
83         1;
84
85         package Suitable::Cmd::CLI;
86
87         use Moo;
88         use MooX::Cmd;
89         use MooX::Options;
90
91         with "CommonRole";
92
93         option '+attr' => (format => 's', repeatable => 1);
94
95         sub execute { shift->common_logic }
96
97         1;
98
99         package Suitable::Web::Request::Handler;
100
101         use Moo;
102
103         with "CommonRole";
104
105         sub all_suits { shift->common_logic }
106
107         1;
108
109         package Suitable::Web;
110
111         use Dancer2;
112         use Suitable::Web::Request::Handler;
113
114         set serializer => "JSON";
115
116         get '/suits' => sub {
117             $my $reqh = Suitable::Web::Request::Handler->new( attr => config->{suit_attr} );
118             $reqh->all_suits;
119         };
120
121         dance;
122
123         1;
124
125       Of course there more ways to to it, Jedi or Catalyst shall be fine,
126       either.
127
128   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
133   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
138       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
142   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
147       autosplit
148           This feature allowes one to split option arguments at a defined
149           character and always return an array (implicit flag "repeatable").
150
151             option "search_path" => ( is => "ro", required => 1, autosplit => ":", format => "s" );
152
153           However, this feature requires following modules are provided:
154
155           •   Data::Record
156
157           •   Regexp::Common
158
159       json format
160           This feature allowes one to invoke a script like
161
162             $ my-tool --json-attr '{ "gem": "sapphire", "color": "blue" }'
163
164           It might be a reasonable enhancement to handles.
165
166           Handling JSON formatted arguments requires any of those modules are
167           loded:
168
169           •   JSON::MaybeXS
170
171           •   JSON::PP (in Core since 5.14).
172
173   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
178         $ my-tool --range 1..5
179
180       is all they desire, autosplit will enabled only when the dependencies
181       of autosplit are fulfilled.
182

IMPORTED METHODS

184       The list of the methods automatically imported into your class.
185
186   new_with_options
187       It will parse your command line params and your inline params, validate
188       and call the "new" method.
189
190         myTool --str=ko
191
192         t->new_with_options()->str # ko
193         t->new_with_options(str => 'ok')->str #ok
194
195   option
196       The "option" keyword replaces the "has" method and adds support for
197       special options for the command line only.
198
199       See "OPTION PARAMETERS" for the documentation.
200
201   options_usage | --help
202       It displays the usage message and returns the exit code.
203
204         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
209       This method is also automatically fired if the command option "--help"
210       is passed.
211
212         myTool --help
213
214   options_man | --man
215       It displays the manual.
216
217         my $t = t->new_with_options();
218         $t->options_man();
219
220       This is automatically fired if the command option "--man" is passed.
221
222         myTool --man
223
224   options_short_usage | --usage
225       It displays a short version of the help message.
226
227         my $t = t->new_with_options();
228         $t->options_short_usage($exit_code);
229
230       This is automatically fired if the command option "--usage" is passed.
231
232         myTool --usage
233

IMPORT PARAMETERS

235       The list of parameters supported by MooX::Options.
236
237   flavour
238       Passes extra arguments for Getopt::Long::Descriptive. It is useful if
239       you want to configure Getopt::Long.
240
241         use MooX::Options flavour => [qw( pass_through )];
242
243       Any flavour is passed to Getopt::Long as a configuration, check the doc
244       to see what is possible.
245
246   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
250         use MooX::Options protect_argv => 0;
251
252   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
257         use MooX::Options skip_options => [qw/multi/];
258
259   prefer_commandline
260       By default, arguments passed to "new_with_options" have a higher
261       priority than the command line options.
262
263       This parameter will give the command line an higher priority.
264
265         use MooX::Options prefer_commandline => 1;
266
267   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
271       myTool :
272
273         use MooX::Options with_config_from_file => 1;
274
275       In /etc/myTool.json
276
277         {"test" : 1}
278
279   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
283       No further action is taken, no language is chosen - everything keep in
284       control.
285
286       Please read Locale::TextDomain::OO carefully how to enable the desired
287       translation setup accordingly.
288

usage_string

290       This parameter is passed to
291       Getopt::Long::Descriptive::describe_options() as the first parameter.
292
293       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
297       %c will be replaced with what Getopt::Long::Descriptive thinks is the
298       program name (it's computed from $0, see "prog_name").
299
300       %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
303       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
307       Literal "%" characters will need to be written as "%%", just like with
308       "sprintf".
309
310   spacer
311       This indicate the char to use for spacer. Please only use 1 char
312       otherwize the text will be too long.
313
314       The default char is " ".
315
316         use MooX::Options space => '+'
317
318       Then the "spacer_before" and "spacer_after" will use it for "man" and
319       "help" message.
320
321         option 'x' => (is => 'ro', spacer_before => 1, spacer_after => 1);
322

OPTION PARAMETERS

324       The keyword "option" extend the keyword "has" with specific parameters
325       for the command line.
326
327   doc | documentation
328       Documentation for the command line option.
329
330   long_doc
331       Documentation for the man page. By default the "doc" parameter will be
332       used.
333
334       See also Man parameters to get more examples how to build a nice man
335       page.
336
337   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
342   format
343       Format of the params, same as Getopt::Long::Descriptive.
344
345       •   i : integer
346
347       •   i@: array of integer
348
349       •   s : string
350
351       •   s@: array of string
352
353       •   f : float value
354
355       By default, it's a boolean value.
356
357       Take a look of available formats with Getopt::Long::Descriptive.
358
359       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
363   format json : special format support
364       The parameter will be treated like a json string.
365
366         option 'hash' => (is => 'ro', json => 1);
367
368       You can also use the json format
369
370         option 'hash' => (is => 'ro', format => "json");
371
372         myTool --hash='{"a":1,"b":2}' # hash = { a => 1, b => 2 }
373
374   negatable
375       It adds the negative version for the option.
376
377         option 'verbose' => (is => 'ro', negatable => 1);
378
379         myTool --verbose    # verbose = 1
380         myTool --no-verbose # verbose = 0
381
382       The former name of this flag, negativable, is discouraged - since it's
383       not a word.
384
385   repeatable
386       It appends to the "format" the array attribute "@".
387
388       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
391         option foo => (is => 'rw', format => 's@', default => sub { [] });
392
393         myTool --foo="abc" --foo="def" # foo = ["abc", "def"]
394
395   autosplit
396       For repeatable option, you can add the autosplit feature with your
397       specific parameters.
398
399         option test => (is => 'ro', format => 'i@', default => sub {[]}, autosplit => ',');
400
401         myTool --test=1 --test=2 # test = (1, 2)
402         myTool --test=1,2,3      # test = (1, 2, 3)
403
404       It will also handle quoted params with the autosplit.
405
406         option testStr => (is => 'ro', format => 's@', default => sub {[]}, autosplit => ',');
407
408         myTool --testStr='a,b,"c,d",e,f' # testStr ("a", "b", "c,d", "e", "f")
409
410   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
415         option test => (is => 'ro', format => 'i@', default => sub {[]}, autorange => 1);
416
417         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
421       It will also handle quoted params like "autosplit", and will not
422       rangify them.
423
424         option testStr => (is => 'ro', format => 's@', default => sub {[]}, autorange => 1);
425
426         myTool --testStr='1,2,"3,a,4",5' # testStr (1, 2, "3,a,4", 5)
427
428       "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
432         option testStr => (is => 'ro', format => 's@', default => sub {[]}, autorange => 1, autosplit => '-');
433
434         myTool --testStr='1-2-3-5..7' # testStr (1, 2, 3, 5, 6, 7)
435
436   short
437       Long option can also have short version or aliased.
438
439         option 'verbose' => (is => 'ro', short => 'v');
440
441         myTool --verbose # verbose = 1
442         myTool -v        # verbose = 1
443
444         option 'account_id' => (is => 'ro', format => 'i', short => 'a|id');
445
446         myTool --account_id=1
447         myTool -a=1
448         myTool --id=1
449
450       You can also use a shorter option without attribute :
451
452         option 'account_id' => (is => 'ro', format => 'i');
453
454         myTool --acc=1
455         myTool --account=1
456
457   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
462         option 'at_the_end' => (is => 'ro', order => 999);
463
464   hidden
465       Hide option from doc but still an option you can use on command line.
466
467         option 'debug' => (is => 'ro', doc => 'hidden');
468
469       Or
470
471         option 'debug' => (is => 'ro', hidden => 1);
472
473   spacer_before, spacer_after
474       Add spacer before or after or both the params
475
476         option 'myoption' => (is => 'ro', spacer_before => 1, spacer_after => 1);
477

COMPATIBILITY

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
484       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
490       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
494       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

ADDITIONAL MANUALS

499       •   Man parameters
500
501       •   Using namespace::clean
502
503       •   Manage your tools with MooX::Cmd
504

EXTERNAL EXAMPLES

506       •   Slide3D about MooX::Options
507           <http://perltalks.celogeek.com/slides/2012/08/moox-options-
508           slide3d.html>
509

Translation

511       Translation is now supported.
512
513       Use the dzil command to update the pot and merge into the po files.
514
515       •   dzil msg-init
516
517           Create a new language po
518
519       •   dzil msg-scan
520
521           Scan and generate or update the pot file
522
523       •   dzil msg-merge
524
525           Update all languages using the pot file
526
527   THANKS
528       •   sschober
529
530           For implementation and German translation.
531

THANKS

533       •   Matt S. Trout (mst) <mst@shadowcat.co.uk>
534
535           For his patience and advice.
536
537       •   Tomas Doran (t0m) <bobtfish@bobtfish.net>
538
539           To help me release the new version, and using it :)
540
541       •   Torsten Raudssus (Getty)
542
543           to use it a lot in DuckDuckGo <http://duckduckgo.com> (go to see
544           MooX module also)
545
546       •   Jens Rehsack (REHSACK)
547
548           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
551       •   All contributors
552
553           For improving and add more feature to MooX::Options
554

SUPPORT

556       You can find documentation for this module with the perldoc command.
557
558           perldoc MooX::Options
559
560       You can also look for information at:
561
562       •   RT: CPAN's request tracker (report bugs here)
563
564           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=MooX-Options>
565
566       •   AnnoCPAN: Annotated CPAN documentation
567
568           <http://annocpan.org/dist/MooX-Options>
569
570       •   CPAN Ratings
571
572           <http://cpanratings.perl.org/d/MooX-Options>
573
574       •   Search CPAN
575
576           <http://search.cpan.org/dist/MooX-Options/>
577

AUTHOR

579       celogeek <me@celogeek.com>
580
582       This software is copyright (c) 2013 by celogeek <me@celogeek.com>.
583
584       This software is copyright (c) 2017 by Jens Rehsack.
585
586       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.
588
589
590
591perl v5.34.0                      2022-01-21                  MooX::Options(3)
Impressum