1App::Yath::Options(3) User Contributed Perl DocumentationApp::Yath::Options(3)
2
3
4

NAME

6       App::Yath::Options - Tools for defining and tracking yath CLI options.
7

DESCRIPTION

9       This class represents a collection of options, and holds the logic for
10       processing them. This package also exports sugar to help you define
11       options.
12

SYNOPSIS

14           package My::Options;
15
16           use App::Yath::Options;
17
18           # This package now has a package instance of options, which can be obtained
19           # via the options() method.
20           my $options = __PACKAGE__->options;
21
22           # We can include options from other packages
23           include_options(
24               'Package::With::Options::A',
25               'Package::With::Options::B',
26               ...,
27           );
28
29           # Define an option group with some options
30           option_group { %common_fields } => sub {
31
32               # Define an option
33               option foo => (
34                   type => 's',
35                   default => "FOOOOOOO",
36                   category => 'foo',
37                   description => "This is foo"
38                   long_examples => [' value'],
39                   ...
40               );
41
42               option bar => ( ... );
43               ...
44           };
45
46           # Action to call right after options are parsed.
47           post sub {
48               my %params = @_;
49
50               ...
51           };
52

EXPORTS

54       $opts = options()
55       $opts = $class->options()
56           This returns the options instance associated with your package.
57
58       include_options(@CLASSES)
59           This lets you include options defined in other packages.
60
61       option_group \%COMMON_FIELDS => sub { ... }
62           An option group is simply a block where all calls to option() will
63           have common fields added automatically, this makes it easier to
64           define multiple options that share common fields. Common fields can
65           be overridden inside the option definition.
66
67           These are both equivalent:
68
69               # Using option group
70               option_group { category => 'foo', prefix => 'foo' } => sub {
71                   option a => (type => 'b');
72                   option b => (type => 's');
73               };
74
75               # Not using option group
76               option a => (type => 'b', category => 'foo', prefix => 'foo');
77               option b => (type => 's', category => 'foo', prefix => 'foo');
78
79       option TITLE => %FIELDS
80           Define an option. The first argument is the "title" attribute for
81           the new option, all other arguments should be attribute/value pairs
82           used to construct the option. See App::Yath::Option for the
83           documentation of attributes.
84
85       post sub { ... }
86       post $weight => sub { ... }
87           "post" callbacks are run after all command line arguments have been
88           processed.  This is a place to verify the result of several options
89           combined, sanity check, or even add short-circuit behavior. This is
90           how the "--help" and "--show-opts" options are implemented.
91
92           If no $weight is specified then 0 is used. "post" callbacks or
93           sorted based on weight with higher values being run later.
94

OPTIONS INSTANCES

96       In general you should not be using the options instance directly.
97       Options instances are mostly an implementation detail that should be
98       treated as a black box. There are however a few valid reasons to
99       interact with them directly. In those cases there are a few public
100       attributes/methods you can work with. This section documents the public
101       interface.
102
103   ATTRIBUTES
104       This section only lists attributes that may be useful to people working
105       with options instances. There are a lot of internal (to yath)
106       attributes that are implementation details that are not listed here.
107       Attributes not listed here are not intended for external use and may
108       change at any time.
109
110       $arrayref = $options->all
111           Arrayref containing all the App::Yath::Option instances in the
112           options instance.
113
114       $settings = $options->settings
115           Get the Test2::Harness::Settings instance.
116
117       $arrayref = $options->args
118           Get the reference to the list of command line arguments. This list
119           is modified as arguments are processed, there are no guarentees
120           about what is in here at any given stage of argument processing.
121
122       $class_name = $options->command_class
123           If yath has determined what command is being executed this will be
124           populated with that command class. This will be undefined if the
125           class has not been determined yet.
126
127       $arrayref = $options->used_plugins
128           This is a list of all plugins who's options have been used. Plugins
129           may appear more than once.
130
131       $hashref = $options->included
132           A hashref where every key is a package who's options have been
133           included into this options instance. The values are an
134           implementation detail, do not rely on them.
135
136   METHODS
137       This section only lists methods that may be useful to people working
138       with options instances. There are a lot of internal (to yath) methods
139       that are implementation details that are not listed here. Methods not
140       listed here are not intended for external use and may change at any
141       time.
142
143       $opt = $options->option(%OPTION_ATTRIBUTES)
144           This will create a new option with the provided attributes and add
145           it to the options instance. A "trace" attribute will be
146           automatically set for you.
147
148       $options->include($options_instance)
149           This method lets you directly include options from a second
150           instance into the first.
151
152       $options->include_from(@CLASSES)
153           This lets you include options from multiple classes that have
154           options defined.
155
156       $options->include_option($opt)
157           This lets you include a single already defined option instance.
158
159       $options->pre_docs($format, @args)
160           Get documentation for pre-command options. $format may be 'cli' or
161           'pod'.
162
163       $options->cmd_docs($format, @args)
164           Get documentation for command options. $format may be 'cli' or
165           'pod'.
166

SOURCE

168       The source code repository for Test2-Harness can be found at
169       http://github.com/Test-More/Test2-Harness/.
170

MAINTAINERS

172       Chad Granum <exodist@cpan.org>
173

AUTHORS

175       Chad Granum <exodist@cpan.org>
176
178       Copyright 2020 Chad Granum <exodist7@gmail.com>.
179
180       This program is free software; you can redistribute it and/or modify it
181       under the same terms as Perl itself.
182
183       See http://dev.perl.org/licenses/
184
185
186
187perl v5.36.1                      2023-10-04             App::Yath::Options(3)
Impressum