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 action => sub {
118 my ($prefix, $field, $raw, $norm, $slot, $settings) = @_;
119 # $norm will be '1' if option was used without an argument, so we
121 # just use the provided value when it is not 1'.
122 return $$slot = $norm unless $norm eq '1';
123 # $norm was 1, so this is our no-arg "default" behavior
125 # Do nothing if a value is already set
127 return if $$slot;
128 # Set the default value of 'summary.json'
130 return $$slot = 'summary.json';
131 },
132 );
133 };
134 D multi-def multiple-default list-default array-default
136 This is a combination of "d" and "m". You can use the opt
137 multiple times to list multiple values, and you can call it
138 without args to add a set of "default" values (not to be
139 confused with THE default attribute, which is used even if the
140 option never appears on the command line.)
141 Real world example (simplified for doc purposes):
143 option dev_libs => (
145 type => 'D',
146 short => 'D',
147 name => 'dev-lib',
148 category => 'Developer',
150 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.',
151 long_examples => ['', '=lib'],
153 short_examples => ['', '=lib', 'lib'],
154 action => sub {
156 my ($prefix, $field, $raw, $norm, $slot, $settings) = @_;
157 # If no argument was provided use the 'lib', 'blib/lib', and 'blib/arch' defaults.
159 # If an argument was provided, use it.
160 push @{$$slot} => ($norm eq '1') ? ('lib', 'blib/lib', 'blib/arch') : ($norm);
161 },
162 );
163 h hash
165 The hash type. Each time the option is used it is to add a
166 single key/value pair to the hash. Use an "=" sign to split the
167 key and value. The option can be used multiple times. A value
168 is required.
169 yath --opt foo=bar --opt baz=bat
171 H hash-list
173 Similar to the 'h' type except the key/value pair expects a
174 comma separated list for the value, and it will be placed under
175 the key as an arrayef.
176 yath --opt foo=a,b,c --opt bar=1,2,3
178 The yath command obove would produce this structure:
180 {
182 foo => ['a', 'b', 'c'],
183 bar => ['1', '2', '3'],
184 }
185 $class->new(title => 'my_title')
187 $title = $opt->title()
188 You MUST specify either a title, or BOTH a name and field. If you
189 only specify a title it will be used to generate the name and
190 field.
191 If your title is 'foo-bar_baz' then your field will be
193 'foo_bar_baz' and your name will be '$PREFIX-foo-bar-baz'.
194 Basically title is used to generate a sane field and/or name if
196 niether are specified. For field all dashes are changed to
197 underscores. The field is used as a key in the settings:
198 "$settings->prefix->field". For the name all underscores are
199 changed to dashes, if the option is provided by a plugin then
200 'prefix-' is prepended as well. The name is used for the command
201 line argument '--name'.
202 If you do not want/like the name and field generated from a title
204 then you can specify a name or title directly.
205 $class->new(name => 'my-name')
207 $name = $opt->name()
208 You MUST specify either a title, or BOTH a name and field. If you
209 only specify a title it will be used to generate the name and
210 field.
211 This name is used as your primary command line argument. If your
213 name is "foo" then your command line argument is "--foo".
214 $class->new(field => 'my_field')
216 $field = $opt->field()
217 You MUST specify either a title, or BOTH a name and field. If you
218 only specify a title it will be used to generate the name and
219 field.
220 The field is used in the settings hash. If your field is "foo" then
222 your settings path is "$setting->prefix->foo".
223 OPTIONAL
225 $class->new(action => sub ...)
227 $coderef = $opt->action()
228 option foo => (
229 ...,
230 action => sub {
231 my ($prefix, $field_name, $raw_value, $normalized_value, $slot_ref, $settings, $handler, $options) = @_;
232 # If no action is specified the following is all that is normally
234 # done. Having an action means this is not done, so if you want the
235 # value stored you must call this or similar.
236 $handler->($slot, $normalized_value);
237 },
238 );
239 $prefix
241 The prefix for the option, specified when the option was
242 defined.
243 $field_name
245 The field for the option, specified whent the option was
246 defined.
247 $raw_value
249 The value/argument provided at the command line "--foo bar"
250 would give us "bar". This is BEFORE any processing/normalizing
251 is done.
252 For options that do not take arguments, or where argumentes are
254 optional and none are provided, this will be '1'.
255 $normalized_value
257 If a normalize callback was provided this will be the result of
258 putting the $raw_value through the normalize callback.
259 $slot_ref
261 This is a scalar reference to the settings slot that holds the
262 option value(s).
263 The default behavior when no action is specified is usually one
265 of these:
266 $$slot_ref = $normalized_value;
268 push @{$$slot_ref} => $normalized_value;
269 However, to save yourself trouble you can use the $handler
271 instead (see below).
272 $settings
274 The Test2::Harness::Settings instance.
275 $handler
277 A callback that "does the right thing" as far as setting the
278 value in the settings hash. This is what is used when you do
279 not set an action callback.
280 $handler->($slot, $normalized_value);
282 $options
284 The App::Yath::Options instance this options belongs to. This
285 is mainly useful if you have an option that may add even more
286 options (such as the "--plugin" option can do). Note that if
287 you do this you should also set the "adds_options" attribute to
288 true, if you do not then the options list will not be refreshed
289 and your new options may not show up.
290 $class->new(adds_options => $bool)
292 $bool = $opt->adds_options()
293 If this is true then it means using this option could result in
294 more options being available (example: Loading a plugin).
295 $class->new(alt => ['alt1', 'alt2', ...])
297 $arrayref = $opt->alt()
298 Provide alternative names for the option. These are aliases that
299 can be used to achieve the same thing on the command line. This is
300 mainly useful for backcompat if an option is renamed.
301 $class->new(builds => 'My::Class')
303 $my_class = $opt->builds()
304 If this option is used in the construction of another object (such
305 as the group it belongs to is composed of options that translate
306 1-to-1 to fields in another object to build) then this can be used
307 to specify that. The ultimate effect is that an exception will be
308 thrown if that class does not have the correct attribute. This is a
309 safety net to catch errors early if field names change, or are
310 missing between this representation and the object being composed.
311 $class->new(category => 'My Category')
313 $category = $opt->category()
314 This is used to sort/display help and POD documentation for your
315 option. If you do not provide a category it is set to 'NO CATEGORY
316 - FIX ME'. The default value makes sure everyone knows that you do
317 not know what you are doing :-).
318 $class->new(clear_env_vars => $bool)
320 $bool = $opt->clear_env_vars()
321 This option is only useful when paired with the "env_vars"
322 attribute.
323 Example:
325 option foo => (
327 ...
328 env_vars => ['foo', 'bar', 'baz'],
329 clear_env_vars => 1,
330 ):
331 In this case you are saying option foo can be set to the value of
333 $ENV{foo}, $ENV{bar}, or $ENV{baz} vars if any are defined. The
334 "clear_env_vars" tell it to then delete the environment variables
335 after they are used to set the option. This is useful if you want
336 to use the env var to set an option, but do not want any tests to
337 be able to see the env var after it is used to set the option.
338 $class->new(default => $scalar)
340 $class->new(default => sub { return $default })
341 $scalar_or_coderef = $opt->default()
342 This sets a default value for the field in the settings hash, the
343 default is set before any command line processing is done, so if
344 the option is never used in the command line the default value will
345 be there.
346 Be sure to use the correct default value for your type. A scalar
348 for 's', an arrayref for 'm', etc.
349 Note, for any non-scalar type you want to use a subref to define
351 the value:
352 option foo => (
354 ...
355 type => 'm',
356 default => sub { [qw/a b c/] },
357 );
358 $class->new(description => "Fe Fi Fo Fum")
360 $multiline_string = $opt->description()
361 Description of your option. This is used in help output and POD. If
362 you do not provide a value the default is 'NO DESCRIPTION - FIX
363 ME'.
364 $class->new(env_vars => \@LIST)
366 $arrayref = $opt->env_vars()
367 If set, this should be an arrayref of environment variable names.
368 If any of the environment variables are defined then the settings
369 will be updated as though the option was provided onthe command
370 line with that value.
371 Example:
373 option foo => (
375 prefix => 'blah',
376 type => 's',
377 env_vars => ['FOO', 'BAR'],
378 );
379 Then command line:
381 FOO="xxx" yath test
383 Should be the same as
385 yath test --foo "xxx"
387 You can also ask to have the environment variables cleared after
389 they are checked:
390 option foo => (
392 prefix => 'blah',
393 type => 's',
394 env_vars => ['FOO', 'BAR'],
395 clear_env_vars => 1, # This tells yath to clear the env vars after they
396 are used.
397 );
398 If you would like the option set to the opposite of the envarinment
400 variable you can prefix it with a '!' character:
401 option foo =>(
403 ...
404 env_vars => ['!FOO'],
405 );
406 In this case these are equivelent:
408 FOO=0 yath test
410 yath test --foo=1
411 Note that this only works when the variable is defined. If
413 $ENV{FOO} is not defined then the variable is not used.
414 $class->new(from_command => 'App::Yath::Command::COMMAND')
416 $cmd_class = $opt->from_command()
417 If your option was defined for a specific command this will be set.
418 You do not normally set this yourself, the tools in
419 App::Yath::Options usually handle that for you.
420 $class->new(from_plugin => 'App::Yath::Plugin::PLUGIN')
422 $plugin_class = $opt->from_plugin()
423 If your option was defined for a specific plugin this will be set.
424 You do not normally set this yourself, the tools in
425 App::Yath::Options usually handle that for you.
426 $class->new(long_examples => [' foo', '=bar', ...])
428 $arrayref = $opt->long_examples()
429 Used for documentation purposes. If your option takes arguments
430 then you can give examples here. The examples should not include
431 the option itself, so "--foo bar" would be wrong, you should just
432 do " bar".
433 $class->new(negate => sub { ... })
435 $coderef = $opt->negate()
436 If you want a custom handler for negation "--no-OPT" you can
437 provide one here.
438 option foo => (
440 ...
441 negate => sub {
442 my ($prefix, $field, $slot, $settings, $options) = @_;
443 ...
445 },
446 );
447 The variables are the same as those in the "action" callback.
449 $class->new(normalize => sub { ... })
451 $coderef = $opt->normalize()
452 The normalize attribute holds a callback sub that takes the raw
453 value as input and returns the normalized form.
454 option foo => (
456 ...,
457 normalize => sub {
458 my $raw = shift;
459 ...
461 return $norm;
463 },
464 );
465 $class->new(pre_command => $bool)
467 $bool = $opt->pre_command()
468 Options are either command-specific, or pre-command. Pre-command
469 options are ones yath processes even if it has not determined what
470 comamnd is being used. Good examples are "--dev-lib" and
471 "--plugin".
472 yath --pre-command-opt COMMAND --command-opt
474 Most of the time this should be false, very few options qualify as
476 pre-command.
477 $class->new(pre_process => sub { ... })
479 $coderef = $opt->pre_process()
480 This is essentially a BEGIN block for options. This callback is
481 called as soon as the option is parsed from the command line, well
482 before the value is normalized and added to settings. A good use
483 for this is if your option needs to inject additional
484 App::Yath::Option instances into the App::Yath::Options instance.
485 option foo => (
487 ...
488 pre_process => sub {
490 my %params = @_;
491 my $opt = $params{opt};
493 my $options = $params{options};
494 my $action = $params{action};
495 my $type = $params{type};
496 my $val = $params{val};
497 ...;
499 },
500 );
501 Explanation of paremeters:
503 $params{opt}
505 The op instance
506 $params{options}
508 The App::Yath::Options instance.
509 $params{action}
511 A string, usually either "handle" or "handle_negation"
512 $params{type}
514 A string, usually "pre-command" or "command ($CLASS)" where the
515 second has the command package in the parentheses.
516 $params{val}
518 The value being set, if any. For options that do not take
519 arguments, or in the case of negation this key may not exist.
520 $class->new(short => $single_character_string)
522 $single_character_string = $opt->short()
523 If you want your option to be usable as a short option (single
524 character, single dash "-X") then you can provide the character to
525 use here. If the option does not require an argument then it can be
526 used along with other no-argument short options: "-xyz" would be
527 equivilent to "-x -y -z".
528 There are only so many single-characters available, so options are
530 restricted to picking only 1.
531 Please note: Yath reserves the right to add any single-character
533 short options in the main distribution, if they conflict with third
534 party plugins/commands then the third party must adapt and change
535 its options. As such it is not recommended to use any short options
536 in third party addons.
537 $class->new(short_examples => [' foo', ...])
539 $arrayref = $opt->short_examples()
540 Used for documentation purposes. If your option takes arguments
541 then you can give examples here. The examples should not include
542 the option itself, so "-f bar" would be wrong, you should just do "
543 bar".
544 This attribute is not used if you do not provide a "short"
546 attribute.
547 $class->new(trace => [$package, $file, $line])
549 $arrayref = $opt->trace()
550 This is almost always auto-populated for you via "caller()". It
551 should be an arrayref with a package, filename and line number.
552 This is used if there is a conflict between parameter names and/or
553 short options. If such a situation arises the file/line number of
554 all conflicting options will be reported so it can be fixed.
555
557 $bool = $opt->allows_arg()
558 True if arguments can be provided to the option (based on type).
559 This does not mean the option MUST accept arguments. 'D' type
560 options can accept arguments, but can also be used without
561 arguments.
562 $bool = $opt->applicable($options)
564 If an option provides an applicability callback this will use it to
565 determine if the option is applicable given the App::Yath::Options
566 instance.
567 If no callback was provided then this returns true.
569 $character = $opt->canon_type($type_name)
571 Given a long alias for an option type this will return the single-
572 character canonical name. This will return undef for any unknown
573 strings. This will not translate single character names to
574 themselves, so "$opt->canon_type('s')" will return undef while
575 "$opt->canon_type('string')" will return 's'.
576 $val = $opt->get_default()
578 This will return the proper default value for the option. If a
579 custom default was provided it will be returned, otherwise the
580 correct generic default for the option type will be used.
581 Here is a snippet showing the defaults for types:
583 # First check env vars and return any values from there
585 ...
586 # Then check for a custom default and use it.
587 ...
588 return 0
590 if $self->{+TYPE} eq 'c'
591 || $self->{+TYPE} eq 'b';
592 return []
594 if $self->{+TYPE} eq 'm'
595 || $self->{+TYPE} eq 'D';
596 return {}
598 if $self->{+TYPE} eq 'h'
599 || $self->{+TYPE} eq 'H';
600 # All others get undef
602 return undef;
603 $val $opt->get_normalized($raw)
605 This converts a raw value to a normalized one. If a custom
606 "normalize" attribute was set then it will be used, otherwise it is
607 normalized in accordance to the type.
608 This is where booleans are turned into 0 or 1, hashes are split,
610 hash-lists are split further, etc.
611 $opt->handle($raw, $settings, $options, $list)
613 This method handles setting the value in $settings. You should not
614 normally need to call this yourself.
615 $opt->handle_negation()
617 This method is used to handle a negated option. You should not
618 normally need to call this yourself.
619 @list = $opt->long_args()
621 Returns the name and any aliases.
622 $ref = $opt->option_slot($settings)
624 Get the settings->prefix->field reference. This creates the setting
625 field if necessary.
626 $bool = $opt->requires_arg()
628 Returns true if this option requires an argument when used.
629 $string = $opt->trace_string()
631 return a string like "somefile.pm line 42" based on where the
632 option was defined.
633 $bool = $opt->valid_type($character)
635 Check if a single character type is valid.
636 DOCUMENTATION GENERATION
638 $string = $opt->cli_docs()
639 Get the option documentation in a format that works for the "yath
640 help COMMAND" command.
641 $string = $opt->pod_docs()
643 Get the option documentation in POD format.
644 =item ....
646 .. option details ...
648
650 The source code repository for Test2-Harness can be found at
651 http://github.com/Test-More/Test2-Harness/.
652
654 Chad Granum <exodist@cpan.org>
655
657 Chad Granum <exodist@cpan.org>
658
660 Copyright 2020 Chad Granum <exodist7@gmail.com>.
661 This program is free software; you can redistribute it and/or modify it
663 under the same terms as Perl itself.
664 See http://dev.perl.org/licenses/
666perl v5.36.0 2022-09-08 App::Yath::Option(3)