1App::Yath::Option(3) User Contributed Perl Documentation App::Yath::Option(3)
2
6 App::Yath::Option - Representation of a yath option.
7
9 This class represents a single command line option for yath.
10
12 You usually will not be creating option instances directly. Usually you
13 will use App::Yath::Options which provides sugar, and helps make sure
14 options get to the right place.
15 use App::Yath::Options;
17 # You can specify a single option:
19 option color => (
20 prefix => 'display',
21 category => "Display Options",
22 description => "Turn color on, default is true if STDOUT is a TTY.",
23 default => sub { -t STDOUT ? 1 : 0 },
24 );
25 # If you are specifying multiple options you can use an option_group to
27 # define common parameters.
28 option_group {prefix => 'display', category => "Display Options"} => sub {
29 option color => (
30 description => "Turn color on, default is true if STDOUT is a TTY.",
31 default => sub { -t STDOUT ? 1 : 0 },
32 );
33 option verbose => (
35 short => 'v',
36 type => 'c',
37 description => "Be more verbose",
38 default => 0,
39 );
40 };
41
43 These can be provided at object construction, or are generated
44 internally.
45 CONSTRUCTION ONLY
47 applicable => sub { ... }
48 This is callback is used by the applicable() method.
49 option foo => (
51 ...,
52 applicable => sub {
53 my ($opt, $options) = @_;
54 ...
55 return $bool;
56 },
57 );
58 READ-ONLY
60 REQUIRED
61 $class->new(prefix => 'my_prefix')
63 $scalar = $opt->prefix()
64 A prefix is required. All options have their values inserted into
65 the settings structure, an instance of Test2::Harness::Settings.
66 The structure is "$settings->PREFIX->OPTION".
67 If you do not specify a "name" attribute then the default name will
69 be "PREFIX-TITLE". The name is the main command line argument, so
70 "--PREFIX-TITLE" is the default name.
71 $class->new(type => $type)
73 $type = $opt->type()
74 All options must have a type, if non is specified the default is
75 'b' aka boolean.
76 Here are all the possible types, along with their aliases. You may
78 use the type character, or any of the aliases to specify that type.
79 b bool boolean
81 True of false values, will be normalized to 0 or 1 in most
82 cases.
83 c count counter counting
85 Counter, starts at 0 and then increments every time the option
86 is used.
87 s scalar string number
89 Requires an argument which is treated as a scalar value. No
90 type checking is done by the option itself, though you can
91 check it using "action" or "normalize" callbacks which are
92 documented under those attributes.
93 m multi multiple list array
95 Requires an argument which is treated as a scalar value. Can be
96 used multiple times. All arguments provided are appended to an
97 array.
98 d def default
100 Argument is optional, scalar when provided. "--opt=arg" to
101 provide an argument, "--opt arg" will not work, "arg" will be
102 seen as its own item on the command line. Can be specified
103 without an arg "--opt" to signify a default argument should be
104 used (set via the "action" callback, not the "default"
105 attribute which is a default value regardless of if the option
106 is used.)
107 Real world example from the debug options (simplified for doc
109 purposes):
110 option summary => (
112 type => 'd',
113 description => "Write out a summary json file, if no path is provided 'summary.json' will be used. The .json extension is added automatically if omitted.",
114 long_examples => ['', '=/path/to/summary.json'],
116 # New way to specify an auto-fill value for when no =VAL is provided.
118 # If you do not specify this the default autofill is '1' for legacy support.
119 autofill => 'VALUE',
120 # Old way to autofill a value (default is 1 for auto-fill)
122 # Using autofill is significantly better.
123 # You can also use action for additional behavior along with autofill,
124 # but the default will be your auto-fill value, not '1'.
125 action => sub {
126 my ($prefix, $field, $raw, $norm, $slot, $settings) = @_;
127 # $norm will be '1' if option was used without an argument, so we
129 # just use the provided value when it is not 1'.
130 return $$slot = $norm unless $norm eq '1';
131 # $norm was 1, so this is our no-arg "default" behavior
133 # Do nothing if a value is already set
135 return if $$slot;
136 # Set the default value of 'summary.json'
138 return $$slot = 'summary.json';
139 },
140 );
141 };
142 D multi-def multiple-default list-default array-default
144 This is a combination of "d" and "m". You can use the opt
145 multiple times to list multiple values, and you can call it
146 without args to add a set of "default" values (not to be
147 confused with THE default attribute, which is used even if the
148 option never appears on the command line.)
149 Real world example (simplified for doc purposes):
151 option dev_libs => (
153 type => 'D',
154 short => 'D',
155 name => 'dev-lib',
156 category => 'Developer',
158 description => 'Add paths to @INC before loading ANYTHING. This is what you use if you are developing yath or yath plugins to make sure the yath script finds the local code instead of the installed versions of the same code. You can provide an argument (-Dfoo) to provide a custom path, or you can just use -D without and arg to add lib, blib/lib and blib/arch.',
159 long_examples => ['', '=lib'],
161 short_examples => ['', '=lib', 'lib'],
162 # New way to specify the auto-fill values. This may be a single scalar,
164 # or an arrayref.
165 autofill => [ 'lib', 'blib/lib', 'blib/arch' ],
166 # Old way to specify the auto-fill values.
168 action => sub {
169 my ($prefix, $field, $raw, $norm, $slot, $settings) = @_;
170 # If no argument was provided use the 'lib', 'blib/lib', and 'blib/arch' defaults.
172 # If an argument was provided, use it.
173 push @{$$slot} => ($norm eq '1') ? ('lib', 'blib/lib', 'blib/arch') : ($norm);
174 },
175 );
176 h hash
178 The hash type. Each time the option is used it is to add a
179 single key/value pair to the hash. Use an "=" sign to split the
180 key and value. The option can be used multiple times. A value
181 is required.
182 yath --opt foo=bar --opt baz=bat
184 H hash-list
186 Similar to the 'h' type except the key/value pair expects a
187 comma separated list for the value, and it will be placed under
188 the key as an arrayef.
189 yath --opt foo=a,b,c --opt bar=1,2,3
191 The yath command obove would produce this structure:
193 {
195 foo => ['a', 'b', 'c'],
196 bar => ['1', '2', '3'],
197 }
198 $class->new(title => 'my_title')
200 $title = $opt->title()
201 You MUST specify either a title, or BOTH a name and field. If you
202 only specify a title it will be used to generate the name and
203 field.
204 If your title is 'foo-bar_baz' then your field will be
206 'foo_bar_baz' and your name will be '$PREFIX-foo-bar-baz'.
207 Basically title is used to generate a sane field and/or name if
209 niether are specified. For field all dashes are changed to
210 underscores. The field is used as a key in the settings:
211 "$settings->prefix->field". For the name all underscores are
212 changed to dashes, if the option is provided by a plugin then
213 'prefix-' is prepended as well. The name is used for the command
214 line argument '--name'.
215 If you do not want/like the name and field generated from a title
217 then you can specify a name or title directly.
218 $class->new(name => 'my-name')
220 $name = $opt->name()
221 You MUST specify either a title, or BOTH a name and field. If you
222 only specify a title it will be used to generate the name and
223 field.
224 This name is used as your primary command line argument. If your
226 name is "foo" then your command line argument is "--foo".
227 $class->new(field => 'my_field')
229 $field = $opt->field()
230 You MUST specify either a title, or BOTH a name and field. If you
231 only specify a title it will be used to generate the name and
232 field.
233 The field is used in the settings hash. If your field is "foo" then
235 your settings path is "$setting->prefix->foo".
236 OPTIONAL
238 $class->new(action => sub ...)
240 $coderef = $opt->action()
241 option foo => (
242 ...,
243 action => sub {
244 my ($prefix, $field_name, $raw_value, $normalized_value, $slot_ref, $settings, $handler, $options) = @_;
245 # If no action is specified the following is all that is normally
247 # done. Having an action means this is not done, so if you want the
248 # value stored you must call this or similar.
249 $handler->($slot, $normalized_value);
250 },
251 );
252 $prefix
254 The prefix for the option, specified when the option was
255 defined.
256 $field_name
258 The field for the option, specified whent the option was
259 defined.
260 $raw_value
262 The value/argument provided at the command line "--foo bar"
263 would give us "bar". This is BEFORE any processing/normalizing
264 is done.
265 For options that do not take arguments, or where argumentes are
267 optional and none are provided, this will be '1'.
268 $normalized_value
270 If a normalize callback was provided this will be the result of
271 putting the $raw_value through the normalize callback.
272 $slot_ref
274 This is a scalar reference to the settings slot that holds the
275 option value(s).
276 The default behavior when no action is specified is usually one
278 of these:
279 $$slot_ref = $normalized_value;
281 push @{$$slot_ref} => $normalized_value;
282 However, to save yourself trouble you can use the $handler
284 instead (see below).
285 $settings
287 The Test2::Harness::Settings instance.
288 $handler
290 A callback that "does the right thing" as far as setting the
291 value in the settings hash. This is what is used when you do
292 not set an action callback.
293 $handler->($slot, $normalized_value);
295 $options
297 The App::Yath::Options instance this options belongs to. This
298 is mainly useful if you have an option that may add even more
299 options (such as the "--plugin" option can do). Note that if
300 you do this you should also set the "adds_options" attribute to
301 true, if you do not then the options list will not be refreshed
302 and your new options may not show up.
303 $class->new(adds_options => $bool)
305 $bool = $opt->adds_options()
306 If this is true then it means using this option could result in
307 more options being available (example: Loading a plugin).
308 $class->new(alt => ['alt1', 'alt2', ...])
310 $arrayref = $opt->alt()
311 Provide alternative names for the option. These are aliases that
312 can be used to achieve the same thing on the command line. This is
313 mainly useful for backcompat if an option is renamed.
314 $class->new(builds => 'My::Class')
316 $my_class = $opt->builds()
317 If this option is used in the construction of another object (such
318 as the group it belongs to is composed of options that translate
319 1-to-1 to fields in another object to build) then this can be used
320 to specify that. The ultimate effect is that an exception will be
321 thrown if that class does not have the correct attribute. This is a
322 safety net to catch errors early if field names change, or are
323 missing between this representation and the object being composed.
324 $class->new(category => 'My Category')
326 $category = $opt->category()
327 This is used to sort/display help and POD documentation for your
328 option. If you do not provide a category it is set to 'NO CATEGORY
329 - FIX ME'. The default value makes sure everyone knows that you do
330 not know what you are doing :-).
331 $class->new(clear_env_vars => $bool)
333 $bool = $opt->clear_env_vars()
334 This option is only useful when paired with the "env_vars"
335 attribute.
336 Example:
338 option foo => (
340 ...
341 env_vars => ['foo', 'bar', 'baz'],
342 clear_env_vars => 1,
343 ):
344 In this case you are saying option foo can be set to the value of
346 $ENV{foo}, $ENV{bar}, or $ENV{baz} vars if any are defined. The
347 "clear_env_vars" tell it to then delete the environment variables
348 after they are used to set the option. This is useful if you want
349 to use the env var to set an option, but do not want any tests to
350 be able to see the env var after it is used to set the option.
351 $class->new(default => $scalar)
353 $class->new(default => sub { return $default })
354 $scalar_or_coderef = $opt->default()
355 This sets a default value for the field in the settings hash, the
356 default is set before any command line processing is done, so if
357 the option is never used in the command line the default value will
358 be there.
359 Be sure to use the correct default value for your type. A scalar
361 for 's', an arrayref for 'm', etc.
362 Note, for any non-scalar type you want to use a subref to define
364 the value:
365 option foo => (
367 ...
368 type => 'm',
369 default => sub { [qw/a b c/] },
370 );
371 $class->new(description => "Fe Fi Fo Fum")
373 $multiline_string = $opt->description()
374 Description of your option. This is used in help output and POD. If
375 you do not provide a value the default is 'NO DESCRIPTION - FIX
376 ME'.
377 $class->new(env_vars => \@LIST)
379 $arrayref = $opt->env_vars()
380 If set, this should be an arrayref of environment variable names.
381 If any of the environment variables are defined then the settings
382 will be updated as though the option was provided onthe command
383 line with that value.
384 Example:
386 option foo => (
388 prefix => 'blah',
389 type => 's',
390 env_vars => ['FOO', 'BAR'],
391 );
392 Then command line:
394 FOO="xxx" yath test
396 Should be the same as
398 yath test --foo "xxx"
400 You can also ask to have the environment variables cleared after
402 they are checked:
403 option foo => (
405 prefix => 'blah',
406 type => 's',
407 env_vars => ['FOO', 'BAR'],
408 clear_env_vars => 1, # This tells yath to clear the env vars after they
409 are used.
410 );
411 If you would like the option set to the opposite of the envarinment
413 variable you can prefix it with a '!' character:
414 option foo =>(
416 ...
417 env_vars => ['!FOO'],
418 );
419 In this case these are equivelent:
421 FOO=0 yath test
423 yath test --foo=1
424 Note that this only works when the variable is defined. If
426 $ENV{FOO} is not defined then the variable is not used.
427 $class->new(from_command => 'App::Yath::Command::COMMAND')
429 $cmd_class = $opt->from_command()
430 If your option was defined for a specific command this will be set.
431 You do not normally set this yourself, the tools in
432 App::Yath::Options usually handle that for you.
433 $class->new(from_plugin => 'App::Yath::Plugin::PLUGIN')
435 $plugin_class = $opt->from_plugin()
436 If your option was defined for a specific plugin this will be set.
437 You do not normally set this yourself, the tools in
438 App::Yath::Options usually handle that for you.
439 $class->new(long_examples => [' foo', '=bar', ...])
441 $arrayref = $opt->long_examples()
442 Used for documentation purposes. If your option takes arguments
443 then you can give examples here. The examples should not include
444 the option itself, so "--foo bar" would be wrong, you should just
445 do " bar".
446 $class->new(negate => sub { ... })
448 $coderef = $opt->negate()
449 If you want a custom handler for negation "--no-OPT" you can
450 provide one here.
451 option foo => (
453 ...
454 negate => sub {
455 my ($prefix, $field, $slot, $settings, $options) = @_;
456 ...
458 },
459 );
460 The variables are the same as those in the "action" callback.
462 $class->new(normalize => sub { ... })
464 $coderef = $opt->normalize()
465 The normalize attribute holds a callback sub that takes the raw
466 value as input and returns the normalized form.
467 option foo => (
469 ...,
470 normalize => sub {
471 my $raw = shift;
472 ...
474 return $norm;
476 },
477 );
478 $class->new(pre_command => $bool)
480 $bool = $opt->pre_command()
481 Options are either command-specific, or pre-command. Pre-command
482 options are ones yath processes even if it has not determined what
483 comamnd is being used. Good examples are "--dev-lib" and
484 "--plugin".
485 yath --pre-command-opt COMMAND --command-opt
487 Most of the time this should be false, very few options qualify as
489 pre-command.
490 $class->new(pre_process => sub { ... })
492 $coderef = $opt->pre_process()
493 This is essentially a BEGIN block for options. This callback is
494 called as soon as the option is parsed from the command line, well
495 before the value is normalized and added to settings. A good use
496 for this is if your option needs to inject additional
497 App::Yath::Option instances into the App::Yath::Options instance.
498 option foo => (
500 ...
501 pre_process => sub {
503 my %params = @_;
504 my $opt = $params{opt};
506 my $options = $params{options};
507 my $action = $params{action};
508 my $type = $params{type};
509 my $val = $params{val};
510 ...;
512 },
513 );
514 Explanation of paremeters:
516 $params{opt}
518 The op instance
519 $params{options}
521 The App::Yath::Options instance.
522 $params{action}
524 A string, usually either "handle" or "handle_negation"
525 $params{type}
527 A string, usually "pre-command" or "command ($CLASS)" where the
528 second has the command package in the parentheses.
529 $params{val}
531 The value being set, if any. For options that do not take
532 arguments, or in the case of negation this key may not exist.
533 $class->new(short => $single_character_string)
535 $single_character_string = $opt->short()
536 If you want your option to be usable as a short option (single
537 character, single dash "-X") then you can provide the character to
538 use here. If the option does not require an argument then it can be
539 used along with other no-argument short options: "-xyz" would be
540 equivilent to "-x -y -z".
541 There are only so many single-characters available, so options are
543 restricted to picking only 1.
544 Please note: Yath reserves the right to add any single-character
546 short options in the main distribution, if they conflict with third
547 party plugins/commands then the third party must adapt and change
548 its options. As such it is not recommended to use any short options
549 in third party addons.
550 $class->new(short_examples => [' foo', ...])
552 $arrayref = $opt->short_examples()
553 Used for documentation purposes. If your option takes arguments
554 then you can give examples here. The examples should not include
555 the option itself, so "-f bar" would be wrong, you should just do "
556 bar".
557 This attribute is not used if you do not provide a "short"
559 attribute.
560 $class->new(trace => [$package, $file, $line])
562 $arrayref = $opt->trace()
563 This is almost always auto-populated for you via caller(). It
564 should be an arrayref with a package, filename and line number.
565 This is used if there is a conflict between parameter names and/or
566 short options. If such a situation arises the file/line number of
567 all conflicting options will be reported so it can be fixed.
568
570 $bool = $opt->allows_arg()
571 True if arguments can be provided to the option (based on type).
572 This does not mean the option MUST accept arguments. 'D' type
573 options can accept arguments, but can also be used without
574 arguments.
575 $bool = $opt->applicable($options)
577 If an option provides an applicability callback this will use it to
578 determine if the option is applicable given the App::Yath::Options
579 instance.
580 If no callback was provided then this returns true.
582 $character = $opt->canon_type($type_name)
584 Given a long alias for an option type this will return the single-
585 character canonical name. This will return undef for any unknown
586 strings. This will not translate single character names to
587 themselves, so "$opt->canon_type('s')" will return undef while
588 "$opt->canon_type('string')" will return 's'.
589 $val = $opt->get_default()
591 This will return the proper default value for the option. If a
592 custom default was provided it will be returned, otherwise the
593 correct generic default for the option type will be used.
594 Here is a snippet showing the defaults for types:
596 # First check env vars and return any values from there
598 ...
599 # Then check for a custom default and use it.
600 ...
601 return 0
603 if $self->{+TYPE} eq 'c'
604 || $self->{+TYPE} eq 'b';
605 return []
607 if $self->{+TYPE} eq 'm'
608 || $self->{+TYPE} eq 'D';
609 return {}
611 if $self->{+TYPE} eq 'h'
612 || $self->{+TYPE} eq 'H';
613 # All others get undef
615 return undef;
616 $val $opt->get_normalized($raw)
618 This converts a raw value to a normalized one. If a custom
619 "normalize" attribute was set then it will be used, otherwise it is
620 normalized in accordance to the type.
621 This is where booleans are turned into 0 or 1, hashes are split,
623 hash-lists are split further, etc.
624 $opt->handle($raw, $settings, $options, $list)
626 This method handles setting the value in $settings. You should not
627 normally need to call this yourself.
628 $opt->handle_negation()
630 This method is used to handle a negated option. You should not
631 normally need to call this yourself.
632 @list = $opt->long_args()
634 Returns the name and any aliases.
635 $ref = $opt->option_slot($settings)
637 Get the settings->prefix->field reference. This creates the setting
638 field if necessary.
639 $bool = $opt->requires_arg()
641 Returns true if this option requires an argument when used.
642 $string = $opt->trace_string()
644 return a string like "somefile.pm line 42" based on where the
645 option was defined.
646 $bool = $opt->valid_type($character)
648 Check if a single character type is valid.
649 DOCUMENTATION GENERATION
651 $string = $opt->cli_docs()
652 Get the option documentation in a format that works for the "yath
653 help COMMAND" command.
654 $string = $opt->pod_docs()
656 Get the option documentation in POD format.
657 =item ....
659 .. option details ...
661
663 The source code repository for Test2-Harness can be found at
664 http://github.com/Test-More/Test2-Harness/.
665
667 Chad Granum <exodist@cpan.org>
668
670 Chad Granum <exodist@cpan.org>
671
673 Copyright 2020 Chad Granum <exodist7@gmail.com>.
674 This program is free software; you can redistribute it and/or modify it
676 under the same terms as Perl itself.
677 See http://dev.perl.org/licenses/
679perl v5.38.0 2023-10-04 App::Yath::Option(3)