1Getopt::Long::DescriptiUvsee(r3)Contributed Perl DocumenGteattoipotn::Long::Descriptive(3)
2
3
4

NAME

6       Getopt::Long::Descriptive - Getopt::Long, but simpler and more powerful
7

VERSION

9       version 0.110
10

SYNOPSIS

12         use Getopt::Long::Descriptive;
13
14         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
23         print($usage->text), exit if $opt->help;
24
25         Client->connect( $opt->server, $opt->port );
26
27         print "Connected!\n" if $opt->verbose;
28
29       ...and running "my-program --help" will produce:
30
31         my-program [-psv] [long options...] <some-arg>
32           -s --server     the server to connect to
33           -p --port       the port to connect to
34
35           -v --verbose    print extra stuff
36           --help          print usage message and exit
37

DESCRIPTION

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
43       It also provides usage (help) messages, data validation, and a few
44       other useful features.
45

PERL VERSION

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
50       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

FUNCTIONS

56       Getopt::Long::Descriptive only exports one routine by default:
57       "describe_options".  All GLD's exports are exported by Sub::Exporter.
58
59   describe_options
60         my ($opt, $usage) = describe_options($usage_desc, @opt_spec, \%arg);
61
62       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
67       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
73       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
78       $usage_desc
79
80       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
85         $usage_desc = "%c %o <source> <desc>";
86
87       %c will be replaced with what Getopt::Long::Descriptive thinks is the
88       program name (it's computed from $0, see "prog_name").
89
90       %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
93       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
97       Literal "%" characters will need to be written as "%%", just like with
98       "sprintf".
99
100       @opt_spec
101
102       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
106         @opt_spec = (
107           [ "verbose|V" => "be noisy"       ],
108           [ "logfile=s" => "file to log to" ],
109         );
110
111       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
120       For more information on how these work, see the Getopt::Long
121       documentation.
122
123       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
128       The second value in the arrayref is a description of the option, for
129       use in the usage message.
130
131       Special Option Specifications
132
133       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
136       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
141       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
146       implies
147             implies => 'bar'
148             implies => [qw(foo bar)]
149             implies => { foo => 1, bar => 2 }
150
151           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
156       required
157             required => 1
158
159           If an option is required, failure to provide the option will result
160           in "describe_options" printing the usage message and exiting.
161
162       hidden
163             hidden => 1
164
165           This option will not show up in the usage text.
166
167           You can achieve the same behavior by using the string "hidden" for
168           the option's description.
169
170       one_of
171             one_of => \@subopt_specs
172
173           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
176           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
179             [ "mode" => hidden => { one_of => [
180               [ "get|g"  => "get the value" ],
181               [ "set|s"  => "set the value" ],
182               [ "delete" => "delete it" ],
183             ] } ],
184
185           No usage text for 'mode' will be displayed, but text for get, set,
186           and delete will be displayed.
187
188           If more than one of get, set, or delete is given, an error will be
189           thrown.
190
191           So, given the @opt_spec above, and an @ARGV of "('--get')", the
192           following would be true:
193
194             $opt->get == 1;
195
196             $opt->mode eq 'get';
197
198           Note: "get" would not be set if "mode" defaulted to 'get' and no
199           arguments were passed in.
200
201           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
205           As a further shorthand, you may specify "one_of" options using this
206           form:
207
208             [ mode => \@option_specs, \%constraints ]
209
210       shortcircuit
211             shortcircuit => 1
212
213           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
218       Params::Validate
219           In addition, any constraint understood by Params::Validate may be
220           used.
221
222           For example, to accept positive integers:
223
224             [ 'max-iterations=i', "maximum number of iterations",
225               { callbacks => { positive => sub { shift() > 0 } } } ],
226
227           (Internally, all constraints are translated into Params::Validate
228           options or callbacks.)
229
230       %arg
231
232       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
236         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
241   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

OTHER EXPORTS

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
252   "-all"
253       This import group will import "-type", "describe_options", and
254       "prog_name".
255

CUSTOMIZING

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
262       The following methods can be overridden:
263
264   usage_class
265         my $class = Getopt::Long::Descriptive->usage_class;
266
267       This returns the class to be used for constructing a Usage object, and
268       defaults to Getopt::Long::Descriptive::Usage.
269

SEE ALSO

271       •   Getopt::Long
272
273       •   Params::Validate
274

AUTHORS

276       •   Hans Dieter Pearcey <hdp@cpan.org>
277
278       •   Ricardo Signes <rjbs@semiotic.systems>
279

CONTRIBUTORS

281       •   Arthur Axel 'fREW' Schmidt <frioux@gmail.com>
282
283       •   Dave Rolsky <autarch@urth.org>
284
285       •   Diab Jerius <djerius@cfa.harvard.edu>
286
287       •   Hans Dieter Pearcey <hdp@pobox.com>
288
289       •   Hans Dieter Pearcey <hdp@weftsoar.net>
290
291       •   Harley Pig <harleypig@gmail.com>
292
293       •   hdp@cpan.org <hdp@cpan.org@fc0e91e4-031c-0410-8307-be39b06d7656>
294
295       •   Karen Etheridge <ether@cpan.org>
296
297       •   Michael McClimon <michael@mcclimon.org>
298
299       •   Niels Thykier <niels@thykier.net>
300
301       •   Olaf Alders <olaf@wundersolutions.com>
302
303       •   Roman Hubacek <roman.hubacek@centrum.cz>
304
305       •   Smylers <SMYLERS@cpan.fsck.com>
306
307       •   Thomas Neumann <blacky+perl@fluffbunny.de>
308
309       •   zhouzhen1 <zhouzhen1@gmail.com>
310
312       This software is copyright (c) 2005 by Hans Dieter Pearcey.
313
314       This is free software; you can redistribute it and/or modify it under
315       the same terms as the Perl 5 programming language system itself.
316
317
318
319perl v5.36.0                      2022-07-22      Getopt::Long::Descriptive(3)
Impressum