1App::Yath::Options(3) User Contributed Perl DocumentationApp::Yath::Options(3)
2
6 App::Yath::Options - Tools for defining and tracking yath CLI options.
7
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
14 package My::Options;
15 use App::Yath::Options;
17 # This package now has a package instance of options, which can be obtained
19 # via the options() method.
20 my $options = __PACKAGE__->options;
21 # We can include options from other packages
23 include_options(
24 'Package::With::Options::A',
25 'Package::With::Options::B',
26 ...,
27 );
28 # Define an option group with some options
30 option_group { %common_fields } => sub {
31 # 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 option bar => ( ... );
43 ...
44 };
45 # Action to call right after options are parsed.
47 post sub {
48 my %params = @_;
49 ...
51 };
52
54 $opts = options()
55 $opts = $class->options()
56 This returns the options instance associated with your package.
57 include_options(@CLASSES)
59 This lets you include options defined in other packages.
60 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 These are both equivalent:
68 # Using option group
70 option_group { category => 'foo', prefix => 'foo' } => sub {
71 option a => (type => 'b');
72 option b => (type => 's');
73 };
74 # Not using option group
76 option a => (type => 'b', category => 'foo', prefix => 'foo');
77 option b => (type => 's', category => 'foo', prefix => 'foo');
78 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 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 If no $weight is specified then 0 is used. "post" callbacks or
93 sorted based on weight with higher values being run later.
94
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 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 $arrayref = $options->all
111 Arrayref containing all the App::Yath::Option instances in the
112 options instance.
113 $settings = $options->settings
115 Get the Test2::Harness::Settings instance.
116 $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 $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 $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 $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 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 $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 $options->include($options_instance)
149 This method lets you directly include options from a second
150 instance into the first.
151 $options->include_from(@CLASSES)
153 This lets you include options from multiple classes that have
154 options defined.
155 $options->include_option($opt)
157 This lets you include a single already defined option instance.
158 $options->pre_docs($format, @args)
160 Get documentation for pre-command options. $format may be 'cli' or
161 'pod'.
162 $options->cmd_docs($format, @args)
164 Get documentation for command options. $format may be 'cli' or
165 'pod'.
166
168 The source code repository for Test2-Harness can be found at
169 http://github.com/Test-More/Test2-Harness/.
170
172 Chad Granum <exodist@cpan.org>
173
175 Chad Granum <exodist@cpan.org>
176
178 Copyright 2020 Chad Granum <exodist7@gmail.com>.
179 This program is free software; you can redistribute it and/or modify it
181 under the same terms as Perl itself.
182 See http://dev.perl.org/licenses/
184perl v5.36.1 2023-10-04 App::Yath::Options(3)