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.090
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" ],
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" ],
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 Getopt::Long::Descriptive only exports one routine by default:
48 "describe_options". All GLD's exports are exported by Sub::Exporter.
49 describe_options
51 my ($opt, $usage) = describe_options($usage_desc, @opt_spec, \%arg);
52 This routine inspects @ARGV returns the options given and a object for
54 generating usage messages.
55 The $opt object will be a dynamically-generated subclass of
57 Getopt::Long::Descriptive::Opts. In brief, each of the options in
58 @opt_spec becomes an accessor method on the object, using the first-
59 given name, with dashes converted to underscores. For more
60 information, see the documentation for the Opts class.
61 The $usage object will be a Getopt::Long::Descriptive::Usage object,
63 which provides a "text" method to get the text of the usage message and
64 "die" to die with it. For more methods and options, consults the
65 documentation for the Usage class.
66 $usage_desc
68 The $usage_desc parameter to "describe_options" is a "sprintf"-like
70 string that is used in generating the first line of the usage message.
71 It's a one-line summary of how the command is to be invoked. A typical
72 usage description might be:
73 $usage_desc = "%c %o <source> <desc>";
75 %c will be replaced with what Getopt::Long::Descriptive thinks is the
77 program name (it's computed from $0, see "prog_name").
78 %o will be replaced with a list of the short options, as well as the
80 text "[long options...]" if any have been defined.
81 The rest of the usage description can be used to summarize what
83 arguments are expected to follow the program's options, and is entirely
84 free-form.
85 Literal "%" characters will need to be written as "%%", just like with
87 "sprintf".
88 @opt_spec
90 The @opt_spec part of the args to "describe_options" is used to
92 configure option parsing and to produce the usage message. Each entry
93 in the list is an arrayref describing one option, like this:
94 @opt_spec = (
96 [ "verbose|V" => "be noisy" ],
97 [ "logfile=s" => "file to log to" ],
98 );
99 The first value in the arrayref is a Getopt::Long-style option
101 specification. In brief, they work like this: each one is a pipe-
102 delimited list of names, optionally followed by a type declaration.
103 Type declarations are '=x' or ':x', where "=" means a value is required
104 and ":" means it is optional. x may be 's' to indicate a string is
105 required, 'i' for an integer, or 'f' for a number with a fractional
106 part. The type spec may end in "@" to indicate that the option may
107 appear multiple times.
108 For more information on how these work, see the Getopt::Long
110 documentation.
111 The first name given should be the canonical name, as it will be used
113 as the accessor method on the $opt object. Dashes in the name will be
114 converted to underscores, and all letters will be lowercased. For this
115 reason, all options should generally have a long-form name.
116 The second value in the arrayref is a description of the option, for
118 use in the usage message.
119 Special Option Specifications
121 If the option specification (arrayref) is empty, it will have no effect
123 other than causing a blank line to appear in the usage message.
124 If the option specification contains only one element, it will be
126 printed in the usage message with no other effect.
127 If the option specification contains a third element, it adds extra
129 constraints or modifiers to the interpretation and validation of the
130 value. These are the keys that may be present in that hashref, and how
131 they behave:
132 implies
134 implies => 'bar'
135 implies => [qw(foo bar)]
136 implies => { foo => 1, bar => 2 }
137 If option A has an "implies" entry, then if A is given, other
139 options will be enabled. The value may be a single option to set,
140 an arrayref of options to set, or a hashref of options to set to
141 specific values.
142 required
144 required => 1
145 If an option is required, failure to provide the option will result
147 in "describe_options" printing the usage message and exiting.
148 hidden
150 hidden => 1
151 This option will not show up in the usage text.
153 You can achieve the same behavior by using the string "hidden" for
155 the option's description.
156 one_of
158 one_of => \@subopt_specs
159 This is useful for a group of options that are related. Each
161 option spec is added to the list for normal parsing and validation.
162 Your option name will end up with a value of the name of the option
164 that was chosen. For example, given the following spec:
165 [ "mode" => hidden => { one_of => [
167 [ "get|g" => "get the value" ],
168 [ "set|s" => "set the value" ],
169 [ "delete" => "delete it" ],
170 ] } ],
171 No usage text for 'mode' will be displayed, but text for get, set,
173 and delete will be displayed.
174 If more than one of get, set, or delete is given, an error will be
176 thrown.
177 So, given the @opt_spec above, and an @ARGV of "('--get')", the
179 following would be true:
180 $opt->get == 1;
182 $opt->mode eq 'get';
184 Note: "get" would not be set if "mode" defaulted to 'get' and no
186 arguments were passed in.
187 Even though the option sub-specs for "one_of" are meant to be
189 'first class' specs, some options don't make sense with them, e.g.
190 "required".
191 As a further shorthand, you may specify "one_of" options using this
193 form:
194 [ mode => \@option_specs, \%constraints ]
196 Params::Validate
198 In addition, any constraint understood by Params::Validate may be
199 used.
200 (Internally, all constraints are translated into Params::Validate
202 options or callbacks.)
203 %arg
205 The %arg to "describe_options" is optional. If the last parameter is a
207 hashref, it contains extra arguments to modify the way
208 "describe_options" works. Valid arguments are:
209 getopt_conf - an arrayref of strings, passed to Getopt::Long::Configure
211 prog_name
213 This routine, exported on demand, returns the basename of $0, grabbed
214 at compile-time. You can override this guess by calling
215 "prog_name($string)" yourself.
216
218 "-types"
219 Any of the Params::Validate type constants ("SCALAR", etc.) can be
220 imported as well. You can get all of them at once by importing
221 "-types".
222 "-all"
224 This import group will import "-type", "describe_options", and
225 "prog_name".
226
228 Getopt::Long::Descriptive uses Sub::Exporter to build and export the
229 "describe_options" routine. By writing a new class that extends
230 Getopt::Long::Descriptive, the behavior of the constructed
231 "describe_options" routine can be changed.
232 The following methods can be overridden:
234 usage_class
236 my $class = Getopt::Long::Descriptive->usage_class;
237 This returns the class to be used for constructing a Usage object, and
239 defaults to Getopt::Long::Descriptive::Usage.
240
242 · Getopt::Long
243 · Params::Validate
245
247 · Hans Dieter Pearcey <hdp@cpan.org>
248 · Ricardo Signes <rjbs@cpan.org>
250
252 This software is copyright (c) 2005 by Hans Dieter Pearcey.
253 This is free software; you can redistribute it and/or modify it under
255 the same terms as the Perl 5 programming language system itself.
256perl v5.12.3 2011-04-22 Getopt::Long::Descriptive(3)