1Getopt::Long::DescriptiUvsee(r3)Contributed Perl DocumenGteattoipotn::Long::Descriptive(3)
2
6 Getopt::Long::Descriptive - Getopt::Long, but simpler and more powerful
7
9 version 0.111
10
12 use Getopt::Long::Descriptive;
13 my ($opt, $usage) = describe_options(
15 'my-program %o <some-arg>',
16 [ 'server|s=s', "the server to connect to", { required => 1 } ],
17 [ 'port|p=i', "the port to connect to", { default => 79 } ],
18 [],
19 [ 'verbose|v', "print extra stuff" ],
20 [ 'help', "print usage message and exit", { shortcircuit => 1 } ],
21 );
22 print($usage->text), exit if $opt->help;
24 Client->connect( $opt->server, $opt->port );
26 print "Connected!\n" if $opt->verbose;
28 ...and running "my-program --help" will produce:
30 my-program [-psv] [long options...] <some-arg>
32 -s --server the server to connect to
33 -p --port the port to connect to
34 -v --verbose print extra stuff
36 --help print usage message and exit
37
39 Getopt::Long::Descriptive is yet another Getopt library. It's built
40 atop Getopt::Long, and gets a lot of its features, but tries to avoid
41 making you think about its huge array of options.
42 It also provides usage (help) messages, data validation, and a few
44 other useful features.
45
47 This library should run on perls released even a long time ago. It
48 should work on any version of perl released in the last five years.
49 Although it may work on older versions of perl, no guarantee is made
51 that the minimum required version will not be increased. The version
52 may be increased for any reason, and there is no promise that patches
53 will be accepted to lower the minimum required perl.
54
56 Getopt::Long::Descriptive only exports one routine by default:
57 "describe_options". All GLD's exports are exported by Sub::Exporter.
58 describe_options
60 my ($opt, $usage) = describe_options($usage_desc, @opt_spec, \%arg);
61 This routine inspects @ARGV for options that match the supplied spec.
63 If all the options are valid then it returns the options given and an
64 object for generating usage messages; if not then it dies with an
65 explanation of what was wrong and a usage message.
66 The $opt object will be a dynamically-generated subclass of
68 Getopt::Long::Descriptive::Opts. In brief, each of the options in
69 @opt_spec becomes an accessor method on the object, using the first-
70 given name, with dashes converted to underscores. For more
71 information, see the documentation for the Opts class.
72 The $usage object will be a Getopt::Long::Descriptive::Usage object,
74 which provides a "text" method to get the text of the usage message and
75 "die" to die with it. For more methods and options, consults the
76 documentation for the Usage class.
77 $usage_desc
79 The $usage_desc parameter to "describe_options" is a "sprintf"-like
81 string that is used in generating the first line of the usage message.
82 It's a one-line summary of how the command is to be invoked. A typical
83 usage description might be:
84 $usage_desc = "%c %o <source> <desc>";
86 %c will be replaced with what Getopt::Long::Descriptive thinks is the
88 program name (it's computed from $0, see "prog_name").
89 %o will be replaced with a list of the short options, as well as the
91 text "[long options...]" if any have been defined.
92 The rest of the usage description can be used to summarize what
94 arguments are expected to follow the program's options, and is entirely
95 free-form.
96 Literal "%" characters will need to be written as "%%", just like with
98 "sprintf".
99 @opt_spec
101 The @opt_spec part of the args to "describe_options" is used to
103 configure option parsing and to produce the usage message. Each entry
104 in the list is an arrayref describing one option, like this:
105 @opt_spec = (
107 [ "verbose|V" => "be noisy" ],
108 [ "logfile=s" => "file to log to" ],
109 );
110 The first value in the arrayref is a Getopt::Long-style option
112 specification. In brief, they work like this: each one is a pipe-
113 delimited list of names, optionally followed by a type declaration.
114 Type declarations are '=x' or ':x', where "=" means a value is required
115 and ":" means it is optional. x may be 's' to indicate a string is
116 required, 'i' for an integer, or 'f' for a number with a fractional
117 part. The type spec may end in "@" to indicate that the option may
118 appear multiple times.
119 For more information on how these work, see the Getopt::Long
121 documentation.
122 The first name given should be the canonical name, as it will be used
124 as the accessor method on the $opt object. Dashes in the name will be
125 converted to underscores, and all letters will be lowercased. For this
126 reason, all options should generally have a long-form name.
127 The second value in the arrayref is a description of the option, for
129 use in the usage message.
130 Special Option Specifications
132 If the option specification (arrayref) is empty, it will have no effect
134 other than causing a blank line to appear in the usage message.
135 If the option specification contains only one element, it will be
137 printed in the usage message with no other effect. If the element is a
138 reference, its referent will be printed as-is. Otherwise, it will be
139 reformatted like other text in the usage message.
140 If the option specification contains a third element, it adds extra
142 constraints or modifiers to the interpretation and validation of the
143 value. These are the keys that may be present in that hashref, and how
144 they behave:
145 implies
147 implies => 'bar'
148 implies => [qw(foo bar)]
149 implies => { foo => 1, bar => 2 }
150 If option A has an "implies" entry, then if A is given, other
152 options will be enabled. The value may be a single option to set,
153 an arrayref of options to set, or a hashref of options to set to
154 specific values.
155 required
157 required => 1
158 If an option is required, failure to provide the option will result
160 in "describe_options" printing the usage message and exiting.
161 hidden
163 hidden => 1
164 This option will not show up in the usage text.
166 You can achieve the same behavior by using the string "hidden" for
168 the option's description.
169 one_of
171 one_of => \@subopt_specs
172 This is useful for a group of options that are related. Each
174 option spec is added to the list for normal parsing and validation.
175 Your option name will end up with a value of the name of the option
177 that was chosen. For example, given the following spec:
178 [ "mode" => hidden => { one_of => [
180 [ "get|g" => "get the value" ],
181 [ "set|s" => "set the value" ],
182 [ "delete" => "delete it" ],
183 ] } ],
184 No usage text for 'mode' will be displayed, but text for get, set,
186 and delete will be displayed.
187 If more than one of get, set, or delete is given, an error will be
189 thrown.
190 So, given the @opt_spec above, and an @ARGV of "('--get')", the
192 following would be true:
193 $opt->get == 1;
195 $opt->mode eq 'get';
197 Note: "get" would not be set if "mode" defaulted to 'get' and no
199 arguments were passed in.
200 Even though the option sub-specs for "one_of" are meant to be
202 'first class' specs, some options don't make sense with them, e.g.
203 "required".
204 As a further shorthand, you may specify "one_of" options using this
206 form:
207 [ mode => \@option_specs, \%constraints ]
209 shortcircuit
211 shortcircuit => 1
212 If this option is present no other options will be returned. Other
214 options present will be checked for proper types, but not for
215 constraints. This provides a way of specifying "--help" style
216 options.
217 Params::Validate
219 In addition, any constraint understood by Params::Validate may be
220 used.
221 For example, to accept positive integers:
223 [ 'max-iterations=i', "maximum number of iterations",
225 { callbacks => { positive => sub { shift() > 0 } } } ],
226 (Internally, all constraints are translated into Params::Validate
228 options or callbacks.)
229 %arg
231 The %arg to "describe_options" is optional. If the last parameter is a
233 hashref, it contains extra arguments to modify the way
234 "describe_options" works. Valid arguments are:
235 getopt_conf - an arrayref of strings, passed to Getopt::Long::Configure
237 show_defaults - a boolean which controls whether an option's default
238 value (if applicable) is shown as part of the usage message
239 (for backward compatibility this defaults to false)
240 prog_name
242 This routine, exported on demand, returns the basename of $0, grabbed
243 at compile-time. You can override this guess by calling
244 prog_name($string) yourself.
245
247 "-types"
248 Any of the Params::Validate type constants ("SCALAR", etc.) can be
249 imported as well. You can get all of them at once by importing
250 "-types".
251 "-all"
253 This import group will import "-type", "describe_options", and
254 "prog_name".
255
257 Getopt::Long::Descriptive uses Sub::Exporter to build and export the
258 "describe_options" routine. By writing a new class that extends
259 Getopt::Long::Descriptive, the behavior of the constructed
260 "describe_options" routine can be changed.
261 The following methods can be overridden:
263 usage_class
265 my $class = Getopt::Long::Descriptive->usage_class;
266 This returns the class to be used for constructing a Usage object, and
268 defaults to Getopt::Long::Descriptive::Usage.
269
271 • Getopt::Long
272 • Params::Validate
274
276 • Hans Dieter Pearcey <hdp@cpan.org>
277 • Ricardo Signes <cpan@semiotic.systems>
279
281 • Arthur Axel 'fREW' Schmidt <frioux@gmail.com>
282 • Dave Rolsky <autarch@urth.org>
284 • Diab Jerius <djerius@cfa.harvard.edu>
286 • Hans Dieter Pearcey <hdp@pobox.com>
288 • Hans Dieter Pearcey <hdp@weftsoar.net>
290 • Harley Pig <harleypig@gmail.com>
292 • hdp@cpan.org <hdp@cpan.org@fc0e91e4-031c-0410-8307-be39b06d7656>
294 • Karen Etheridge <ether@cpan.org>
296 • Michael McClimon <michael@mcclimon.org>
298 • Niels Thykier <niels@thykier.net>
300 • Olaf Alders <olaf@wundersolutions.com>
302 • Ricardo Signes <rjbs@semiotic.systems>
304 • Roman Hubacek <roman.hubacek@centrum.cz>
306 • Smylers <SMYLERS@cpan.fsck.com>
308 • Thomas Neumann <blacky+perl@fluffbunny.de>
310 • zhouzhen1 <zhouzhen1@gmail.com>
312
314 This software is copyright (c) 2005 by Hans Dieter Pearcey.
315 This is free software; you can redistribute it and/or modify it under
317 the same terms as the Perl 5 programming language system itself.
318perl v5.36.0 2023-01-20 Getopt::Long::Descriptive(3)