1 # GetOpt::Long.pm -- Universal options parsing
5 # RCS Status : $Id: GetoptLong.pm,v 2.16 1998-03-13 11:05:29+01 jv Exp $
6 # Author : Johan Vromans
7 # Created On : Tue Sep 11 15:00:12 1990
8 # Last Modified By: Johan Vromans
9 # Last Modified On: Fri Mar 13 11:05:28 1998
13 ################ Copyright ################
15 # This program is Copyright 1990,1998 by Johan Vromans.
16 # This program is free software; you can redistribute it and/or
17 # modify it under the terms of the GNU General Public License
18 # as published by the Free Software Foundation; either version 2
19 # of the License, or (at your option) any later version.
21 # This program is distributed in the hope that it will be useful,
22 # but WITHOUT ANY WARRANTY; without even the implied warranty of
23 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
24 # GNU General Public License for more details.
26 # If you do not have a copy of the GNU General Public License write to
27 # the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,
30 ################ Module Preamble ################
37 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
38 $VERSION = sprintf("%d.%02d", q$Revision: 2.16 $ =~ /(\d+)\.(\d+)/);
41 @EXPORT = qw(&GetOptions $REQUIRE_ORDER $PERMUTE $RETURN_IN_ORDER);
46 use vars @EXPORT, @EXPORT_OK;
47 # User visible variables.
48 use vars qw($error $debug $major_version $minor_version);
49 # Deprecated visible variables.
50 use vars qw($autoabbrev $getopt_compat $ignorecase $bundling $order
53 ################ Local Variables ################
55 my $gen_prefix; # generic prefix (option starters)
56 my $argend; # option list terminator
57 my %opctl; # table of arg.specs (long and abbrevs)
58 my %bopctl; # table of arg.specs (bundles)
59 my @opctl; # the possible long option names
60 my $pkg; # current context. Needed if no linkage.
61 my %aliases; # alias table
62 my $genprefix; # so we can call the same module more
63 my $opt; # current option
64 my $arg; # current option value, if any
65 my $array; # current option is array typed
66 my $hash; # current option is hash typed
67 my $key; # hash key for a hash option
68 # than once in differing environments
69 my $config_defaults; # set config defaults
70 my $find_option; # helper routine
71 my $croak; # helper routine
73 ################ Subroutines ################
77 my @optionlist = @_; # local copy of the option descriptions
78 $argend = '--'; # option list terminator
79 %opctl = (); # table of arg.specs (long and abbrevs)
80 %bopctl = (); # table of arg.specs (bundles)
81 $pkg = (caller)[0]; # current context
82 # Needed if linkage is omitted.
83 %aliases= (); # alias table
84 my @ret = (); # accum for non-options
85 my %linkage; # linkage
86 my $userlinkage; # user supplied HASH
87 $genprefix = $gen_prefix; # so we can call the same module many times
90 print STDERR ('GetOptions $Revision: 2.16 $ ',
91 "[GetOpt::Long $Getopt::Long::VERSION] -- ",
92 "called from package \"$pkg\".\n",
94 " autoabbrev=$autoabbrev".
95 ",bundling=$bundling",
96 ",getopt_compat=$getopt_compat",
98 ",\n ignorecase=$ignorecase",
99 ",passthrough=$passthrough",
100 ",genprefix=\"$genprefix\"",
104 # Check for ref HASH as first argument.
105 # First argument may be an object. It's OK to use this as long
106 # as it is really a hash underneath.
107 $userlinkage = undef;
108 if ( ref($optionlist[0]) and
109 "$optionlist[0]" =~ /^(?:.*\=)?HASH\([^\(]*\)$/ ) {
110 $userlinkage = shift (@optionlist);
111 print STDERR ("=> user linkage: $userlinkage\n") if $debug;
114 # See if the first element of the optionlist contains option
115 # starter characters.
116 if ( $optionlist[0] =~ /^\W+$/ ) {
117 $genprefix = shift (@optionlist);
118 # Turn into regexp. Needs to be parenthesized!
119 $genprefix =~ s/(\W)/\\$1/g;
120 $genprefix = "([" . $genprefix . "])";
123 # Verify correctness of optionlist.
126 while ( @optionlist > 0 ) {
127 my $opt = shift (@optionlist);
129 # Strip leading prefix so people can specify "--foo=i" if they like.
130 $opt = $+ if $opt =~ /^$genprefix+(.*)$/s;
132 if ( $opt eq '<>' ) {
133 if ( (defined $userlinkage)
134 && !(@optionlist > 0 && ref($optionlist[0]))
135 && (exists $userlinkage->{$opt})
136 && ref($userlinkage->{$opt}) ) {
137 unshift (@optionlist, $userlinkage->{$opt});
139 unless ( @optionlist > 0
140 && ref($optionlist[0]) && ref($optionlist[0]) eq 'CODE' ) {
141 $error .= "Option spec <> requires a reference to a subroutine\n";
144 $linkage{'<>'} = shift (@optionlist);
148 # Match option spec. Allow '?' as an alias.
149 if ( $opt !~ /^((\w+[-\w]*)(\|(\?|\w[-\w]*)?)*)?(!|[=:][infse][@%]?)?$/ ) {
150 $error .= "Error in option spec: \"$opt\"\n";
153 my ($o, $c, $a) = ($1, $5);
154 $c = '' unless defined $c;
156 if ( ! defined $o ) {
157 # empty -> '-' option
158 $opctl{$o = ''} = $c;
162 my @o = split (/\|/, $o);
163 my $linko = $o = $o[0];
164 # Force an alias if the option name is not locase.
165 $a = $o unless $o eq lc($o);
169 && ($bundling ? length($o) > 1 : 1));
172 if ( $bundling && length($_) == 1 ) {
173 $_ = lc ($_) if $ignorecase > 1;
176 warn ("Ignoring '!' modifier for short option $_\n");
179 $opctl{$_} = $bopctl{$_} = $c;
182 $_ = lc ($_) if $ignorecase;
201 # If no linkage is supplied in the @optionlist, copy it from
202 # the userlinkage if available.
203 if ( defined $userlinkage ) {
204 unless ( @optionlist > 0 && ref($optionlist[0]) ) {
205 if ( exists $userlinkage->{$o} && ref($userlinkage->{$o}) ) {
206 print STDERR ("=> found userlinkage for \"$o\": ",
207 "$userlinkage->{$o}\n")
209 unshift (@optionlist, $userlinkage->{$o});
212 # Do nothing. Being undefined will be handled later.
218 # Copy the linkage. If omitted, link to global variable.
219 if ( @optionlist > 0 && ref($optionlist[0]) ) {
220 print STDERR ("=> link \"$o\" to $optionlist[0]\n")
222 if ( ref($optionlist[0]) =~ /^(SCALAR|CODE)$/ ) {
223 $linkage{$o} = shift (@optionlist);
225 elsif ( ref($optionlist[0]) =~ /^(ARRAY)$/ ) {
226 $linkage{$o} = shift (@optionlist);
228 if $opctl{$o} ne '' and $opctl{$o} !~ /\@$/;
230 if $bundling and defined $bopctl{$o} and
231 $bopctl{$o} ne '' and $bopctl{$o} !~ /\@$/;
233 elsif ( ref($optionlist[0]) =~ /^(HASH)$/ ) {
234 $linkage{$o} = shift (@optionlist);
236 if $opctl{$o} ne '' and $opctl{$o} !~ /\%$/;
238 if $bundling and defined $bopctl{$o} and
239 $bopctl{$o} ne '' and $bopctl{$o} !~ /\%$/;
242 $error .= "Invalid option linkage for \"$opt\"\n";
246 # Link to global $opt_XXX variable.
247 # Make sure a valid perl identifier results.
251 print STDERR ("=> link \"$o\" to \@$pkg","::opt_$ov\n")
253 eval ("\$linkage{\$o} = \\\@".$pkg."::opt_$ov;");
255 elsif ( $c =~ /%/ ) {
256 print STDERR ("=> link \"$o\" to \%$pkg","::opt_$ov\n")
258 eval ("\$linkage{\$o} = \\\%".$pkg."::opt_$ov;");
261 print STDERR ("=> link \"$o\" to \$$pkg","::opt_$ov\n")
263 eval ("\$linkage{\$o} = \\\$".$pkg."::opt_$ov;");
268 # Bail out if errors found.
269 die ($error) if $error;
272 # Sort the possible long option names.
273 @opctl = sort(keys (%opctl)) if $autoabbrev;
275 # Show the options tables if debugging.
279 while ( ($k,$v) = each(%opctl) ) {
280 print STDERR ($arrow, "\$opctl{\"$k\"} = \"$v\"\n");
284 while ( ($k,$v) = each(%bopctl) ) {
285 print STDERR ($arrow, "\$bopctl{\"$k\"} = \"$v\"\n");
290 # Process argument list
291 while ( @ARGV > 0 ) {
293 #### Get next argument ####
295 $opt = shift (@ARGV);
298 print STDERR ("=> option \"", $opt, "\"\n") if $debug;
300 #### Determine what we have ####
302 # Double dash is option list terminator.
303 if ( $opt eq $argend ) {
304 # Finish. Push back accumulated arguments and return.
305 unshift (@ARGV, @ret)
306 if $order == $PERMUTE;
307 return ($error == 0);
312 # find_option operates on the GLOBAL $opt and $arg!
313 if ( &$find_option () ) {
315 # find_option undefines $opt in case of errors.
316 next unless defined $opt;
318 if ( defined $arg ) {
319 $opt = $aliases{$opt} if defined $aliases{$opt};
321 if ( defined $linkage{$opt} ) {
322 print STDERR ("=> ref(\$L{$opt}) -> ",
323 ref($linkage{$opt}), "\n") if $debug;
325 if ( ref($linkage{$opt}) eq 'SCALAR' ) {
326 print STDERR ("=> \$\$L{$opt} = \"$arg\"\n") if $debug;
327 ${$linkage{$opt}} = $arg;
329 elsif ( ref($linkage{$opt}) eq 'ARRAY' ) {
330 print STDERR ("=> push(\@{\$L{$opt}, \"$arg\")\n")
332 push (@{$linkage{$opt}}, $arg);
334 elsif ( ref($linkage{$opt}) eq 'HASH' ) {
335 print STDERR ("=> \$\$L{$opt}->{$key} = \"$arg\"\n")
337 $linkage{$opt}->{$key} = $arg;
339 elsif ( ref($linkage{$opt}) eq 'CODE' ) {
340 print STDERR ("=> &L{$opt}(\"$opt\", \"$arg\")\n")
342 &{$linkage{$opt}}($opt, $arg);
345 print STDERR ("Invalid REF type \"", ref($linkage{$opt}),
347 &$croak ("Getopt::Long -- internal error!\n");
350 # No entry in linkage means entry in userlinkage.
352 if ( defined $userlinkage->{$opt} ) {
353 print STDERR ("=> push(\@{\$L{$opt}}, \"$arg\")\n")
355 push (@{$userlinkage->{$opt}}, $arg);
358 print STDERR ("=>\$L{$opt} = [\"$arg\"]\n")
360 $userlinkage->{$opt} = [$arg];
364 if ( defined $userlinkage->{$opt} ) {
365 print STDERR ("=> \$L{$opt}->{$key} = \"$arg\"\n")
367 $userlinkage->{$opt}->{$key} = $arg;
370 print STDERR ("=>\$L{$opt} = {$key => \"$arg\"}\n")
372 $userlinkage->{$opt} = {$key => $arg};
376 print STDERR ("=>\$L{$opt} = \"$arg\"\n") if $debug;
377 $userlinkage->{$opt} = $arg;
382 # Not an option. Save it if we $PERMUTE and don't have a <>.
383 elsif ( $order == $PERMUTE ) {
384 # Try non-options call-back.
386 if ( (defined ($cb = $linkage{'<>'})) ) {
390 print STDERR ("=> saving \"$tryopt\" ",
391 "(not an option, may permute)\n") if $debug;
392 push (@ret, $tryopt);
397 # ...otherwise, terminate.
399 # Push this one back and exit.
400 unshift (@ARGV, $tryopt);
401 return ($error == 0);
407 if ( $order == $PERMUTE ) {
408 # Push back accumulated arguments
409 print STDERR ("=> restoring \"", join('" "', @ret), "\"\n")
410 if $debug && @ret > 0;
411 unshift (@ARGV, @ret) if @ret > 0;
414 return ($error == 0);
420 foreach $opt ( @options ) {
423 if ( $try =~ /^no_?(.*)$/s ) {
427 if ( $try eq 'default' or $try eq 'defaults' ) {
428 &$config_defaults () if $action;
430 elsif ( $try eq 'auto_abbrev' or $try eq 'autoabbrev' ) {
431 $autoabbrev = $action;
433 elsif ( $try eq 'getopt_compat' ) {
434 $getopt_compat = $action;
436 elsif ( $try eq 'ignorecase' or $try eq 'ignore_case' ) {
437 $ignorecase = $action;
439 elsif ( $try eq 'ignore_case_always' ) {
440 $ignorecase = $action ? 2 : 0;
442 elsif ( $try eq 'bundling' ) {
445 elsif ( $try eq 'bundling_override' ) {
446 $bundling = $action ? 2 : 0;
448 elsif ( $try eq 'require_order' ) {
449 $order = $action ? $REQUIRE_ORDER : $PERMUTE;
451 elsif ( $try eq 'permute' ) {
452 $order = $action ? $PERMUTE : $REQUIRE_ORDER;
454 elsif ( $try eq 'pass_through' or $try eq 'passthrough' ) {
455 $passthrough = $action;
457 elsif ( $try =~ /^prefix=(.+)$/ ) {
459 # Turn into regexp. Needs to be parenthesized!
460 $gen_prefix = "(" . quotemeta($gen_prefix) . ")";
461 eval { '' =~ /$gen_prefix/; };
462 &$croak ("Getopt::Long: invalid pattern \"$gen_prefix\"") if $@;
464 elsif ( $try =~ /^prefix_pattern=(.+)$/ ) {
466 # Parenthesize if needed.
467 $gen_prefix = "(" . $gen_prefix . ")"
468 unless $gen_prefix =~ /^\(.*\)$/;
469 eval { '' =~ /$gen_prefix/; };
470 &$croak ("Getopt::Long: invalid pattern \"$gen_prefix\"") if $@;
472 elsif ( $try eq 'debug' ) {
476 &$croak ("Getopt::Long: unknown config parameter \"$opt\"")
481 # To prevent Carp from being loaded unnecessarily.
484 $Carp::CarpLevel = 1;
488 ################ Private Subroutines ################
492 print STDERR ("=> find \"$opt\", genprefix=\"$genprefix\"\n") if $debug;
494 return 0 unless $opt =~ /^$genprefix(.*)$/s;
499 print STDERR ("=> split \"$starter\"+\"$opt\"\n") if $debug;
501 my $optarg = undef; # value supplied with --opt=value
502 my $rest = undef; # remainder from unbundling
504 # If it is a long option, it may include the value.
505 if (($starter eq "--" || ($getopt_compat && !$bundling))
506 && $opt =~ /^([^=]+)=(.*)$/s ) {
509 print STDERR ("=> option \"", $opt,
510 "\", optarg = \"$optarg\"\n") if $debug;
515 my $tryopt = $opt; # option to try
516 my $optbl = \%opctl; # table to look it up (long names)
519 if ( $bundling && $starter eq '-' ) {
520 # Unbundle single letter option.
521 $rest = substr ($tryopt, 1);
522 $tryopt = substr ($tryopt, 0, 1);
523 $tryopt = lc ($tryopt) if $ignorecase > 1;
524 print STDERR ("=> $starter$tryopt unbundled from ",
525 "$starter$tryopt$rest\n") if $debug;
526 $rest = undef unless $rest ne '';
527 $optbl = \%bopctl; # look it up in the short names table
529 # If bundling == 2, long options can override bundles.
530 if ( $bundling == 2 and
531 defined ($type = $opctl{$tryopt.$rest}) ) {
532 print STDERR ("=> $starter$tryopt rebundled to ",
533 "$starter$tryopt$rest\n") if $debug;
539 # Try auto-abbreviation.
540 elsif ( $autoabbrev ) {
541 # Downcase if allowed.
542 $tryopt = $opt = lc ($opt) if $ignorecase;
543 # Turn option name into pattern.
544 my $pat = quotemeta ($opt);
545 # Look up in option names.
546 my @hits = grep (/^$pat/, @opctl);
547 print STDERR ("=> ", scalar(@hits), " hits (@hits) with \"$pat\" ",
548 "out of ", scalar(@opctl), "\n") if $debug;
550 # Check for ambiguous results.
551 unless ( (@hits <= 1) || (grep ($_ eq $opt, @hits) == 1) ) {
552 # See if all matches are for the same option.
555 $_ = $aliases{$_} if defined $aliases{$_};
558 # Now see if it really is ambiguous.
559 unless ( keys(%hit) == 1 ) {
560 return 0 if $passthrough;
561 warn ("Option ", $opt, " is ambiguous (",
562 join(", ", @hits), ")\n");
570 # Complete the option name, if appropriate.
571 if ( @hits == 1 && $hits[0] ne $opt ) {
573 $tryopt = lc ($tryopt) if $ignorecase;
574 print STDERR ("=> option \"$opt\" -> \"$tryopt\"\n")
579 # Map to all lowercase if ignoring case.
580 elsif ( $ignorecase ) {
584 # Check validity by fetching the info.
585 $type = $optbl->{$tryopt} unless defined $type;
586 unless ( defined $type ) {
587 return 0 if $passthrough;
588 warn ("Unknown option: ", $opt, "\n");
594 print STDERR ("=> found \"$type\" for ", $opt, "\n") if $debug;
596 #### Determine argument status ####
598 # If it is an option w/o argument, we're almost finished with it.
599 if ( $type eq '' || $type eq '!' ) {
600 if ( defined $optarg ) {
601 return 0 if $passthrough;
602 warn ("Option ", $opt, " does not take an argument\n");
606 elsif ( $type eq '' ) {
607 $arg = 1; # supply explicit value
610 substr ($opt, 0, 2) = ''; # strip NO prefix
611 $arg = 0; # supply explicit value
613 unshift (@ARGV, $starter.$rest) if defined $rest;
617 # Get mandatory status and type info.
619 ($mand, $type, $array, $hash) = $type =~ /^(.)(.)(@?)(%?)$/;
621 # Check if there is an option argument available.
622 if ( defined $optarg ? ($optarg eq '')
623 : !(defined $rest || @ARGV > 0) ) {
624 # Complain if this option needs an argument.
625 if ( $mand eq "=" ) {
626 return 0 if $passthrough;
627 warn ("Option ", $opt, " requires an argument\n");
631 if ( $mand eq ":" ) {
632 $arg = $type eq "s" ? '' : 0;
637 # Get (possibly optional) argument.
638 $arg = (defined $rest ? $rest
639 : (defined $optarg ? $optarg : shift (@ARGV)));
641 # Get key if this is a "name=value" pair for a hash option.
643 if ($hash && defined $arg) {
644 ($key, $arg) = ($arg =~ /^(.*)=(.*)$/s) ? ($1, $2) : ($arg, 1);
647 #### Check if the argument is valid for this option ####
649 if ( $type eq "s" ) { # string
650 # A mandatory string takes anything.
651 return 1 if $mand eq "=";
653 # An optional string takes almost anything.
654 return 1 if defined $optarg || defined $rest;
655 return 1 if $arg eq "-"; # ??
657 # Check for option or option list terminator.
658 if ($arg eq $argend ||
659 $arg =~ /^$genprefix.+/) {
661 unshift (@ARGV, $arg);
662 # Supply empty value.
667 elsif ( $type eq "n" || $type eq "i" ) { # numeric/integer
668 if ( $bundling && defined $rest && $rest =~ /^(-?[0-9]+)(.*)$/s ) {
671 unshift (@ARGV, $starter.$rest) if defined $rest && $rest ne '';
673 elsif ( $arg !~ /^-?[0-9]+$/ ) {
674 if ( defined $optarg || $mand eq "=" ) {
675 if ( $passthrough ) {
676 unshift (@ARGV, defined $rest ? $starter.$rest : $arg)
677 unless defined $optarg;
680 warn ("Value \"", $arg, "\" invalid for option ",
681 $opt, " (number expected)\n");
685 unshift (@ARGV, $starter.$rest) if defined $rest;
689 unshift (@ARGV, defined $rest ? $starter.$rest : $arg);
690 # Supply default value.
696 elsif ( $type eq "f" ) { # real number, int is also ok
697 # We require at least one digit before a point or 'e',
698 # and at least one digit following the point and 'e'.
700 if ( $bundling && defined $rest &&
701 $rest =~ /^(-?[0-9]+(\.[0-9]+)?([eE]-?[0-9]+)?)(.*)$/s ) {
704 unshift (@ARGV, $starter.$rest) if defined $rest && $rest ne '';
706 elsif ( $arg !~ /^-?[0-9.]+(\.[0-9]+)?([eE]-?[0-9]+)?$/ ) {
707 if ( defined $optarg || $mand eq "=" ) {
708 if ( $passthrough ) {
709 unshift (@ARGV, defined $rest ? $starter.$rest : $arg)
710 unless defined $optarg;
713 warn ("Value \"", $arg, "\" invalid for option ",
714 $opt, " (real number expected)\n");
718 unshift (@ARGV, $starter.$rest) if defined $rest;
722 unshift (@ARGV, defined $rest ? $starter.$rest : $arg);
723 # Supply default value.
729 &$croak ("GetOpt::Long internal error (Can't happen)\n");
734 $config_defaults = sub {
735 # Handle POSIX compliancy.
736 if ( defined $ENV{"POSIXLY_CORRECT"} ) {
737 $gen_prefix = "(--|-)";
738 $autoabbrev = 0; # no automatic abbrev of options
739 $bundling = 0; # no bundling of single letter switches
740 $getopt_compat = 0; # disallow '+' to start options
741 $order = $REQUIRE_ORDER;
744 $gen_prefix = "(--|-|\\+)";
745 $autoabbrev = 1; # automatic abbrev of options
746 $bundling = 0; # bundling off by default
747 $getopt_compat = 1; # allow '+' to start options
750 # Other configurable settings.
751 $debug = 0; # for debugging
752 $error = 0; # error tally
753 $ignorecase = 1; # ignore case when matching options
754 $passthrough = 0; # leave unrecognized options alone
757 ################ Initialization ################
759 # Values for $order. See GNU getopt.c for details.
760 ($REQUIRE_ORDER, $PERMUTE, $RETURN_IN_ORDER) = (0..2);
761 # Version major/minor numbers.
762 ($major_version, $minor_version) = $VERSION =~ /^(\d+)\.(\d+)/;
765 &$config_defaults ();
767 ################ Package return ################
775 GetOptions - extended processing of command line options
780 $result = GetOptions (...option-descriptions...);
784 The Getopt::Long module implements an extended getopt function called
785 GetOptions(). This function adheres to the POSIX syntax for command
786 line options, with GNU extensions. In general, this means that options
787 have long names instead of single letters, and are introduced with a
788 double dash "--". Support for bundling of command line options, as was
789 the case with the more traditional single-letter approach, is provided
790 but not enabled by default. For example, the UNIX "ps" command can be
791 given the command line "option"
795 which means the combination of B<-v>, B<-a> and B<-x>. With the new
796 syntax B<--vax> would be a single option, probably indicating a
797 computer architecture.
799 Command line options can be used to set values. These values can be
800 specified in one of two ways:
805 GetOptions is called with a list of option-descriptions, each of which
806 consists of two elements: the option specifier and the option linkage.
807 The option specifier defines the name of the option and, optionally,
808 the value it can take. The option linkage is usually a reference to a
809 variable that will be set when the option is used. For example, the
810 following call to GetOptions:
812 GetOptions("size=i" => \$offset);
814 will accept a command line option "size" that must have an integer
815 value. With a command line of "--size 24" this will cause the variable
816 $offset to get the value 24.
818 Alternatively, the first argument to GetOptions may be a reference to
819 a HASH describing the linkage for the options, or an object whose
820 class is based on a HASH. The following call is equivalent to the
823 %optctl = ("size" => \$offset);
824 GetOptions(\%optctl, "size=i");
826 Linkage may be specified using either of the above methods, or both.
827 Linkage specified in the argument list takes precedence over the
828 linkage specified in the HASH.
830 The command line options are taken from array @ARGV. Upon completion
831 of GetOptions, @ARGV will contain the rest (i.e. the non-options) of
834 Each option specifier designates the name of the option, optionally
835 followed by an argument specifier.
837 Options that do not take arguments will have no argument specifier.
838 The option variable will be set to 1 if the option is used.
840 For the other options, the values for argument specifiers are:
846 Option does not take an argument and may be negated, i.e. prefixed by
847 "no". E.g. "foo!" will allow B<--foo> (with value 1) and B<-nofoo>
849 The option variable will be set to 1, or 0 if negated.
853 Option takes a mandatory string argument.
854 This string will be assigned to the option variable.
855 Note that even if the string argument starts with B<-> or B<-->, it
856 will not be considered an option on itself.
860 Option takes an optional string argument.
861 This string will be assigned to the option variable.
862 If omitted, it will be assigned "" (an empty string).
863 If the string argument starts with B<-> or B<-->, it
864 will be considered an option on itself.
868 Option takes a mandatory integer argument.
869 This value will be assigned to the option variable.
870 Note that the value may start with B<-> to indicate a negative
875 Option takes an optional integer argument.
876 This value will be assigned to the option variable.
877 If omitted, the value 0 will be assigned.
878 Note that the value may start with B<-> to indicate a negative
883 Option takes a mandatory real number argument.
884 This value will be assigned to the option variable.
885 Note that the value may start with B<-> to indicate a negative
890 Option takes an optional real number argument.
891 This value will be assigned to the option variable.
892 If omitted, the value 0 will be assigned.
896 A lone dash B<-> is considered an option, the corresponding option
897 name is the empty string.
899 A double dash on itself B<--> signals end of the options list.
901 =head2 Linkage specification
903 The linkage specifier is optional. If no linkage is explicitly
904 specified but a ref HASH is passed, GetOptions will place the value in
905 the HASH. For example:
908 GetOptions (\%optctl, "size=i");
910 will perform the equivalent of the assignment
912 $optctl{"size"} = 24;
914 For array options, a reference to an array is used, e.g.:
917 GetOptions (\%optctl, "sizes=i@");
919 with command line "-sizes 24 -sizes 48" will perform the equivalent of
922 $optctl{"sizes"} = [24, 48];
924 For hash options (an option whose argument looks like "name=value"),
925 a reference to a hash is used, e.g.:
928 GetOptions (\%optctl, "define=s%");
930 with command line "--define foo=hello --define bar=world" will perform the
931 equivalent of the assignment
933 $optctl{"define"} = {foo=>'hello', bar=>'world')
935 If no linkage is explicitly specified and no ref HASH is passed,
936 GetOptions will put the value in a global variable named after the
937 option, prefixed by "opt_". To yield a usable Perl variable,
938 characters that are not part of the syntax for variables are
939 translated to underscores. For example, "--fpp-struct-return" will set
940 the variable $opt_fpp_struct_return. Note that this variable resides
941 in the namespace of the calling program, not necessarily B<main>.
944 GetOptions ("size=i", "sizes=i@");
946 with command line "-size 10 -sizes 24 -sizes 48" will perform the
947 equivalent of the assignments
950 @opt_sizes = (24, 48);
952 A lone dash B<-> is considered an option, the corresponding Perl
953 identifier is $opt_ .
955 The linkage specifier can be a reference to a scalar, a reference to
956 an array, a reference to a hash or a reference to a subroutine.
958 Note that, if your code is running under the recommended C<use strict
959 'vars'> pragma, it may be helpful to declare these package variables
960 via C<use vars> perhaps something like this:
962 use vars qw/ $opt_size @opt_sizes $opt_bar /;
964 If a REF SCALAR is supplied, the new value is stored in the referenced
965 variable. If the option occurs more than once, the previous value is
968 If a REF ARRAY is supplied, the new value is appended (pushed) to the
971 If a REF HASH is supplied, the option value should look like "key" or
972 "key=value" (if the "=value" is omitted then a value of 1 is implied).
973 In this case, the element of the referenced hash with the key "key"
976 If a REF CODE is supplied, the referenced subroutine is called with
977 two arguments: the option name and the option value.
978 The option name is always the true name, not an abbreviation or alias.
980 =head2 Aliases and abbreviations
982 The option name may actually be a list of option names, separated by
983 "|"s, e.g. "foo|bar|blech=s". In this example, "foo" is the true name
984 of this option. If no linkage is specified, options "foo", "bar" and
985 "blech" all will set $opt_foo. For convenience, the single character
986 "?" is allowed as an alias, e.g. "help|?".
988 Option names may be abbreviated to uniqueness, depending on
989 configuration option B<auto_abbrev>.
991 =head2 Non-option call-back routine
993 A special option specifier, E<lt>E<gt>, can be used to designate a subroutine
994 to handle non-option arguments. GetOptions will immediately call this
995 subroutine for every non-option it encounters in the options list.
996 This subroutine gets the name of the non-option passed.
997 This feature requires configuration option B<permute>, see section
998 CONFIGURATION OPTIONS.
1000 See also the examples.
1002 =head2 Option starters
1004 On the command line, options can start with B<-> (traditional), B<-->
1005 (POSIX) and B<+> (GNU, now being phased out). The latter is not
1006 allowed if the environment variable B<POSIXLY_CORRECT> has been
1009 Options that start with "--" may have an argument appended, separated
1010 with an "=", e.g. "--foo=bar".
1012 =head2 Return values and Errors
1014 Configuration errors and errors in the option definitions are
1015 signalled using C<die()> and will terminate the calling
1016 program unless the call to C<Getopt::Long::GetOptions()> was embedded
1017 in C<eval { ... }> or C<die()> was trapped using C<$SIG{__DIE__}>.
1019 A return value of 1 (true) indicates success.
1021 A return status of 0 (false) indicates that the function detected one
1022 or more errors during option parsing. These errors are signalled using
1023 C<warn()> and can be trapped with C<$SIG{__WARN__}>.
1025 Errors that can't happen are signalled using C<Carp::croak()>.
1027 =head1 COMPATIBILITY
1029 Getopt::Long::GetOptions() is the successor of
1030 B<newgetopt.pl> that came with Perl 4. It is fully upward compatible.
1031 In fact, the Perl 5 version of newgetopt.pl is just a wrapper around
1034 If an "@" sign is appended to the argument specifier, the option is
1035 treated as an array. Value(s) are not set, but pushed into array
1036 @opt_name. If explicit linkage is supplied, this must be a reference
1039 If an "%" sign is appended to the argument specifier, the option is
1040 treated as a hash. Value(s) of the form "name=value" are set by
1041 setting the element of the hash %opt_name with key "name" to "value"
1042 (if the "=value" portion is omitted it defaults to 1). If explicit
1043 linkage is supplied, this must be a reference to a HASH.
1045 If configuration option B<getopt_compat> is set (see section
1046 CONFIGURATION OPTIONS), options that start with "+" or "-" may also
1047 include their arguments, e.g. "+foo=bar". This is for compatiblity
1048 with older implementations of the GNU "getopt" routine.
1050 If the first argument to GetOptions is a string consisting of only
1051 non-alphanumeric characters, it is taken to specify the option starter
1052 characters. Everything starting with one of these characters from the
1053 starter will be considered an option. B<Using a starter argument is
1054 strongly deprecated.>
1056 For convenience, option specifiers may have a leading B<-> or B<-->,
1057 so it is possible to write:
1059 GetOptions qw(-foo=s --bar=i --ar=s);
1063 If the option specifier is "one:i" (i.e. takes an optional integer
1064 argument), then the following situations are handled:
1066 -one -two -> $opt_one = '', -two is next option
1067 -one -2 -> $opt_one = -2
1069 Also, assume specifiers "foo=s" and "bar:s" :
1071 -bar -xxx -> $opt_bar = '', '-xxx' is next option
1072 -foo -bar -> $opt_foo = '-bar'
1073 -foo -- -> $opt_foo = '--'
1075 In GNU or POSIX format, option names and values can be combined:
1077 +foo=blech -> $opt_foo = 'blech'
1078 --bar= -> $opt_bar = ''
1079 --bar=-- -> $opt_bar = '--'
1081 Example of using variable references:
1083 $ret = GetOptions ('foo=s', \$foo, 'bar=i', 'ar=s', \@ar);
1085 With command line options "-foo blech -bar 24 -ar xx -ar yy"
1086 this will result in:
1092 Example of using the E<lt>E<gt> option specifier:
1094 @ARGV = qw(-foo 1 bar -foo 2 blech);
1095 GetOptions("foo=i", \$myfoo, "<>", \&mysub);
1099 mysub("bar") will be called (with $myfoo being 1)
1100 mysub("blech") will be called (with $myfoo being 2)
1104 @ARGV = qw(-foo 1 bar -foo 2 blech);
1105 GetOptions("foo=i", \$myfoo);
1107 This will leave the non-options in @ARGV:
1110 @ARGV -> qw(bar blech)
1112 =head1 CONFIGURATION OPTIONS
1114 B<GetOptions> can be configured by calling subroutine
1115 B<Getopt::Long::config>. This subroutine takes a list of quoted
1116 strings, each specifying a configuration option to be set, e.g.
1117 B<ignore_case>. Options can be reset by prefixing with B<no_>, e.g.
1118 B<no_ignore_case>. Case does not matter. Multiple calls to B<config>
1121 Previous versions of Getopt::Long used variables for the purpose of
1122 configuring. Although manipulating these variables still work, it
1123 is strongly encouraged to use the new B<config> routine. Besides, it
1126 The following options are available:
1132 This option causes all configuration options to be reset to their
1137 Allow option names to be abbreviated to uniqueness.
1138 Default is set unless environment variable
1139 POSIXLY_CORRECT has been set, in which case B<auto_abbrev> is reset.
1143 Allow '+' to start options.
1144 Default is set unless environment variable
1145 POSIXLY_CORRECT has been set, in which case B<getopt_compat> is reset.
1149 Whether non-options are allowed to be mixed with
1151 Default is set unless environment variable
1152 POSIXLY_CORRECT has been set, in which case b<require_order> is reset.
1154 See also B<permute>, which is the opposite of B<require_order>.
1158 Whether non-options are allowed to be mixed with
1160 Default is set unless environment variable
1161 POSIXLY_CORRECT has been set, in which case B<permute> is reset.
1162 Note that B<permute> is the opposite of B<require_order>.
1164 If B<permute> is set, this means that
1166 -foo arg1 -bar arg2 arg3
1170 -foo -bar arg1 arg2 arg3
1172 If a non-option call-back routine is specified, @ARGV will always be
1173 empty upon succesful return of GetOptions since all options have been
1174 processed, except when B<--> is used:
1176 -foo arg1 -bar arg2 -- arg3
1178 will call the call-back routine for arg1 and arg2, and terminate
1179 leaving arg2 in @ARGV.
1181 If B<require_order> is set, options processing
1182 terminates when the first non-option is encountered.
1184 -foo arg1 -bar arg2 arg3
1188 -foo -- arg1 -bar arg2 arg3
1190 =item bundling (default: reset)
1192 Setting this variable to a non-zero value will allow single-character
1193 options to be bundled. To distinguish bundles from long option names,
1194 long options must be introduced with B<--> and single-character
1195 options (and bundles) with B<->. For example,
1199 would be equivalent to
1203 provided "vax", "v", "a" and "x" have been defined to be valid
1206 Bundled options can also include a value in the bundle; for strings
1207 this value is the rest of the bundle, but integer and floating values
1208 may be combined in the bundle, e.g.
1216 Note: resetting B<bundling> also resets B<bundling_override>.
1218 =item bundling_override (default: reset)
1220 If B<bundling_override> is set, bundling is enabled as with
1221 B<bundling> but now long option names override option bundles. In the
1222 above example, B<-vax> would be interpreted as the option "vax", not
1223 the bundle "v", "a", "x".
1225 Note: resetting B<bundling_override> also resets B<bundling>.
1227 B<Note:> Using option bundling can easily lead to unexpected results,
1228 especially when mixing long options and bundles. Caveat emptor.
1230 =item ignore_case (default: set)
1232 If set, case is ignored when matching options.
1234 Note: resetting B<ignore_case> also resets B<ignore_case_always>.
1236 =item ignore_case_always (default: reset)
1238 When bundling is in effect, case is ignored on single-character
1241 Note: resetting B<ignore_case_always> also resets B<ignore_case>.
1243 =item pass_through (default: reset)
1245 Unknown options are passed through in @ARGV instead of being flagged
1246 as errors. This makes it possible to write wrapper scripts that
1247 process only part of the user supplied options, and passes the
1248 remaining options to some other program.
1250 This can be very confusing, especially when B<permute> is also set.
1254 The string that starts options. See also B<prefix_pattern>.
1256 =item prefix_pattern
1258 A Perl pattern that identifies the strings that introduce options.
1259 Default is C<(--|-|\+)> unless environment variable
1260 POSIXLY_CORRECT has been set, in which case it is C<(--|-)>.
1262 =item debug (default: reset)
1264 Enable copious debugging output.
1268 =head1 OTHER USEFUL VARIABLES
1272 =item $Getopt::Long::VERSION
1274 The version number of this Getopt::Long implementation in the format
1275 C<major>.C<minor>. This can be used to have Exporter check the
1278 use Getopt::Long 3.00;
1280 You can inspect $Getopt::Long::major_version and
1281 $Getopt::Long::minor_version for the individual components.
1283 =item $Getopt::Long::error
1285 Internal error flag. May be incremented from a call-back routine to
1286 cause options parsing to fail.
1292 Johan Vromans E<lt>jvromans@squirrel.nlE<gt>
1294 =head1 COPYRIGHT AND DISCLAIMER
1296 This program is Copyright 1990,1998 by Johan Vromans.
1297 This program is free software; you can redistribute it and/or
1298 modify it under the terms of the GNU General Public License
1299 as published by the Free Software Foundation; either version 2
1300 of the License, or (at your option) any later version.
1302 This program is distributed in the hope that it will be useful,
1303 but WITHOUT ANY WARRANTY; without even the implied warranty of
1304 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1305 GNU General Public License for more details.
1307 If you do not have a copy of the GNU General Public License write to
1308 the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,