1Getopt::Long(3pm) Perl Programmers Reference Guide Getopt::Long(3pm)
2
6 Getopt::Long - Extended processing of command line options
7
9 use Getopt::Long;
10 my $data = "file.dat";
11 my $length = 24;
12 my $verbose;
13 $result = GetOptions ("length=i" => \$length, # numeric
14 "file=s" => \$data, # string
15 "verbose" => \$verbose); # flag
16
18 The Getopt::Long module implements an extended getopt function called
19 GetOptions(). This function adheres to the POSIX syntax for command
20 line options, with GNU extensions. In general, this means that options
21 have long names instead of single letters, and are introduced with a
22 double dash "--". Support for bundling of command line options, as was
23 the case with the more traditional single-letter approach, is provided
24 but not enabled by default.
25
27 Command line operated programs traditionally take their arguments from
28 the command line, for example filenames or other information that the
29 program needs to know. Besides arguments, these programs often take
30 command line options as well. Options are not necessary for the program
31 to work, hence the name 'option', but are used to modify its default
32 behaviour. For example, a program could do its job quietly, but with a
33 suitable option it could provide verbose information about what it did.
34 Command line options come in several flavours. Historically, they are
36 preceded by a single dash "-", and consist of a single letter.
37 -l -a -c
39 Usually, these single-character options can be bundled:
41 -lac
43 Options can have values, the value is placed after the option charac‐
45 ter. Sometimes with whitespace in between, sometimes not:
46 -s 24 -s24
48 Due to the very cryptic nature of these options, another style was
50 developed that used long names. So instead of a cryptic "-l" one could
51 use the more descriptive "--long". To distinguish between a bundle of
52 single-character options and a long one, two dashes are used to precede
53 the option name. Early implementations of long options used a plus "+"
54 instead. Also, option values could be specified either like
55 --size=24
57 or
59 --size 24
61 The "+" form is now obsolete and strongly deprecated.
63
65 Getopt::Long is the Perl5 successor of "newgetopt.pl". This was the
66 first Perl module that provided support for handling the new style of
67 command line options, hence the name Getopt::Long. This module also
68 supports single-character options and bundling. Single character
69 options may be any alphabetic character, a question mark, and a dash.
70 Long options may consist of a series of letters, digits, and dashes.
71 Although this is currently not enforced by Getopt::Long, multiple con‐
72 secutive dashes are not allowed, and the option name must not end with
73 a dash.
74 To use Getopt::Long from a Perl program, you must include the following
76 line in your Perl program:
77 use Getopt::Long;
79 This will load the core of the Getopt::Long module and prepare your
81 program for using it. Most of the actual Getopt::Long code is not
82 loaded until you really call one of its functions.
83 In the default configuration, options names may be abbreviated to
85 uniqueness, case does not matter, and a single dash is sufficient, even
86 for long option names. Also, options may be placed between non-option
87 arguments. See "Configuring Getopt::Long" for more details on how to
88 configure Getopt::Long.
89 Simple options
91 The most simple options are the ones that take no values. Their mere
93 presence on the command line enables the option. Popular examples are:
94 --all --verbose --quiet --debug
96 Handling simple options is straightforward:
98 my $verbose = ''; # option variable with default value (false)
100 my $all = ''; # option variable with default value (false)
101 GetOptions ('verbose' => \$verbose, 'all' => \$all);
102 The call to GetOptions() parses the command line arguments that are
104 present in @ARGV and sets the option variable to the value 1 if the
105 option did occur on the command line. Otherwise, the option variable is
106 not touched. Setting the option value to true is often called enabling
107 the option.
108 The option name as specified to the GetOptions() function is called the
110 option specification. Later we'll see that this specification can con‐
111 tain more than just the option name. The reference to the variable is
112 called the option destination.
113 GetOptions() will return a true value if the command line could be pro‐
115 cessed successfully. Otherwise, it will write error messages to STDERR,
116 and return a false result.
117 A little bit less simple options
119 Getopt::Long supports two useful variants of simple options: negatable
121 options and incremental options.
122 A negatable option is specified with an exclamation mark "!" after the
124 option name:
125 my $verbose = ''; # option variable with default value (false)
127 GetOptions ('verbose!' => \$verbose);
128 Now, using "--verbose" on the command line will enable $verbose, as
130 expected. But it is also allowed to use "--noverbose", which will dis‐
131 able $verbose by setting its value to 0. Using a suitable default
132 value, the program can find out whether $verbose is false by default,
133 or disabled by using "--noverbose".
134 An incremental option is specified with a plus "+" after the option
136 name:
137 my $verbose = ''; # option variable with default value (false)
139 GetOptions ('verbose+' => \$verbose);
140 Using "--verbose" on the command line will increment the value of $ver‐
142 bose. This way the program can keep track of how many times the option
143 occurred on the command line. For example, each occurrence of "--ver‐
144 bose" could increase the verbosity level of the program.
145 Mixing command line option with other arguments
147 Usually programs take command line options as well as other arguments,
149 for example, file names. It is good practice to always specify the
150 options first, and the other arguments last. Getopt::Long will, how‐
151 ever, allow the options and arguments to be mixed and 'filter out' all
152 the options before passing the rest of the arguments to the program. To
153 stop Getopt::Long from processing further arguments, insert a double
154 dash "--" on the command line:
155 --size 24 -- --all
157 In this example, "--all" will not be treated as an option, but passed
159 to the program unharmed, in @ARGV.
160 Options with values
162 For options that take values it must be specified whether the option
164 value is required or not, and what kind of value the option expects.
165 Three kinds of values are supported: integer numbers, floating point
167 numbers, and strings.
168 If the option value is required, Getopt::Long will take the command
170 line argument that follows the option and assign this to the option
171 variable. If, however, the option value is specified as optional, this
172 will only be done if that value does not look like a valid command line
173 option itself.
174 my $tag = ''; # option variable with default value
176 GetOptions ('tag=s' => \$tag);
177 In the option specification, the option name is followed by an equals
179 sign "=" and the letter "s". The equals sign indicates that this option
180 requires a value. The letter "s" indicates that this value is an arbi‐
181 trary string. Other possible value types are "i" for integer values,
182 and "f" for floating point values. Using a colon ":" instead of the
183 equals sign indicates that the option value is optional. In this case,
184 if no suitable value is supplied, string valued options get an empty
185 string '' assigned, while numeric options are set to 0.
186 Options with multiple values
188 Options sometimes take several values. For example, a program could use
190 multiple directories to search for library files:
191 --library lib/stdlib --library lib/extlib
193 To accomplish this behaviour, simply specify an array reference as the
195 destination for the option:
196 GetOptions ("library=s" => \@libfiles);
198 Alternatively, you can specify that the option can have multiple values
200 by adding a "@", and pass a scalar reference as the destination:
201 GetOptions ("library=s@" => \$libfiles);
203 Used with the example above, @libfiles (or @$libfiles) would contain
205 two strings upon completion: "lib/srdlib" and "lib/extlib", in that
206 order. It is also possible to specify that only integer or floating
207 point numbers are acceptable values.
208 Often it is useful to allow comma-separated lists of values as well as
210 multiple occurrences of the options. This is easy using Perl's split()
211 and join() operators:
212 GetOptions ("library=s" => \@libfiles);
214 @libfiles = split(/,/,join(',',@libfiles));
215 Of course, it is important to choose the right separator string for
217 each purpose.
218 Warning: What follows is an experimental feature.
220 Options can take multiple values at once, for example
222 --coordinates 52.2 16.4 --rgbcolor 255 255 149
224 This can be accomplished by adding a repeat specifier to the option
226 specification. Repeat specifiers are very similar to the "{...}" repeat
227 specifiers that can be used with regular expression patterns. For
228 example, the above command line would be handled as follows:
229 GetOptions('coordinates=f{2}' => \@coor, 'rgbcolor=i{3}' => \@color);
231 The destination for the option must be an array or array reference.
233 It is also possible to specify the minimal and maximal number of argu‐
235 ments an option takes. "foo=s{2,4}" indicates an option that takes at
236 least two and at most 4 arguments. "foo=s{,}" indicates one or more
237 values; "foo:s{,}" indicates zero or more option values.
238 Options with hash values
240 If the option destination is a reference to a hash, the option will
242 take, as value, strings of the form key"="value. The value will be
243 stored with the specified key in the hash.
244 GetOptions ("define=s" => \%defines);
246 Alternatively you can use:
248 GetOptions ("define=s%" => \$defines);
250 When used with command line options:
252 --define os=linux --define vendor=redhat
254 the hash %defines (or %$defines) will contain two keys, "os" with value
256 ""linux" and "vendor" with value "redhat". It is also possible to spec‐
257 ify that only integer or floating point numbers are acceptable values.
258 The keys are always taken to be strings.
259 User-defined subroutines to handle options
261 Ultimate control over what should be done when (actually: each time) an
263 option is encountered on the command line can be achieved by designat‐
264 ing a reference to a subroutine (or an anonymous subroutine) as the
265 option destination. When GetOptions() encounters the option, it will
266 call the subroutine with two or three arguments. The first argument is
267 the name of the option. For a scalar or array destination, the second
268 argument is the value to be stored. For a hash destination, the second
269 arguments is the key to the hash, and the third argument the value to
270 be stored. It is up to the subroutine to store the value, or do what‐
271 ever it thinks is appropriate.
272 A trivial application of this mechanism is to implement options that
274 are related to each other. For example:
275 my $verbose = ''; # option variable with default value (false)
277 GetOptions ('verbose' => \$verbose,
278 'quiet' => sub { $verbose = 0 });
279 Here "--verbose" and "--quiet" control the same variable $verbose, but
281 with opposite values.
282 If the subroutine needs to signal an error, it should call die() with
284 the desired error message as its argument. GetOptions() will catch the
285 die(), issue the error message, and record that an error result must be
286 returned upon completion.
287 If the text of the error message starts with an exclamation mark "!"
289 it is interpreted specially by GetOptions(). There is currently one
290 special command implemented: "die("!FINISH")" will cause GetOptions()
291 to stop processing options, as if it encountered a double dash "--".
292 Options with multiple names
294 Often it is user friendly to supply alternate mnemonic names for
296 options. For example "--height" could be an alternate name for
297 "--length". Alternate names can be included in the option specifica‐
298 tion, separated by vertical bar "⎪" characters. To implement the above
299 example:
300 GetOptions ('length⎪height=f' => \$length);
302 The first name is called the primary name, the other names are called
304 aliases. When using a hash to store options, the key will always be the
305 primary name.
306 Multiple alternate names are possible.
308 Case and abbreviations
310 Without additional configuration, GetOptions() will ignore the case of
312 option names, and allow the options to be abbreviated to uniqueness.
313 GetOptions ('length⎪height=f' => \$length, "head" => \$head);
315 This call will allow "--l" and "--L" for the length option, but
317 requires a least "--hea" and "--hei" for the head and height options.
318 Summary of Option Specifications
320 Each option specifier consists of two parts: the name specification and
322 the argument specification.
323 The name specification contains the name of the option, optionally fol‐
325 lowed by a list of alternative names separated by vertical bar charac‐
326 ters.
327 length option name is "length"
329 length⎪size⎪l name is "length", aliases are "size" and "l"
330 The argument specification is optional. If omitted, the option is con‐
332 sidered boolean, a value of 1 will be assigned when the option is used
333 on the command line.
334 The argument specification can be
336 ! The option does not take an argument and may be negated by prefix‐
338 ing it with "no" or "no-". E.g. "foo!" will allow "--foo" (a value
339 of 1 will be assigned) as well as "--nofoo" and "--no-foo" (a value
340 of 0 will be assigned). If the option has aliases, this applies to
341 the aliases as well.
342 Using negation on a single letter option when bundling is in effect
344 is pointless and will result in a warning.
345 + The option does not take an argument and will be incremented by 1
347 every time it appears on the command line. E.g. "more+", when used
348 with "--more --more --more", will increment the value three times,
349 resulting in a value of 3 (provided it was 0 or undefined at
350 first).
351 The "+" specifier is ignored if the option destination is not a
353 scalar.
354 = type [ desttype ] [ repeat ]
356 The option requires an argument of the given type. Supported types
357 are:
358 s String. An arbitrary sequence of characters. It is valid for
360 the argument to start with "-" or "--".
361 i Integer. An optional leading plus or minus sign, followed by a
363 sequence of digits.
364 o Extended integer, Perl style. This can be either an optional
366 leading plus or minus sign, followed by a sequence of digits,
367 or an octal string (a zero, optionally followed by '0', '1', ..
368 '7'), or a hexadecimal string ("0x" followed by '0' .. '9', 'a'
369 .. 'f', case insensitive), or a binary string ("0b" followed by
370 a series of '0' and '1').
371 f Real number. For example 3.14, "-6.23E24" and so on.
373 The desttype can be "@" or "%" to specify that the option is list
375 or a hash valued. This is only needed when the destination for the
376 option value is not otherwise specified. It should be omitted when
377 not needed.
378 The repeat specifies the number of values this option takes per
380 occurrence on the command line. It has the format "{" [ min ] [ ","
381 [ max ] ] "}".
382 min denotes the minimal number of arguments. It defaults to 1 for
384 options with "=" and to 0 for options with ":", see below. Note
385 that min overrules the "=" / ":" semantics.
386 max denotes the maximum number of arguments. It must be at least
388 min. If max is omitted, but the comma is not, there is no upper
389 bound to the number of argument values taken.
390 : type [ desttype ]
392 Like "=", but designates the argument as optional. If omitted, an
393 empty string will be assigned to string values options, and the
394 value zero to numeric options.
395 Note that if a string argument starts with "-" or "--", it will be
397 considered an option on itself.
398 : number [ desttype ]
400 Like ":i", but if the value is omitted, the number will be
401 assigned.
402 : + [ desttype ]
404 Like ":i", but if the value is omitted, the current value for the
405 option will be incremented.
406
408 Object oriented interface
409 Getopt::Long can be used in an object oriented way as well:
411 use Getopt::Long;
413 $p = new Getopt::Long::Parser;
414 $p->configure(...configuration options...);
415 if ($p->getoptions(...options descriptions...)) ...
416 Configuration options can be passed to the constructor:
418 $p = new Getopt::Long::Parser
420 config => [...configuration options...];
421 Thread Safety
423 Getopt::Long is thread safe when using ithreads as of Perl 5.8. It is
425 not thread safe when using the older (experimental and now obsolete)
426 threads implementation that was added to Perl 5.005.
427 Documentation and help texts
429 Getopt::Long encourages the use of Pod::Usage to produce help messages.
431 For example:
432 use Getopt::Long;
434 use Pod::Usage;
435 my $man = 0;
437 my $help = 0;
438 GetOptions('help⎪?' => \$help, man => \$man) or pod2usage(2);
440 pod2usage(1) if $help;
441 pod2usage(-exitstatus => 0, -verbose => 2) if $man;
442 __END__
444 =head1 NAME
446 sample - Using Getopt::Long and Pod::Usage
448 =head1 SYNOPSIS
450 sample [options] [file ...]
452 Options:
454 -help brief help message
455 -man full documentation
456 =head1 OPTIONS
458 =over 8
460 =item B<-help>
462 Print a brief help message and exits.
464 =item B<-man>
466 Prints the manual page and exits.
468 =back
470 =head1 DESCRIPTION
472 B<This program> will read the given input file(s) and do something
474 useful with the contents thereof.
475 =cut
477 See Pod::Usage for details.
479 Storing option values in a hash
481 Sometimes, for example when there are a lot of options, having a sepa‐
483 rate variable for each of them can be cumbersome. GetOptions() sup‐
484 ports, as an alternative mechanism, storing options in a hash.
485 To obtain this, a reference to a hash must be passed as the first argu‐
487 ment to GetOptions(). For each option that is specified on the command
488 line, the option value will be stored in the hash with the option name
489 as key. Options that are not actually used on the command line will not
490 be put in the hash, on other words, "exists($h{option})" (or defined())
491 can be used to test if an option was used. The drawback is that warn‐
492 ings will be issued if the program runs under "use strict" and uses
493 $h{option} without testing with exists() or defined() first.
494 my %h = ();
496 GetOptions (\%h, 'length=i'); # will store in $h{length}
497 For options that take list or hash values, it is necessary to indicate
499 this by appending an "@" or "%" sign after the type:
500 GetOptions (\%h, 'colours=s@'); # will push to @{$h{colours}}
502 To make things more complicated, the hash may contain references to the
504 actual destinations, for example:
505 my $len = 0;
507 my %h = ('length' => \$len);
508 GetOptions (\%h, 'length=i'); # will store in $len
509 This example is fully equivalent with:
511 my $len = 0;
513 GetOptions ('length=i' => \$len); # will store in $len
514 Any mixture is possible. For example, the most frequently used options
516 could be stored in variables while all other options get stored in the
517 hash:
518 my $verbose = 0; # frequently referred
520 my $debug = 0; # frequently referred
521 my %h = ('verbose' => \$verbose, 'debug' => \$debug);
522 GetOptions (\%h, 'verbose', 'debug', 'filter', 'size=i');
523 if ( $verbose ) { ... }
524 if ( exists $h{filter} ) { ... option 'filter' was specified ... }
525 Bundling
527 With bundling it is possible to set several single-character options at
529 once. For example if "a", "v" and "x" are all valid options,
530 -vax
532 would set all three.
534 Getopt::Long supports two levels of bundling. To enable bundling, a
536 call to Getopt::Long::Configure is required.
537 The first level of bundling can be enabled with:
539 Getopt::Long::Configure ("bundling");
541 Configured this way, single-character options can be bundled but long
543 options must always start with a double dash "--" to avoid ambiguity.
544 For example, when "vax", "a", "v" and "x" are all valid options,
545 -vax
547 would set "a", "v" and "x", but
549 --vax
551 would set "vax".
553 The second level of bundling lifts this restriction. It can be enabled
555 with:
556 Getopt::Long::Configure ("bundling_override");
558 Now, "-vax" would set the option "vax".
560 When any level of bundling is enabled, option values may be inserted in
562 the bundle. For example:
563 -h24w80
565 is equivalent to
567 -h 24 -w 80
569 When configured for bundling, single-character options are matched case
571 sensitive while long options are matched case insensitive. To have the
572 single-character options matched case insensitive as well, use:
573 Getopt::Long::Configure ("bundling", "ignorecase_always");
575 It goes without saying that bundling can be quite confusing.
577 The lonesome dash
579 Normally, a lone dash "-" on the command line will not be considered an
581 option. Option processing will terminate (unless "permute" is config‐
582 ured) and the dash will be left in @ARGV.
583 It is possible to get special treatment for a lone dash. This can be
585 achieved by adding an option specification with an empty name, for
586 example:
587 GetOptions ('' => \$stdio);
589 A lone dash on the command line will now be a legal option, and using
591 it will set variable $stdio.
592 Argument callback
594 A special option 'name' "<>" can be used to designate a subroutine to
596 handle non-option arguments. When GetOptions() encounters an argument
597 that does not look like an option, it will immediately call this sub‐
598 routine and passes it one parameter: the argument name.
599 For example:
601 my $width = 80;
603 sub process { ... }
604 GetOptions ('width=i' => \$width, '<>' => \&process);
605 When applied to the following command line:
607 arg1 --width=72 arg2 --width=60 arg3
609 This will call "process("arg1")" while $width is 80, "process("arg2")"
611 while $width is 72, and "process("arg3")" while $width is 60.
612 This feature requires configuration option permute, see section "Con‐
614 figuring Getopt::Long".
615
617 Getopt::Long can be configured by calling subroutine Getopt::Long::Con‐
618 figure(). This subroutine takes a list of quoted strings, each specify‐
619 ing a configuration option to be enabled, e.g. "ignore_case", or dis‐
620 abled, e.g. "no_ignore_case". Case does not matter. Multiple calls to
621 Configure() are possible.
622 Alternatively, as of version 2.24, the configuration options may be
624 passed together with the "use" statement:
625 use Getopt::Long qw(:config no_ignore_case bundling);
627 The following options are available:
629 default This option causes all configuration options to be reset to
631 their default values.
632 posix_default
634 This option causes all configuration options to be reset to
635 their default values as if the environment variable
636 POSIXLY_CORRECT had been set.
637 auto_abbrev Allow option names to be abbreviated to uniqueness.
639 Default is enabled unless environment variable POSIXLY_COR‐
640 RECT has been set, in which case "auto_abbrev" is disabled.
641 getopt_compat
643 Allow "+" to start options. Default is enabled unless
644 environment variable POSIXLY_CORRECT has been set, in which
645 case "getopt_compat" is disabled.
646 gnu_compat "gnu_compat" controls whether "--opt=" is allowed, and what
648 it should do. Without "gnu_compat", "--opt=" gives an
649 error. With "gnu_compat", "--opt=" will give option "opt"
650 and empty value. This is the way GNU getopt_long() does
651 it.
652 gnu_getopt This is a short way of setting "gnu_compat" "bundling"
654 "permute" "no_getopt_compat". With "gnu_getopt", command
655 line handling should be fully compatible with GNU
656 getopt_long().
657 require_order
659 Whether command line arguments are allowed to be mixed with
660 options. Default is disabled unless environment variable
661 POSIXLY_CORRECT has been set, in which case "require_order"
662 is enabled.
663 See also "permute", which is the opposite of
665 "require_order".
666 permute Whether command line arguments are allowed to be mixed with
668 options. Default is enabled unless environment variable
669 POSIXLY_CORRECT has been set, in which case "permute" is
670 disabled. Note that "permute" is the opposite of
671 "require_order".
672 If "permute" is enabled, this means that
674 --foo arg1 --bar arg2 arg3
676 is equivalent to
678 --foo --bar arg1 arg2 arg3
680 If an argument callback routine is specified, @ARGV will
682 always be empty upon successful return of GetOptions()
683 since all options have been processed. The only exception
684 is when "--" is used:
685 --foo arg1 --bar arg2 -- arg3
687 This will call the callback routine for arg1 and arg2, and
689 then terminate GetOptions() leaving "arg2" in @ARGV.
690 If "require_order" is enabled, options processing termi‐
692 nates when the first non-option is encountered.
693 --foo arg1 --bar arg2 arg3
695 is equivalent to
697 --foo -- arg1 --bar arg2 arg3
699 If "pass_through" is also enabled, options processing will
701 terminate at the first unrecognized option, or non-option,
702 whichever comes first.
703 bundling (default: disabled)
705 Enabling this option will allow single-character options to
706 be bundled. To distinguish bundles from long option names,
707 long options must be introduced with "--" and bundles with
708 "-".
709 Note that, if you have options "a", "l" and "all", and
711 auto_abbrev enabled, possible arguments and option settings
712 are:
713 using argument sets option(s)
715 ------------------------------------------
716 -a, --a a
717 -l, --l l
718 -al, -la, -ala, -all,... a, l
719 --al, --all all
720 The surprising part is that "--a" sets option "a" (due to
722 auto completion), not "all".
723 Note: disabling "bundling" also disables "bundling_over‐
725 ride".
726 bundling_override (default: disabled)
728 If "bundling_override" is enabled, bundling is enabled as
729 with "bundling" but now long option names override option
730 bundles.
731 Note: disabling "bundling_override" also disables
733 "bundling".
734 Note: Using option bundling can easily lead to unexpected
736 results, especially when mixing long options and bundles.
737 Caveat emptor.
738 ignore_case (default: enabled)
740 If enabled, case is ignored when matching long option
741 names. If, however, bundling is enabled as well, single
742 character options will be treated case-sensitive.
743 With "ignore_case", option specifications for options that
745 only differ in case, e.g., "foo" and "Foo", will be flagged
746 as duplicates.
747 Note: disabling "ignore_case" also disables
749 "ignore_case_always".
750 ignore_case_always (default: disabled)
752 When bundling is in effect, case is ignored on single-char‐
753 acter options also.
754 Note: disabling "ignore_case_always" also disables
756 "ignore_case".
757 auto_version (default:disabled)
759 Automatically provide support for the --version option if
760 the application did not specify a handler for this option
761 itself.
762 Getopt::Long will provide a standard version message that
764 includes the program name, its version (if $main::VERSION
765 is defined), and the versions of Getopt::Long and Perl. The
766 message will be written to standard output and processing
767 will terminate.
768 "auto_version" will be enabled if the calling program
770 explicitly specified a version number higher than 2.32 in
771 the "use" or "require" statement.
772 auto_help (default:disabled)
774 Automatically provide support for the --help and -? options
775 if the application did not specify a handler for this
776 option itself.
777 Getopt::Long will provide a help message using module
779 Pod::Usage. The message, derived from the SYNOPSIS POD sec‐
780 tion, will be written to standard output and processing
781 will terminate.
782 "auto_help" will be enabled if the calling program explic‐
784 itly specified a version number higher than 2.32 in the
785 "use" or "require" statement.
786 pass_through (default: disabled)
788 Options that are unknown, ambiguous or supplied with an
789 invalid option value are passed through in @ARGV instead of
790 being flagged as errors. This makes it possible to write
791 wrapper scripts that process only part of the user supplied
792 command line arguments, and pass the remaining options to
793 some other program.
794 If "require_order" is enabled, options processing will ter‐
796 minate at the first unrecognized option, or non-option,
797 whichever comes first. However, if "permute" is enabled
798 instead, results can become confusing.
799 Note that the options terminator (default "--"), if
801 present, will also be passed through in @ARGV.
802 prefix The string that starts options. If a constant string is not
804 sufficient, see "prefix_pattern".
805 prefix_pattern
807 A Perl pattern that identifies the strings that introduce
808 options. Default is "--⎪-⎪\+" unless environment variable
809 POSIXLY_CORRECT has been set, in which case it is "--⎪-".
810 long_prefix_pattern
812 A Perl pattern that allows the disambiguation of long and
813 short prefixes. Default is "--".
814 Typically you only need to set this if you are using non‐
816 standard prefixes and want some or all of them to have the
817 same semantics as '--' does under normal circumstances.
818 For example, setting prefix_pattern to "--⎪-⎪\+⎪\/" and
820 long_prefix_pattern to "--⎪\/" would add Win32 style argu‐
821 ment handling.
822 debug (default: disabled)
824 Enable debugging output.
825
827 VersionMessage
828 This subroutine provides a standard version message. Its argument
829 can be:
830 * A string containing the text of a message to print before
832 printing the standard message.
833 * A numeric value corresponding to the desired exit status.
835 * A reference to a hash.
837 If more than one argument is given then the entire argument list is
839 assumed to be a hash. If a hash is supplied (either as a reference
840 or as a list) it should contain one or more elements with the fol‐
841 lowing keys:
842 "-message"
844 "-msg"
845 The text of a message to print immediately prior to printing
846 the program's usage message.
847 "-exitval"
849 The desired exit status to pass to the exit() function. This
850 should be an integer, or else the string "NOEXIT" to indicate
851 that control should simply be returned without terminating the
852 invoking process.
853 "-output"
855 A reference to a filehandle, or the pathname of a file to which
856 the usage message should be written. The default is "\*STDERR"
857 unless the exit value is less than 2 (in which case the default
858 is "\*STDOUT").
859 You cannot tie this routine directly to an option, e.g.:
861 GetOptions("version" => \&VersionMessage);
863 Use this instead:
865 GetOptions("version" => sub { VersionMessage() });
867 HelpMessage
869 This subroutine produces a standard help message, derived from the
870 program's POD section SYNOPSIS using Pod::Usage. It takes the same
871 arguments as VersionMessage(). In particular, you cannot tie it
872 directly to an option, e.g.:
873 GetOptions("help" => \&HelpMessage);
875 Use this instead:
877 GetOptions("help" => sub { HelpMessage() });
879
881 Configuration errors and errors in the option definitions are signalled
882 using die() and will terminate the calling program unless the call to
883 Getopt::Long::GetOptions() was embedded in "eval { ... }", or die()
884 was trapped using $SIG{__DIE__}.
885 GetOptions returns true to indicate success. It returns false when the
887 function detected one or more errors during option parsing. These
888 errors are signalled using warn() and can be trapped with
889 $SIG{__WARN__}.
890
892 The earliest development of "newgetopt.pl" started in 1990, with Perl
893 version 4. As a result, its development, and the development of
894 Getopt::Long, has gone through several stages. Since backward compati‐
895 bility has always been extremely important, the current version of
896 Getopt::Long still supports a lot of constructs that nowadays are no
897 longer necessary or otherwise unwanted. This section describes briefly
898 some of these 'features'.
899 Default destinations
901 When no destination is specified for an option, GetOptions will store
903 the resultant value in a global variable named "opt_"XXX, where XXX is
904 the primary name of this option. When a progam executes under "use
905 strict" (recommended), these variables must be pre-declared with our()
906 or "use vars".
907 our $opt_length = 0;
909 GetOptions ('length=i'); # will store in $opt_length
910 To yield a usable Perl variable, characters that are not part of the
912 syntax for variables are translated to underscores. For example,
913 "--fpp-struct-return" will set the variable $opt_fpp_struct_return.
914 Note that this variable resides in the namespace of the calling pro‐
915 gram, not necessarily "main". For example:
916 GetOptions ("size=i", "sizes=i@");
918 with command line "-size 10 -sizes 24 -sizes 48" will perform the
920 equivalent of the assignments
921 $opt_size = 10;
923 @opt_sizes = (24, 48);
924 Alternative option starters
926 A string of alternative option starter characters may be passed as the
928 first argument (or the first argument after a leading hash reference
929 argument).
930 my $len = 0;
932 GetOptions ('/', 'length=i' => $len);
933 Now the command line may look like:
935 /length 24 -- arg
937 Note that to terminate options processing still requires a double dash
939 "--".
940 GetOptions() will not interpret a leading "<>" as option starters if
942 the next argument is a reference. To force "<" and ">" as option
943 starters, use "><". Confusing? Well, using a starter argument is
944 strongly deprecated anyway.
945 Configuration variables
947 Previous versions of Getopt::Long used variables for the purpose of
949 configuring. Although manipulating these variables still work, it is
950 strongly encouraged to use the "Configure" routine that was introduced
951 in version 2.17. Besides, it is much easier.
952
954 GetOptions does not return a false result when an option is not sup‐
955 plied
956 That's why they're called 'options'.
958 GetOptions does not split the command line correctly
960 The command line is not split by GetOptions, but by the command line
962 interpreter (CLI). On Unix, this is the shell. On Windows, it is COM‐
963 MAND.COM or CMD.EXE. Other operating systems have other CLIs.
964 It is important to know that these CLIs may behave different when the
966 command line contains special characters, in particular quotes or back‐
967 slashes. For example, with Unix shells you can use single quotes ("'")
968 and double quotes (""") to group words together. The following alterna‐
969 tives are equivalent on Unix:
970 "two words"
972 'two words'
973 two\ words
974 In case of doubt, insert the following statement in front of your Perl
976 program:
977 print STDERR (join("⎪",@ARGV),"\n");
979 to verify how your CLI passes the arguments to the program.
981 Undefined subroutine &main::GetOptions called
983 Are you running Windows, and did you write
985 use GetOpt::Long;
987 (note the capital 'O')?
989 How do I put a "-?" option into a Getopt::Long?
991 You can only obtain this using an alias, and Getopt::Long of at least
993 version 2.13.
994 use Getopt::Long;
996 GetOptions ("help⎪?"); # -help and -? will both set $opt_help
997
999 Johan Vromans <jvromans@squirrel.nl>
1000
1002 This program is Copyright 1990,2005 by Johan Vromans. This program is
1003 free software; you can redistribute it and/or modify it under the terms
1004 of the Perl Artistic License or the GNU General Public License as pub‐
1005 lished by the Free Software Foundation; either version 2 of the
1006 License, or (at your option) any later version.
1007 This program is distributed in the hope that it will be useful, but
1009 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
1010 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
1011 Public License for more details.
1012 If you do not have a copy of the GNU General Public License write to
1014 the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
1015 USA.
1016perl v5.8.8 2001-09-21 Getopt::Long(3pm)