Debian Codegraph @

upstream/debian-unstable/man3/Getopt::Long.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Getopt::Long 3perl"
58 .TH Getopt::Long 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Getopt::Long \- Extended processing of command line options
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 8
68 \& use Getopt::Long;
69 \& my $data = "file.dat";
70 \& my $length = 24;
71 \& my $verbose;
72 \& GetOptions ("length=i" => \e$length, # numeric
73 \& "file=s" => \e$data, # string
74 \& "verbose" => \e$verbose) # flag
75 \& or die("Error in command line arguments\en");
76 .Ve
77 .SH DESCRIPTION
78 .IX Header "DESCRIPTION"
79 The Getopt::Long module implements an extended getopt function called
80 \&\fBGetOptions()\fR. It parses the command line from \f(CW@ARGV\fR, recognizing
81 and removing specified options and their possible values.
82 .PP
83 This function adheres to the POSIX syntax for command
84 line options, with GNU extensions. In general, this means that options
85 have long names instead of single letters, and are introduced with a
86 double dash "\-\-". Support for bundling of command line options, as was
87 the case with the more traditional single-letter approach, is provided
88 but not enabled by default.
89 .SH "Command Line Options, an Introduction"
90 .IX Header "Command Line Options, an Introduction"
91 Command line operated programs traditionally take their arguments from
92 the command line, for example filenames or other information that the
93 program needs to know. Besides arguments, these programs often take
94 command line \fIoptions\fR as well. Options are not necessary for the
95 program to work, hence the name 'option', but are used to modify its
96 default behaviour. For example, a program could do its job quietly,
97 but with a suitable option it could provide verbose information about
98 what it did.
99 .PP
100 Command line options come in several flavours. Historically, they are
101 preceded by a single dash \f(CW\*(C`\-\*(C'\fR, and consist of a single letter.
102 .PP
103 .Vb 1
104 \& \-l \-a \-c
105 .Ve
106 .PP
107 Usually, these single-character options can be bundled:
108 .PP
109 .Vb 1
110 \& \-lac
111 .Ve
112 .PP
113 Options can have values, the value is placed after the option
114 character. Sometimes with whitespace in between, sometimes not:
115 .PP
116 .Vb 1
117 \& \-s 24 \-s24
118 .Ve
119 .PP
120 Due to the very cryptic nature of these options, another style was
121 developed that used long names. So instead of a cryptic \f(CW\*(C`\-l\*(C'\fR one
122 could use the more descriptive \f(CW\*(C`\-\-long\*(C'\fR. To distinguish between a
123 bundle of single-character options and a long one, two dashes are used
124 to precede the option name. Early implementations of long options used
125 a plus \f(CW\*(C`+\*(C'\fR instead. Also, option values could be specified either
126 like
127 .PP
128 .Vb 1
129 \& \-\-size=24
130 .Ve
131 .PP
132 or
133 .PP
134 .Vb 1
135 \& \-\-size 24
136 .Ve
137 .PP
138 The \f(CW\*(C`+\*(C'\fR form is now obsolete and strongly deprecated.
139 .SH "Getting Started with Getopt::Long"
140 .IX Header "Getting Started with Getopt::Long"
141 Getopt::Long is the Perl5 successor of \f(CW\*(C`newgetopt.pl\*(C'\fR. This was the
142 first Perl module that provided support for handling the new style of
143 command line options, in particular long option names, hence the Perl5
144 name Getopt::Long. This module also supports single-character options
145 and bundling.
146 .PP
147 To use Getopt::Long from a Perl program, you must include the
148 following line in your Perl program:
149 .PP
150 .Vb 1
151 \& use Getopt::Long;
152 .Ve
153 .PP
154 This will load the core of the Getopt::Long module and prepare your
155 program for using it. Most of the actual Getopt::Long code is not
156 loaded until you really call one of its functions.
157 .PP
158 In the default configuration, options names may be abbreviated to
159 uniqueness, case does not matter, and a single dash is sufficient,
160 even for long option names. Also, options may be placed between
161 non-option arguments. See "Configuring Getopt::Long" for more
162 details on how to configure Getopt::Long.
163 .SS "Simple options"
164 .IX Subsection "Simple options"
165 The most simple options are the ones that take no values. Their mere
166 presence on the command line enables the option. Popular examples are:
167 .PP
168 .Vb 1
169 \& \-\-all \-\-verbose \-\-quiet \-\-debug
170 .Ve
171 .PP
172 Handling simple options is straightforward:
173 .PP
174 .Vb 3
175 \& my $verbose = \*(Aq\*(Aq; # option variable with default value (false)
176 \& my $all = \*(Aq\*(Aq; # option variable with default value (false)
177 \& GetOptions (\*(Aqverbose\*(Aq => \e$verbose, \*(Aqall\*(Aq => \e$all);
178 .Ve
179 .PP
180 The call to \fBGetOptions()\fR parses the command line arguments that are
181 present in \f(CW@ARGV\fR and sets the option variable to the value \f(CW1\fR if
182 the option did occur on the command line. Otherwise, the option
183 variable is not touched. Setting the option value to true is often
184 called \fIenabling\fR the option.
185 .PP
186 The option name as specified to the \fBGetOptions()\fR function is called
187 the option \fIspecification\fR. Later we'll see that this specification
188 can contain more than just the option name. The reference to the
189 variable is called the option \fIdestination\fR.
190 .PP
191 \&\fBGetOptions()\fR will return a true value if the command line could be
192 processed successfully. Otherwise, it will write error messages using
193 \&\fBdie()\fR and \fBwarn()\fR, and return a false result.
194 .SS "A little bit less simple options"
195 .IX Subsection "A little bit less simple options"
196 Getopt::Long supports two useful variants of simple options:
197 \&\fInegatable\fR options and \fIincremental\fR options.
198 .PP
199 A negatable option is specified with an exclamation mark \f(CW\*(C`!\*(C'\fR after the
200 option name:
201 .PP
202 .Vb 2
203 \& my $verbose = \*(Aq\*(Aq; # option variable with default value (false)
204 \& GetOptions (\*(Aqverbose!\*(Aq => \e$verbose);
205 .Ve
206 .PP
207 Now, using \f(CW\*(C`\-\-verbose\*(C'\fR on the command line will enable \f(CW$verbose\fR,
208 as expected. But it is also allowed to use \f(CW\*(C`\-\-noverbose\*(C'\fR, which will
209 disable \f(CW$verbose\fR by setting its value to \f(CW0\fR. Using a suitable
210 default value, the program can find out whether \f(CW$verbose\fR is false
211 by default, or disabled by using \f(CW\*(C`\-\-noverbose\*(C'\fR.
212 .PP
213 (If both \f(CW\*(C`\-\-verbose\*(C'\fR and \f(CW\*(C`\-\-noverbose\*(C'\fR are given, whichever is given
214 last takes precedence.)
215 .PP
216 An incremental option is specified with a plus \f(CW\*(C`+\*(C'\fR after the
217 option name:
218 .PP
219 .Vb 2
220 \& my $verbose = \*(Aq\*(Aq; # option variable with default value (false)
221 \& GetOptions (\*(Aqverbose+\*(Aq => \e$verbose);
222 .Ve
223 .PP
224 Using \f(CW\*(C`\-\-verbose\*(C'\fR on the command line will increment the value of
225 \&\f(CW$verbose\fR. This way the program can keep track of how many times the
226 option occurred on the command line. For example, each occurrence of
227 \&\f(CW\*(C`\-\-verbose\*(C'\fR could increase the verbosity level of the program.
228 .SS "Mixing command line option with other arguments"
229 .IX Subsection "Mixing command line option with other arguments"
230 Usually programs take command line options as well as other arguments,
231 for example, file names. It is good practice to always specify the
232 options first, and the other arguments last. Getopt::Long will,
233 however, allow the options and arguments to be mixed and 'filter out'
234 all the options before passing the rest of the arguments to the
235 program. To stop Getopt::Long from processing further arguments,
236 insert a double dash \f(CW\*(C`\-\-\*(C'\fR on the command line:
237 .PP
238 .Vb 1
239 \& \-\-size 24 \-\- \-\-all
240 .Ve
241 .PP
242 In this example, \f(CW\*(C`\-\-all\*(C'\fR will \fInot\fR be treated as an option, but
243 passed to the program unharmed, in \f(CW@ARGV\fR.
244 .SS "Options with values"
245 .IX Subsection "Options with values"
246 For options that take values it must be specified whether the option
247 value is required or not, and what kind of value the option expects.
248 .PP
249 Three kinds of values are supported: integer numbers, floating point
250 numbers, and strings.
251 .PP
252 If the option value is required, Getopt::Long will take the
253 command line argument that follows the option and assign this to the
254 option variable. If, however, the option value is specified as
255 optional, this will only be done if that value does not look like a
256 valid command line option itself.
257 .PP
258 .Vb 2
259 \& my $tag = \*(Aq\*(Aq; # option variable with default value
260 \& GetOptions (\*(Aqtag=s\*(Aq => \e$tag);
261 .Ve
262 .PP
263 In the option specification, the option name is followed by an equals
264 sign \f(CW\*(C`=\*(C'\fR and the letter \f(CW\*(C`s\*(C'\fR. The equals sign indicates that this
265 option requires a value. The letter \f(CW\*(C`s\*(C'\fR indicates that this value is
266 an arbitrary string. Other possible value types are \f(CW\*(C`i\*(C'\fR for integer
267 values, and \f(CW\*(C`f\*(C'\fR for floating point values. Using a colon \f(CW\*(C`:\*(C'\fR instead
268 of the equals sign indicates that the option value is optional. In
269 this case, if no suitable value is supplied, string valued options get
270 an empty string \f(CW\*(Aq\*(Aq\fR assigned, while numeric options are set to \f(CW0\fR.
271 .PP
272 (If the same option appears more than once on the command line, the
273 last given value is used. If you want to take all the values, see
274 below.)
275 .SS "Options with multiple values"
276 .IX Subsection "Options with multiple values"
277 Options sometimes take several values. For example, a program could
278 use multiple directories to search for library files:
279 .PP
280 .Vb 1
281 \& \-\-library lib/stdlib \-\-library lib/extlib
282 .Ve
283 .PP
284 To accomplish this behaviour, simply specify an array reference as the
285 destination for the option:
286 .PP
287 .Vb 1
288 \& GetOptions ("library=s" => \e@libfiles);
289 .Ve
290 .PP
291 Alternatively, you can specify that the option can have multiple
292 values by adding a "@", and pass a reference to a scalar as the
293 destination:
294 .PP
295 .Vb 1
296 \& GetOptions ("library=s@" => \e$libfiles);
297 .Ve
298 .PP
299 Used with the example above, \f(CW@libfiles\fR c.q. \f(CW@$libfiles\fR would
300 contain two strings upon completion: \f(CW"lib/stdlib"\fR and
301 \&\f(CW"lib/extlib"\fR, in that order. It is also possible to specify that
302 only integer or floating point numbers are acceptable values.
303 .PP
304 Often it is useful to allow comma-separated lists of values as well as
305 multiple occurrences of the options. This is easy using Perl's \fBsplit()\fR
306 and \fBjoin()\fR operators:
307 .PP
308 .Vb 2
309 \& GetOptions ("library=s" => \e@libfiles);
310 \& @libfiles = split(/,/,join(\*(Aq,\*(Aq,@libfiles));
311 .Ve
312 .PP
313 Of course, it is important to choose the right separator string for
314 each purpose.
315 .PP
316 Warning: What follows is an experimental feature.
317 .PP
318 Options can take multiple values at once, for example
319 .PP
320 .Vb 1
321 \& \-\-coordinates 52.2 16.4 \-\-rgbcolor 255 255 149
322 .Ve
323 .PP
324 This can be accomplished by adding a repeat specifier to the option
325 specification. Repeat specifiers are very similar to the \f(CW\*(C`{...}\*(C'\fR
326 repeat specifiers that can be used with regular expression patterns.
327 For example, the above command line would be handled as follows:
328 .PP
329 .Vb 1
330 \& GetOptions(\*(Aqcoordinates=f{2}\*(Aq => \e@coor, \*(Aqrgbcolor=i{3}\*(Aq => \e@color);
331 .Ve
332 .PP
333 The destination for the option must be an array or array reference.
334 .PP
335 It is also possible to specify the minimal and maximal number of
336 arguments an option takes. \f(CW\*(C`foo=s{2,4}\*(C'\fR indicates an option that
337 takes at least two and at most 4 arguments. \f(CW\*(C`foo=s{1,}\*(C'\fR indicates one
338 or more values; \f(CW\*(C`foo:s{,}\*(C'\fR indicates zero or more option values.
339 .SS "Options with hash values"
340 .IX Subsection "Options with hash values"
341 If the option destination is a reference to a hash, the option will
342 take, as value, strings of the form \fIkey\fR\f(CW\*(C`=\*(C'\fR\fIvalue\fR. The value will
343 be stored with the specified key in the hash.
344 .PP
345 .Vb 1
346 \& GetOptions ("define=s" => \e%defines);
347 .Ve
348 .PP
349 Alternatively you can use:
350 .PP
351 .Vb 1
352 \& GetOptions ("define=s%" => \e$defines);
353 .Ve
354 .PP
355 When used with command line options:
356 .PP
357 .Vb 1
358 \& \-\-define os=linux \-\-define vendor=redhat
359 .Ve
360 .PP
361 the hash \f(CW%defines\fR (or \f(CW%$defines\fR) will contain two keys, \f(CW"os"\fR
362 with value \f(CW"linux"\fR and \f(CW"vendor"\fR with value \f(CW"redhat"\fR. It is
363 also possible to specify that only integer or floating point numbers
364 are acceptable values. The keys are always taken to be strings.
365 .SS "User-defined subroutines to handle options"
366 .IX Subsection "User-defined subroutines to handle options"
367 Ultimate control over what should be done when (actually: each time)
368 an option is encountered on the command line can be achieved by
369 designating a reference to a subroutine (or an anonymous subroutine)
370 as the option destination. When \fBGetOptions()\fR encounters the option, it
371 will call the subroutine with two or three arguments. The first
372 argument is the name of the option. (Actually, it is an object that
373 stringifies to the name of the option.) For a scalar or array destination,
374 the second argument is the value to be stored. For a hash destination,
375 the second argument is the key to the hash, and the third argument
376 the value to be stored. It is up to the subroutine to store the value,
377 or do whatever it thinks is appropriate.
378 .PP
379 A trivial application of this mechanism is to implement options that
380 are related to each other. For example:
381 .PP
382 .Vb 3
383 \& my $verbose = \*(Aq\*(Aq; # option variable with default value (false)
384 \& GetOptions (\*(Aqverbose\*(Aq => \e$verbose,
385 \& \*(Aqquiet\*(Aq => sub { $verbose = 0 });
386 .Ve
387 .PP
388 Here \f(CW\*(C`\-\-verbose\*(C'\fR and \f(CW\*(C`\-\-quiet\*(C'\fR control the same variable
389 \&\f(CW$verbose\fR, but with opposite values.
390 .PP
391 If the subroutine needs to signal an error, it should call \fBdie()\fR with
392 the desired error message as its argument. \fBGetOptions()\fR will catch the
393 \&\fBdie()\fR, issue the error message, and record that an error result must
394 be returned upon completion.
395 .PP
396 If the text of the error message starts with an exclamation mark \f(CW\*(C`!\*(C'\fR
397 it is interpreted specially by \fBGetOptions()\fR. There is currently one
398 special command implemented: \f(CWdie("!FINISH")\fR will cause \fBGetOptions()\fR
399 to stop processing options, as if it encountered a double dash \f(CW\*(C`\-\-\*(C'\fR.
400 .PP
401 Here is an example of how to access the option name and value from within
402 a subroutine:
403 .PP
404 .Vb 5
405 \& GetOptions (\*(Aqopt=i\*(Aq => \e&handler);
406 \& sub handler {
407 \& my ($opt_name, $opt_value) = @_;
408 \& print("Option name is $opt_name and value is $opt_value\en");
409 \& }
410 .Ve
411 .SS "Options with multiple names"
412 .IX Subsection "Options with multiple names"
413 Often it is user friendly to supply alternate mnemonic names for
414 options. For example \f(CW\*(C`\-\-height\*(C'\fR could be an alternate name for
415 \&\f(CW\*(C`\-\-length\*(C'\fR. Alternate names can be included in the option
416 specification, separated by vertical bar \f(CW\*(C`|\*(C'\fR characters. To implement
417 the above example:
418 .PP
419 .Vb 1
420 \& GetOptions (\*(Aqlength|height=f\*(Aq => \e$length);
421 .Ve
422 .PP
423 The first name is called the \fIprimary\fR name, the other names are
424 called \fIaliases\fR. When using a hash to store options, the key will
425 always be the primary name.
426 .PP
427 Multiple alternate names are possible.
428 .SS "Case and abbreviations"
429 .IX Subsection "Case and abbreviations"
430 Without additional configuration, \fBGetOptions()\fR will ignore the case of
431 option names, and allow the options to be abbreviated to uniqueness.
432 .PP
433 .Vb 1
434 \& GetOptions (\*(Aqlength|height=f\*(Aq => \e$length, "head" => \e$head);
435 .Ve
436 .PP
437 This call will allow \f(CW\*(C`\-\-l\*(C'\fR and \f(CW\*(C`\-\-L\*(C'\fR for the length option, but
438 requires a least \f(CW\*(C`\-\-hea\*(C'\fR and \f(CW\*(C`\-\-hei\*(C'\fR for the head and height options.
439 .SS "Summary of Option Specifications"
440 .IX Subsection "Summary of Option Specifications"
441 Each option specifier consists of two parts: the name specification
442 and the argument specification.
443 .PP
444 The name specification contains the name of the option, optionally
445 followed by a list of alternative names separated by vertical bar
446 characters. The name is made up of alphanumeric characters, hyphens,
447 underscores. If \f(CW\*(C`pass_through\*(C'\fR is disabled, a period is also allowed in
448 option names.
449 .PP
450 .Vb 2
451 \& length option name is "length"
452 \& length|size|l name is "length", aliases are "size" and "l"
453 .Ve
454 .PP
455 The argument specification is optional. If omitted, the option is
456 considered boolean, a value of 1 will be assigned when the option is
457 used on the command line.
458 .PP
459 The argument specification can be
460 .IP ! 4
461 The option does not take an argument and may be negated by prefixing
462 it with "no" or "no\-". E.g. \f(CW"foo!"\fR will allow \f(CW\*(C`\-\-foo\*(C'\fR (a value of
463 1 will be assigned) as well as \f(CW\*(C`\-\-nofoo\*(C'\fR and \f(CW\*(C`\-\-no\-foo\*(C'\fR (a value of
464 0 will be assigned). If the option has aliases, this applies to the
465 aliases as well.
466 .Sp
467 Using negation on a single letter option when bundling is in effect is
468 pointless and will result in a warning.
469 .IP + 4
470 The option does not take an argument and will be incremented by 1
471 every time it appears on the command line. E.g. \f(CW"more+"\fR, when used
472 with \f(CW\*(C`\-\-more \-\-more \-\-more\*(C'\fR, will increment the value three times,
473 resulting in a value of 3 (provided it was 0 or undefined at first).
474 .Sp
475 The \f(CW\*(C`+\*(C'\fR specifier is ignored if the option destination is not a scalar.
476 .IP "= \fItype\fR [ \fIdesttype\fR ] [ \fIrepeat\fR ]" 4
477 .IX Item "= type [ desttype ] [ repeat ]"
478 The option requires an argument of the given type. Supported types
479 are:
480 .RS 4
481 .IP s 4
482 .IX Item "s"
483 String. An arbitrary sequence of characters. It is valid for the
484 argument to start with \f(CW\*(C`\-\*(C'\fR or \f(CW\*(C`\-\-\*(C'\fR.
485 .IP i 4
486 .IX Item "i"
487 Integer. An optional leading plus or minus sign, followed by a
488 sequence of digits.
489 .IP o 4
490 .IX Item "o"
491 Extended integer, Perl style. This can be either an optional leading
492 plus or minus sign, followed by a sequence of digits, or an octal
493 string (a zero, optionally followed by '0', '1', .. '7'), or a
494 hexadecimal string (\f(CW\*(C`0x\*(C'\fR followed by '0' .. '9', 'a' .. 'f', case
495 insensitive), or a binary string (\f(CW\*(C`0b\*(C'\fR followed by a series of '0'
496 and '1').
497 .IP f 4
498 .IX Item "f"
499 Real number. For example \f(CW3.14\fR, \f(CW\-6.23E24\fR and so on.
500 .RE
501 .RS 4
502 .Sp
503 The \fIdesttype\fR can be \f(CW\*(C`@\*(C'\fR or \f(CW\*(C`%\*(C'\fR to specify that the option is
504 list or a hash valued. This is only needed when the destination for
505 the option value is not otherwise specified. It should be omitted when
506 not needed.
507 .Sp
508 The \fIrepeat\fR specifies the number of values this option takes per
509 occurrence on the command line. It has the format \f(CW\*(C`{\*(C'\fR [ \fImin\fR ] [ \f(CW\*(C`,\*(C'\fR [ \fImax\fR ] ] \f(CW\*(C`}\*(C'\fR.
510 .Sp
511 \&\fImin\fR denotes the minimal number of arguments. It defaults to 1 for
512 options with \f(CW\*(C`=\*(C'\fR and to 0 for options with \f(CW\*(C`:\*(C'\fR, see below. Note that
513 \&\fImin\fR overrules the \f(CW\*(C`=\*(C'\fR / \f(CW\*(C`:\*(C'\fR semantics.
514 .Sp
515 \&\fImax\fR denotes the maximum number of arguments. It must be at least
516 \&\fImin\fR. If \fImax\fR is omitted, \fIbut the comma is not\fR, there is no
517 upper bound to the number of argument values taken.
518 .RE
519 .IP ": \fItype\fR [ \fIdesttype\fR ]" 4
520 .IX Item ": type [ desttype ]"
521 Like \f(CW\*(C`=\*(C'\fR, but designates the argument as optional.
522 If omitted, an empty string will be assigned to string values options,
523 and the value zero to numeric options.
524 .Sp
525 Note that if a string argument starts with \f(CW\*(C`\-\*(C'\fR or \f(CW\*(C`\-\-\*(C'\fR, it will be
526 considered an option on itself.
527 .IP ": \fInumber\fR [ \fIdesttype\fR ]" 4
528 .IX Item ": number [ desttype ]"
529 Like \f(CW\*(C`:i\*(C'\fR, but if the value is omitted, the \fInumber\fR will be assigned.
530 .Sp
531 If the \fInumber\fR is octal, hexadecimal or binary, behaves like \f(CW\*(C`:o\*(C'\fR.
532 .IP ": + [ \fIdesttype\fR ]" 4
533 .IX Item ": + [ desttype ]"
534 Like \f(CW\*(C`:i\*(C'\fR, but if the value is omitted, the current value for the
535 option will be incremented.
536 .SH "Advanced Possibilities"
537 .IX Header "Advanced Possibilities"
538 .SS "Object oriented interface"
539 .IX Subsection "Object oriented interface"
540 See Getopt::Long::Parser.
541 .SS "Callback object"
542 .IX Subsection "Callback object"
543 In version 2.37 the first argument to the callback function was
544 changed from string to object. This was done to make room for
545 extensions and more detailed control. The object stringifies to the
546 option name so this change should not introduce compatibility
547 problems.
548 .PP
549 The callback object has the following methods:
550 .IP name 4
551 .IX Item "name"
552 The name of the option, unabbreviated. For an option with multiple
553 names it return the first (canonical) name.
554 .IP given 4
555 .IX Item "given"
556 The name of the option as actually used, unabbreveated.
557 .SS "Thread Safety"
558 .IX Subsection "Thread Safety"
559 Getopt::Long is thread safe when using ithreads as of Perl 5.8. It is
560 \&\fInot\fR thread safe when using the older (experimental and now
561 obsolete) threads implementation that was added to Perl 5.005.
562 .SS "Documentation and help texts"
563 .IX Subsection "Documentation and help texts"
564 Getopt::Long encourages the use of Pod::Usage to produce help
565 messages. For example:
566 .PP
567 .Vb 2
568 \& use Getopt::Long;
569 \& use Pod::Usage;
570 \&
571 \& my $man = 0;
572 \& my $help = 0;
573 \&
574 \& GetOptions(\*(Aqhelp|?\*(Aq => \e$help, man => \e$man) or pod2usage(2);
575 \& pod2usage(1) if $help;
576 \& pod2usage(\-exitval => 0, \-verbose => 2) if $man;
577 \&
578 \& _\|_END_\|_
579 \&
580 \& =head1 NAME
581 \&
582 \& sample \- Using Getopt::Long and Pod::Usage
583 \&
584 \& =head1 SYNOPSIS
585 \&
586 \& sample [options] [file ...]
587 \&
588 \& Options:
589 \& \-help brief help message
590 \& \-man full documentation
591 \&
592 \& =head1 OPTIONS
593 \&
594 \& =over 8
595 \&
596 \& =item B<\-help>
597 \&
598 \& Print a brief help message and exits.
599 \&
600 \& =item B<\-man>
601 \&
602 \& Prints the manual page and exits.
603 \&
604 \& =back
605 \&
606 \& =head1 DESCRIPTION
607 \&
608 \& B<This program> will read the given input file(s) and do something
609 \& useful with the contents thereof.
610 \&
611 \& =cut
612 .Ve
613 .PP
614 See Pod::Usage for details.
615 .SS "Parsing options from an arbitrary array"
616 .IX Subsection "Parsing options from an arbitrary array"
617 By default, GetOptions parses the options that are present in the
618 global array \f(CW@ARGV\fR. A special entry \f(CW\*(C`GetOptionsFromArray\*(C'\fR can be
619 used to parse options from an arbitrary array.
620 .PP
621 .Vb 2
622 \& use Getopt::Long qw(GetOptionsFromArray);
623 \& $ret = GetOptionsFromArray(\e@myopts, ...);
624 .Ve
625 .PP
626 When used like this, options and their possible values are removed
627 from \f(CW@myopts\fR, the global \f(CW@ARGV\fR is not touched at all.
628 .PP
629 The following two calls behave identically:
630 .PP
631 .Vb 2
632 \& $ret = GetOptions( ... );
633 \& $ret = GetOptionsFromArray(\e@ARGV, ... );
634 .Ve
635 .PP
636 This also means that a first argument hash reference now becomes the
637 second argument:
638 .PP
639 .Vb 2
640 \& $ret = GetOptions(\e%opts, ... );
641 \& $ret = GetOptionsFromArray(\e@ARGV, \e%opts, ... );
642 .Ve
643 .SS "Parsing options from an arbitrary string"
644 .IX Subsection "Parsing options from an arbitrary string"
645 A special entry \f(CW\*(C`GetOptionsFromString\*(C'\fR can be used to parse options
646 from an arbitrary string.
647 .PP
648 .Vb 2
649 \& use Getopt::Long qw(GetOptionsFromString);
650 \& $ret = GetOptionsFromString($string, ...);
651 .Ve
652 .PP
653 The contents of the string are split into arguments using a call to
654 \&\f(CW\*(C`Text::ParseWords::shellwords\*(C'\fR. As with \f(CW\*(C`GetOptionsFromArray\*(C'\fR, the
655 global \f(CW@ARGV\fR is not touched.
656 .PP
657 It is possible that, upon completion, not all arguments in the string
658 have been processed. \f(CW\*(C`GetOptionsFromString\*(C'\fR will, when called in list
659 context, return both the return status and an array reference to any
660 remaining arguments:
661 .PP
662 .Vb 1
663 \& ($ret, $args) = GetOptionsFromString($string, ... );
664 .Ve
665 .PP
666 If any arguments remain, and \f(CW\*(C`GetOptionsFromString\*(C'\fR was not called in
667 list context, a message will be given and \f(CW\*(C`GetOptionsFromString\*(C'\fR will
668 return failure.
669 .PP
670 As with GetOptionsFromArray, a first argument hash reference now
671 becomes the second argument. See the next section.
672 .SS "Storing options values in a hash"
673 .IX Subsection "Storing options values in a hash"
674 Sometimes, for example when there are a lot of options, having a
675 separate variable for each of them can be cumbersome. \fBGetOptions()\fR
676 supports, as an alternative mechanism, storing options values in a
677 hash.
678 .PP
679 To obtain this, a reference to a hash must be passed \fIas the first
680 argument\fR to \fBGetOptions()\fR. For each option that is specified on the
681 command line, the option value will be stored in the hash with the
682 option name as key. Options that are not actually used on the command
683 line will not be put in the hash, on other words,
684 \&\f(CWexists($h{option})\fR (or \fBdefined()\fR) can be used to test if an option
685 was used. The drawback is that warnings will be issued if the program
686 runs under \f(CW\*(C`use strict\*(C'\fR and uses \f(CW$h{option}\fR without testing with
687 \&\fBexists()\fR or \fBdefined()\fR first.
688 .PP
689 .Vb 2
690 \& my %h = ();
691 \& GetOptions (\e%h, \*(Aqlength=i\*(Aq); # will store in $h{length}
692 .Ve
693 .PP
694 For options that take list or hash values, it is necessary to indicate
695 this by appending an \f(CW\*(C`@\*(C'\fR or \f(CW\*(C`%\*(C'\fR sign after the type:
696 .PP
697 .Vb 1
698 \& GetOptions (\e%h, \*(Aqcolours=s@\*(Aq); # will push to @{$h{colours}}
699 .Ve
700 .PP
701 To make things more complicated, the hash may contain references to
702 the actual destinations, for example:
703 .PP
704 .Vb 3
705 \& my $len = 0;
706 \& my %h = (\*(Aqlength\*(Aq => \e$len);
707 \& GetOptions (\e%h, \*(Aqlength=i\*(Aq); # will store in $len
708 .Ve
709 .PP
710 This example is fully equivalent with:
711 .PP
712 .Vb 2
713 \& my $len = 0;
714 \& GetOptions (\*(Aqlength=i\*(Aq => \e$len); # will store in $len
715 .Ve
716 .PP
717 Any mixture is possible. For example, the most frequently used options
718 could be stored in variables while all other options get stored in the
719 hash:
720 .PP
721 .Vb 6
722 \& my $verbose = 0; # frequently referred
723 \& my $debug = 0; # frequently referred
724 \& my %h = (\*(Aqverbose\*(Aq => \e$verbose, \*(Aqdebug\*(Aq => \e$debug);
725 \& GetOptions (\e%h, \*(Aqverbose\*(Aq, \*(Aqdebug\*(Aq, \*(Aqfilter\*(Aq, \*(Aqsize=i\*(Aq);
726 \& if ( $verbose ) { ... }
727 \& if ( exists $h{filter} ) { ... option \*(Aqfilter\*(Aq was specified ... }
728 .Ve
729 .SS Bundling
730 .IX Subsection "Bundling"
731 With bundling it is possible to set several single-character options
732 at once. For example if \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`v\*(C'\fR and \f(CW\*(C`x\*(C'\fR are all valid options,
733 .PP
734 .Vb 1
735 \& \-vax
736 .Ve
737 .PP
738 will set all three.
739 .PP
740 Getopt::Long supports three styles of bundling. To enable bundling, a
741 call to Getopt::Long::Configure is required.
742 .PP
743 The simplest style of bundling can be enabled with:
744 .PP
745 .Vb 1
746 \& Getopt::Long::Configure ("bundling");
747 .Ve
748 .PP
749 Configured this way, single-character options can be bundled but long
750 options (and any of their auto-abbreviated shortened forms) \fBmust\fR
751 always start with a double dash \f(CW\*(C`\-\-\*(C'\fR to avoid ambiguity. For example,
752 when \f(CW\*(C`vax\*(C'\fR, \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`v\*(C'\fR and \f(CW\*(C`x\*(C'\fR are all valid options,
753 .PP
754 .Vb 1
755 \& \-vax
756 .Ve
757 .PP
758 will set \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`v\*(C'\fR and \f(CW\*(C`x\*(C'\fR, but
759 .PP
760 .Vb 1
761 \& \-\-vax
762 .Ve
763 .PP
764 will set \f(CW\*(C`vax\*(C'\fR.
765 .PP
766 The second style of bundling lifts this restriction. It can be enabled
767 with:
768 .PP
769 .Vb 1
770 \& Getopt::Long::Configure ("bundling_override");
771 .Ve
772 .PP
773 Now, \f(CW\*(C`\-vax\*(C'\fR will set the option \f(CW\*(C`vax\*(C'\fR.
774 .PP
775 In all of the above cases, option values may be inserted in the
776 bundle. For example:
777 .PP
778 .Vb 1
779 \& \-h24w80
780 .Ve
781 .PP
782 is equivalent to
783 .PP
784 .Vb 1
785 \& \-h 24 \-w 80
786 .Ve
787 .PP
788 A third style of bundling allows only values to be bundled with
789 options. It can be enabled with:
790 .PP
791 .Vb 1
792 \& Getopt::Long::Configure ("bundling_values");
793 .Ve
794 .PP
795 Now, \f(CW\*(C`\-h24\*(C'\fR will set the option \f(CW\*(C`h\*(C'\fR to \f(CW24\fR, but option bundles
796 like \f(CW\*(C`\-vxa\*(C'\fR and \f(CW\*(C`\-h24w80\*(C'\fR are flagged as errors.
797 .PP
798 Enabling \f(CW\*(C`bundling_values\*(C'\fR will disable the other two styles of
799 bundling.
800 .PP
801 When configured for bundling, single-character options are matched
802 case sensitive while long options are matched case insensitive. To
803 have the single-character options matched case insensitive as well,
804 use:
805 .PP
806 .Vb 1
807 \& Getopt::Long::Configure ("bundling", "ignorecase_always");
808 .Ve
809 .PP
810 It goes without saying that bundling can be quite confusing.
811 .SS "The lonesome dash"
812 .IX Subsection "The lonesome dash"
813 Normally, a lone dash \f(CW\*(C`\-\*(C'\fR on the command line will not be considered
814 an option. Option processing will terminate (unless "permute" is
815 configured) and the dash will be left in \f(CW@ARGV\fR.
816 .PP
817 It is possible to get special treatment for a lone dash. This can be
818 achieved by adding an option specification with an empty name, for
819 example:
820 .PP
821 .Vb 1
822 \& GetOptions (\*(Aq\*(Aq => \e$stdio);
823 .Ve
824 .PP
825 A lone dash on the command line will now be a legal option, and using
826 it will set variable \f(CW$stdio\fR.
827 .SS "Argument callback"
828 .IX Subsection "Argument callback"
829 A special option 'name' \f(CW\*(C`<>\*(C'\fR can be used to designate a subroutine
830 to handle non-option arguments. When \fBGetOptions()\fR encounters an
831 argument that does not look like an option, it will immediately call this
832 subroutine and passes it one parameter: the argument name.
833 .PP
834 For example:
835 .PP
836 .Vb 3
837 \& my $width = 80;
838 \& sub process { ... }
839 \& GetOptions (\*(Aqwidth=i\*(Aq => \e$width, \*(Aq<>\*(Aq => \e&process);
840 .Ve
841 .PP
842 When applied to the following command line:
843 .PP
844 .Vb 1
845 \& arg1 \-\-width=72 arg2 \-\-width=60 arg3
846 .Ve
847 .PP
848 This will call
849 \&\f(CWprocess("arg1")\fR while \f(CW$width\fR is \f(CW80\fR,
850 \&\f(CWprocess("arg2")\fR while \f(CW$width\fR is \f(CW72\fR, and
851 \&\f(CWprocess("arg3")\fR while \f(CW$width\fR is \f(CW60\fR.
852 .PP
853 This feature requires configuration option \fBpermute\fR, see section
854 "Configuring Getopt::Long".
855 .SH "Configuring Getopt::Long"
856 .IX Header "Configuring Getopt::Long"
857 Getopt::Long can be configured by calling subroutine
858 \&\fBGetopt::Long::Configure()\fR. This subroutine takes a list of quoted
859 strings, each specifying a configuration option to be enabled, e.g.
860 \&\f(CW\*(C`ignore_case\*(C'\fR. To disable, prefix with \f(CW\*(C`no\*(C'\fR or \f(CW\*(C`no_\*(C'\fR, e.g.
861 \&\f(CW\*(C`no_ignore_case\*(C'\fR. Case does not matter. Multiple calls to \fBConfigure()\fR
862 are possible.
863 .PP
864 Alternatively, as of version 2.24, the configuration options may be
865 passed together with the \f(CW\*(C`use\*(C'\fR statement:
866 .PP
867 .Vb 1
868 \& use Getopt::Long qw(:config no_ignore_case bundling);
869 .Ve
870 .PP
871 The following options are available:
872 .IP default 12
873 .IX Item "default"
874 This option causes all configuration options to be reset to their
875 default values.
876 .IP posix_default 12
877 .IX Item "posix_default"
878 This option causes all configuration options to be reset to their
879 default values as if the environment variable POSIXLY_CORRECT had
880 been set.
881 .IP auto_abbrev 12
882 .IX Item "auto_abbrev"
883 Allow option names to be abbreviated to uniqueness.
884 Default is enabled unless environment variable
885 POSIXLY_CORRECT has been set, in which case \f(CW\*(C`auto_abbrev\*(C'\fR is disabled.
886 .IP getopt_compat 12
887 .IX Item "getopt_compat"
888 Allow \f(CW\*(C`+\*(C'\fR to start options.
889 Default is enabled unless environment variable
890 POSIXLY_CORRECT has been set, in which case \f(CW\*(C`getopt_compat\*(C'\fR is disabled.
891 .IP gnu_compat 12
892 .IX Item "gnu_compat"
893 \&\f(CW\*(C`gnu_compat\*(C'\fR controls whether \f(CW\*(C`\-\-opt=\*(C'\fR is allowed, and what it should
894 do. Without \f(CW\*(C`gnu_compat\*(C'\fR, \f(CW\*(C`\-\-opt=\*(C'\fR gives an error. With \f(CW\*(C`gnu_compat\*(C'\fR,
895 \&\f(CW\*(C`\-\-opt=\*(C'\fR will give option \f(CW\*(C`opt\*(C'\fR an empty value.
896 This is the way GNU \fBgetopt_long()\fR does it.
897 .Sp
898 Note that for options with optional arguments, \f(CW\*(C`\-\-opt value\*(C'\fR is still
899 accepted, even though GNU \fBgetopt_long()\fR requires writing \f(CW\*(C`\-\-opt=value\*(C'\fR
900 in this case.
901 .IP gnu_getopt 12
902 .IX Item "gnu_getopt"
903 This is a short way of setting \f(CW\*(C`gnu_compat\*(C'\fR \f(CW\*(C`bundling\*(C'\fR \f(CW\*(C`permute\*(C'\fR
904 \&\f(CW\*(C`no_getopt_compat\*(C'\fR. With \f(CW\*(C`gnu_getopt\*(C'\fR, command line handling should be
905 reasonably compatible with GNU \fBgetopt_long()\fR.
906 .IP require_order 12
907 .IX Item "require_order"
908 Whether command line arguments are allowed to be mixed with options.
909 Default is disabled unless environment variable
910 POSIXLY_CORRECT has been set, in which case \f(CW\*(C`require_order\*(C'\fR is enabled.
911 .Sp
912 See also \f(CW\*(C`permute\*(C'\fR, which is the opposite of \f(CW\*(C`require_order\*(C'\fR.
913 .IP permute 12
914 .IX Item "permute"
915 Whether command line arguments are allowed to be mixed with options.
916 Default is enabled unless environment variable
917 POSIXLY_CORRECT has been set, in which case \f(CW\*(C`permute\*(C'\fR is disabled.
918 Note that \f(CW\*(C`permute\*(C'\fR is the opposite of \f(CW\*(C`require_order\*(C'\fR.
919 .Sp
920 If \f(CW\*(C`permute\*(C'\fR is enabled, this means that
921 .Sp
922 .Vb 1
923 \& \-\-foo arg1 \-\-bar arg2 arg3
924 .Ve
925 .Sp
926 is equivalent to
927 .Sp
928 .Vb 1
929 \& \-\-foo \-\-bar arg1 arg2 arg3
930 .Ve
931 .Sp
932 If an argument callback routine is specified, \f(CW@ARGV\fR will always be
933 empty upon successful return of \fBGetOptions()\fR since all options have been
934 processed. The only exception is when \f(CW\*(C`\-\-\*(C'\fR is used:
935 .Sp
936 .Vb 1
937 \& \-\-foo arg1 \-\-bar arg2 \-\- arg3
938 .Ve
939 .Sp
940 This will call the callback routine for arg1 and arg2, and then
941 terminate \fBGetOptions()\fR leaving \f(CW"arg3"\fR in \f(CW@ARGV\fR.
942 .Sp
943 If \f(CW\*(C`require_order\*(C'\fR is enabled, options processing
944 terminates when the first non-option is encountered.
945 .Sp
946 .Vb 1
947 \& \-\-foo arg1 \-\-bar arg2 arg3
948 .Ve
949 .Sp
950 is equivalent to
951 .Sp
952 .Vb 1
953 \& \-\-foo \-\- arg1 \-\-bar arg2 arg3
954 .Ve
955 .Sp
956 If \f(CW\*(C`pass_through\*(C'\fR is also enabled, options processing will terminate
957 at the first unrecognized option, or non-option, whichever comes
958 first.
959 .IP "bundling (default: disabled)" 12
960 .IX Item "bundling (default: disabled)"
961 Enabling this option will allow single-character options to be
962 bundled. To distinguish bundles from long option names, long options
963 (and any of their auto-abbreviated shortened forms) \fImust\fR be
964 introduced with \f(CW\*(C`\-\-\*(C'\fR and bundles with \f(CW\*(C`\-\*(C'\fR.
965 .Sp
966 Note that, if you have options \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`l\*(C'\fR and \f(CW\*(C`all\*(C'\fR, and
967 auto_abbrev enabled, possible arguments and option settings are:
968 .Sp
969 .Vb 6
970 \& using argument sets option(s)
971 \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
972 \& \-a, \-\-a a
973 \& \-l, \-\-l l
974 \& \-al, \-la, \-ala, \-all,... a, l
975 \& \-\-al, \-\-all all
976 .Ve
977 .Sp
978 The surprising part is that \f(CW\*(C`\-\-a\*(C'\fR sets option \f(CW\*(C`a\*(C'\fR (due to auto
979 completion), not \f(CW\*(C`all\*(C'\fR.
980 .Sp
981 Note: disabling \f(CW\*(C`bundling\*(C'\fR also disables \f(CW\*(C`bundling_override\*(C'\fR.
982 .IP "bundling_override (default: disabled)" 12
983 .IX Item "bundling_override (default: disabled)"
984 If \f(CW\*(C`bundling_override\*(C'\fR is enabled, bundling is enabled as with
985 \&\f(CW\*(C`bundling\*(C'\fR but now long option names override option bundles.
986 .Sp
987 Note: disabling \f(CW\*(C`bundling_override\*(C'\fR also disables \f(CW\*(C`bundling\*(C'\fR.
988 .Sp
989 \&\fBNote:\fR Using option bundling can easily lead to unexpected results,
990 especially when mixing long options and bundles. Caveat emptor.
991 .IP "ignore_case (default: enabled)" 12
992 .IX Item "ignore_case (default: enabled)"
993 If enabled, case is ignored when matching option names. If, however,
994 bundling is enabled as well, single character options will be treated
995 case-sensitive.
996 .Sp
997 With \f(CW\*(C`ignore_case\*(C'\fR, option specifications for options that only
998 differ in case, e.g., \f(CW"foo"\fR and \f(CW"Foo"\fR, will be flagged as
999 duplicates.
1000 .Sp
1001 Note: disabling \f(CW\*(C`ignore_case\*(C'\fR also disables \f(CW\*(C`ignore_case_always\*(C'\fR.
1002 .IP "ignore_case_always (default: disabled)" 12
1003 .IX Item "ignore_case_always (default: disabled)"
1004 When bundling is in effect, case is ignored on single-character
1005 options also.
1006 .Sp
1007 Note: disabling \f(CW\*(C`ignore_case_always\*(C'\fR also disables \f(CW\*(C`ignore_case\*(C'\fR.
1008 .IP "auto_version (default:disabled)" 12
1009 .IX Item "auto_version (default:disabled)"
1010 Automatically provide support for the \fB\-\-version\fR option if
1011 the application did not specify a handler for this option itself.
1012 .Sp
1013 Getopt::Long will provide a standard version message that includes the
1014 program name, its version (if \f(CW$main::VERSION\fR is defined), and the
1015 versions of Getopt::Long and Perl. The message will be written to
1016 standard output and processing will terminate.
1017 .Sp
1018 \&\f(CW\*(C`auto_version\*(C'\fR will be enabled if the calling program explicitly
1019 specified a version number higher than 2.32 in the \f(CW\*(C`use\*(C'\fR or
1020 \&\f(CW\*(C`require\*(C'\fR statement.
1021 .IP "auto_help (default:disabled)" 12
1022 .IX Item "auto_help (default:disabled)"
1023 Automatically provide support for the \fB\-\-help\fR and \fB\-?\fR options if
1024 the application did not specify a handler for this option itself.
1025 .Sp
1026 Getopt::Long will provide a help message using module Pod::Usage. The
1027 message, derived from the SYNOPSIS POD section, will be written to
1028 standard output and processing will terminate.
1029 .Sp
1030 \&\f(CW\*(C`auto_help\*(C'\fR will be enabled if the calling program explicitly
1031 specified a version number higher than 2.32 in the \f(CW\*(C`use\*(C'\fR or
1032 \&\f(CW\*(C`require\*(C'\fR statement.
1033 .IP "pass_through (default: disabled)" 12
1034 .IX Item "pass_through (default: disabled)"
1035 With \f(CW\*(C`pass_through\*(C'\fR anything that is unknown, ambiguous or supplied with
1036 an invalid option will not be flagged as an error. Instead the unknown
1037 option(s) will be passed to the catchall \f(CW\*(C`<>\*(C'\fR if present, otherwise
1038 through to \f(CW@ARGV\fR. This makes it possible to write wrapper scripts that
1039 process only part of the user supplied command line arguments, and pass the
1040 remaining options to some other program.
1041 .Sp
1042 If \f(CW\*(C`require_order\*(C'\fR is enabled, options processing will terminate at the
1043 first unrecognized option, or non-option, whichever comes first and all
1044 remaining arguments are passed to \f(CW@ARGV\fR instead of the catchall
1045 \&\f(CW\*(C`<>\*(C'\fR if present. However, if \f(CW\*(C`permute\*(C'\fR is enabled instead, results
1046 can become confusing.
1047 .Sp
1048 Note that the options terminator (default \f(CW\*(C`\-\-\*(C'\fR), if present, will
1049 also be passed through in \f(CW@ARGV\fR.
1050 .IP prefix 12
1051 .IX Item "prefix"
1052 The string that starts options. If a constant string is not
1053 sufficient, see \f(CW\*(C`prefix_pattern\*(C'\fR.
1054 .IP prefix_pattern 12
1055 .IX Item "prefix_pattern"
1056 A Perl pattern that identifies the strings that introduce options.
1057 Default is \f(CW\*(C`\-\-|\-|\e+\*(C'\fR unless environment variable
1058 POSIXLY_CORRECT has been set, in which case it is \f(CW\*(C`\-\-|\-\*(C'\fR.
1059 .IP long_prefix_pattern 12
1060 .IX Item "long_prefix_pattern"
1061 A Perl pattern that allows the disambiguation of long and short
1062 prefixes. Default is \f(CW\*(C`\-\-\*(C'\fR.
1063 .Sp
1064 Typically you only need to set this if you are using nonstandard
1065 prefixes and want some or all of them to have the same semantics as
1066 \&'\-\-' does under normal circumstances.
1067 .Sp
1068 For example, setting prefix_pattern to \f(CW\*(C`\-\-|\-|\e+|\e/\*(C'\fR and
1069 long_prefix_pattern to \f(CW\*(C`\-\-|\e/\*(C'\fR would add Win32 style argument
1070 handling.
1071 .IP "debug (default: disabled)" 12
1072 .IX Item "debug (default: disabled)"
1073 Enable debugging output.
1074 .SH "Exportable Methods"
1075 .IX Header "Exportable Methods"
1076 .IP VersionMessage 4
1077 .IX Item "VersionMessage"
1078 This subroutine provides a standard version message. Its argument can be:
1079 .RS 4
1080 .IP \(bu 4
1081 A string containing the text of a message to print \fIbefore\fR printing
1082 the standard message.
1083 .IP \(bu 4
1084 A numeric value corresponding to the desired exit status.
1085 .IP \(bu 4
1086 A reference to a hash.
1087 .RE
1088 .RS 4
1089 .Sp
1090 If more than one argument is given then the entire argument list is
1091 assumed to be a hash. If a hash is supplied (either as a reference or
1092 as a list) it should contain one or more elements with the following
1093 keys:
1094 .ie n .IP """\-message""" 4
1095 .el .IP \f(CW\-message\fR 4
1096 .IX Item "-message"
1097 .PD 0
1098 .ie n .IP """\-msg""" 4
1099 .el .IP \f(CW\-msg\fR 4
1100 .IX Item "-msg"
1101 .PD
1102 The text of a message to print immediately prior to printing the
1103 program's usage message.
1104 .ie n .IP """\-exitval""" 4
1105 .el .IP \f(CW\-exitval\fR 4
1106 .IX Item "-exitval"
1107 The desired exit status to pass to the \fBexit()\fR function.
1108 This should be an integer, or else the string "NOEXIT" to
1109 indicate that control should simply be returned without
1110 terminating the invoking process.
1111 .ie n .IP """\-output""" 4
1112 .el .IP \f(CW\-output\fR 4
1113 .IX Item "-output"
1114 A reference to a filehandle, or the pathname of a file to which the
1115 usage message should be written. The default is \f(CW\*(C`\e*STDERR\*(C'\fR unless the
1116 exit value is less than 2 (in which case the default is \f(CW\*(C`\e*STDOUT\*(C'\fR).
1117 .RE
1118 .RS 4
1119 .Sp
1120 You cannot tie this routine directly to an option, e.g.:
1121 .Sp
1122 .Vb 1
1123 \& GetOptions("version" => \e&VersionMessage);
1124 .Ve
1125 .Sp
1126 Use this instead:
1127 .Sp
1128 .Vb 1
1129 \& GetOptions("version" => sub { VersionMessage() });
1130 .Ve
1131 .RE
1132 .IP HelpMessage 4
1133 .IX Item "HelpMessage"
1134 This subroutine produces a standard help message, derived from the
1135 program's POD section SYNOPSIS using Pod::Usage. It takes the same
1136 arguments as \fBVersionMessage()\fR. In particular, you cannot tie it
1137 directly to an option, e.g.:
1138 .Sp
1139 .Vb 1
1140 \& GetOptions("help" => \e&HelpMessage);
1141 .Ve
1142 .Sp
1143 Use this instead:
1144 .Sp
1145 .Vb 1
1146 \& GetOptions("help" => sub { HelpMessage() });
1147 .Ve
1148 .SH "Return values and Errors"
1149 .IX Header "Return values and Errors"
1150 Configuration errors and errors in the option definitions are
1151 signalled using \fBdie()\fR and will terminate the calling program unless
1152 the call to \fBGetopt::Long::GetOptions()\fR was embedded in \f(CW\*(C`eval { ...
1153 }\*(C'\fR, or \fBdie()\fR was trapped using \f(CW$SIG{_\|_DIE_\|_}\fR.
1154 .PP
1155 GetOptions returns true to indicate success.
1156 It returns false when the function detected one or more errors during
1157 option parsing. These errors are signalled using \fBwarn()\fR and can be
1158 trapped with \f(CW$SIG{_\|_WARN_\|_}\fR.
1159 .SH Legacy
1160 .IX Header "Legacy"
1161 The earliest development of \f(CW\*(C`newgetopt.pl\*(C'\fR started in 1990, with Perl
1162 version 4. As a result, its development, and the development of
1163 Getopt::Long, has gone through several stages. Since backward
1164 compatibility has always been extremely important, the current version
1165 of Getopt::Long still supports a lot of constructs that nowadays are
1166 no longer necessary or otherwise unwanted. This section describes
1167 briefly some of these 'features'.
1168 .SS "Default destinations"
1169 .IX Subsection "Default destinations"
1170 When no destination is specified for an option, GetOptions will store
1171 the resultant value in a global variable named \f(CW\*(C`opt_\*(C'\fR\fIXXX\fR, where
1172 \&\fIXXX\fR is the primary name of this option. When a program executes
1173 under \f(CW\*(C`use strict\*(C'\fR (recommended), these variables must be
1174 pre-declared with \fBour()\fR.
1175 .PP
1176 .Vb 2
1177 \& our $opt_length = 0;
1178 \& GetOptions (\*(Aqlength=i\*(Aq); # will store in $opt_length
1179 .Ve
1180 .PP
1181 To yield a usable Perl variable, characters that are not part of the
1182 syntax for variables are translated to underscores. For example,
1183 \&\f(CW\*(C`\-\-fpp\-struct\-return\*(C'\fR will set the variable
1184 \&\f(CW$opt_fpp_struct_return\fR. Note that this variable resides in the
1185 namespace of the calling program, not necessarily \f(CW\*(C`main\*(C'\fR. For
1186 example:
1187 .PP
1188 .Vb 1
1189 \& GetOptions ("size=i", "sizes=i@");
1190 .Ve
1191 .PP
1192 with command line "\-size 10 \-sizes 24 \-sizes 48" will perform the
1193 equivalent of the assignments
1194 .PP
1195 .Vb 2
1196 \& $opt_size = 10;
1197 \& @opt_sizes = (24, 48);
1198 .Ve
1199 .SS "Alternative option starters"
1200 .IX Subsection "Alternative option starters"
1201 A string of alternative option starter characters may be passed as the
1202 first argument (or the first argument after a leading hash reference
1203 argument).
1204 .PP
1205 .Vb 2
1206 \& my $len = 0;
1207 \& GetOptions (\*(Aq/\*(Aq, \*(Aqlength=i\*(Aq => $len);
1208 .Ve
1209 .PP
1210 Now the command line may look like:
1211 .PP
1212 .Vb 1
1213 \& /length 24 \-\- arg
1214 .Ve
1215 .PP
1216 Note that to terminate options processing still requires a double dash
1217 \&\f(CW\*(C`\-\-\*(C'\fR.
1218 .PP
1219 \&\fBGetOptions()\fR will not interpret a leading \f(CW"<>"\fR as option starters
1220 if the next argument is a reference. To force \f(CW"<"\fR and \f(CW">"\fR as
1221 option starters, use \f(CW"><"\fR. Confusing? Well, \fBusing a starter
1222 argument is strongly deprecated\fR anyway.
1223 .SS "Configuration variables"
1224 .IX Subsection "Configuration variables"
1225 Previous versions of Getopt::Long used variables for the purpose of
1226 configuring. Although manipulating these variables still work, it is
1227 strongly encouraged to use the \f(CW\*(C`Configure\*(C'\fR routine that was introduced
1228 in version 2.17. Besides, it is much easier.
1229 .SH "Tips and Techniques"
1230 .IX Header "Tips and Techniques"
1231 .SS "Pushing multiple values in a hash option"
1232 .IX Subsection "Pushing multiple values in a hash option"
1233 Sometimes you want to combine the best of hashes and arrays. For
1234 example, the command line:
1235 .PP
1236 .Vb 1
1237 \& \-\-list add=first \-\-list add=second \-\-list add=third
1238 .Ve
1239 .PP
1240 where each successive 'list add' option will push the value of add
1241 into array ref \f(CW$list\fR\->{'add'}. The result would be like
1242 .PP
1243 .Vb 1
1244 \& $list\->{add} = [qw(first second third)];
1245 .Ve
1246 .PP
1247 This can be accomplished with a destination routine:
1248 .PP
1249 .Vb 2
1250 \& GetOptions(\*(Aqlist=s%\*(Aq =>
1251 \& sub { push(@{$list{$_[1]}}, $_[2]) });
1252 .Ve
1253 .SH Troubleshooting
1254 .IX Header "Troubleshooting"
1255 .SS "GetOptions does not return a false result when an option is not supplied"
1256 .IX Subsection "GetOptions does not return a false result when an option is not supplied"
1257 That's why they're called 'options'.
1258 .SS "GetOptions does not split the command line correctly"
1259 .IX Subsection "GetOptions does not split the command line correctly"
1260 The command line is not split by GetOptions, but by the command line
1261 interpreter (CLI). On Unix, this is the shell. On Windows, it is
1262 COMMAND.COM or CMD.EXE. Other operating systems have other CLIs.
1263 .PP
1264 It is important to know that these CLIs may behave different when the
1265 command line contains special characters, in particular quotes or
1266 backslashes. For example, with Unix shells you can use single quotes
1267 (\f(CW\*(C`\*(Aq\*(C'\fR) and double quotes (\f(CW\*(C`"\*(C'\fR) to group words together. The following
1268 alternatives are equivalent on Unix:
1269 .PP
1270 .Vb 3
1271 \& "two words"
1272 \& \*(Aqtwo words\*(Aq
1273 \& two\e words
1274 .Ve
1275 .PP
1276 In case of doubt, insert the following statement in front of your Perl
1277 program:
1278 .PP
1279 .Vb 1
1280 \& print STDERR (join("|",@ARGV),"\en");
1281 .Ve
1282 .PP
1283 to verify how your CLI passes the arguments to the program.
1284 .SS "Undefined subroutine &main::GetOptions called"
1285 .IX Subsection "Undefined subroutine &main::GetOptions called"
1286 Are you running Windows, and did you write
1287 .PP
1288 .Vb 1
1289 \& use GetOpt::Long;
1290 .Ve
1291 .PP
1292 (note the capital 'O')?
1293 .SS "How do I put a ""\-?"" option into a Getopt::Long?"
1294 .IX Subsection "How do I put a ""-?"" option into a Getopt::Long?"
1295 You can only obtain this using an alias, and Getopt::Long of at least
1296 version 2.13.
1297 .PP
1298 .Vb 2
1299 \& use Getopt::Long;
1300 \& GetOptions ("help|?"); # \-help and \-? will both set $opt_help
1301 .Ve
1302 .PP
1303 Other characters that can't appear in Perl identifiers are also
1304 supported in aliases with Getopt::Long of at version 2.39. Note that
1305 the characters \f(CW\*(C`!\*(C'\fR, \f(CW\*(C`|\*(C'\fR, \f(CW\*(C`+\*(C'\fR, \f(CW\*(C`=\*(C'\fR, and \f(CW\*(C`:\*(C'\fR can only appear as the
1306 first (or only) character of an alias.
1307 .PP
1308 As of version 2.32 Getopt::Long provides auto-help, a quick and easy way
1309 to add the options \-\-help and \-? to your program, and handle them.
1310 .PP
1311 See \f(CW\*(C`auto_help\*(C'\fR in section "Configuring Getopt::Long".
1312 .SH AUTHOR
1313 .IX Header "AUTHOR"
1314 Johan Vromans <[email protected]>
1315 .SH "COPYRIGHT AND DISCLAIMER"
1316 .IX Header "COPYRIGHT AND DISCLAIMER"
1317 This program is Copyright 1990,2015,2023 by Johan Vromans.
1318 This program is free software; you can redistribute it and/or
1319 modify it under the terms of the Perl Artistic License or the
1320 GNU General Public License as published by the Free Software
1321 Foundation; either version 2 of the License, or (at your option) any
1322 later version.
1323 .PP
1324 This program is distributed in the hope that it will be useful,
1325 but WITHOUT ANY WARRANTY; without even the implied warranty of
1326 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1327 GNU General Public License for more details.
1328 .PP
1329 If you do not have a copy of the GNU General Public License write to
1330 the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,
1331 MA 02139, USA.