1 # Getopt::Long.pm -- Universal options parsing
5 # RCS Status : $Id: GetoptLong.pm,v 2.68 2003-09-23 15:24:53+02 jv Exp jv $
6 # Author : Johan Vromans
7 # Created On : Tue Sep 11 15:00:12 1990
8 # Last Modified By: Johan Vromans
9 # Last Modified On: Wed Dec 31 20:48:15 2003
13 ################ Copyright ################
15 # This program is Copyright 1990,2002 by Johan Vromans.
16 # This program is free software; you can redistribute it and/or
17 # modify it under the terms of the Perl Artistic License or the
18 # GNU General Public License as published by the Free Software
19 # Foundation; either version 2 of the License, or (at your option) any
22 # This program is distributed in the hope that it will be useful,
23 # but WITHOUT ANY WARRANTY; without even the implied warranty of
24 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
25 # GNU General Public License for more details.
27 # If you do not have a copy of the GNU General Public License write to
28 # the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,
31 ################ Module Preamble ################
37 use vars qw($VERSION);
39 # For testing versions only.
40 use vars qw($VERSION_STRING);
41 $VERSION_STRING = "2.34_01";
44 use vars qw(@ISA @EXPORT @EXPORT_OK);
47 # Exported subroutines.
48 sub GetOptions(@); # always
49 sub Configure(@); # on demand
50 sub HelpMessage(@); # on demand
51 sub VersionMessage(@); # in demand
54 # Init immediately so their contents can be used in the 'use vars' below.
55 @EXPORT = qw(&GetOptions $REQUIRE_ORDER $PERMUTE $RETURN_IN_ORDER);
56 @EXPORT_OK = qw(&HelpMessage &VersionMessage &Configure);
59 # User visible variables.
60 use vars @EXPORT, @EXPORT_OK;
61 use vars qw($error $debug $major_version $minor_version);
62 # Deprecated visible variables.
63 use vars qw($autoabbrev $getopt_compat $ignorecase $bundling $order
65 # Official invisible variables.
66 use vars qw($genprefix $caller $gnu_compat $auto_help $auto_version);
69 sub config(@); # deprecated name
71 # Private subroutines.
73 sub ParseOptionSpec($$);
76 sub ValidValue ($$$$$);
78 ################ Local Variables ################
80 # $requested_version holds the version that was mentioned in the 'use'
81 # or 'require', if any. It can be used to enable or disable specific
83 my $requested_version = 0;
85 ################ Resident subroutines ################
87 sub ConfigDefaults() {
88 # Handle POSIX compliancy.
89 if ( defined $ENV{"POSIXLY_CORRECT"} ) {
90 $genprefix = "(--|-)";
91 $autoabbrev = 0; # no automatic abbrev of options
92 $bundling = 0; # no bundling of single letter switches
93 $getopt_compat = 0; # disallow '+' to start options
94 $order = $REQUIRE_ORDER;
97 $genprefix = "(--|-|\\+)";
98 $autoabbrev = 1; # automatic abbrev of options
99 $bundling = 0; # bundling off by default
100 $getopt_compat = 1; # allow '+' to start options
103 # Other configurable settings.
104 $debug = 0; # for debugging
105 $error = 0; # error tally
106 $ignorecase = 1; # ignore case when matching options
107 $passthrough = 0; # leave unrecognized options alone
108 $gnu_compat = 0; # require --opt=val if value is optional
113 my $pkg = shift; # package
114 my @syms = (); # symbols to import
115 my @config = (); # configuration
116 my $dest = \@syms; # symbols first
118 if ( $_ eq ':config' ) {
119 $dest = \@config; # config next
122 push(@$dest, $_); # push
124 # Hide one level and call super.
125 local $Exporter::ExportLevel = 1;
126 push(@syms, qw(&GetOptions)) if @syms; # always export GetOptions
127 $pkg->SUPER::import(@syms);
129 Configure(@config) if @config;
132 ################ Initialization ################
134 # Values for $order. See GNU getopt.c for details.
135 ($REQUIRE_ORDER, $PERMUTE, $RETURN_IN_ORDER) = (0..2);
136 # Version major/minor numbers.
137 ($major_version, $minor_version) = $VERSION =~ /^(\d+)\.(\d+)/;
141 ################ OO Interface ################
143 package Getopt::Long::Parser;
145 # Store a copy of the default configuration. Since ConfigDefaults has
146 # just been called, what we get from Configure is the default.
147 my $default_config = do {
148 Getopt::Long::Configure ()
153 my $class = ref($that) || $that;
156 # Register the callers package.
157 my $self = { caller_pkg => (caller)[0] };
159 bless ($self, $class);
161 # Process config attributes.
162 if ( defined $atts{config} ) {
163 my $save = Getopt::Long::Configure ($default_config, @{$atts{config}});
164 $self->{settings} = Getopt::Long::Configure ($save);
165 delete ($atts{config});
167 # Else use default config.
169 $self->{settings} = $default_config;
172 if ( %atts ) { # Oops
173 die(__PACKAGE__.": unhandled attributes: ".
174 join(" ", sort(keys(%atts)))."\n");
183 # Restore settings, merge new settings in.
184 my $save = Getopt::Long::Configure ($self->{settings}, @_);
186 # Restore orig config and save the new config.
187 $self->{settings} = Getopt::Long::Configure ($save);
193 # Restore config settings.
194 my $save = Getopt::Long::Configure ($self->{settings});
198 $Getopt::Long::caller = $self->{caller_pkg};
201 # Locally set exception handler to default, otherwise it will
202 # be called implicitly here, and again explicitly when we try
203 # to deliver the messages.
204 local ($SIG{__DIE__}) = '__DEFAULT__';
205 $ret = Getopt::Long::GetOptions (@_);
208 # Restore saved settings.
209 Getopt::Long::Configure ($save);
211 # Handle errors and return value.
216 package Getopt::Long;
218 ################ Back to Normal ################
220 # Indices in option control info.
221 # Note that ParseOptions uses the fields directly. Search for 'hard-wired'.
222 use constant CTL_TYPE => 0;
223 #use constant CTL_TYPE_FLAG => '';
224 #use constant CTL_TYPE_NEG => '!';
225 #use constant CTL_TYPE_INCR => '+';
226 #use constant CTL_TYPE_INT => 'i';
227 #use constant CTL_TYPE_INTINC => 'I';
228 #use constant CTL_TYPE_XINT => 'o';
229 #use constant CTL_TYPE_FLOAT => 'f';
230 #use constant CTL_TYPE_STRING => 's';
232 use constant CTL_CNAME => 1;
234 use constant CTL_DEFAULT => 2;
236 use constant CTL_DEST => 3;
237 use constant CTL_DEST_SCALAR => 0;
238 use constant CTL_DEST_ARRAY => 1;
239 use constant CTL_DEST_HASH => 2;
240 use constant CTL_DEST_CODE => 3;
242 use constant CTL_AMIN => 4;
243 use constant CTL_AMAX => 5;
246 #use constant CTL_RANGE => ;
247 #use constant CTL_REPEAT => ;
251 my @optionlist = @_; # local copy of the option descriptions
252 my $argend = '--'; # option list terminator
253 my %opctl = (); # table of option specs
254 my $pkg = $caller || (caller)[0]; # current context
255 # Needed if linkage is omitted.
256 my @ret = (); # accum for non-options
257 my %linkage; # linkage
258 my $userlinkage; # user supplied HASH
259 my $opt; # current option
260 my $prefix = $genprefix; # current prefix
265 # Avoid some warnings if debugging.
268 ("Getopt::Long $Getopt::Long::VERSION (",
269 '$Revision: 2.68 $', ") ",
270 "called from package \"$pkg\".",
274 "autoabbrev=$autoabbrev,".
275 "bundling=$bundling,",
276 "getopt_compat=$getopt_compat,",
277 "gnu_compat=$gnu_compat,",
280 "ignorecase=$ignorecase,",
281 "requested_version=$requested_version,",
282 "passthrough=$passthrough,",
283 "genprefix=\"$genprefix\".",
287 # Check for ref HASH as first argument.
288 # First argument may be an object. It's OK to use this as long
289 # as it is really a hash underneath.
290 $userlinkage = undef;
291 if ( @optionlist && ref($optionlist[0]) and
292 "$optionlist[0]" =~ /^(?:.*\=)?HASH\([^\(]*\)$/ ) {
293 $userlinkage = shift (@optionlist);
294 print STDERR ("=> user linkage: $userlinkage\n") if $debug;
297 # See if the first element of the optionlist contains option
298 # starter characters.
299 # Be careful not to interpret '<>' as option starters.
300 if ( @optionlist && $optionlist[0] =~ /^\W+$/
301 && !($optionlist[0] eq '<>'
303 && ref($optionlist[1])) ) {
304 $prefix = shift (@optionlist);
305 # Turn into regexp. Needs to be parenthesized!
306 $prefix =~ s/(\W)/\\$1/g;
307 $prefix = "([" . $prefix . "])";
308 print STDERR ("=> prefix=\"$prefix\"\n") if $debug;
311 # Verify correctness of optionlist.
313 while ( @optionlist ) {
314 my $opt = shift (@optionlist);
316 # Strip leading prefix so people can specify "--foo=i" if they like.
317 $opt = $+ if $opt =~ /^$prefix+(.*)$/s;
319 if ( $opt eq '<>' ) {
320 if ( (defined $userlinkage)
321 && !(@optionlist > 0 && ref($optionlist[0]))
322 && (exists $userlinkage->{$opt})
323 && ref($userlinkage->{$opt}) ) {
324 unshift (@optionlist, $userlinkage->{$opt});
326 unless ( @optionlist > 0
327 && ref($optionlist[0]) && ref($optionlist[0]) eq 'CODE' ) {
328 $error .= "Option spec <> requires a reference to a subroutine\n";
329 # Kill the linkage (to avoid another error).
331 if @optionlist && ref($optionlist[0]);
334 $linkage{'<>'} = shift (@optionlist);
339 my ($name, $orig) = ParseOptionSpec ($opt, \%opctl);
340 unless ( defined $name ) {
341 # Failed. $orig contains the error message. Sorry for the abuse.
343 # Kill the linkage (to avoid another error).
345 if @optionlist && ref($optionlist[0]);
349 # If no linkage is supplied in the @optionlist, copy it from
350 # the userlinkage if available.
351 if ( defined $userlinkage ) {
352 unless ( @optionlist > 0 && ref($optionlist[0]) ) {
353 if ( exists $userlinkage->{$orig} &&
354 ref($userlinkage->{$orig}) ) {
355 print STDERR ("=> found userlinkage for \"$orig\": ",
356 "$userlinkage->{$orig}\n")
358 unshift (@optionlist, $userlinkage->{$orig});
361 # Do nothing. Being undefined will be handled later.
367 # Copy the linkage. If omitted, link to global variable.
368 if ( @optionlist > 0 && ref($optionlist[0]) ) {
369 print STDERR ("=> link \"$orig\" to $optionlist[0]\n")
371 my $rl = ref($linkage{$orig} = shift (@optionlist));
373 if ( $rl eq "ARRAY" ) {
374 $opctl{$name}[CTL_DEST] = CTL_DEST_ARRAY;
376 elsif ( $rl eq "HASH" ) {
377 $opctl{$name}[CTL_DEST] = CTL_DEST_HASH;
379 elsif ( $rl eq "SCALAR" ) {
380 # if ( $opctl{$name}[CTL_DEST] == CTL_DEST_ARRAY ) {
381 # my $t = $linkage{$orig};
382 # $$t = $linkage{$orig} = [];
384 # elsif ( $opctl{$name}[CTL_DEST] == CTL_DEST_HASH ) {
390 elsif ( $rl eq "CODE" ) {
394 $error .= "Invalid option linkage for \"$opt\"\n";
398 # Link to global $opt_XXX variable.
399 # Make sure a valid perl identifier results.
402 if ( $opctl{$name}[CTL_DEST] == CTL_DEST_ARRAY ) {
403 print STDERR ("=> link \"$orig\" to \@$pkg","::opt_$ov\n")
405 eval ("\$linkage{\$orig} = \\\@".$pkg."::opt_$ov;");
407 elsif ( $opctl{$name}[CTL_DEST] == CTL_DEST_HASH ) {
408 print STDERR ("=> link \"$orig\" to \%$pkg","::opt_$ov\n")
410 eval ("\$linkage{\$orig} = \\\%".$pkg."::opt_$ov;");
413 print STDERR ("=> link \"$orig\" to \$$pkg","::opt_$ov\n")
415 eval ("\$linkage{\$orig} = \\\$".$pkg."::opt_$ov;");
420 # Bail out if errors found.
421 die ($error) if $error;
424 # Supply --version and --help support, if needed and allowed.
425 if ( defined($auto_version) ? $auto_version : ($requested_version >= 2.3203) ) {
426 if ( !defined($opctl{version}) ) {
427 $opctl{version} = ['','version',0,CTL_DEST_CODE,undef];
428 $linkage{version} = \&VersionMessage;
432 if ( defined($auto_help) ? $auto_help : ($requested_version >= 2.3203) ) {
433 if ( !defined($opctl{help}) && !defined($opctl{'?'}) ) {
434 $opctl{help} = $opctl{'?'} = ['','help',0,CTL_DEST_CODE,undef];
435 $linkage{help} = \&HelpMessage;
440 # Show the options tables if debugging.
444 while ( ($k,$v) = each(%opctl) ) {
445 print STDERR ($arrow, "\$opctl{$k} = $v ", OptCtl($v), "\n");
450 # Process argument list
452 while ( $goon && @ARGV > 0 ) {
455 $opt = shift (@ARGV);
456 print STDERR ("=> arg \"", $opt, "\"\n") if $debug;
458 # Double dash is option list terminator.
459 if ( $opt eq $argend ) {
460 push (@ret, $argend) if $passthrough;
466 my $found; # success status
467 my $key; # key (if hash type)
468 my $arg; # option argument
469 my $ctl; # the opctl entry
471 ($found, $opt, $ctl, $arg, $key) =
472 FindOption ($prefix, $argend, $opt, \%opctl);
476 # FindOption undefines $opt in case of errors.
477 next unless defined $opt;
480 while ( defined $arg ) {
482 # Get the canonical name.
483 print STDERR ("=> cname for \"$opt\" is ") if $debug;
484 $opt = $ctl->[CTL_CNAME];
485 print STDERR ("\"$ctl->[CTL_CNAME]\"\n") if $debug;
487 if ( defined $linkage{$opt} ) {
488 print STDERR ("=> ref(\$L{$opt}) -> ",
489 ref($linkage{$opt}), "\n") if $debug;
491 if ( ref($linkage{$opt}) eq 'SCALAR' ) {
492 if ( $ctl->[CTL_TYPE] eq '+' ) {
493 print STDERR ("=> \$\$L{$opt} += \"$arg\"\n")
495 if ( defined ${$linkage{$opt}} ) {
496 ${$linkage{$opt}} += $arg;
499 ${$linkage{$opt}} = $arg;
502 elsif ( $ctl->[CTL_DEST] == CTL_DEST_ARRAY ) {
503 print STDERR ("=> ref(\$L{$opt}) auto-vivified",
506 my $t = $linkage{$opt};
507 $$t = $linkage{$opt} = [];
508 print STDERR ("=> push(\@{\$L{$opt}, \"$arg\")\n")
510 push (@{$linkage{$opt}}, $arg);
512 elsif ( $ctl->[CTL_DEST] == CTL_DEST_HASH ) {
513 print STDERR ("=> ref(\$L{$opt}) auto-vivified",
516 my $t = $linkage{$opt};
517 $$t = $linkage{$opt} = {};
518 print STDERR ("=> \$\$L{$opt}->{$key} = \"$arg\"\n")
520 $linkage{$opt}->{$key} = $arg;
523 print STDERR ("=> \$\$L{$opt} = \"$arg\"\n")
525 ${$linkage{$opt}} = $arg;
528 elsif ( ref($linkage{$opt}) eq 'ARRAY' ) {
529 print STDERR ("=> push(\@{\$L{$opt}, \"$arg\")\n")
531 push (@{$linkage{$opt}}, $arg);
533 elsif ( ref($linkage{$opt}) eq 'HASH' ) {
534 print STDERR ("=> \$\$L{$opt}->{$key} = \"$arg\"\n")
536 $linkage{$opt}->{$key} = $arg;
538 elsif ( ref($linkage{$opt}) eq 'CODE' ) {
539 print STDERR ("=> &L{$opt}(\"$opt\"",
540 $ctl->[CTL_DEST] == CTL_DEST_HASH ? ", \"$key\"" : "",
543 my $eval_error = do {
545 local $SIG{__DIE__} = '__DEFAULT__';
547 &{$linkage{$opt}}($opt,
548 $ctl->[CTL_DEST] == CTL_DEST_HASH ? ($key) : (),
553 print STDERR ("=> die($eval_error)\n")
554 if $debug && $eval_error ne '';
555 if ( $eval_error =~ /^!/ ) {
556 if ( $eval_error =~ /^!FINISH\b/ ) {
560 elsif ( $eval_error ne '' ) {
566 print STDERR ("Invalid REF type \"", ref($linkage{$opt}),
568 die("Getopt::Long -- internal error!\n");
571 # No entry in linkage means entry in userlinkage.
572 elsif ( $ctl->[CTL_DEST] == CTL_DEST_ARRAY ) {
573 if ( defined $userlinkage->{$opt} ) {
574 print STDERR ("=> push(\@{\$L{$opt}}, \"$arg\")\n")
576 push (@{$userlinkage->{$opt}}, $arg);
579 print STDERR ("=>\$L{$opt} = [\"$arg\"]\n")
581 $userlinkage->{$opt} = [$arg];
584 elsif ( $ctl->[CTL_DEST] == CTL_DEST_HASH ) {
585 if ( defined $userlinkage->{$opt} ) {
586 print STDERR ("=> \$L{$opt}->{$key} = \"$arg\"\n")
588 $userlinkage->{$opt}->{$key} = $arg;
591 print STDERR ("=>\$L{$opt} = {$key => \"$arg\"}\n")
593 $userlinkage->{$opt} = {$key => $arg};
597 if ( $ctl->[CTL_TYPE] eq '+' ) {
598 print STDERR ("=> \$L{$opt} += \"$arg\"\n")
600 if ( defined $userlinkage->{$opt} ) {
601 $userlinkage->{$opt} += $arg;
604 $userlinkage->{$opt} = $arg;
608 print STDERR ("=>\$L{$opt} = \"$arg\"\n") if $debug;
609 $userlinkage->{$opt} = $arg;
614 last if $argcnt >= $ctl->[CTL_AMAX];
618 if ( $argcnt < $ctl->[CTL_AMIN] ) {
620 if ( ValidValue($ctl, $ARGV[0], 1, $argend, $prefix) ) {
622 ($key,$arg) = $arg =~ /^([^=]+)=(.*)/
623 if $ctl->[CTL_DEST] == CTL_DEST_HASH;
626 warn("Value \"$ARGV[0]\" invalid for option $opt\n");
630 warn("Insufficient arguments for option $opt\n");
636 if ( @ARGV && ValidValue($ctl, $ARGV[0], 0, $argend, $prefix) ) {
638 ($key,$arg) = $arg =~ /^([^=]+)=(.*)/
639 if $ctl->[CTL_DEST] == CTL_DEST_HASH;
645 # Not an option. Save it if we $PERMUTE and don't have a <>.
646 elsif ( $order == $PERMUTE ) {
647 # Try non-options call-back.
649 if ( (defined ($cb = $linkage{'<>'})) ) {
650 print STDERR ("=> &L{$tryopt}(\"$tryopt\")\n")
652 my $eval_error = do {
654 local $SIG{__DIE__} = '__DEFAULT__';
655 eval { &$cb ($tryopt) };
658 print STDERR ("=> die($eval_error)\n")
659 if $debug && $eval_error ne '';
660 if ( $eval_error =~ /^!/ ) {
661 if ( $eval_error =~ /^!FINISH\b/ ) {
665 elsif ( $eval_error ne '' ) {
671 print STDERR ("=> saving \"$tryopt\" ",
672 "(not an option, may permute)\n") if $debug;
673 push (@ret, $tryopt);
678 # ...otherwise, terminate.
680 # Push this one back and exit.
681 unshift (@ARGV, $tryopt);
682 return ($error == 0);
688 if ( @ret && $order == $PERMUTE ) {
689 # Push back accumulated arguments
690 print STDERR ("=> restoring \"", join('" "', @ret), "\"\n")
692 unshift (@ARGV, @ret);
695 return ($error == 0);
698 # A readable representation of what's in an optbl.
701 my @v = map { defined($_) ? ($_) : ("<undef>") } @$v;
706 "\"$v[CTL_DEFAULT]\"",
707 ("\$","\@","\%","\&")[$v[CTL_DEST] || 0],
710 # $v[CTL_RANGE] || '',
711 # $v[CTL_REPEAT] || '',
715 # Parse an option specification and fill the tables.
716 sub ParseOptionSpec ($$) {
717 my ($opt, $opctl) = @_;
724 # Alias names, or "?"
725 (?: \| (?: \? | \w[-\w]* )? )*
728 # Either modifiers ...
731 # ... or a value/dest/repeat specification
732 [=:] [ionfs] [@%]? (?: \{\d*,?\d*\} )?
734 # ... or an optional-with-default spec
735 : (?: -?\d+ | \+ ) [@%]?
738 return (undef, "Error in option spec: \"$opt\"\n");
741 my ($names, $spec) = ($1, $2);
742 $spec = '' unless defined $spec;
744 # $orig keeps track of the primary name the user specified.
745 # This name will be used for the internal or external linkage.
746 # In other words, if the user specifies "FoO|BaR", it will
747 # match any case combinations of 'foo' and 'bar', but if a global
748 # variable needs to be set, it will be $opt_FoO in the exact case
753 if ( defined $names ) {
754 @names = split (/\|/, $names);
762 # Construct the opctl entries.
764 if ( $spec eq '' || $spec eq '+' || $spec eq '!' ) {
765 # Fields are hard-wired here.
766 $entry = [$spec,$orig,undef,CTL_DEST_SCALAR,0,0];
768 elsif ( $spec =~ /^:(-?\d+|\+)([@%])?$/ ) {
771 my $type = $def eq '+' ? 'I' : 'i';
773 $dest = $dest eq '@' ? CTL_DEST_ARRAY
774 : $dest eq '%' ? CTL_DEST_HASH : CTL_DEST_SCALAR;
775 # Fields are hard-wired here.
776 $entry = [$type,$orig,$def eq '+' ? undef : $def,
780 my ($mand, $type, $dest) =
781 $spec =~ /^([=:])([ionfs])([@%])?(\{(\d+)?(,)?(\d+)?\})?$/;
782 return (undef, "Cannot repeat while bundling: \"$opt\"\n")
783 if $bundling && defined($4);
784 my ($mi, $cm, $ma) = ($5, $6, $7);
785 return (undef, "{0} is useless in option spec: \"$opt\"\n")
786 if defined($mi) && !$mi && !defined($ma) && !defined($cm);
788 $type = 'i' if $type eq 'n';
790 $dest = $dest eq '@' ? CTL_DEST_ARRAY
791 : $dest eq '%' ? CTL_DEST_HASH : CTL_DEST_SCALAR;
792 # Default minargs to 1/0 depending on mand status.
793 $mi = $mand eq '=' ? 1 : 0 unless defined $mi;
794 # Adjust mand status according to minargs.
795 $mand = $mi ? '=' : ':';
797 $ma = $mi ? $mi : 1 unless defined $ma || defined $cm;
798 return (undef, "Max must be greater than zero in option spec: \"$opt\"\n")
799 if defined($ma) && !$ma;
800 return (undef, "Max less than min in option spec: \"$opt\"\n")
801 if defined($ma) && $ma < $mi;
803 # Fields are hard-wired here.
804 $entry = [$type,$orig,undef,$dest,$mi,$ma||-1];
807 # Process all names. First is canonical, the rest are aliases.
812 if $ignorecase > (($bundling && length($_) == 1) ? 1 : 0);
814 if ( exists $opctl->{$_} ) {
815 $dups .= "Duplicate specification \"$opt\" for option \"$_\"\n";
818 if ( $spec eq '!' ) {
819 $opctl->{"no$_"} = $entry;
820 $opctl->{"no-$_"} = $entry;
821 $opctl->{$_} = [@$entry];
822 $opctl->{$_}->[CTL_TYPE] = '';
825 $opctl->{$_} = $entry;
829 if ( $dups && $^W ) {
830 foreach ( split(/\n+/, $dups) ) {
838 sub FindOption ($$$$) {
840 # returns (1, $opt, $ctl, $arg, $key) if okay,
841 # returns (1, undef) if option in error,
842 # returns (0) otherwise.
844 my ($prefix, $argend, $opt, $opctl) = @_;
846 print STDERR ("=> find \"$opt\"\n") if $debug;
848 return (0) unless $opt =~ /^$prefix(.*)$/s;
849 return (0) if $opt eq "-" && !defined $opctl->{''};
854 print STDERR ("=> split \"$starter\"+\"$opt\"\n") if $debug;
856 my $optarg; # value supplied with --opt=value
857 my $rest; # remainder from unbundling
859 # If it is a long option, it may include the value.
860 # With getopt_compat, only if not bundling.
861 if ( ($starter eq "--"
862 || ($getopt_compat && ($bundling == 0 || $bundling == 2)))
863 && $opt =~ /^([^=]+)=(.*)$/s ) {
866 print STDERR ("=> option \"", $opt,
867 "\", optarg = \"$optarg\"\n") if $debug;
872 my $tryopt = $opt; # option to try
874 if ( $bundling && $starter eq '-' ) {
876 # To try overrides, obey case ignore.
877 $tryopt = $ignorecase ? lc($opt) : $opt;
879 # If bundling == 2, long options can override bundles.
880 if ( $bundling == 2 && length($tryopt) > 1
881 && defined ($opctl->{$tryopt}) ) {
882 print STDERR ("=> $starter$tryopt overrides unbundling\n")
887 # Unbundle single letter option.
888 $rest = length ($tryopt) > 0 ? substr ($tryopt, 1) : '';
889 $tryopt = substr ($tryopt, 0, 1);
890 $tryopt = lc ($tryopt) if $ignorecase > 1;
891 print STDERR ("=> $starter$tryopt unbundled from ",
892 "$starter$tryopt$rest\n") if $debug;
893 $rest = undef unless $rest ne '';
897 # Try auto-abbreviation.
898 elsif ( $autoabbrev ) {
899 # Sort the possible long option names.
900 my @names = sort(keys (%$opctl));
901 # Downcase if allowed.
902 $opt = lc ($opt) if $ignorecase;
904 # Turn option name into pattern.
905 my $pat = quotemeta ($opt);
906 # Look up in option names.
907 my @hits = grep (/^$pat/, @names);
908 print STDERR ("=> ", scalar(@hits), " hits (@hits) with \"$pat\" ",
909 "out of ", scalar(@names), "\n") if $debug;
911 # Check for ambiguous results.
912 unless ( (@hits <= 1) || (grep ($_ eq $opt, @hits) == 1) ) {
913 # See if all matches are for the same option.
916 $_ = $opctl->{$_}->[CTL_CNAME]
917 if defined $opctl->{$_}->[CTL_CNAME];
920 # Remove auto-supplied options (version, help).
921 if ( keys(%hit) == 2 ) {
922 if ( $auto_version && exists($hit{version}) ) {
923 delete $hit{version};
925 elsif ( $auto_help && exists($hit{help}) ) {
929 # Now see if it really is ambiguous.
930 unless ( keys(%hit) == 1 ) {
931 return (0) if $passthrough;
932 warn ("Option ", $opt, " is ambiguous (",
933 join(", ", @hits), ")\n");
940 # Complete the option name, if appropriate.
941 if ( @hits == 1 && $hits[0] ne $opt ) {
943 $tryopt = lc ($tryopt) if $ignorecase;
944 print STDERR ("=> option \"$opt\" -> \"$tryopt\"\n")
949 # Map to all lowercase if ignoring case.
950 elsif ( $ignorecase ) {
954 # Check validity by fetching the info.
955 my $ctl = $opctl->{$tryopt};
956 unless ( defined $ctl ) {
957 return (0) if $passthrough;
958 # Pretend one char when bundling.
959 if ( $bundling == 1) {
960 $opt = substr($opt,0,1);
961 unshift (@ARGV, $starter.$rest) if defined $rest;
963 warn ("Unknown option: ", $opt, "\n");
969 print STDERR ("=> found ", OptCtl($ctl),
970 " for \"", $opt, "\"\n") if $debug;
972 #### Determine argument status ####
974 # If it is an option w/o argument, we're almost finished with it.
975 my $type = $ctl->[CTL_TYPE];
978 if ( $type eq '' || $type eq '!' || $type eq '+' ) {
979 if ( defined $optarg ) {
980 return (0) if $passthrough;
981 warn ("Option ", $opt, " does not take an argument\n");
985 elsif ( $type eq '' || $type eq '+' ) {
986 # Supply explicit value.
990 $opt =~ s/^no-?//i; # strip NO prefix
991 $arg = 0; # supply explicit value
993 unshift (@ARGV, $starter.$rest) if defined $rest;
994 return (1, $opt, $ctl, $arg);
997 # Get mandatory status and type info.
998 my $mand = $ctl->[CTL_AMIN];
1000 # Check if there is an option argument available.
1001 if ( $gnu_compat && defined $optarg && $optarg eq '' ) {
1002 return (1, $opt, $ctl, $type eq 's' ? '' : 0) unless $mand;
1003 $optarg = 0 unless $type eq 's';
1006 # Check if there is an option argument available.
1007 if ( defined $optarg
1009 : !(defined $rest || @ARGV > 0) ) {
1010 # Complain if this option needs an argument.
1012 return (0) if $passthrough;
1013 warn ("Option ", $opt, " requires an argument\n");
1017 if ( $type eq 'I' ) {
1018 # Fake incremental type.
1021 return (1, $opt, \@c, 1);
1023 return (1, $opt, $ctl,
1024 defined($ctl->[CTL_DEFAULT]) ? $ctl->[CTL_DEFAULT] :
1025 $type eq 's' ? '' : 0);
1028 # Get (possibly optional) argument.
1029 $arg = (defined $rest ? $rest
1030 : (defined $optarg ? $optarg : shift (@ARGV)));
1032 # Get key if this is a "name=value" pair for a hash option.
1034 if ($ctl->[CTL_DEST] == CTL_DEST_HASH && defined $arg) {
1035 ($key, $arg) = ($arg =~ /^([^=]*)=(.*)$/s) ? ($1, $2)
1036 : ($arg, defined($ctl->[CTL_DEFAULT]) ? $ctl->[CTL_DEFAULT] :
1037 ($mand ? undef : ($type eq 's' ? "" : 1)));
1038 if (! defined $arg) {
1039 warn ("Option $opt, key \"$key\", requires a value\n");
1042 unshift (@ARGV, $starter.$rest) if defined $rest;
1047 #### Check if the argument is valid for this option ####
1049 my $key_valid = $ctl->[CTL_DEST] == CTL_DEST_HASH ? "[^=]+=" : "";
1051 if ( $type eq 's' ) { # string
1052 # A mandatory string takes anything.
1053 return (1, $opt, $ctl, $arg, $key) if $mand;
1055 # An optional string takes almost anything.
1056 return (1, $opt, $ctl, $arg, $key)
1057 if defined $optarg || defined $rest;
1058 return (1, $opt, $ctl, $arg, $key) if $arg eq "-"; # ??
1060 # Check for option or option list terminator.
1061 if ($arg eq $argend ||
1062 $arg =~ /^$prefix.+/) {
1064 unshift (@ARGV, $arg);
1065 # Supply empty value.
1070 elsif ( $type eq 'i' # numeric/integer
1071 || $type eq 'I' # numeric/integer w/ incr default
1072 || $type eq 'o' ) { # dec/oct/hex/bin value
1075 $type eq 'o' ? "[-+]?[1-9][0-9]*|0x[0-9a-f]+|0b[01]+|0[0-7]*"
1078 if ( $bundling && defined $rest
1079 && $rest =~ /^($key_valid)($o_valid)(.*)$/si ) {
1080 ($key, $arg, $rest) = ($1, $2, $+);
1082 $arg = ($type eq 'o' && $arg =~ /^0/) ? oct($arg) : 0+$arg;
1083 unshift (@ARGV, $starter.$rest) if defined $rest && $rest ne '';
1085 elsif ( $arg =~ /^($o_valid)$/si ) {
1086 $arg = ($type eq 'o' && $arg =~ /^0/) ? oct($arg) : 0+$arg;
1089 if ( defined $optarg || $mand ) {
1090 if ( $passthrough ) {
1091 unshift (@ARGV, defined $rest ? $starter.$rest : $arg)
1092 unless defined $optarg;
1095 warn ("Value \"", $arg, "\" invalid for option ",
1097 $type eq 'o' ? "extended " : '',
1098 "number expected)\n");
1101 unshift (@ARGV, $starter.$rest) if defined $rest;
1106 unshift (@ARGV, defined $rest ? $starter.$rest : $arg);
1107 if ( $type eq 'I' ) {
1108 # Fake incremental type.
1111 return (1, $opt, \@c, 1);
1113 # Supply default value.
1114 $arg = defined($ctl->[CTL_DEFAULT]) ? $ctl->[CTL_DEFAULT] : 0;
1119 elsif ( $type eq 'f' ) { # real number, int is also ok
1120 # We require at least one digit before a point or 'e',
1121 # and at least one digit following the point and 'e'.
1123 if ( $bundling && defined $rest &&
1124 $rest =~ /^($key_valid)([-+]?[0-9]+(\.[0-9]+)?([eE][-+]?[0-9]+)?)(.*)$/s ) {
1125 ($key, $arg, $rest) = ($1, $2, $+);
1127 unshift (@ARGV, $starter.$rest) if defined $rest && $rest ne '';
1129 elsif ( $arg !~ /^[-+]?[0-9.]+(\.[0-9]+)?([eE][-+]?[0-9]+)?$/ ) {
1130 if ( defined $optarg || $mand ) {
1131 if ( $passthrough ) {
1132 unshift (@ARGV, defined $rest ? $starter.$rest : $arg)
1133 unless defined $optarg;
1136 warn ("Value \"", $arg, "\" invalid for option ",
1137 $opt, " (real number expected)\n");
1140 unshift (@ARGV, $starter.$rest) if defined $rest;
1145 unshift (@ARGV, defined $rest ? $starter.$rest : $arg);
1146 # Supply default value.
1152 die("Getopt::Long internal error (Can't happen)\n");
1154 return (1, $opt, $ctl, $arg, $key);
1157 sub ValidValue ($$$$$) {
1158 my ($ctl, $arg, $mand, $argend, $prefix) = @_;
1160 if ( $ctl->[CTL_DEST] == CTL_DEST_HASH ) {
1161 return 0 unless $arg =~ /[^=]+=(.*)/;
1165 my $type = $ctl->[CTL_TYPE];
1167 if ( $type eq 's' ) { # string
1168 # A mandatory string takes anything.
1169 return (1) if $mand;
1171 return (1) if $arg eq "-";
1173 # Check for option or option list terminator.
1174 return 0 if $arg eq $argend || $arg =~ /^$prefix.+/;
1178 elsif ( $type eq 'i' # numeric/integer
1179 || $type eq 'I' # numeric/integer w/ incr default
1180 || $type eq 'o' ) { # dec/oct/hex/bin value
1183 $type eq 'o' ? "[-+]?[1-9][0-9]*|0x[0-9a-f]+|0b[01]+|0[0-7]*"
1186 return $arg =~ /^$o_valid$/si;
1189 elsif ( $type eq 'f' ) { # real number, int is also ok
1190 # We require at least one digit before a point or 'e',
1191 # and at least one digit following the point and 'e'.
1193 return $arg =~ /^[-+]?[0-9.]+(\.[0-9]+)?([eE][-+]?[0-9]+)?$/;
1195 die("ValidValue: Cannot happen\n");
1198 # Getopt::Long Configuration.
1203 [ $error, $debug, $major_version, $minor_version,
1204 $autoabbrev, $getopt_compat, $ignorecase, $bundling, $order,
1205 $gnu_compat, $passthrough, $genprefix, $auto_version, $auto_help ];
1207 if ( ref($options[0]) eq 'ARRAY' ) {
1208 ( $error, $debug, $major_version, $minor_version,
1209 $autoabbrev, $getopt_compat, $ignorecase, $bundling, $order,
1210 $gnu_compat, $passthrough, $genprefix, $auto_version, $auto_help ) =
1215 foreach $opt ( @options ) {
1216 my $try = lc ($opt);
1218 if ( $try =~ /^no_?(.*)$/s ) {
1222 if ( ($try eq 'default' or $try eq 'defaults') && $action ) {
1225 elsif ( ($try eq 'posix_default' or $try eq 'posix_defaults') ) {
1226 local $ENV{POSIXLY_CORRECT};
1227 $ENV{POSIXLY_CORRECT} = 1 if $action;
1230 elsif ( $try eq 'auto_abbrev' or $try eq 'autoabbrev' ) {
1231 $autoabbrev = $action;
1233 elsif ( $try eq 'getopt_compat' ) {
1234 $getopt_compat = $action;
1236 elsif ( $try eq 'gnu_getopt' ) {
1244 elsif ( $try eq 'gnu_compat' ) {
1245 $gnu_compat = $action;
1247 elsif ( $try =~ /^(auto_?)?version$/ ) {
1248 $auto_version = $action;
1250 elsif ( $try =~ /^(auto_?)?help$/ ) {
1251 $auto_help = $action;
1253 elsif ( $try eq 'ignorecase' or $try eq 'ignore_case' ) {
1254 $ignorecase = $action;
1256 elsif ( $try eq 'ignore_case_always' ) {
1257 $ignorecase = $action ? 2 : 0;
1259 elsif ( $try eq 'bundling' ) {
1260 $bundling = $action;
1262 elsif ( $try eq 'bundling_override' ) {
1263 $bundling = $action ? 2 : 0;
1265 elsif ( $try eq 'require_order' ) {
1266 $order = $action ? $REQUIRE_ORDER : $PERMUTE;
1268 elsif ( $try eq 'permute' ) {
1269 $order = $action ? $PERMUTE : $REQUIRE_ORDER;
1271 elsif ( $try eq 'pass_through' or $try eq 'passthrough' ) {
1272 $passthrough = $action;
1274 elsif ( $try =~ /^prefix=(.+)$/ && $action ) {
1276 # Turn into regexp. Needs to be parenthesized!
1277 $genprefix = "(" . quotemeta($genprefix) . ")";
1278 eval { '' =~ /$genprefix/; };
1279 die("Getopt::Long: invalid pattern \"$genprefix\"") if $@;
1281 elsif ( $try =~ /^prefix_pattern=(.+)$/ && $action ) {
1283 # Parenthesize if needed.
1284 $genprefix = "(" . $genprefix . ")"
1285 unless $genprefix =~ /^\(.*\)$/;
1286 eval { '' =~ /$genprefix/; };
1287 die("Getopt::Long: invalid pattern \"$genprefix\"") if $@;
1289 elsif ( $try eq 'debug' ) {
1293 die("Getopt::Long: unknown config parameter \"$opt\"")
1304 # Issue a standard message for --version.
1306 # The arguments are mostly the same as for Pod::Usage::pod2usage:
1308 # - a number (exit value)
1309 # - a string (lead in message)
1310 # - a hash with options. See Pod::Usage for details.
1312 sub VersionMessage(@) {
1314 my $pa = setup_pa_args("version", @_);
1316 my $v = $main::VERSION;
1317 my $fh = $pa->{-output} ||
1318 ($pa->{-exitval} eq "NOEXIT" || $pa->{-exitval} < 2) ? \*STDOUT : \*STDERR;
1320 print $fh (defined($pa->{-message}) ? $pa->{-message} : (),
1321 $0, defined $v ? " version $v" : (),
1323 "(", __PACKAGE__, "::", "GetOptions",
1325 defined($Getopt::Long::VERSION_STRING)
1326 ? $Getopt::Long::VERSION_STRING : $VERSION, ";",
1328 $] >= 5.006 ? sprintf("%vd", $^V) : $],
1330 exit($pa->{-exitval}) unless $pa->{-exitval} eq "NOEXIT";
1333 # Issue a standard message for --help.
1335 # The arguments are the same as for Pod::Usage::pod2usage:
1337 # - a number (exit value)
1338 # - a string (lead in message)
1339 # - a hash with options. See Pod::Usage for details.
1341 sub HelpMessage(@) {
1346 } || die("Cannot provide help: cannot load Pod::Usage\n");
1348 # Note that pod2usage will issue a warning if -exitval => NOEXIT.
1349 pod2usage(setup_pa_args("help", @_));
1353 # Helper routine to set up a normalized hash ref to be used as
1354 # argument to pod2usage.
1355 sub setup_pa_args($@) {
1356 my $tag = shift; # who's calling
1358 # If called by direct binding to an option, it will get the option
1359 # name and value as arguments. Remove these, if so.
1360 @_ = () if @_ == 2 && $_[0] eq $tag;
1370 # At this point, $pa can be a number (exit value), string
1371 # (message) or hash with options.
1373 if ( UNIVERSAL::isa($pa, 'HASH') ) {
1374 # Get rid of -msg vs. -message ambiguity.
1375 $pa->{-message} = $pa->{-msg};
1376 delete($pa->{-msg});
1378 elsif ( $pa =~ /^-?\d+$/ ) {
1379 $pa = { -exitval => $pa };
1382 $pa = { -message => $pa };
1385 # These are _our_ defaults.
1386 $pa->{-verbose} = 0 unless exists($pa->{-verbose});
1387 $pa->{-exitval} = 0 unless exists($pa->{-exitval});
1391 # Sneak way to know what version the user requested.
1393 $requested_version = $_[1];
1394 shift->SUPER::VERSION(@_);
1399 ################ Documentation ################
1403 Getopt::Long - Extended processing of command line options
1408 my $data = "file.dat";
1411 $result = GetOptions ("length=i" => \$length, # numeric
1412 "file=s" => \$data, # string
1413 "verbose" => \$verbose); # flag
1417 The Getopt::Long module implements an extended getopt function called
1418 GetOptions(). This function adheres to the POSIX syntax for command
1419 line options, with GNU extensions. In general, this means that options
1420 have long names instead of single letters, and are introduced with a
1421 double dash "--". Support for bundling of command line options, as was
1422 the case with the more traditional single-letter approach, is provided
1423 but not enabled by default.
1425 =head1 Command Line Options, an Introduction
1427 Command line operated programs traditionally take their arguments from
1428 the command line, for example filenames or other information that the
1429 program needs to know. Besides arguments, these programs often take
1430 command line I<options> as well. Options are not necessary for the
1431 program to work, hence the name 'option', but are used to modify its
1432 default behaviour. For example, a program could do its job quietly,
1433 but with a suitable option it could provide verbose information about
1436 Command line options come in several flavours. Historically, they are
1437 preceded by a single dash C<->, and consist of a single letter.
1441 Usually, these single-character options can be bundled:
1445 Options can have values, the value is placed after the option
1446 character. Sometimes with whitespace in between, sometimes not:
1450 Due to the very cryptic nature of these options, another style was
1451 developed that used long names. So instead of a cryptic C<-l> one
1452 could use the more descriptive C<--long>. To distinguish between a
1453 bundle of single-character options and a long one, two dashes are used
1454 to precede the option name. Early implementations of long options used
1455 a plus C<+> instead. Also, option values could be specified either
1464 The C<+> form is now obsolete and strongly deprecated.
1466 =head1 Getting Started with Getopt::Long
1468 Getopt::Long is the Perl5 successor of C<newgetopt.pl>. This was
1469 the first Perl module that provided support for handling the new style
1470 of command line options, hence the name Getopt::Long. This module
1471 also supports single-character options and bundling. In this case, the
1472 options are restricted to alphabetic characters only, and the
1473 characters C<?> and C<->.
1475 To use Getopt::Long from a Perl program, you must include the
1476 following line in your Perl program:
1480 This will load the core of the Getopt::Long module and prepare your
1481 program for using it. Most of the actual Getopt::Long code is not
1482 loaded until you really call one of its functions.
1484 In the default configuration, options names may be abbreviated to
1485 uniqueness, case does not matter, and a single dash is sufficient,
1486 even for long option names. Also, options may be placed between
1487 non-option arguments. See L<Configuring Getopt::Long> for more
1488 details on how to configure Getopt::Long.
1490 =head2 Simple options
1492 The most simple options are the ones that take no values. Their mere
1493 presence on the command line enables the option. Popular examples are:
1495 --all --verbose --quiet --debug
1497 Handling simple options is straightforward:
1499 my $verbose = ''; # option variable with default value (false)
1500 my $all = ''; # option variable with default value (false)
1501 GetOptions ('verbose' => \$verbose, 'all' => \$all);
1503 The call to GetOptions() parses the command line arguments that are
1504 present in C<@ARGV> and sets the option variable to the value C<1> if
1505 the option did occur on the command line. Otherwise, the option
1506 variable is not touched. Setting the option value to true is often
1507 called I<enabling> the option.
1509 The option name as specified to the GetOptions() function is called
1510 the option I<specification>. Later we'll see that this specification
1511 can contain more than just the option name. The reference to the
1512 variable is called the option I<destination>.
1514 GetOptions() will return a true value if the command line could be
1515 processed successfully. Otherwise, it will write error messages to
1516 STDERR, and return a false result.
1518 =head2 A little bit less simple options
1520 Getopt::Long supports two useful variants of simple options:
1521 I<negatable> options and I<incremental> options.
1523 A negatable option is specified with an exclamation mark C<!> after the
1526 my $verbose = ''; # option variable with default value (false)
1527 GetOptions ('verbose!' => \$verbose);
1529 Now, using C<--verbose> on the command line will enable C<$verbose>,
1530 as expected. But it is also allowed to use C<--noverbose>, which will
1531 disable C<$verbose> by setting its value to C<0>. Using a suitable
1532 default value, the program can find out whether C<$verbose> is false
1533 by default, or disabled by using C<--noverbose>.
1535 An incremental option is specified with a plus C<+> after the
1538 my $verbose = ''; # option variable with default value (false)
1539 GetOptions ('verbose+' => \$verbose);
1541 Using C<--verbose> on the command line will increment the value of
1542 C<$verbose>. This way the program can keep track of how many times the
1543 option occurred on the command line. For example, each occurrence of
1544 C<--verbose> could increase the verbosity level of the program.
1546 =head2 Mixing command line option with other arguments
1548 Usually programs take command line options as well as other arguments,
1549 for example, file names. It is good practice to always specify the
1550 options first, and the other arguments last. Getopt::Long will,
1551 however, allow the options and arguments to be mixed and 'filter out'
1552 all the options before passing the rest of the arguments to the
1553 program. To stop Getopt::Long from processing further arguments,
1554 insert a double dash C<--> on the command line:
1558 In this example, C<--all> will I<not> be treated as an option, but
1559 passed to the program unharmed, in C<@ARGV>.
1561 =head2 Options with values
1563 For options that take values it must be specified whether the option
1564 value is required or not, and what kind of value the option expects.
1566 Three kinds of values are supported: integer numbers, floating point
1567 numbers, and strings.
1569 If the option value is required, Getopt::Long will take the
1570 command line argument that follows the option and assign this to the
1571 option variable. If, however, the option value is specified as
1572 optional, this will only be done if that value does not look like a
1573 valid command line option itself.
1575 my $tag = ''; # option variable with default value
1576 GetOptions ('tag=s' => \$tag);
1578 In the option specification, the option name is followed by an equals
1579 sign C<=> and the letter C<s>. The equals sign indicates that this
1580 option requires a value. The letter C<s> indicates that this value is
1581 an arbitrary string. Other possible value types are C<i> for integer
1582 values, and C<f> for floating point values. Using a colon C<:> instead
1583 of the equals sign indicates that the option value is optional. In
1584 this case, if no suitable value is supplied, string valued options get
1585 an empty string C<''> assigned, while numeric options are set to C<0>.
1587 =head2 Options with multiple values
1589 Options sometimes take several values. For example, a program could
1590 use multiple directories to search for library files:
1592 --library lib/stdlib --library lib/extlib
1594 To accomplish this behaviour, simply specify an array reference as the
1595 destination for the option:
1597 GetOptions ("library=s" => \@libfiles);
1599 Alternatively, you can specify that the option can have multiple
1600 values by adding a "@", and pass a scalar reference as the
1603 GetOptions ("library=s@" => \$libfiles);
1605 Used with the example above, C<@libfiles> (or C<@$libfiles>) would
1606 contain two strings upon completion: C<"lib/srdlib"> and
1607 C<"lib/extlib">, in that order. It is also possible to specify that
1608 only integer or floating point numbers are acceptable values.
1610 Often it is useful to allow comma-separated lists of values as well as
1611 multiple occurrences of the options. This is easy using Perl's split()
1612 and join() operators:
1614 GetOptions ("library=s" => \@libfiles);
1615 @libfiles = split(/,/,join(',',@libfiles));
1617 Of course, it is important to choose the right separator string for
1620 Warning: What follows is an experimental feature.
1622 Options can take multiple values at once, for example
1624 --coordinates 52.2 16.4 --rgbcolor 255 255 149
1626 This can be accomplished by adding a repeat specifier to the option
1627 specification. Repeat specifiers are very similar to the C<{...}>
1628 repeat specifiers that can be used with regular expression patterns.
1629 For example, the above command line would be handled as follows:
1631 GetOptions('coordinates=f{2}' => \@coor, 'rgbcolor=i{3}' => \@color);
1633 The destination for the option must be an array or array reference.
1635 It is also possible to specify the minimal and maximal number of
1636 arguments an option takes. C<foo=s{2,4}> indicates an option that
1637 takes at least two and at most 4 arguments. C<foo=s{,}> indicates one
1638 or more values; C<foo:s{,}> indicates zero or more option values.
1640 =head2 Options with hash values
1642 If the option destination is a reference to a hash, the option will
1643 take, as value, strings of the form I<key>C<=>I<value>. The value will
1644 be stored with the specified key in the hash.
1646 GetOptions ("define=s" => \%defines);
1648 Alternatively you can use:
1650 GetOptions ("define=s%" => \$defines);
1652 When used with command line options:
1654 --define os=linux --define vendor=redhat
1656 the hash C<%defines> (or C<%$defines>) will contain two keys, C<"os">
1657 with value C<"linux> and C<"vendor"> with value C<"redhat">. It is
1658 also possible to specify that only integer or floating point numbers
1659 are acceptable values. The keys are always taken to be strings.
1661 =head2 User-defined subroutines to handle options
1663 Ultimate control over what should be done when (actually: each time)
1664 an option is encountered on the command line can be achieved by
1665 designating a reference to a subroutine (or an anonymous subroutine)
1666 as the option destination. When GetOptions() encounters the option, it
1667 will call the subroutine with two or three arguments. The first
1668 argument is the name of the option. For a scalar or array destination,
1669 the second argument is the value to be stored. For a hash destination,
1670 the second arguments is the key to the hash, and the third argument
1671 the value to be stored. It is up to the subroutine to store the value,
1672 or do whatever it thinks is appropriate.
1674 A trivial application of this mechanism is to implement options that
1675 are related to each other. For example:
1677 my $verbose = ''; # option variable with default value (false)
1678 GetOptions ('verbose' => \$verbose,
1679 'quiet' => sub { $verbose = 0 });
1681 Here C<--verbose> and C<--quiet> control the same variable
1682 C<$verbose>, but with opposite values.
1684 If the subroutine needs to signal an error, it should call die() with
1685 the desired error message as its argument. GetOptions() will catch the
1686 die(), issue the error message, and record that an error result must
1687 be returned upon completion.
1689 If the text of the error message starts with an exclamation mark C<!>
1690 it is interpreted specially by GetOptions(). There is currently one
1691 special command implemented: C<die("!FINISH")> will cause GetOptions()
1692 to stop processing options, as if it encountered a double dash C<-->.
1694 =head2 Options with multiple names
1696 Often it is user friendly to supply alternate mnemonic names for
1697 options. For example C<--height> could be an alternate name for
1698 C<--length>. Alternate names can be included in the option
1699 specification, separated by vertical bar C<|> characters. To implement
1702 GetOptions ('length|height=f' => \$length);
1704 The first name is called the I<primary> name, the other names are
1707 Multiple alternate names are possible.
1709 =head2 Case and abbreviations
1711 Without additional configuration, GetOptions() will ignore the case of
1712 option names, and allow the options to be abbreviated to uniqueness.
1714 GetOptions ('length|height=f' => \$length, "head" => \$head);
1716 This call will allow C<--l> and C<--L> for the length option, but
1717 requires a least C<--hea> and C<--hei> for the head and height options.
1719 =head2 Summary of Option Specifications
1721 Each option specifier consists of two parts: the name specification
1722 and the argument specification.
1724 The name specification contains the name of the option, optionally
1725 followed by a list of alternative names separated by vertical bar
1728 length option name is "length"
1729 length|size|l name is "length", aliases are "size" and "l"
1731 The argument specification is optional. If omitted, the option is
1732 considered boolean, a value of 1 will be assigned when the option is
1733 used on the command line.
1735 The argument specification can be
1741 The option does not take an argument and may be negated, i.e. prefixed
1742 by "no". E.g. C<"foo!"> will allow C<--foo> (a value of 1 will be
1743 assigned) and C<--nofoo> and C<--no-foo> (a value of 0 will be assigned). If the
1744 option has aliases, this applies to the aliases as well.
1746 Using negation on a single letter option when bundling is in effect is
1747 pointless and will result in a warning.
1751 The option does not take an argument and will be incremented by 1
1752 every time it appears on the command line. E.g. C<"more+">, when used
1753 with C<--more --more --more>, will increment the value three times,
1754 resulting in a value of 3 (provided it was 0 or undefined at first).
1756 The C<+> specifier is ignored if the option destination is not a scalar.
1758 =item = I<type> [ I<desttype> ] [ I<repeat> ]
1760 The option requires an argument of the given type. Supported types
1767 String. An arbitrary sequence of characters. It is valid for the
1768 argument to start with C<-> or C<-->.
1772 Integer. An optional leading plus or minus sign, followed by a
1777 Extended integer, Perl style. This can be either an optional leading
1778 plus or minus sign, followed by a sequence of digits, or an octal
1779 string (a zero, optionally followed by '0', '1', .. '7'), or a
1780 hexadecimal string (C<0x> followed by '0' .. '9', 'a' .. 'f', case
1781 insensitive), or a binary string (C<0b> followed by a series of '0'
1786 Real number. For example C<3.14>, C<-6.23E24> and so on.
1790 The I<desttype> can be C<@> or C<%> to specify that the option is
1791 list or a hash valued. This is only needed when the destination for
1792 the option value is not otherwise specified. It should be omitted when
1795 The I<repeat> specifies the number of values this option takes per
1796 occurrence on the command line. It has the format C<{> [ I<min> ] [ C<,> [ I<max> ] ] C<}>.
1798 I<min> denotes the minimal number of arguments. It defaults to 1 for
1799 options with C<=> and to 0 for options with C<:>, see below. Note that
1800 I<min> overrules the C<=> / C<:> semantics.
1802 I<max> denotes the maximum number of arguments. It must be at least
1803 I<min>. If I<max> is omitted, I<but the comma is not>, there is no
1804 upper bound to the number of argument values taken.
1806 =item : I<type> [ I<desttype> ]
1808 Like C<=>, but designates the argument as optional.
1809 If omitted, an empty string will be assigned to string values options,
1810 and the value zero to numeric options.
1812 Note that if a string argument starts with C<-> or C<-->, it will be
1813 considered an option on itself.
1815 =item : I<number> [ I<desttype> ]
1817 Like C<:i>, but if the value is omitted, the I<number> will be assigned.
1819 =item : + [ I<desttype> ]
1821 Like C<:i>, but if the value is omitted, the current value for the
1822 option will be incremented.
1826 =head1 Advanced Possibilities
1828 =head2 Object oriented interface
1830 Getopt::Long can be used in an object oriented way as well:
1833 $p = new Getopt::Long::Parser;
1834 $p->configure(...configuration options...);
1835 if ($p->getoptions(...options descriptions...)) ...
1837 Configuration options can be passed to the constructor:
1839 $p = new Getopt::Long::Parser
1840 config => [...configuration options...];
1842 =head2 Thread Safety
1844 Getopt::Long is thread safe when using ithreads as of Perl 5.8. It is
1845 I<not> thread safe when using the older (experimental and now
1846 obsolete) threads implementation that was added to Perl 5.005.
1848 =head2 Documentation and help texts
1850 Getopt::Long encourages the use of Pod::Usage to produce help
1851 messages. For example:
1859 GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
1860 pod2usage(1) if $help;
1861 pod2usage(-exitstatus => 0, -verbose => 2) if $man;
1867 sample - Using Getopt::Long and Pod::Usage
1871 sample [options] [file ...]
1874 -help brief help message
1875 -man full documentation
1883 Print a brief help message and exits.
1887 Prints the manual page and exits.
1893 B<This program> will read the given input file(s) and do something
1894 useful with the contents thereof.
1898 See L<Pod::Usage> for details.
1900 =head2 Storing options in a hash
1902 Sometimes, for example when there are a lot of options, having a
1903 separate variable for each of them can be cumbersome. GetOptions()
1904 supports, as an alternative mechanism, storing options in a hash.
1906 To obtain this, a reference to a hash must be passed I<as the first
1907 argument> to GetOptions(). For each option that is specified on the
1908 command line, the option value will be stored in the hash with the
1909 option name as key. Options that are not actually used on the command
1910 line will not be put in the hash, on other words,
1911 C<exists($h{option})> (or defined()) can be used to test if an option
1912 was used. The drawback is that warnings will be issued if the program
1913 runs under C<use strict> and uses C<$h{option}> without testing with
1914 exists() or defined() first.
1917 GetOptions (\%h, 'length=i'); # will store in $h{length}
1919 For options that take list or hash values, it is necessary to indicate
1920 this by appending an C<@> or C<%> sign after the type:
1922 GetOptions (\%h, 'colours=s@'); # will push to @{$h{colours}}
1924 To make things more complicated, the hash may contain references to
1925 the actual destinations, for example:
1928 my %h = ('length' => \$len);
1929 GetOptions (\%h, 'length=i'); # will store in $len
1931 This example is fully equivalent with:
1934 GetOptions ('length=i' => \$len); # will store in $len
1936 Any mixture is possible. For example, the most frequently used options
1937 could be stored in variables while all other options get stored in the
1940 my $verbose = 0; # frequently referred
1941 my $debug = 0; # frequently referred
1942 my %h = ('verbose' => \$verbose, 'debug' => \$debug);
1943 GetOptions (\%h, 'verbose', 'debug', 'filter', 'size=i');
1944 if ( $verbose ) { ... }
1945 if ( exists $h{filter} ) { ... option 'filter' was specified ... }
1949 With bundling it is possible to set several single-character options
1950 at once. For example if C<a>, C<v> and C<x> are all valid options,
1954 would set all three.
1956 Getopt::Long supports two levels of bundling. To enable bundling, a
1957 call to Getopt::Long::Configure is required.
1959 The first level of bundling can be enabled with:
1961 Getopt::Long::Configure ("bundling");
1963 Configured this way, single-character options can be bundled but long
1964 options B<must> always start with a double dash C<--> to avoid
1965 ambiguity. For example, when C<vax>, C<a>, C<v> and C<x> are all valid
1970 would set C<a>, C<v> and C<x>, but
1976 The second level of bundling lifts this restriction. It can be enabled
1979 Getopt::Long::Configure ("bundling_override");
1981 Now, C<-vax> would set the option C<vax>.
1983 When any level of bundling is enabled, option values may be inserted
1984 in the bundle. For example:
1992 When configured for bundling, single-character options are matched
1993 case sensitive while long options are matched case insensitive. To
1994 have the single-character options matched case insensitive as well,
1997 Getopt::Long::Configure ("bundling", "ignorecase_always");
1999 It goes without saying that bundling can be quite confusing.
2001 =head2 The lonesome dash
2003 Normally, a lone dash C<-> on the command line will not be considered
2004 an option. Option processing will terminate (unless "permute" is
2005 configured) and the dash will be left in C<@ARGV>.
2007 It is possible to get special treatment for a lone dash. This can be
2008 achieved by adding an option specification with an empty name, for
2011 GetOptions ('' => \$stdio);
2013 A lone dash on the command line will now be a legal option, and using
2014 it will set variable C<$stdio>.
2016 =head2 Argument callback
2018 A special option 'name' C<< <> >> can be used to designate a subroutine
2019 to handle non-option arguments. When GetOptions() encounters an
2020 argument that does not look like an option, it will immediately call this
2021 subroutine and passes it one parameter: the argument name.
2027 GetOptions ('width=i' => \$width, '<>' => \&process);
2029 When applied to the following command line:
2031 arg1 --width=72 arg2 --width=60 arg3
2034 C<process("arg1")> while C<$width> is C<80>,
2035 C<process("arg2")> while C<$width> is C<72>, and
2036 C<process("arg3")> while C<$width> is C<60>.
2038 This feature requires configuration option B<permute>, see section
2039 L<Configuring Getopt::Long>.
2041 =head1 Configuring Getopt::Long
2043 Getopt::Long can be configured by calling subroutine
2044 Getopt::Long::Configure(). This subroutine takes a list of quoted
2045 strings, each specifying a configuration option to be enabled, e.g.
2046 C<ignore_case>, or disabled, e.g. C<no_ignore_case>. Case does not
2047 matter. Multiple calls to Configure() are possible.
2049 Alternatively, as of version 2.24, the configuration options may be
2050 passed together with the C<use> statement:
2052 use Getopt::Long qw(:config no_ignore_case bundling);
2054 The following options are available:
2060 This option causes all configuration options to be reset to their
2065 This option causes all configuration options to be reset to their
2066 default values as if the environment variable POSIXLY_CORRECT had
2071 Allow option names to be abbreviated to uniqueness.
2072 Default is enabled unless environment variable
2073 POSIXLY_CORRECT has been set, in which case C<auto_abbrev> is disabled.
2077 Allow C<+> to start options.
2078 Default is enabled unless environment variable
2079 POSIXLY_CORRECT has been set, in which case C<getopt_compat> is disabled.
2083 C<gnu_compat> controls whether C<--opt=> is allowed, and what it should
2084 do. Without C<gnu_compat>, C<--opt=> gives an error. With C<gnu_compat>,
2085 C<--opt=> will give option C<opt> and empty value.
2086 This is the way GNU getopt_long() does it.
2090 This is a short way of setting C<gnu_compat> C<bundling> C<permute>
2091 C<no_getopt_compat>. With C<gnu_getopt>, command line handling should be
2092 fully compatible with GNU getopt_long().
2096 Whether command line arguments are allowed to be mixed with options.
2097 Default is disabled unless environment variable
2098 POSIXLY_CORRECT has been set, in which case C<require_order> is enabled.
2100 See also C<permute>, which is the opposite of C<require_order>.
2104 Whether command line arguments are allowed to be mixed with options.
2105 Default is enabled unless environment variable
2106 POSIXLY_CORRECT has been set, in which case C<permute> is disabled.
2107 Note that C<permute> is the opposite of C<require_order>.
2109 If C<permute> is enabled, this means that
2111 --foo arg1 --bar arg2 arg3
2115 --foo --bar arg1 arg2 arg3
2117 If an argument callback routine is specified, C<@ARGV> will always be
2118 empty upon successful return of GetOptions() since all options have been
2119 processed. The only exception is when C<--> is used:
2121 --foo arg1 --bar arg2 -- arg3
2123 This will call the callback routine for arg1 and arg2, and then
2124 terminate GetOptions() leaving C<"arg2"> in C<@ARGV>.
2126 If C<require_order> is enabled, options processing
2127 terminates when the first non-option is encountered.
2129 --foo arg1 --bar arg2 arg3
2133 --foo -- arg1 --bar arg2 arg3
2135 If C<pass_through> is also enabled, options processing will terminate
2136 at the first unrecognized option, or non-option, whichever comes
2139 =item bundling (default: disabled)
2141 Enabling this option will allow single-character options to be
2142 bundled. To distinguish bundles from long option names, long options
2143 I<must> be introduced with C<--> and bundles with C<->.
2145 Note that, if you have options C<a>, C<l> and C<all>, and
2146 auto_abbrev enabled, possible arguments and option settings are:
2148 using argument sets option(s)
2149 ------------------------------------------
2152 -al, -la, -ala, -all,... a, l
2155 The surprising part is that C<--a> sets option C<a> (due to auto
2156 completion), not C<all>.
2158 Note: disabling C<bundling> also disables C<bundling_override>.
2160 =item bundling_override (default: disabled)
2162 If C<bundling_override> is enabled, bundling is enabled as with
2163 C<bundling> but now long option names override option bundles.
2165 Note: disabling C<bundling_override> also disables C<bundling>.
2167 B<Note:> Using option bundling can easily lead to unexpected results,
2168 especially when mixing long options and bundles. Caveat emptor.
2170 =item ignore_case (default: enabled)
2172 If enabled, case is ignored when matching long option names. If,
2173 however, bundling is enabled as well, single character options will be
2174 treated case-sensitive.
2176 With C<ignore_case>, option specifications for options that only
2177 differ in case, e.g., C<"foo"> and C<"Foo">, will be flagged as
2180 Note: disabling C<ignore_case> also disables C<ignore_case_always>.
2182 =item ignore_case_always (default: disabled)
2184 When bundling is in effect, case is ignored on single-character
2187 Note: disabling C<ignore_case_always> also disables C<ignore_case>.
2189 =item auto_version (default:disabled)
2191 Automatically provide support for the B<--version> option if
2192 the application did not specify a handler for this option itself.
2194 Getopt::Long will provide a standard version message that includes the
2195 program name, its version (if $main::VERSION is defined), and the
2196 versions of Getopt::Long and Perl. The message will be written to
2197 standard output and processing will terminate.
2199 C<auto_version> will be enabled if the calling program explicitly
2200 specified a version number higher than 2.32 in the C<use> or
2201 C<require> statement.
2203 =item auto_help (default:disabled)
2205 Automatically provide support for the B<--help> and B<-?> options if
2206 the application did not specify a handler for this option itself.
2208 Getopt::Long will provide a help message using module L<Pod::Usage>. The
2209 message, derived from the SYNOPSIS POD section, will be written to
2210 standard output and processing will terminate.
2212 C<auto_help> will be enabled if the calling program explicitly
2213 specified a version number higher than 2.32 in the C<use> or
2214 C<require> statement.
2216 =item pass_through (default: disabled)
2218 Options that are unknown, ambiguous or supplied with an invalid option
2219 value are passed through in C<@ARGV> instead of being flagged as
2220 errors. This makes it possible to write wrapper scripts that process
2221 only part of the user supplied command line arguments, and pass the
2222 remaining options to some other program.
2224 If C<require_order> is enabled, options processing will terminate at
2225 the first unrecognized option, or non-option, whichever comes first.
2226 However, if C<permute> is enabled instead, results can become confusing.
2228 Note that the options terminator (default C<-->), if present, will
2229 also be passed through in C<@ARGV>.
2233 The string that starts options. If a constant string is not
2234 sufficient, see C<prefix_pattern>.
2236 =item prefix_pattern
2238 A Perl pattern that identifies the strings that introduce options.
2239 Default is C<(--|-|\+)> unless environment variable
2240 POSIXLY_CORRECT has been set, in which case it is C<(--|-)>.
2242 =item debug (default: disabled)
2244 Enable debugging output.
2248 =head1 Exportable Methods
2252 =item VersionMessage
2254 This subroutine provides a standard version message. Its argument can be:
2260 A string containing the text of a message to print I<before> printing
2261 the standard message.
2265 A numeric value corresponding to the desired exit status.
2269 A reference to a hash.
2273 If more than one argument is given then the entire argument list is
2274 assumed to be a hash. If a hash is supplied (either as a reference or
2275 as a list) it should contain one or more elements with the following
2284 The text of a message to print immediately prior to printing the
2285 program's usage message.
2289 The desired exit status to pass to the B<exit()> function.
2290 This should be an integer, or else the string "NOEXIT" to
2291 indicate that control should simply be returned without
2292 terminating the invoking process.
2296 A reference to a filehandle, or the pathname of a file to which the
2297 usage message should be written. The default is C<\*STDERR> unless the
2298 exit value is less than 2 (in which case the default is C<\*STDOUT>).
2302 You cannot tie this routine directly to an option, e.g.:
2304 GetOptions("version" => \&VersionMessage);
2308 GetOptions("version" => sub { VersionMessage() });
2312 This subroutine produces a standard help message, derived from the
2313 program's POD section SYNOPSIS using L<Pod::Usage>. It takes the same
2314 arguments as VersionMessage(). In particular, you cannot tie it
2315 directly to an option, e.g.:
2317 GetOptions("help" => \&HelpMessage);
2321 GetOptions("help" => sub { HelpMessage() });
2325 =head1 Return values and Errors
2327 Configuration errors and errors in the option definitions are
2328 signalled using die() and will terminate the calling program unless
2329 the call to Getopt::Long::GetOptions() was embedded in C<eval { ...
2330 }>, or die() was trapped using C<$SIG{__DIE__}>.
2332 GetOptions returns true to indicate success.
2333 It returns false when the function detected one or more errors during
2334 option parsing. These errors are signalled using warn() and can be
2335 trapped with C<$SIG{__WARN__}>.
2339 The earliest development of C<newgetopt.pl> started in 1990, with Perl
2340 version 4. As a result, its development, and the development of
2341 Getopt::Long, has gone through several stages. Since backward
2342 compatibility has always been extremely important, the current version
2343 of Getopt::Long still supports a lot of constructs that nowadays are
2344 no longer necessary or otherwise unwanted. This section describes
2345 briefly some of these 'features'.
2347 =head2 Default destinations
2349 When no destination is specified for an option, GetOptions will store
2350 the resultant value in a global variable named C<opt_>I<XXX>, where
2351 I<XXX> is the primary name of this option. When a progam executes
2352 under C<use strict> (recommended), these variables must be
2353 pre-declared with our() or C<use vars>.
2355 our $opt_length = 0;
2356 GetOptions ('length=i'); # will store in $opt_length
2358 To yield a usable Perl variable, characters that are not part of the
2359 syntax for variables are translated to underscores. For example,
2360 C<--fpp-struct-return> will set the variable
2361 C<$opt_fpp_struct_return>. Note that this variable resides in the
2362 namespace of the calling program, not necessarily C<main>. For
2365 GetOptions ("size=i", "sizes=i@");
2367 with command line "-size 10 -sizes 24 -sizes 48" will perform the
2368 equivalent of the assignments
2371 @opt_sizes = (24, 48);
2373 =head2 Alternative option starters
2375 A string of alternative option starter characters may be passed as the
2376 first argument (or the first argument after a leading hash reference
2380 GetOptions ('/', 'length=i' => $len);
2382 Now the command line may look like:
2386 Note that to terminate options processing still requires a double dash
2389 GetOptions() will not interpret a leading C<< "<>" >> as option starters
2390 if the next argument is a reference. To force C<< "<" >> and C<< ">" >> as
2391 option starters, use C<< "><" >>. Confusing? Well, B<using a starter
2392 argument is strongly deprecated> anyway.
2394 =head2 Configuration variables
2396 Previous versions of Getopt::Long used variables for the purpose of
2397 configuring. Although manipulating these variables still work, it is
2398 strongly encouraged to use the C<Configure> routine that was introduced
2399 in version 2.17. Besides, it is much easier.
2401 =head1 Trouble Shooting
2403 =head2 GetOptions does not return a false result when an option is not supplied
2405 That's why they're called 'options'.
2407 =head2 GetOptions does not split the command line correctly
2409 The command line is not split by GetOptions, but by the command line
2410 interpreter (CLI). On Unix, this is the shell. On Windows, it is
2411 COMMAND.COM or CMD.EXE. Other operating systems have other CLIs.
2413 It is important to know that these CLIs may behave different when the
2414 command line contains special characters, in particular quotes or
2415 backslashes. For example, with Unix shells you can use single quotes
2416 (C<'>) and double quotes (C<">) to group words together. The following
2417 alternatives are equivalent on Unix:
2423 In case of doubt, insert the following statement in front of your Perl
2426 print STDERR (join("|",@ARGV),"\n");
2428 to verify how your CLI passes the arguments to the program.
2430 =head2 Undefined subroutine &main::GetOptions called
2432 Are you running Windows, and did you write
2436 (note the capital 'O')?
2438 =head2 How do I put a "-?" option into a Getopt::Long?
2440 You can only obtain this using an alias, and Getopt::Long of at least
2444 GetOptions ("help|?"); # -help and -? will both set $opt_help
2448 Johan Vromans <jvromans@squirrel.nl>
2450 =head1 COPYRIGHT AND DISCLAIMER
2452 This program is Copyright 2003,1990 by Johan Vromans.
2453 This program is free software; you can redistribute it and/or
2454 modify it under the terms of the Perl Artistic License or the
2455 GNU General Public License as published by the Free Software
2456 Foundation; either version 2 of the License, or (at your option) any
2459 This program is distributed in the hope that it will be useful,
2460 but WITHOUT ANY WARRANTY; without even the implied warranty of
2461 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
2462 GNU General Public License for more details.
2464 If you do not have a copy of the GNU General Public License write to
2465 the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,