1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. | will give a
29 .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
131 .IX Title "Getopt::Long::Descriptive 3"
132 .TH Getopt::Long::Descriptive 3 "2009-12-03" "perl v5.8.7" "User Contributed Perl Documentation"
134 Getopt::Long::Descriptive \- Getopt::Long with usage text
139 .IX Header "DESCRIPTION"
140 Convenient wrapper for Getopt::Long and program usage output
142 .IX Header "SYNOPSIS"
144 \& use Getopt::Long::Descriptive;
145 \& my ($opts, $usage) = describe_options($format, @opts, \e%arg);
150 \& $format = "usage: myprog %o myarg...";
153 \&\f(CW%o\fR will be replaced with a list of the short options, as well as the text
154 \&\*(L"[long options...]\*(R" if any have been defined.
156 \&\f(CW%c\fR will be replaced with what Getopt::Long::Descriptive
157 thinks is the program name (see \*(L"prog_name\*(R"). You can
158 override this guess by calling \f(CW\*(C`prog_name($string)\*(C'\fR
161 Because of this, any literal \f(CW\*(C`%\*(C'\fR symbols will need to be written as \f(CW\*(C`%%\*(C'\fR.
164 Option specifications are the same as in Getopt::Long. You should pass in an
165 array of arrayrefs whose first elements are option specs and whose second
166 elements are descriptions.
170 \& [ "verbose|V" => "be noisy" ],
171 \& [ "logfile=s" => "file to log to" ],
175 Option specifications may have a third hashref argument. If
176 present, this configures extra restrictions on the value or
177 presence of that option.
179 You may cause a blank line to be printed by passing an empty
180 arrayref. Likewise, a plain descriptive line will be
181 printed if you pass an arrayref with a single element:
187 \& [ 'other options:' ],
191 .Sh "Option Constraints"
192 .IX Subsection "Option Constraints"
194 .IX Subsection "implies"
201 \& implies => [qw(foo bar)]
205 \& implies => { foo => 1, bar => 2 }
209 .IX Subsection "required"
216 .IX Subsection "hidden"
222 This option will not show up in the usage text.
224 You can achieve this same behavior by using the string \f(CW\*(C`hidden\*(C'\fR for the option's description.
227 .IX Subsection "one_of"
230 \& one_of => \e@option_specs
233 Useful for a group of options that are related. Each option
234 spec is added to the list for normal parsing and validation.
236 Your option name will end up with a value of the name of the
237 option that was chosen. For example, given the following spec:
240 \& [ "mode" => hidden => { one_of => [
241 \& [ "get|g" => "get the value" ],
242 \& [ "set|s" => "set the value" ],
243 \& [ "delete" => "delete it" ],
247 No usage text for 'mode' will be displayed, though
248 get/set/delete will all have descriptions.
250 If more than one of get/set/delete (or their short versions)
251 are given, an error will be thrown.
253 If \f(CW@ARGV\fR is \f(CW\*(C`\-\-get\*(C'\fR, a dump of the resultant option
254 hashref would look like this:
261 \&\s-1NOTE:\s0 \f(CW\*(C`get\*(C'\fR would not be set if \f(CW\*(C`mode\*(C'\fR defaulted
262 to 'get' and no arguments were passed in.
264 \&\s-1WARNING:\s0 Even though the option sub-specs for \f(CW\*(C`one_of\*(C'\fR
265 are meant to be 'first class' specs, some options don't make
266 sense with them, e.g. \f(CW\*(C`required\*(C'\fR.
268 As a further shorthand, you may specify \f(CW\*(C`one_of\*(C'\fR
269 options using this form:
272 \& [ mode => \e@option_specs, \e%constraints ]
275 \fIParams::Validate\fR
276 .IX Subsection "Params::Validate"
278 In addition, any constraint understood by Params::Validate may be used.
280 (Internally, all constraints are translated into Params::Validate options or
282 .SH "EXTRA ARGUMENTS"
283 .IX Header "EXTRA ARGUMENTS"
284 If the last parameter is a hashref, it contains extra arguments to modify the
285 way \f(CW\*(C`describe_options\*(C'\fR works. Valid arguments are:
288 \& getopt_conf \- an arrayref of strings, passed to Getopt::Long::Configure
290 .SH "EXPORTED FUNCTIONS"
291 .IX Header "EXPORTED FUNCTIONS"
292 .ie n .Sh """describe_options"""
293 .el .Sh "\f(CWdescribe_options\fP"
294 .IX Subsection "describe_options"
295 See \s-1SYNOPSIS\s0; returns a hashref of option values and an object that represents
296 the usage statement. You should always import this routine, and not call it
297 directly. The ability to call \f(CW\*(C`Getopt::Long::Descriptive::describe_options\*(C'\fR
298 may go away in the future.
300 The usage object has several methods:
301 .ie n .IP "* ""$usage\->text"" returns the usage string" 4
302 .el .IP "* \f(CW$usage\->text\fR returns the usage string" 4
303 .IX Item "$usage->text returns the usage string"
305 .ie n .IP "* ""$usage\->warn"" prints usage to \s-1STDERR\s0" 4
306 .el .IP "* \f(CW$usage\->warn\fR prints usage to \s-1STDERR\s0" 4
307 .IX Item "$usage->warn prints usage to STDERR"
308 .ie n .IP "* ""$usage\->die"" dies with the usage string" 4
309 .el .IP "* \f(CW$usage\->die\fR dies with the usage string" 4
310 .IX Item "$usage->die dies with the usage string"
313 For more information on the usage object, look at
314 Getopt::Long::Descriptive::Usage.
316 .IX Subsection "prog_name"
317 This routine returns the basename of \f(CW$0\fR, grabbed at compile\-time.
319 .IX Subsection "-types"
320 Any of the Params::Validate type constants (\f(CW\*(C`SCALAR\*(C'\fR, etc.) can be imported as
321 well. You can get all of them at once by importing \f(CW\*(C`\-types\*(C'\fR.
322 .ie n .Sh """\-all"""
323 .el .Sh "\f(CW\-all\fP"
324 .IX Subsection "-all"
325 This gets you everything.
327 .IX Header "CONFIGURATION"
328 .ie n .Sh "$MungeOptions"
329 .el .Sh "\f(CW$MungeOptions\fP"
330 .IX Subsection "$MungeOptions"
331 When \f(CW$Getopt::Long::Descriptive::MungeOptions\fR is true, some munging is done
332 to make option names more hash-key friendly:
333 .IP "* All keys are lowercased" 4
334 .IX Item "All keys are lowercased"
336 .ie n .IP "* ""\-""\fR is changed to \f(CW""_""" 4
337 .el .IP "* \f(CW\-\fR is changed to \f(CW_\fR" 4
338 .IX Item "- is changed to _"
341 The default is a true value.
343 .IX Header "SEE ALSO"
347 .IX Header "CUSTOMIZING"
348 Getopt::Long::Descriptive uses Sub::Exporter to build and
349 export the \f(CW\*(C`describe_options\*(C'\fR routine. By writing a new class that extends
350 Getopt::Long::Descriptive, the behavior of the constructed \f(CW\*(C`describe_options\*(C'\fR
351 routine can be changed.
353 The following methods can be overridden:
355 .IX Subsection "usage_class"
357 \& my $class = Getopt::Long::Descriptive\->usage_class;
360 This returns the class to be used for constructing a Usage object, and defaults
361 to Getopt::Long::Descriptive::Usage.
364 Hans Dieter Pearcey, \f(CW\*(C`<hdp@cpan.org>\*(C'\fR
367 Please report any bugs or feature requests to
368 \&\f(CW\*(C`bug\-getopt\-long\-descriptive@rt.cpan.org\*(C'\fR, or through the web interface at
369 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Getopt\-Long\-Descriptive>.
370 I will be notified, and then you'll automatically be notified of progress on
371 your bug as I make changes.
372 .SH "COPYRIGHT & LICENSE"
373 .IX Header "COPYRIGHT & LICENSE"
374 Copyright 2005 Hans Dieter Pearcey, all rights reserved.
376 This program is free software; you can redistribute it and/or modify it
377 under the same terms as Perl itself.