1 # Getopt::Long.pm -- Universal options parsing
5 # RCS Status : $Id: GetoptLong.pm,v 2.65 2003-05-19 17:44:13+02 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: Mon May 19 17:43:33 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.32_06";
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($$);
77 ################ Local Variables ################
79 # $requested_version holds the version that was mentioned in the 'use'
80 # or 'require', if any. It can be used to enable or disable specific
82 my $requested_version = 0;
84 ################ Resident subroutines ################
86 sub ConfigDefaults() {
87 # Handle POSIX compliancy.
88 if ( defined $ENV{"POSIXLY_CORRECT"} ) {
89 $genprefix = "(--|-)";
90 $autoabbrev = 0; # no automatic abbrev of options
91 $bundling = 0; # no bundling of single letter switches
92 $getopt_compat = 0; # disallow '+' to start options
93 $order = $REQUIRE_ORDER;
96 $genprefix = "(--|-|\\+)";
97 $autoabbrev = 1; # automatic abbrev of options
98 $bundling = 0; # bundling off by default
99 $getopt_compat = 1; # allow '+' to start options
102 # Other configurable settings.
103 $debug = 0; # for debugging
104 $error = 0; # error tally
105 $ignorecase = 1; # ignore case when matching options
106 $passthrough = 0; # leave unrecognized options alone
107 $gnu_compat = 0; # require --opt=val if value is optional
112 my $pkg = shift; # package
113 my @syms = (); # symbols to import
114 my @config = (); # configuration
115 my $dest = \@syms; # symbols first
117 if ( $_ eq ':config' ) {
118 $dest = \@config; # config next
121 push(@$dest, $_); # push
123 # Hide one level and call super.
124 local $Exporter::ExportLevel = 1;
125 push(@syms, qw(&GetOptions)) if @syms; # always export GetOptions
126 $pkg->SUPER::import(@syms);
128 Configure(@config) if @config;
131 ################ Initialization ################
133 # Values for $order. See GNU getopt.c for details.
134 ($REQUIRE_ORDER, $PERMUTE, $RETURN_IN_ORDER) = (0..2);
135 # Version major/minor numbers.
136 ($major_version, $minor_version) = $VERSION =~ /^(\d+)\.(\d+)/;
140 ################ OO Interface ################
142 package Getopt::Long::Parser;
144 # Store a copy of the default configuration. Since ConfigDefaults has
145 # just been called, what we get from Configure is the default.
146 my $default_config = do {
147 Getopt::Long::Configure ()
152 my $class = ref($that) || $that;
155 # Register the callers package.
156 my $self = { caller_pkg => (caller)[0] };
158 bless ($self, $class);
160 # Process config attributes.
161 if ( defined $atts{config} ) {
162 my $save = Getopt::Long::Configure ($default_config, @{$atts{config}});
163 $self->{settings} = Getopt::Long::Configure ($save);
164 delete ($atts{config});
166 # Else use default config.
168 $self->{settings} = $default_config;
171 if ( %atts ) { # Oops
172 die(__PACKAGE__.": unhandled attributes: ".
173 join(" ", sort(keys(%atts)))."\n");
182 # Restore settings, merge new settings in.
183 my $save = Getopt::Long::Configure ($self->{settings}, @_);
185 # Restore orig config and save the new config.
186 $self->{settings} = Getopt::Long::Configure ($save);
192 # Restore config settings.
193 my $save = Getopt::Long::Configure ($self->{settings});
197 $Getopt::Long::caller = $self->{caller_pkg};
200 # Locally set exception handler to default, otherwise it will
201 # be called implicitly here, and again explicitly when we try
202 # to deliver the messages.
203 local ($SIG{__DIE__}) = '__DEFAULT__';
204 $ret = Getopt::Long::GetOptions (@_);
207 # Restore saved settings.
208 Getopt::Long::Configure ($save);
210 # Handle errors and return value.
215 package Getopt::Long;
217 ################ Back to Normal ################
219 # Indices in option control info.
220 # Note that ParseOptions uses the fields directly. Search for 'hard-wired'.
221 use constant CTL_TYPE => 0;
222 #use constant CTL_TYPE_FLAG => '';
223 #use constant CTL_TYPE_NEG => '!';
224 #use constant CTL_TYPE_INCR => '+';
225 #use constant CTL_TYPE_INT => 'i';
226 #use constant CTL_TYPE_INTINC => 'I';
227 #use constant CTL_TYPE_XINT => 'o';
228 #use constant CTL_TYPE_FLOAT => 'f';
229 #use constant CTL_TYPE_STRING => 's';
231 use constant CTL_CNAME => 1;
233 use constant CTL_MAND => 2;
235 use constant CTL_DEST => 3;
236 use constant CTL_DEST_SCALAR => 0;
237 use constant CTL_DEST_ARRAY => 1;
238 use constant CTL_DEST_HASH => 2;
239 use constant CTL_DEST_CODE => 3;
241 use constant CTL_DEFAULT => 4;
244 #use constant CTL_RANGE => ;
245 #use constant CTL_REPEAT => ;
249 my @optionlist = @_; # local copy of the option descriptions
250 my $argend = '--'; # option list terminator
251 my %opctl = (); # table of option specs
252 my $pkg = $caller || (caller)[0]; # current context
253 # Needed if linkage is omitted.
254 my @ret = (); # accum for non-options
255 my %linkage; # linkage
256 my $userlinkage; # user supplied HASH
257 my $opt; # current option
258 my $prefix = $genprefix; # current prefix
262 print STDERR ("Getopt::Long $Getopt::Long::VERSION (",
263 '$Revision: 2.65 $', ") ",
264 "called from package \"$pkg\".",
268 "autoabbrev=$autoabbrev,".
269 "bundling=$bundling,",
270 "getopt_compat=$getopt_compat,",
271 "gnu_compat=$gnu_compat,",
274 "ignorecase=$ignorecase,",
275 "autohelp=$auto_help,",
276 "autoversion=$auto_version,",
277 "passthrough=$passthrough,",
278 "genprefix=\"$genprefix\".",
282 # Check for ref HASH as first argument.
283 # First argument may be an object. It's OK to use this as long
284 # as it is really a hash underneath.
285 $userlinkage = undef;
286 if ( @optionlist && ref($optionlist[0]) and
287 "$optionlist[0]" =~ /^(?:.*\=)?HASH\([^\(]*\)$/ ) {
288 $userlinkage = shift (@optionlist);
289 print STDERR ("=> user linkage: $userlinkage\n") if $debug;
292 # See if the first element of the optionlist contains option
293 # starter characters.
294 # Be careful not to interpret '<>' as option starters.
295 if ( @optionlist && $optionlist[0] =~ /^\W+$/
296 && !($optionlist[0] eq '<>'
298 && ref($optionlist[1])) ) {
299 $prefix = shift (@optionlist);
300 # Turn into regexp. Needs to be parenthesized!
301 $prefix =~ s/(\W)/\\$1/g;
302 $prefix = "([" . $prefix . "])";
303 print STDERR ("=> prefix=\"$prefix\"\n") if $debug;
306 # Verify correctness of optionlist.
308 while ( @optionlist ) {
309 my $opt = shift (@optionlist);
311 # Strip leading prefix so people can specify "--foo=i" if they like.
312 $opt = $+ if $opt =~ /^$prefix+(.*)$/s;
314 if ( $opt eq '<>' ) {
315 if ( (defined $userlinkage)
316 && !(@optionlist > 0 && ref($optionlist[0]))
317 && (exists $userlinkage->{$opt})
318 && ref($userlinkage->{$opt}) ) {
319 unshift (@optionlist, $userlinkage->{$opt});
321 unless ( @optionlist > 0
322 && ref($optionlist[0]) && ref($optionlist[0]) eq 'CODE' ) {
323 $error .= "Option spec <> requires a reference to a subroutine\n";
324 # Kill the linkage (to avoid another error).
326 if @optionlist && ref($optionlist[0]);
329 $linkage{'<>'} = shift (@optionlist);
334 my ($name, $orig) = ParseOptionSpec ($opt, \%opctl);
335 unless ( defined $name ) {
336 # Failed. $orig contains the error message. Sorry for the abuse.
338 # Kill the linkage (to avoid another error).
340 if @optionlist && ref($optionlist[0]);
344 # If no linkage is supplied in the @optionlist, copy it from
345 # the userlinkage if available.
346 if ( defined $userlinkage ) {
347 unless ( @optionlist > 0 && ref($optionlist[0]) ) {
348 if ( exists $userlinkage->{$orig} &&
349 ref($userlinkage->{$orig}) ) {
350 print STDERR ("=> found userlinkage for \"$orig\": ",
351 "$userlinkage->{$orig}\n")
353 unshift (@optionlist, $userlinkage->{$orig});
356 # Do nothing. Being undefined will be handled later.
362 # Copy the linkage. If omitted, link to global variable.
363 if ( @optionlist > 0 && ref($optionlist[0]) ) {
364 print STDERR ("=> link \"$orig\" to $optionlist[0]\n")
366 my $rl = ref($linkage{$orig} = shift (@optionlist));
368 if ( $rl eq "ARRAY" ) {
369 $opctl{$name}[CTL_DEST] = CTL_DEST_ARRAY;
371 elsif ( $rl eq "HASH" ) {
372 $opctl{$name}[CTL_DEST] = CTL_DEST_HASH;
374 elsif ( $rl eq "SCALAR" || $rl eq "CODE" ) {
378 $error .= "Invalid option linkage for \"$opt\"\n";
382 # Link to global $opt_XXX variable.
383 # Make sure a valid perl identifier results.
386 if ( $opctl{$name}[CTL_DEST] == CTL_DEST_ARRAY ) {
387 print STDERR ("=> link \"$orig\" to \@$pkg","::opt_$ov\n")
389 eval ("\$linkage{\$orig} = \\\@".$pkg."::opt_$ov;");
391 elsif ( $opctl{$name}[CTL_DEST] == CTL_DEST_HASH ) {
392 print STDERR ("=> link \"$orig\" to \%$pkg","::opt_$ov\n")
394 eval ("\$linkage{\$orig} = \\\%".$pkg."::opt_$ov;");
397 print STDERR ("=> link \"$orig\" to \$$pkg","::opt_$ov\n")
399 eval ("\$linkage{\$orig} = \\\$".$pkg."::opt_$ov;");
404 # Bail out if errors found.
405 die ($error) if $error;
408 # Supply --version and --help support, if needed and allowed.
409 if ( defined($auto_version) ? $auto_version : ($requested_version >= 2.3203) ) {
410 if ( !defined($opctl{version}) ) {
411 $opctl{version} = ['','version',0,CTL_DEST_CODE,undef];
412 $linkage{version} = \&VersionMessage;
415 if ( defined($auto_help) ? $auto_help : ($requested_version >= 2.3203) ) {
416 if ( !defined($opctl{help}) && !defined($opctl{'?'}) ) {
417 $opctl{help} = $opctl{'?'} = ['','help',0,CTL_DEST_CODE,undef];
418 $linkage{help} = \&HelpMessage;
422 # Show the options tables if debugging.
426 while ( ($k,$v) = each(%opctl) ) {
427 print STDERR ($arrow, "\$opctl{$k} = $v ", OptCtl($v), "\n");
432 # Process argument list
434 while ( $goon && @ARGV > 0 ) {
437 $opt = shift (@ARGV);
438 print STDERR ("=> arg \"", $opt, "\"\n") if $debug;
440 # Double dash is option list terminator.
441 if ( $opt eq $argend ) {
442 push (@ret, $argend) if $passthrough;
448 my $found; # success status
449 my $key; # key (if hash type)
450 my $arg; # option argument
451 my $ctl; # the opctl entry
453 ($found, $opt, $ctl, $arg, $key) =
454 FindOption ($prefix, $argend, $opt, \%opctl);
458 # FindOption undefines $opt in case of errors.
459 next unless defined $opt;
461 if ( defined $arg ) {
463 # Get the canonical name.
464 print STDERR ("=> cname for \"$opt\" is ") if $debug;
465 $opt = $ctl->[CTL_CNAME];
466 print STDERR ("\"$ctl->[CTL_CNAME]\"\n") if $debug;
468 if ( defined $linkage{$opt} ) {
469 print STDERR ("=> ref(\$L{$opt}) -> ",
470 ref($linkage{$opt}), "\n") if $debug;
472 if ( ref($linkage{$opt}) eq 'SCALAR' ) {
473 if ( $ctl->[CTL_TYPE] eq '+' ) {
474 print STDERR ("=> \$\$L{$opt} += \"$arg\"\n")
476 if ( defined ${$linkage{$opt}} ) {
477 ${$linkage{$opt}} += $arg;
480 ${$linkage{$opt}} = $arg;
484 print STDERR ("=> \$\$L{$opt} = \"$arg\"\n")
486 ${$linkage{$opt}} = $arg;
489 elsif ( ref($linkage{$opt}) eq 'ARRAY' ) {
490 print STDERR ("=> push(\@{\$L{$opt}, \"$arg\")\n")
492 push (@{$linkage{$opt}}, $arg);
494 elsif ( ref($linkage{$opt}) eq 'HASH' ) {
495 print STDERR ("=> \$\$L{$opt}->{$key} = \"$arg\"\n")
497 $linkage{$opt}->{$key} = $arg;
499 elsif ( ref($linkage{$opt}) eq 'CODE' ) {
500 print STDERR ("=> &L{$opt}(\"$opt\"",
501 $ctl->[CTL_DEST] == CTL_DEST_HASH ? ", \"$key\"" : "",
504 my $eval_error = do {
506 local $SIG{__DIE__} = '__DEFAULT__';
508 &{$linkage{$opt}}($opt,
509 $ctl->[CTL_DEST] == CTL_DEST_HASH ? ($key) : (),
514 print STDERR ("=> die($eval_error)\n")
515 if $debug && $eval_error ne '';
516 if ( $eval_error =~ /^!/ ) {
517 if ( $eval_error =~ /^!FINISH\b/ ) {
521 elsif ( $eval_error ne '' ) {
527 print STDERR ("Invalid REF type \"", ref($linkage{$opt}),
529 die("Getopt::Long -- internal error!\n");
532 # No entry in linkage means entry in userlinkage.
533 elsif ( $ctl->[CTL_DEST] == CTL_DEST_ARRAY ) {
534 if ( defined $userlinkage->{$opt} ) {
535 print STDERR ("=> push(\@{\$L{$opt}}, \"$arg\")\n")
537 push (@{$userlinkage->{$opt}}, $arg);
540 print STDERR ("=>\$L{$opt} = [\"$arg\"]\n")
542 $userlinkage->{$opt} = [$arg];
545 elsif ( $ctl->[CTL_DEST] == CTL_DEST_HASH ) {
546 if ( defined $userlinkage->{$opt} ) {
547 print STDERR ("=> \$L{$opt}->{$key} = \"$arg\"\n")
549 $userlinkage->{$opt}->{$key} = $arg;
552 print STDERR ("=>\$L{$opt} = {$key => \"$arg\"}\n")
554 $userlinkage->{$opt} = {$key => $arg};
558 if ( $ctl->[CTL_TYPE] eq '+' ) {
559 print STDERR ("=> \$L{$opt} += \"$arg\"\n")
561 if ( defined $userlinkage->{$opt} ) {
562 $userlinkage->{$opt} += $arg;
565 $userlinkage->{$opt} = $arg;
569 print STDERR ("=>\$L{$opt} = \"$arg\"\n") if $debug;
570 $userlinkage->{$opt} = $arg;
576 # Not an option. Save it if we $PERMUTE and don't have a <>.
577 elsif ( $order == $PERMUTE ) {
578 # Try non-options call-back.
580 if ( (defined ($cb = $linkage{'<>'})) ) {
581 print STDERR ("=> &L{$tryopt}(\"$tryopt\")\n")
583 my $eval_error = do {
585 local $SIG{__DIE__} = '__DEFAULT__';
586 eval { &$cb ($tryopt) };
589 print STDERR ("=> die($eval_error)\n")
590 if $debug && $eval_error ne '';
591 if ( $eval_error =~ /^!/ ) {
592 if ( $eval_error =~ /^!FINISH\b/ ) {
596 elsif ( $eval_error ne '' ) {
602 print STDERR ("=> saving \"$tryopt\" ",
603 "(not an option, may permute)\n") if $debug;
604 push (@ret, $tryopt);
609 # ...otherwise, terminate.
611 # Push this one back and exit.
612 unshift (@ARGV, $tryopt);
613 return ($error == 0);
619 if ( @ret && $order == $PERMUTE ) {
620 # Push back accumulated arguments
621 print STDERR ("=> restoring \"", join('" "', @ret), "\"\n")
623 unshift (@ARGV, @ret);
626 return ($error == 0);
629 # A readable representation of what's in an optbl.
632 my @v = map { defined($_) ? ($_) : ("<undef>") } @$v;
637 $v[CTL_MAND] ? "O" : "M",
638 ("\$","\@","\%","\&")[$v[CTL_DEST] || 0],
639 "\"$v[CTL_DEFAULT]\"",
640 # $v[CTL_RANGE] || '',
641 # $v[CTL_REPEAT] || '',
645 # Parse an option specification and fill the tables.
646 sub ParseOptionSpec ($$) {
647 my ($opt, $opctl) = @_;
654 # Alias names, or "?"
655 (?: \| (?: \? | \w[-\w]* )? )*
658 # Either modifiers ...
661 # ... or a value/dest specification
664 # ... or an optional-with-default spec
665 : (?: -?\d+ | \+ ) [@%]?
668 return (undef, "Error in option spec: \"$opt\"\n");
671 my ($names, $spec) = ($1, $2);
672 $spec = '' unless defined $spec;
674 # $orig keeps track of the primary name the user specified.
675 # This name will be used for the internal or external linkage.
676 # In other words, if the user specifies "FoO|BaR", it will
677 # match any case combinations of 'foo' and 'bar', but if a global
678 # variable needs to be set, it will be $opt_FoO in the exact case
683 if ( defined $names ) {
684 @names = split (/\|/, $names);
692 # Construct the opctl entries.
694 if ( $spec eq '' || $spec eq '+' || $spec eq '!' ) {
695 # Fields are hard-wired here.
696 $entry = [$spec,$orig,0,CTL_DEST_SCALAR,undef];
698 elsif ( $spec =~ /:(-?\d+|\+)([@%])?/ ) {
701 my $type = $def eq '+' ? 'I' : 'i';
703 $dest = $dest eq '@' ? CTL_DEST_ARRAY
704 : $dest eq '%' ? CTL_DEST_HASH : CTL_DEST_SCALAR;
705 # Fields are hard-wired here.
706 $entry = [$type,$orig,0,$dest,$def eq '+' ? undef : $def];
709 my ($mand, $type, $dest) = $spec =~ /([=:])([ionfs])([@%])?/;
710 $type = 'i' if $type eq 'n';
712 $dest = $dest eq '@' ? CTL_DEST_ARRAY
713 : $dest eq '%' ? CTL_DEST_HASH : CTL_DEST_SCALAR;
714 # Fields are hard-wired here.
715 $entry = [$type,$orig,$mand eq '=',$dest,undef];
718 # Process all names. First is canonical, the rest are aliases.
723 if $ignorecase > (($bundling && length($_) == 1) ? 1 : 0);
725 if ( exists $opctl->{$_} ) {
726 $dups .= "Duplicate specification \"$opt\" for option \"$_\"\n";
729 if ( $spec eq '!' ) {
730 $opctl->{"no$_"} = $entry;
731 $opctl->{"no-$_"} = $entry;
732 $opctl->{$_} = [@$entry];
733 $opctl->{$_}->[CTL_TYPE] = '';
736 $opctl->{$_} = $entry;
740 if ( $dups && $^W ) {
741 foreach ( split(/\n+/, $dups) ) {
749 sub FindOption ($$$$) {
751 # returns (1, $opt, $ctl, $arg, $key) if okay,
752 # returns (1, undef) if option in error,
753 # returns (0) otherwise.
755 my ($prefix, $argend, $opt, $opctl) = @_;
757 print STDERR ("=> find \"$opt\"\n") if $debug;
759 return (0) unless $opt =~ /^$prefix(.*)$/s;
760 return (0) if $opt eq "-" && !defined $opctl->{''};
765 print STDERR ("=> split \"$starter\"+\"$opt\"\n") if $debug;
767 my $optarg; # value supplied with --opt=value
768 my $rest; # remainder from unbundling
770 # If it is a long option, it may include the value.
771 # With getopt_compat, only if not bundling.
772 if ( ($starter eq "--"
773 || ($getopt_compat && ($bundling == 0 || $bundling == 2)))
774 && $opt =~ /^([^=]+)=(.*)$/s ) {
777 print STDERR ("=> option \"", $opt,
778 "\", optarg = \"$optarg\"\n") if $debug;
783 my $tryopt = $opt; # option to try
785 if ( $bundling && $starter eq '-' ) {
787 # To try overrides, obey case ignore.
788 $tryopt = $ignorecase ? lc($opt) : $opt;
790 # If bundling == 2, long options can override bundles.
791 if ( $bundling == 2 && length($tryopt) > 1
792 && defined ($opctl->{$tryopt}) ) {
793 print STDERR ("=> $starter$tryopt overrides unbundling\n")
798 # Unbundle single letter option.
799 $rest = length ($tryopt) > 0 ? substr ($tryopt, 1) : '';
800 $tryopt = substr ($tryopt, 0, 1);
801 $tryopt = lc ($tryopt) if $ignorecase > 1;
802 print STDERR ("=> $starter$tryopt unbundled from ",
803 "$starter$tryopt$rest\n") if $debug;
804 $rest = undef unless $rest ne '';
808 # Try auto-abbreviation.
809 elsif ( $autoabbrev ) {
810 # Sort the possible long option names.
811 my @names = sort(keys (%$opctl));
812 # Downcase if allowed.
813 $opt = lc ($opt) if $ignorecase;
815 # Turn option name into pattern.
816 my $pat = quotemeta ($opt);
817 # Look up in option names.
818 my @hits = grep (/^$pat/, @names);
819 print STDERR ("=> ", scalar(@hits), " hits (@hits) with \"$pat\" ",
820 "out of ", scalar(@names), "\n") if $debug;
822 # Check for ambiguous results.
823 unless ( (@hits <= 1) || (grep ($_ eq $opt, @hits) == 1) ) {
824 # See if all matches are for the same option.
827 $_ = $opctl->{$_}->[CTL_CNAME]
828 if defined $opctl->{$_}->[CTL_CNAME];
831 # Now see if it really is ambiguous.
832 unless ( keys(%hit) == 1 ) {
833 return (0) if $passthrough;
834 warn ("Option ", $opt, " is ambiguous (",
835 join(", ", @hits), ")\n");
842 # Complete the option name, if appropriate.
843 if ( @hits == 1 && $hits[0] ne $opt ) {
845 $tryopt = lc ($tryopt) if $ignorecase;
846 print STDERR ("=> option \"$opt\" -> \"$tryopt\"\n")
851 # Map to all lowercase if ignoring case.
852 elsif ( $ignorecase ) {
856 # Check validity by fetching the info.
857 my $ctl = $opctl->{$tryopt};
858 unless ( defined $ctl ) {
859 return (0) if $passthrough;
860 warn ("Unknown option: ", $opt, "\n");
866 print STDERR ("=> found ", OptCtl($ctl),
867 " for \"", $opt, "\"\n") if $debug;
869 #### Determine argument status ####
871 # If it is an option w/o argument, we're almost finished with it.
872 my $type = $ctl->[CTL_TYPE];
875 if ( $type eq '' || $type eq '!' || $type eq '+' ) {
876 if ( defined $optarg ) {
877 return (0) if $passthrough;
878 warn ("Option ", $opt, " does not take an argument\n");
882 elsif ( $type eq '' || $type eq '+' ) {
883 # Supply explicit value.
887 $opt =~ s/^no-?//i; # strip NO prefix
888 $arg = 0; # supply explicit value
890 unshift (@ARGV, $starter.$rest) if defined $rest;
891 return (1, $opt, $ctl, $arg);
894 # Get mandatory status and type info.
895 my $mand = $ctl->[CTL_MAND];
897 # Check if there is an option argument available.
898 if ( $gnu_compat && defined $optarg && $optarg eq '' ) {
899 return (1, $opt, $ctl, $type eq 's' ? '' : 0) unless $mand;
900 $optarg = 0 unless $type eq 's';
903 # Check if there is an option argument available.
906 : !(defined $rest || @ARGV > 0) ) {
907 # Complain if this option needs an argument.
909 return (0) if $passthrough;
910 warn ("Option ", $opt, " requires an argument\n");
914 if ( $type eq 'I' ) {
915 # Fake incremental type.
918 return (1, $opt, \@c, 1);
920 return (1, $opt, $ctl,
921 defined($ctl->[CTL_DEFAULT]) ? $ctl->[CTL_DEFAULT] :
922 $type eq 's' ? '' : 0);
925 # Get (possibly optional) argument.
926 $arg = (defined $rest ? $rest
927 : (defined $optarg ? $optarg : shift (@ARGV)));
929 # Get key if this is a "name=value" pair for a hash option.
931 if ($ctl->[CTL_DEST] == CTL_DEST_HASH && defined $arg) {
932 ($key, $arg) = ($arg =~ /^([^=]*)=(.*)$/s) ? ($1, $2)
933 : ($arg, defined($ctl->[CTL_DEFAULT]) ? $ctl->[CTL_DEFAULT] :
934 ($mand ? undef : ($type eq 's' ? "" : 1)));
935 if (! defined $arg) {
936 warn ("Option $opt, key \"$key\", requires a value\n");
939 unshift (@ARGV, $starter.$rest) if defined $rest;
944 #### Check if the argument is valid for this option ####
946 my $key_valid = $ctl->[CTL_DEST] == CTL_DEST_HASH ? "[^=]+=" : "";
948 if ( $type eq 's' ) { # string
949 # A mandatory string takes anything.
950 return (1, $opt, $ctl, $arg, $key) if $mand;
952 # An optional string takes almost anything.
953 return (1, $opt, $ctl, $arg, $key)
954 if defined $optarg || defined $rest;
955 return (1, $opt, $ctl, $arg, $key) if $arg eq "-"; # ??
957 # Check for option or option list terminator.
958 if ($arg eq $argend ||
959 $arg =~ /^$prefix.+/) {
961 unshift (@ARGV, $arg);
962 # Supply empty value.
967 elsif ( $type eq 'i' # numeric/integer
968 || $type eq 'I' # numeric/integer w/ incr default
969 || $type eq 'o' ) { # dec/oct/hex/bin value
972 $type eq 'o' ? "[-+]?[1-9][0-9]*|0x[0-9a-f]+|0b[01]+|0[0-7]*"
975 if ( $bundling && defined $rest
976 && $rest =~ /^($key_valid)($o_valid)(.*)$/si ) {
977 ($key, $arg, $rest) = ($1, $2, $+);
979 $arg = ($type eq 'o' && $arg =~ /^0/) ? oct($arg) : 0+$arg;
980 unshift (@ARGV, $starter.$rest) if defined $rest && $rest ne '';
982 elsif ( $arg =~ /^($o_valid)$/si ) {
983 $arg = ($type eq 'o' && $arg =~ /^0/) ? oct($arg) : 0+$arg;
986 if ( defined $optarg || $mand ) {
987 if ( $passthrough ) {
988 unshift (@ARGV, defined $rest ? $starter.$rest : $arg)
989 unless defined $optarg;
992 warn ("Value \"", $arg, "\" invalid for option ",
994 $type eq 'o' ? "extended " : '',
995 "number expected)\n");
998 unshift (@ARGV, $starter.$rest) if defined $rest;
1003 unshift (@ARGV, defined $rest ? $starter.$rest : $arg);
1004 if ( $type eq 'I' ) {
1005 # Fake incremental type.
1008 return (1, $opt, \@c, 1);
1010 # Supply default value.
1011 $arg = defined($ctl->[CTL_DEFAULT]) ? $ctl->[CTL_DEFAULT] : 0;
1016 elsif ( $type eq 'f' ) { # real number, int is also ok
1017 # We require at least one digit before a point or 'e',
1018 # and at least one digit following the point and 'e'.
1020 if ( $bundling && defined $rest &&
1021 $rest =~ /^($key_valid)([-+]?[0-9]+(\.[0-9]+)?([eE][-+]?[0-9]+)?)(.*)$/s ) {
1022 ($key, $arg, $rest) = ($1, $2, $+);
1024 unshift (@ARGV, $starter.$rest) if defined $rest && $rest ne '';
1026 elsif ( $arg !~ /^[-+]?[0-9.]+(\.[0-9]+)?([eE][-+]?[0-9]+)?$/ ) {
1027 if ( defined $optarg || $mand ) {
1028 if ( $passthrough ) {
1029 unshift (@ARGV, defined $rest ? $starter.$rest : $arg)
1030 unless defined $optarg;
1033 warn ("Value \"", $arg, "\" invalid for option ",
1034 $opt, " (real number expected)\n");
1037 unshift (@ARGV, $starter.$rest) if defined $rest;
1042 unshift (@ARGV, defined $rest ? $starter.$rest : $arg);
1043 # Supply default value.
1049 die("Getopt::Long internal error (Can't happen)\n");
1051 return (1, $opt, $ctl, $arg, $key);
1054 # Getopt::Long Configuration.
1059 [ $error, $debug, $major_version, $minor_version,
1060 $autoabbrev, $getopt_compat, $ignorecase, $bundling, $order,
1061 $gnu_compat, $passthrough, $genprefix, $auto_version, $auto_help ];
1063 if ( ref($options[0]) eq 'ARRAY' ) {
1064 ( $error, $debug, $major_version, $minor_version,
1065 $autoabbrev, $getopt_compat, $ignorecase, $bundling, $order,
1066 $gnu_compat, $passthrough, $genprefix, $auto_version, $auto_help ) =
1071 foreach $opt ( @options ) {
1072 my $try = lc ($opt);
1074 if ( $try =~ /^no_?(.*)$/s ) {
1078 if ( ($try eq 'default' or $try eq 'defaults') && $action ) {
1081 elsif ( ($try eq 'posix_default' or $try eq 'posix_defaults') ) {
1082 local $ENV{POSIXLY_CORRECT};
1083 $ENV{POSIXLY_CORRECT} = 1 if $action;
1086 elsif ( $try eq 'auto_abbrev' or $try eq 'autoabbrev' ) {
1087 $autoabbrev = $action;
1089 elsif ( $try eq 'getopt_compat' ) {
1090 $getopt_compat = $action;
1092 elsif ( $try eq 'gnu_getopt' ) {
1100 elsif ( $try eq 'gnu_compat' ) {
1101 $gnu_compat = $action;
1103 elsif ( $try =~ /^(auto_?)?version$/ ) {
1104 $auto_version = $action;
1106 elsif ( $try =~ /^(auto_?)?help$/ ) {
1107 $auto_help = $action;
1109 elsif ( $try eq 'ignorecase' or $try eq 'ignore_case' ) {
1110 $ignorecase = $action;
1112 elsif ( $try eq 'ignore_case_always' ) {
1113 $ignorecase = $action ? 2 : 0;
1115 elsif ( $try eq 'bundling' ) {
1116 $bundling = $action;
1118 elsif ( $try eq 'bundling_override' ) {
1119 $bundling = $action ? 2 : 0;
1121 elsif ( $try eq 'require_order' ) {
1122 $order = $action ? $REQUIRE_ORDER : $PERMUTE;
1124 elsif ( $try eq 'permute' ) {
1125 $order = $action ? $PERMUTE : $REQUIRE_ORDER;
1127 elsif ( $try eq 'pass_through' or $try eq 'passthrough' ) {
1128 $passthrough = $action;
1130 elsif ( $try =~ /^prefix=(.+)$/ && $action ) {
1132 # Turn into regexp. Needs to be parenthesized!
1133 $genprefix = "(" . quotemeta($genprefix) . ")";
1134 eval { '' =~ /$genprefix/; };
1135 die("Getopt::Long: invalid pattern \"$genprefix\"") if $@;
1137 elsif ( $try =~ /^prefix_pattern=(.+)$/ && $action ) {
1139 # Parenthesize if needed.
1140 $genprefix = "(" . $genprefix . ")"
1141 unless $genprefix =~ /^\(.*\)$/;
1142 eval { '' =~ /$genprefix/; };
1143 die("Getopt::Long: invalid pattern \"$genprefix\"") if $@;
1145 elsif ( $try eq 'debug' ) {
1149 die("Getopt::Long: unknown config parameter \"$opt\"")
1160 # Issue a standard message for --version.
1162 # The arguments are mostly the same as for Pod::Usage::pod2usage:
1164 # - a number (exit value)
1165 # - a string (lead in message)
1166 # - a hash with options. See Pod::Usage for details.
1168 sub VersionMessage(@) {
1170 my $pa = setup_pa_args("version", @_);
1172 my $v = $main::VERSION;
1173 my $fh = $pa->{-output} ||
1174 ($pa->{-exitval} eq "NOEXIT" || $pa->{-exitval} < 2) ? \*STDOUT : \*STDERR;
1176 print $fh (defined($pa->{-message}) ? $pa->{-message} : (),
1177 $0, defined $v ? " version $v" : (),
1179 "(", __PACKAGE__, "::", "GetOptions",
1181 defined($Getopt::Long::VERSION_STRING)
1182 ? $Getopt::Long::VERSION_STRING : $VERSION, ";",
1184 $] >= 5.006 ? sprintf("%vd", $^V) : $],
1186 exit($pa->{-exitval}) unless $pa->{-exitval} eq "NOEXIT";
1189 # Issue a standard message for --help.
1191 # The arguments are the same as for Pod::Usage::pod2usage:
1193 # - a number (exit value)
1194 # - a string (lead in message)
1195 # - a hash with options. See Pod::Usage for details.
1197 sub HelpMessage(@) {
1202 } || die("Cannot provide help: cannot load Pod::Usage\n");
1204 # Note that pod2usage will issue a warning if -exitval => NOEXIT.
1205 pod2usage(setup_pa_args("help", @_));
1209 # Helper routine to set up a normalized hash ref to be used as
1210 # argument to pod2usage.
1211 sub setup_pa_args($@) {
1212 my $tag = shift; # who's calling
1214 # If called by direct binding to an option, it will get the option
1215 # name and value as arguments. Remove these, if so.
1216 @_ = () if @_ == 2 && $_[0] eq $tag;
1226 # At this point, $pa can be a number (exit value), string
1227 # (message) or hash with options.
1229 if ( UNIVERSAL::isa($pa, 'HASH') ) {
1230 # Get rid of -msg vs. -message ambiguity.
1231 $pa->{-message} = $pa->{-msg};
1232 delete($pa->{-msg});
1234 elsif ( $pa =~ /^-?\d+$/ ) {
1235 $pa = { -exitval => $pa };
1238 $pa = { -message => $pa };
1241 # These are _our_ defaults.
1242 $pa->{-verbose} = 0 unless exists($pa->{-verbose});
1243 $pa->{-exitval} = 0 unless exists($pa->{-exitval});
1247 # Sneak way to know what version the user requested.
1249 $requested_version = $_[1];
1250 shift->SUPER::VERSION(@_);
1255 ################ Documentation ################
1259 Getopt::Long - Extended processing of command line options
1264 my $data = "file.dat";
1267 $result = GetOptions ("length=i" => \$length, # numeric
1268 "file=s" => \$data, # string
1269 "verbose" => \$verbose); # flag
1273 The Getopt::Long module implements an extended getopt function called
1274 GetOptions(). This function adheres to the POSIX syntax for command
1275 line options, with GNU extensions. In general, this means that options
1276 have long names instead of single letters, and are introduced with a
1277 double dash "--". Support for bundling of command line options, as was
1278 the case with the more traditional single-letter approach, is provided
1279 but not enabled by default.
1281 =head1 Command Line Options, an Introduction
1283 Command line operated programs traditionally take their arguments from
1284 the command line, for example filenames or other information that the
1285 program needs to know. Besides arguments, these programs often take
1286 command line I<options> as well. Options are not necessary for the
1287 program to work, hence the name 'option', but are used to modify its
1288 default behaviour. For example, a program could do its job quietly,
1289 but with a suitable option it could provide verbose information about
1292 Command line options come in several flavours. Historically, they are
1293 preceded by a single dash C<->, and consist of a single letter.
1297 Usually, these single-character options can be bundled:
1301 Options can have values, the value is placed after the option
1302 character. Sometimes with whitespace in between, sometimes not:
1306 Due to the very cryptic nature of these options, another style was
1307 developed that used long names. So instead of a cryptic C<-l> one
1308 could use the more descriptive C<--long>. To distinguish between a
1309 bundle of single-character options and a long one, two dashes are used
1310 to precede the option name. Early implementations of long options used
1311 a plus C<+> instead. Also, option values could be specified either
1320 The C<+> form is now obsolete and strongly deprecated.
1322 =head1 Getting Started with Getopt::Long
1324 Getopt::Long is the Perl5 successor of C<newgetopt.pl>. This was
1325 the first Perl module that provided support for handling the new style
1326 of command line options, hence the name Getopt::Long. This module
1327 also supports single-character options and bundling. In this case, the
1328 options are restricted to alphabetic characters only, and the
1329 characters C<?> and C<->.
1331 To use Getopt::Long from a Perl program, you must include the
1332 following line in your Perl program:
1336 This will load the core of the Getopt::Long module and prepare your
1337 program for using it. Most of the actual Getopt::Long code is not
1338 loaded until you really call one of its functions.
1340 In the default configuration, options names may be abbreviated to
1341 uniqueness, case does not matter, and a single dash is sufficient,
1342 even for long option names. Also, options may be placed between
1343 non-option arguments. See L<Configuring Getopt::Long> for more
1344 details on how to configure Getopt::Long.
1346 =head2 Simple options
1348 The most simple options are the ones that take no values. Their mere
1349 presence on the command line enables the option. Popular examples are:
1351 --all --verbose --quiet --debug
1353 Handling simple options is straightforward:
1355 my $verbose = ''; # option variable with default value (false)
1356 my $all = ''; # option variable with default value (false)
1357 GetOptions ('verbose' => \$verbose, 'all' => \$all);
1359 The call to GetOptions() parses the command line arguments that are
1360 present in C<@ARGV> and sets the option variable to the value C<1> if
1361 the option did occur on the command line. Otherwise, the option
1362 variable is not touched. Setting the option value to true is often
1363 called I<enabling> the option.
1365 The option name as specified to the GetOptions() function is called
1366 the option I<specification>. Later we'll see that this specification
1367 can contain more than just the option name. The reference to the
1368 variable is called the option I<destination>.
1370 GetOptions() will return a true value if the command line could be
1371 processed successfully. Otherwise, it will write error messages to
1372 STDERR, and return a false result.
1374 =head2 A little bit less simple options
1376 Getopt::Long supports two useful variants of simple options:
1377 I<negatable> options and I<incremental> options.
1379 A negatable option is specified with an exclamation mark C<!> after the
1382 my $verbose = ''; # option variable with default value (false)
1383 GetOptions ('verbose!' => \$verbose);
1385 Now, using C<--verbose> on the command line will enable C<$verbose>,
1386 as expected. But it is also allowed to use C<--noverbose>, which will
1387 disable C<$verbose> by setting its value to C<0>. Using a suitable
1388 default value, the program can find out whether C<$verbose> is false
1389 by default, or disabled by using C<--noverbose>.
1391 An incremental option is specified with a plus C<+> after the
1394 my $verbose = ''; # option variable with default value (false)
1395 GetOptions ('verbose+' => \$verbose);
1397 Using C<--verbose> on the command line will increment the value of
1398 C<$verbose>. This way the program can keep track of how many times the
1399 option occurred on the command line. For example, each occurrence of
1400 C<--verbose> could increase the verbosity level of the program.
1402 =head2 Mixing command line option with other arguments
1404 Usually programs take command line options as well as other arguments,
1405 for example, file names. It is good practice to always specify the
1406 options first, and the other arguments last. Getopt::Long will,
1407 however, allow the options and arguments to be mixed and 'filter out'
1408 all the options before passing the rest of the arguments to the
1409 program. To stop Getopt::Long from processing further arguments,
1410 insert a double dash C<--> on the command line:
1414 In this example, C<--all> will I<not> be treated as an option, but
1415 passed to the program unharmed, in C<@ARGV>.
1417 =head2 Options with values
1419 For options that take values it must be specified whether the option
1420 value is required or not, and what kind of value the option expects.
1422 Three kinds of values are supported: integer numbers, floating point
1423 numbers, and strings.
1425 If the option value is required, Getopt::Long will take the
1426 command line argument that follows the option and assign this to the
1427 option variable. If, however, the option value is specified as
1428 optional, this will only be done if that value does not look like a
1429 valid command line option itself.
1431 my $tag = ''; # option variable with default value
1432 GetOptions ('tag=s' => \$tag);
1434 In the option specification, the option name is followed by an equals
1435 sign C<=> and the letter C<s>. The equals sign indicates that this
1436 option requires a value. The letter C<s> indicates that this value is
1437 an arbitrary string. Other possible value types are C<i> for integer
1438 values, and C<f> for floating point values. Using a colon C<:> instead
1439 of the equals sign indicates that the option value is optional. In
1440 this case, if no suitable value is supplied, string valued options get
1441 an empty string C<''> assigned, while numeric options are set to C<0>.
1443 =head2 Options with multiple values
1445 Options sometimes take several values. For example, a program could
1446 use multiple directories to search for library files:
1448 --library lib/stdlib --library lib/extlib
1450 To accomplish this behaviour, simply specify an array reference as the
1451 destination for the option:
1454 GetOptions ("library=s" => \@libfiles);
1456 Used with the example above, C<@libfiles> would contain two strings
1457 upon completion: C<"lib/srdlib"> and C<"lib/extlib">, in that order.
1458 It is also possible to specify that only integer or floating point
1459 numbers are acceptible values.
1461 Often it is useful to allow comma-separated lists of values as well as
1462 multiple occurrences of the options. This is easy using Perl's split()
1463 and join() operators:
1466 GetOptions ("library=s" => \@libfiles);
1467 @libfiles = split(/,/,join(',',@libfiles));
1469 Of course, it is important to choose the right separator string for
1472 =head2 Options with hash values
1474 If the option destination is a reference to a hash, the option will
1475 take, as value, strings of the form I<key>C<=>I<value>. The value will
1476 be stored with the specified key in the hash.
1479 GetOptions ("define=s" => \%defines);
1481 When used with command line options:
1483 --define os=linux --define vendor=redhat
1485 the hash C<%defines> will contain two keys, C<"os"> with value
1486 C<"linux> and C<"vendor"> with value C<"redhat">.
1487 It is also possible to specify that only integer or floating point
1488 numbers are acceptible values. The keys are always taken to be strings.
1490 =head2 User-defined subroutines to handle options
1492 Ultimate control over what should be done when (actually: each time)
1493 an option is encountered on the command line can be achieved by
1494 designating a reference to a subroutine (or an anonymous subroutine)
1495 as the option destination. When GetOptions() encounters the option, it
1496 will call the subroutine with two or three arguments. The first
1497 argument is the name of the option. For a scalar or array destination,
1498 the second argument is the value to be stored. For a hash destination,
1499 the second arguments is the key to the hash, and the third argument
1500 the value to be stored. It is up to the subroutine to store the value,
1501 or do whatever it thinks is appropriate.
1503 A trivial application of this mechanism is to implement options that
1504 are related to each other. For example:
1506 my $verbose = ''; # option variable with default value (false)
1507 GetOptions ('verbose' => \$verbose,
1508 'quiet' => sub { $verbose = 0 });
1510 Here C<--verbose> and C<--quiet> control the same variable
1511 C<$verbose>, but with opposite values.
1513 If the subroutine needs to signal an error, it should call die() with
1514 the desired error message as its argument. GetOptions() will catch the
1515 die(), issue the error message, and record that an error result must
1516 be returned upon completion.
1518 If the text of the error message starts with an exclamantion mark C<!>
1519 it is interpreted specially by GetOptions(). There is currently one
1520 special command implemented: C<die("!FINISH")> will cause GetOptions()
1521 to stop processing options, as if it encountered a double dash C<-->.
1523 =head2 Options with multiple names
1525 Often it is user friendly to supply alternate mnemonic names for
1526 options. For example C<--height> could be an alternate name for
1527 C<--length>. Alternate names can be included in the option
1528 specification, separated by vertical bar C<|> characters. To implement
1531 GetOptions ('length|height=f' => \$length);
1533 The first name is called the I<primary> name, the other names are
1536 Multiple alternate names are possible.
1538 =head2 Case and abbreviations
1540 Without additional configuration, GetOptions() will ignore the case of
1541 option names, and allow the options to be abbreviated to uniqueness.
1543 GetOptions ('length|height=f' => \$length, "head" => \$head);
1545 This call will allow C<--l> and C<--L> for the length option, but
1546 requires a least C<--hea> and C<--hei> for the head and height options.
1548 =head2 Summary of Option Specifications
1550 Each option specifier consists of two parts: the name specification
1551 and the argument specification.
1553 The name specification contains the name of the option, optionally
1554 followed by a list of alternative names separated by vertical bar
1557 length option name is "length"
1558 length|size|l name is "length", aliases are "size" and "l"
1560 The argument specification is optional. If omitted, the option is
1561 considered boolean, a value of 1 will be assigned when the option is
1562 used on the command line.
1564 The argument specification can be
1570 The option does not take an argument and may be negated, i.e. prefixed
1571 by "no". E.g. C<"foo!"> will allow C<--foo> (a value of 1 will be
1572 assigned) and C<--nofoo> and C<--no-foo> (a value of 0 will be assigned). If the
1573 option has aliases, this applies to the aliases as well.
1575 Using negation on a single letter option when bundling is in effect is
1576 pointless and will result in a warning.
1580 The option does not take an argument and will be incremented by 1
1581 every time it appears on the command line. E.g. C<"more+">, when used
1582 with C<--more --more --more>, will increment the value three times,
1583 resulting in a value of 3 (provided it was 0 or undefined at first).
1585 The C<+> specifier is ignored if the option destination is not a scalar.
1587 =item = I<type> [ I<desttype> ]
1589 The option requires an argument of the given type. Supported types
1596 String. An arbitrary sequence of characters. It is valid for the
1597 argument to start with C<-> or C<-->.
1601 Integer. An optional leading plus or minus sign, followed by a
1606 Extended integer, Perl style. This can be either an optional leading
1607 plus or minus sign, followed by a sequence of digits, or an octal
1608 string (a zero, optionally followed by '0', '1', .. '7'), or a
1609 hexadecimal string (C<0x> followed by '0' .. '9', 'a' .. 'f', case
1610 insensitive), or a binary string (C<0b> followed by a series of '0'
1615 Real number. For example C<3.14>, C<-6.23E24> and so on.
1619 The I<desttype> can be C<@> or C<%> to specify that the option is
1620 list or a hash valued. This is only needed when the destination for
1621 the option value is not otherwise specified. It should be omitted when
1624 =item : I<type> [ I<desttype> ]
1626 Like C<=>, but designates the argument as optional.
1627 If omitted, an empty string will be assigned to string values options,
1628 and the value zero to numeric options.
1630 Note that if a string argument starts with C<-> or C<-->, it will be
1631 considered an option on itself.
1633 =item : I<number> [ I<desttype> ]
1635 Like C<:i>, but if the value is omitted, the I<number> will be assigned.
1637 =item : + [ I<desttype> ]
1639 Like C<:i>, but if the value is omitted, the current value for the
1640 option will be incremented.
1644 =head1 Advanced Possibilities
1646 =head2 Object oriented interface
1648 Getopt::Long can be used in an object oriented way as well:
1651 $p = new Getopt::Long::Parser;
1652 $p->configure(...configuration options...);
1653 if ($p->getoptions(...options descriptions...)) ...
1655 Configuration options can be passed to the constructor:
1657 $p = new Getopt::Long::Parser
1658 config => [...configuration options...];
1660 =head2 Thread Safety
1662 Getopt::Long is thread safe when using ithreads as of Perl 5.8. It is
1663 I<not> thread safe when using the older (experimental and now
1664 obsolete) threads implementation that was added to Perl 5.005.
1666 =head2 Documentation and help texts
1668 Getopt::Long encourages the use of Pod::Usage to produce help
1669 messages. For example:
1677 GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
1678 pod2usage(1) if $help;
1679 pod2usage(-exitstatus => 0, -verbose => 2) if $man;
1685 sample - Using Getopt::Long and Pod::Usage
1689 sample [options] [file ...]
1692 -help brief help message
1693 -man full documentation
1701 Print a brief help message and exits.
1705 Prints the manual page and exits.
1711 B<This program> will read the given input file(s) and do someting
1712 useful with the contents thereof.
1716 See L<Pod::Usage> for details.
1718 =head2 Storing options in a hash
1720 Sometimes, for example when there are a lot of options, having a
1721 separate variable for each of them can be cumbersome. GetOptions()
1722 supports, as an alternative mechanism, storing options in a hash.
1724 To obtain this, a reference to a hash must be passed I<as the first
1725 argument> to GetOptions(). For each option that is specified on the
1726 command line, the option value will be stored in the hash with the
1727 option name as key. Options that are not actually used on the command
1728 line will not be put in the hash, on other words,
1729 C<exists($h{option})> (or defined()) can be used to test if an option
1730 was used. The drawback is that warnings will be issued if the program
1731 runs under C<use strict> and uses C<$h{option}> without testing with
1732 exists() or defined() first.
1735 GetOptions (\%h, 'length=i'); # will store in $h{length}
1737 For options that take list or hash values, it is necessary to indicate
1738 this by appending an C<@> or C<%> sign after the type:
1740 GetOptions (\%h, 'colours=s@'); # will push to @{$h{colours}}
1742 To make things more complicated, the hash may contain references to
1743 the actual destinations, for example:
1746 my %h = ('length' => \$len);
1747 GetOptions (\%h, 'length=i'); # will store in $len
1749 This example is fully equivalent with:
1752 GetOptions ('length=i' => \$len); # will store in $len
1754 Any mixture is possible. For example, the most frequently used options
1755 could be stored in variables while all other options get stored in the
1758 my $verbose = 0; # frequently referred
1759 my $debug = 0; # frequently referred
1760 my %h = ('verbose' => \$verbose, 'debug' => \$debug);
1761 GetOptions (\%h, 'verbose', 'debug', 'filter', 'size=i');
1762 if ( $verbose ) { ... }
1763 if ( exists $h{filter} ) { ... option 'filter' was specified ... }
1767 With bundling it is possible to set several single-character options
1768 at once. For example if C<a>, C<v> and C<x> are all valid options,
1772 would set all three.
1774 Getopt::Long supports two levels of bundling. To enable bundling, a
1775 call to Getopt::Long::Configure is required.
1777 The first level of bundling can be enabled with:
1779 Getopt::Long::Configure ("bundling");
1781 Configured this way, single-character options can be bundled but long
1782 options B<must> always start with a double dash C<--> to avoid
1783 abiguity. For example, when C<vax>, C<a>, C<v> and C<x> are all valid
1788 would set C<a>, C<v> and C<x>, but
1794 The second level of bundling lifts this restriction. It can be enabled
1797 Getopt::Long::Configure ("bundling_override");
1799 Now, C<-vax> would set the option C<vax>.
1801 When any level of bundling is enabled, option values may be inserted
1802 in the bundle. For example:
1810 When configured for bundling, single-character options are matched
1811 case sensitive while long options are matched case insensitive. To
1812 have the single-character options matched case insensitive as well,
1815 Getopt::Long::Configure ("bundling", "ignorecase_always");
1817 It goes without saying that bundling can be quite confusing.
1819 =head2 The lonesome dash
1821 Normally, a lone dash C<-> on the command line will not be considered
1822 an option. Option processing will terminate (unless "permute" is
1823 configured) and the dash will be left in C<@ARGV>.
1825 It is possible to get special treatment for a lone dash. This can be
1826 achieved by adding an option specification with an empty name, for
1829 GetOptions ('' => \$stdio);
1831 A lone dash on the command line will now be a legal option, and using
1832 it will set variable C<$stdio>.
1834 =head2 Argument callback
1836 A special option 'name' C<< <> >> can be used to designate a subroutine
1837 to handle non-option arguments. When GetOptions() encounters an
1838 argument that does not look like an option, it will immediately call this
1839 subroutine and passes it one parameter: the argument name.
1845 GetOptions ('width=i' => \$width, '<>' => \&process);
1847 When applied to the following command line:
1849 arg1 --width=72 arg2 --width=60 arg3
1852 C<process("arg1")> while C<$width> is C<80>,
1853 C<process("arg2")> while C<$width> is C<72>, and
1854 C<process("arg3")> while C<$width> is C<60>.
1856 This feature requires configuration option B<permute>, see section
1857 L<Configuring Getopt::Long>.
1859 =head1 Configuring Getopt::Long
1861 Getopt::Long can be configured by calling subroutine
1862 Getopt::Long::Configure(). This subroutine takes a list of quoted
1863 strings, each specifying a configuration option to be enabled, e.g.
1864 C<ignore_case>, or disabled, e.g. C<no_ignore_case>. Case does not
1865 matter. Multiple calls to Configure() are possible.
1867 Alternatively, as of version 2.24, the configuration options may be
1868 passed together with the C<use> statement:
1870 use Getopt::Long qw(:config no_ignore_case bundling);
1872 The following options are available:
1878 This option causes all configuration options to be reset to their
1883 This option causes all configuration options to be reset to their
1884 default values as if the environment variable POSIXLY_CORRECT had
1889 Allow option names to be abbreviated to uniqueness.
1890 Default is enabled unless environment variable
1891 POSIXLY_CORRECT has been set, in which case C<auto_abbrev> is disabled.
1895 Allow C<+> to start options.
1896 Default is enabled unless environment variable
1897 POSIXLY_CORRECT has been set, in which case C<getopt_compat> is disabled.
1901 C<gnu_compat> controls whether C<--opt=> is allowed, and what it should
1902 do. Without C<gnu_compat>, C<--opt=> gives an error. With C<gnu_compat>,
1903 C<--opt=> will give option C<opt> and empty value.
1904 This is the way GNU getopt_long() does it.
1908 This is a short way of setting C<gnu_compat> C<bundling> C<permute>
1909 C<no_getopt_compat>. With C<gnu_getopt>, command line handling should be
1910 fully compatible with GNU getopt_long().
1914 Whether command line arguments are allowed to be mixed with options.
1915 Default is disabled unless environment variable
1916 POSIXLY_CORRECT has been set, in which case C<require_order> is enabled.
1918 See also C<permute>, which is the opposite of C<require_order>.
1922 Whether command line arguments are allowed to be mixed with options.
1923 Default is enabled unless environment variable
1924 POSIXLY_CORRECT has been set, in which case C<permute> is disabled.
1925 Note that C<permute> is the opposite of C<require_order>.
1927 If C<permute> is enabled, this means that
1929 --foo arg1 --bar arg2 arg3
1933 --foo --bar arg1 arg2 arg3
1935 If an argument callback routine is specified, C<@ARGV> will always be
1936 empty upon succesful return of GetOptions() since all options have been
1937 processed. The only exception is when C<--> is used:
1939 --foo arg1 --bar arg2 -- arg3
1941 This will call the callback routine for arg1 and arg2, and then
1942 terminate GetOptions() leaving C<"arg2"> in C<@ARGV>.
1944 If C<require_order> is enabled, options processing
1945 terminates when the first non-option is encountered.
1947 --foo arg1 --bar arg2 arg3
1951 --foo -- arg1 --bar arg2 arg3
1953 If C<pass_through> is also enabled, options processing will terminate
1954 at the first unrecognized option, or non-option, whichever comes
1957 =item bundling (default: disabled)
1959 Enabling this option will allow single-character options to be
1960 bundled. To distinguish bundles from long option names, long options
1961 I<must> be introduced with C<--> and bundles with C<->.
1963 Note that, if you have options C<a>, C<l> and C<all>, and
1964 auto_abbrev enabled, possible arguments and option settings are:
1966 using argument sets option(s)
1967 ------------------------------------------
1970 -al, -la, -ala, -all,... a, l
1973 The suprising part is that C<--a> sets option C<a> (due to auto
1974 completion), not C<all>.
1976 Note: disabling C<bundling> also disables C<bundling_override>.
1978 =item bundling_override (default: disabled)
1980 If C<bundling_override> is enabled, bundling is enabled as with
1981 C<bundling> but now long option names override option bundles.
1983 Note: disabling C<bundling_override> also disables C<bundling>.
1985 B<Note:> Using option bundling can easily lead to unexpected results,
1986 especially when mixing long options and bundles. Caveat emptor.
1988 =item ignore_case (default: enabled)
1990 If enabled, case is ignored when matching long option names. If,
1991 however, bundling is enabled as well, single character options will be
1992 treated case-sensitive.
1994 With C<ignore_case>, option specifications for options that only
1995 differ in case, e.g., C<"foo"> and C<"Foo">, will be flagged as
1998 Note: disabling C<ignore_case> also disables C<ignore_case_always>.
2000 =item ignore_case_always (default: disabled)
2002 When bundling is in effect, case is ignored on single-character
2005 Note: disabling C<ignore_case_always> also disables C<ignore_case>.
2007 =item auto_version (default:disabled)
2009 Automatically provide support for the B<--version> option if
2010 the application did not specify a handler for this option itself.
2012 Getopt::Long will provide a standard version message that includes the
2013 program name, its version (if $main::VERSION is defined), and the
2014 versions of Getopt::Long and Perl. The message will be written to
2015 standard output and processing will terminate.
2017 =item auto_help (default:disabled)
2019 Automatically provide support for the B<--help> and B<-?> options if
2020 the application did not specify a handler for this option itself.
2022 Getopt::Long will provide a help message using module L<Pod::Usage>. The
2023 message, derived from the SYNOPSIS POD section, will be written to
2024 standard output and processing will terminate.
2026 =item pass_through (default: disabled)
2028 Options that are unknown, ambiguous or supplied with an invalid option
2029 value are passed through in C<@ARGV> instead of being flagged as
2030 errors. This makes it possible to write wrapper scripts that process
2031 only part of the user supplied command line arguments, and pass the
2032 remaining options to some other program.
2034 If C<require_order> is enabled, options processing will terminate at
2035 the first unrecognized option, or non-option, whichever comes first.
2036 However, if C<permute> is enabled instead, results can become confusing.
2038 Note that the options terminator (default C<-->), if present, will
2039 also be passed through in C<@ARGV>.
2043 The string that starts options. If a constant string is not
2044 sufficient, see C<prefix_pattern>.
2046 =item prefix_pattern
2048 A Perl pattern that identifies the strings that introduce options.
2049 Default is C<(--|-|\+)> unless environment variable
2050 POSIXLY_CORRECT has been set, in which case it is C<(--|-)>.
2052 =item debug (default: disabled)
2054 Enable debugging output.
2058 =head1 Exportable Methods
2062 =item VersionMessage
2064 This subroutine provides a standard version message. Its argument can be:
2070 A string containing the text of a message to print I<before> printing
2071 the standard message.
2075 A numeric value corresponding to the desired exit status.
2079 A reference to a hash.
2083 If more than one argument is given then the entire argument list is
2084 assumed to be a hash. If a hash is supplied (either as a reference or
2085 as a list) it should contain one or more elements with the following
2094 The text of a message to print immediately prior to printing the
2095 program's usage message.
2099 The desired exit status to pass to the B<exit()> function.
2100 This should be an integer, or else the string "NOEXIT" to
2101 indicate that control should simply be returned without
2102 terminating the invoking process.
2106 A reference to a filehandle, or the pathname of a file to which the
2107 usage message should be written. The default is C<\*STDERR> unless the
2108 exit value is less than 2 (in which case the default is C<\*STDOUT>).
2112 You cannot tie this routine directly to an option, e.g.:
2114 GetOptions("version" => \&VersionMessage);
2118 GetOptions("version" => sub { VersionMessage() });
2122 This subroutine produces a standard help message, derived from the
2123 program's POD section SYNOPSIS using L<Pod::Usage>. It takes the same
2124 arguments as VersionMessage(). In particular, you cannot tie it
2125 directly to an option, e.g.:
2127 GetOptions("help" => \&HelpMessage);
2131 GetOptions("help" => sub { HelpMessage() });
2135 =head1 Return values and Errors
2137 Configuration errors and errors in the option definitions are
2138 signalled using die() and will terminate the calling program unless
2139 the call to Getopt::Long::GetOptions() was embedded in C<eval { ...
2140 }>, or die() was trapped using C<$SIG{__DIE__}>.
2142 GetOptions returns true to indicate success.
2143 It returns false when the function detected one or more errors during
2144 option parsing. These errors are signalled using warn() and can be
2145 trapped with C<$SIG{__WARN__}>.
2149 The earliest development of C<newgetopt.pl> started in 1990, with Perl
2150 version 4. As a result, its development, and the development of
2151 Getopt::Long, has gone through several stages. Since backward
2152 compatibility has always been extremely important, the current version
2153 of Getopt::Long still supports a lot of constructs that nowadays are
2154 no longer necessary or otherwise unwanted. This section describes
2155 briefly some of these 'features'.
2157 =head2 Default destinations
2159 When no destination is specified for an option, GetOptions will store
2160 the resultant value in a global variable named C<opt_>I<XXX>, where
2161 I<XXX> is the primary name of this option. When a progam executes
2162 under C<use strict> (recommended), these variables must be
2163 pre-declared with our() or C<use vars>.
2165 our $opt_length = 0;
2166 GetOptions ('length=i'); # will store in $opt_length
2168 To yield a usable Perl variable, characters that are not part of the
2169 syntax for variables are translated to underscores. For example,
2170 C<--fpp-struct-return> will set the variable
2171 C<$opt_fpp_struct_return>. Note that this variable resides in the
2172 namespace of the calling program, not necessarily C<main>. For
2175 GetOptions ("size=i", "sizes=i@");
2177 with command line "-size 10 -sizes 24 -sizes 48" will perform the
2178 equivalent of the assignments
2181 @opt_sizes = (24, 48);
2183 =head2 Alternative option starters
2185 A string of alternative option starter characters may be passed as the
2186 first argument (or the first argument after a leading hash reference
2190 GetOptions ('/', 'length=i' => $len);
2192 Now the command line may look like:
2196 Note that to terminate options processing still requires a double dash
2199 GetOptions() will not interpret a leading C<< "<>" >> as option starters
2200 if the next argument is a reference. To force C<< "<" >> and C<< ">" >> as
2201 option starters, use C<< "><" >>. Confusing? Well, B<using a starter
2202 argument is strongly deprecated> anyway.
2204 =head2 Configuration variables
2206 Previous versions of Getopt::Long used variables for the purpose of
2207 configuring. Although manipulating these variables still work, it is
2208 strongly encouraged to use the C<Configure> routine that was introduced
2209 in version 2.17. Besides, it is much easier.
2211 =head1 Trouble Shooting
2213 =head2 Warning: Ignoring '!' modifier for short option
2215 This warning is issued when the '!' modifier is applied to a short
2216 (one-character) option and bundling is in effect. E.g.,
2218 Getopt::Long::Configure("bundling");
2219 GetOptions("foo|f!" => \$foo);
2221 Note that older Getopt::Long versions did not issue a warning, because
2222 the '!' modifier was applied to the first name only. This bug was
2225 Solution: separate the long and short names and apply the '!' to the
2226 long names only, e.g.,
2228 GetOptions("foo!" => \$foo, "f" => \$foo);
2230 =head2 GetOptions does not return a false result when an option is not supplied
2232 That's why they're called 'options'.
2234 =head2 GetOptions does not split the command line correctly
2236 The command line is not split by GetOptions, but by the command line
2237 interpreter (CLI). On Unix, this is the shell. On Windows, it is
2238 COMMAND.COM or CMD.EXE. Other operating systems have other CLIs.
2240 It is important to know that these CLIs may behave different when the
2241 command line contains special characters, in particular quotes or
2242 backslashes. For example, with Unix shells you can use single quotes
2243 (C<'>) and double quotes (C<">) to group words together. The following
2244 alternatives are equivalent on Unix:
2250 In case of doubt, insert the following statement in front of your Perl
2253 print STDERR (join("|",@ARGV),"\n");
2255 to verify how your CLI passes the arguments to the program.
2257 =head2 Undefined subroutine &main::GetOptions called
2259 Are you running Windows, and did you write
2263 (note the capital 'O')?
2265 =head2 How do I put a "-?" option into a Getopt::Long?
2267 You can only obtain this using an alias, and Getopt::Long of at least
2271 GetOptions ("help|?"); # -help and -? will both set $opt_help
2275 Johan Vromans <jvromans@squirrel.nl>
2277 =head1 COPYRIGHT AND DISCLAIMER
2279 This program is Copyright 2003,1990 by Johan Vromans.
2280 This program is free software; you can redistribute it and/or
2281 modify it under the terms of the Perl Artistic License or the
2282 GNU General Public License as published by the Free Software
2283 Foundation; either version 2 of the License, or (at your option) any
2286 This program is distributed in the hope that it will be useful,
2287 but WITHOUT ANY WARRANTY; without even the implied warranty of
2288 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
2289 GNU General Public License for more details.
2291 If you do not have a copy of the GNU General Public License write to
2292 the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,