Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Getopt::Long.3pm

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