This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Retract #10874 (the hack should be unnecessary by now)
[perl5.git] / lib / Getopt / Long.pm
CommitLineData
a11f5414 1# GetOpt::Long.pm -- Universal options parsing
404cbe93 2
a11f5414
JV
3package Getopt::Long;
4
ac634a9a 5# RCS Status : $Id: GetoptLong.pl,v 2.26 2001-01-31 10:20:29+01 jv Exp $
404cbe93
PP
6# Author : Johan Vromans
7# Created On : Tue Sep 11 15:00:12 1990
8# Last Modified By: Johan Vromans
76744544
JH
9# Last Modified On: Sat Jan 6 17:12:27 2001
10# Update Count : 748
404cbe93
PP
11# Status : Released
12
bb40d378 13################ Copyright ################
f06db76b 14
76744544 15# This program is Copyright 1990,2001 by Johan Vromans.
bb40d378 16# This program is free software; you can redistribute it and/or
1a505819
GS
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
20# later version.
21#
bb40d378
JV
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.
0b7031a2 26#
bb40d378 27# If you do not have a copy of the GNU General Public License write to
0b7031a2 28# the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,
f9a400e4 29# MA 02139, USA.
f06db76b 30
bb40d378 31################ Module Preamble ################
404cbe93 32
76744544
JH
33use 5.004;
34
bb40d378 35use strict;
404cbe93 36
76744544 37use vars qw($VERSION $VERSION_STRING);
ac634a9a
JH
38$VERSION = 2.25;
39$VERSION_STRING = "2.25";
e6d5c530 40
76744544
JH
41use Exporter;
42use AutoLoader qw(AUTOLOAD);
43
44use vars qw(@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
45@ISA = qw(Exporter);
46%EXPORT_TAGS = qw();
47BEGIN {
48 # Init immediately so their contents can be used in the 'use vars' below.
e6d5c530 49 @EXPORT = qw(&GetOptions $REQUIRE_ORDER $PERMUTE $RETURN_IN_ORDER);
e6d5c530 50 @EXPORT_OK = qw();
bb40d378 51}
404cbe93 52
bb40d378 53# User visible variables.
e6d5c530 54use vars @EXPORT, @EXPORT_OK;
bb40d378
JV
55use vars qw($error $debug $major_version $minor_version);
56# Deprecated visible variables.
57use vars qw($autoabbrev $getopt_compat $ignorecase $bundling $order
58 $passthrough);
e6d5c530 59# Official invisible variables.
10e5c9cc 60use vars qw($genprefix $caller $gnu_compat);
e6d5c530 61
0b7031a2 62# Public subroutines.
e6d5c530
JV
63sub Configure (@);
64sub config (@); # deprecated name
65sub GetOptions;
66
0b7031a2 67# Private subroutines.
e6d5c530
JV
68sub ConfigDefaults ();
69sub FindOption ($$$$$$$);
70sub Croak (@); # demand loading the real Croak
404cbe93 71
bb40d378 72################ Local Variables ################
404cbe93 73
e6d5c530
JV
74################ Resident subroutines ################
75
76sub ConfigDefaults () {
77 # Handle POSIX compliancy.
78 if ( defined $ENV{"POSIXLY_CORRECT"} ) {
79 $genprefix = "(--|-)";
80 $autoabbrev = 0; # no automatic abbrev of options
81 $bundling = 0; # no bundling of single letter switches
82 $getopt_compat = 0; # disallow '+' to start options
83 $order = $REQUIRE_ORDER;
84 }
85 else {
86 $genprefix = "(--|-|\\+)";
87 $autoabbrev = 1; # automatic abbrev of options
88 $bundling = 0; # bundling off by default
89 $getopt_compat = 1; # allow '+' to start options
90 $order = $PERMUTE;
91 }
92 # Other configurable settings.
93 $debug = 0; # for debugging
94 $error = 0; # error tally
95 $ignorecase = 1; # ignore case when matching options
96 $passthrough = 0; # leave unrecognized options alone
10e5c9cc
JH
97 $gnu_compat = 0; # require --opt=val if value is optional
98}
99
100# Override import.
101sub import {
102 my $pkg = shift; # package
103 my @syms = (); # symbols to import
104 my @config = (); # configuration
105 my $dest = \@syms; # symbols first
106 for ( @_ ) {
107 if ( $_ eq ':config' ) {
108 $dest = \@config; # config next
109 next;
110 }
111 push (@$dest, $_); # push
112 }
113 # Hide one level and call super.
114 local $Exporter::ExportLevel = 1;
115 $pkg->SUPER::import(@syms);
116 # And configure.
117 Configure (@config) if @config;
e6d5c530
JV
118}
119
120################ Initialization ################
121
122# Values for $order. See GNU getopt.c for details.
123($REQUIRE_ORDER, $PERMUTE, $RETURN_IN_ORDER) = (0..2);
124# Version major/minor numbers.
125($major_version, $minor_version) = $VERSION =~ /^(\d+)\.(\d+)/;
126
0b7031a2
GS
127ConfigDefaults();
128
10e5c9cc
JH
129################ OO Interface ################
130
131package Getopt::Long::Parser;
132
133# NOTE: The object oriented routines use $error for thread locking.
134my $_lock = sub {
135 lock ($Getopt::Long::error) if $] >= 5.005
136};
137
138# Store a copy of the default configuration. Since ConfigDefaults has
139# just been called, what we get from Configure is the default.
140my $default_config = do {
141 &$_lock;
142 Getopt::Long::Configure ()
143};
144
145sub new {
146 my $that = shift;
147 my $class = ref($that) || $that;
148 my %atts = @_;
149
150 # Register the callers package.
ea071ac9 151 my $self = { caller_pkg => (caller)[0] };
10e5c9cc
JH
152
153 bless ($self, $class);
154
155 # Process config attributes.
156 if ( defined $atts{config} ) {
157 &$_lock;
158 my $save = Getopt::Long::Configure ($default_config, @{$atts{config}});
159 $self->{settings} = Getopt::Long::Configure ($save);
160 delete ($atts{config});
161 }
162 # Else use default config.
163 else {
164 $self->{settings} = $default_config;
165 }
166
167 if ( %atts ) { # Oops
168 Getopt::Long::Croak(__PACKAGE__.": unhandled attributes: ".
169 join(" ", sort(keys(%atts))));
170 }
171
172 $self;
173}
174
175sub configure {
176 my ($self) = shift;
177
178 &$_lock;
179
180 # Restore settings, merge new settings in.
181 my $save = Getopt::Long::Configure ($self->{settings}, @_);
182
183 # Restore orig config and save the new config.
184 $self->{settings} = Configure ($save);
185}
186
187sub getoptions {
188 my ($self) = shift;
189
190 &$_lock;
191
192 # Restore config settings.
193 my $save = Getopt::Long::Configure ($self->{settings});
194
195 # Call main routine.
196 my $ret = 0;
ea071ac9 197 $Getopt::Long::caller = $self->{caller_pkg};
10e5c9cc
JH
198 eval { $ret = Getopt::Long::GetOptions (@_); };
199
200 # Restore saved settings.
201 Getopt::Long::Configure ($save);
202
203 # Handle errors and return value.
204 die ($@) if $@;
205 return $ret;
206}
207
208package Getopt::Long;
209
e6d5c530
JV
210################ Package return ################
211
2121;
213
214__END__
215
216################ AutoLoading subroutines ################
217
ac634a9a 218# RCS Status : $Id: GetoptLongAl.pl,v 2.30 2001-01-31 10:21:11+01 jv Exp $
e6d5c530
JV
219# Author : Johan Vromans
220# Created On : Fri Mar 27 11:50:30 1998
221# Last Modified By: Johan Vromans
ea071ac9
JH
222# Last Modified On: Tue Dec 26 18:01:16 2000
223# Update Count : 98
e6d5c530 224# Status : Released
404cbe93 225
bb40d378 226sub GetOptions {
404cbe93 227
bb40d378 228 my @optionlist = @_; # local copy of the option descriptions
e6d5c530
JV
229 my $argend = '--'; # option list terminator
230 my %opctl = (); # table of arg.specs (long and abbrevs)
231 my %bopctl = (); # table of arg.specs (bundles)
0b7031a2 232 my $pkg = $caller || (caller)[0]; # current context
bb40d378 233 # Needed if linkage is omitted.
e6d5c530 234 my %aliases= (); # alias table
bb40d378
JV
235 my @ret = (); # accum for non-options
236 my %linkage; # linkage
237 my $userlinkage; # user supplied HASH
e6d5c530
JV
238 my $opt; # current option
239 my $genprefix = $genprefix; # so we can call the same module many times
240 my @opctl; # the possible long option names
241
bb40d378 242 $error = '';
404cbe93 243
e6d5c530
JV
244 print STDERR ("GetOpt::Long $Getopt::Long::VERSION ",
245 "called from package \"$pkg\".",
246 "\n ",
ac634a9a 247 'GetOptionsAl $Revision: 2.30 $ ',
e6d5c530
JV
248 "\n ",
249 "ARGV: (@ARGV)",
250 "\n ",
251 "autoabbrev=$autoabbrev,".
252 "bundling=$bundling,",
253 "getopt_compat=$getopt_compat,",
10e5c9cc 254 "gnu_compat=$gnu_compat,",
e6d5c530
JV
255 "order=$order,",
256 "\n ",
257 "ignorecase=$ignorecase,",
258 "passthrough=$passthrough,",
259 "genprefix=\"$genprefix\".",
260 "\n")
bb40d378 261 if $debug;
404cbe93 262
0b7031a2 263 # Check for ref HASH as first argument.
bb40d378 264 # First argument may be an object. It's OK to use this as long
0b7031a2 265 # as it is really a hash underneath.
bb40d378
JV
266 $userlinkage = undef;
267 if ( ref($optionlist[0]) and
268 "$optionlist[0]" =~ /^(?:.*\=)?HASH\([^\(]*\)$/ ) {
269 $userlinkage = shift (@optionlist);
270 print STDERR ("=> user linkage: $userlinkage\n") if $debug;
271 }
404cbe93 272
bb40d378
JV
273 # See if the first element of the optionlist contains option
274 # starter characters.
1a505819
GS
275 # Be careful not to interpret '<>' as option starters.
276 if ( $optionlist[0] =~ /^\W+$/
277 && !($optionlist[0] eq '<>'
278 && @optionlist > 0
279 && ref($optionlist[1])) ) {
bb40d378
JV
280 $genprefix = shift (@optionlist);
281 # Turn into regexp. Needs to be parenthesized!
282 $genprefix =~ s/(\W)/\\$1/g;
283 $genprefix = "([" . $genprefix . "])";
284 }
404cbe93 285
bb40d378
JV
286 # Verify correctness of optionlist.
287 %opctl = ();
288 %bopctl = ();
289 while ( @optionlist > 0 ) {
290 my $opt = shift (@optionlist);
404cbe93 291
bb40d378 292 # Strip leading prefix so people can specify "--foo=i" if they like.
3a0431da 293 $opt = $+ if $opt =~ /^$genprefix+(.*)$/s;
404cbe93 294
bb40d378
JV
295 if ( $opt eq '<>' ) {
296 if ( (defined $userlinkage)
297 && !(@optionlist > 0 && ref($optionlist[0]))
298 && (exists $userlinkage->{$opt})
299 && ref($userlinkage->{$opt}) ) {
300 unshift (@optionlist, $userlinkage->{$opt});
301 }
0b7031a2 302 unless ( @optionlist > 0
bb40d378
JV
303 && ref($optionlist[0]) && ref($optionlist[0]) eq 'CODE' ) {
304 $error .= "Option spec <> requires a reference to a subroutine\n";
305 next;
306 }
307 $linkage{'<>'} = shift (@optionlist);
308 next;
309 }
404cbe93 310
10e5c9cc 311 # Match option spec. Allow '?' as an alias only.
e6d5c530 312 if ( $opt !~ /^((\w+[-\w]*)(\|(\?|\w[-\w]*)?)*)?([!~+]|[=:][infse][@%]?)?$/ ) {
bb40d378
JV
313 $error .= "Error in option spec: \"$opt\"\n";
314 next;
315 }
316 my ($o, $c, $a) = ($1, $5);
317 $c = '' unless defined $c;
404cbe93 318
10e5c9cc
JH
319 # $linko keeps track of the primary name the user specified.
320 # This name will be used for the internal or external linkage.
321 # In other words, if the user specifies "FoO|BaR", it will
322 # match any case combinations of 'foo' and 'bar', but if a global
323 # variable needs to be set, it will be $opt_FoO in the exact case
324 # as specified.
325 my $linko;
326
bb40d378
JV
327 if ( ! defined $o ) {
328 # empty -> '-' option
ea071ac9
JH
329 $linko = $o = '';
330 $opctl{''} = $c;
331 $bopctl{''} = $c if $bundling;
bb40d378
JV
332 }
333 else {
334 # Handle alias names
335 my @o = split (/\|/, $o);
10e5c9cc 336 $linko = $o = $o[0];
bb40d378
JV
337 # Force an alias if the option name is not locase.
338 $a = $o unless $o eq lc($o);
339 $o = lc ($o)
0b7031a2 340 if $ignorecase > 1
bb40d378
JV
341 || ($ignorecase
342 && ($bundling ? length($o) > 1 : 1));
404cbe93 343
bb40d378
JV
344 foreach ( @o ) {
345 if ( $bundling && length($_) == 1 ) {
346 $_ = lc ($_) if $ignorecase > 1;
347 if ( $c eq '!' ) {
348 $opctl{"no$_"} = $c;
349 warn ("Ignoring '!' modifier for short option $_\n");
265c41c2
GS
350 $opctl{$_} = $bopctl{$_} = '';
351 }
352 else {
353 $opctl{$_} = $bopctl{$_} = $c;
bb40d378 354 }
bb40d378
JV
355 }
356 else {
357 $_ = lc ($_) if $ignorecase;
358 if ( $c eq '!' ) {
359 $opctl{"no$_"} = $c;
265c41c2
GS
360 $opctl{$_} = ''
361 }
362 else {
363 $opctl{$_} = $c;
bb40d378 364 }
bb40d378
JV
365 }
366 if ( defined $a ) {
367 # Note alias.
368 $aliases{$_} = $a;
369 }
370 else {
371 # Set primary name.
372 $a = $_;
373 }
374 }
bb40d378 375 }
404cbe93 376
bb40d378
JV
377 # If no linkage is supplied in the @optionlist, copy it from
378 # the userlinkage if available.
379 if ( defined $userlinkage ) {
380 unless ( @optionlist > 0 && ref($optionlist[0]) ) {
10e5c9cc
JH
381 if ( exists $userlinkage->{$linko} &&
382 ref($userlinkage->{$linko}) ) {
383 print STDERR ("=> found userlinkage for \"$linko\": ",
384 "$userlinkage->{$linko}\n")
bb40d378 385 if $debug;
10e5c9cc 386 unshift (@optionlist, $userlinkage->{$linko});
bb40d378
JV
387 }
388 else {
389 # Do nothing. Being undefined will be handled later.
390 next;
391 }
392 }
393 }
404cbe93 394
bb40d378
JV
395 # Copy the linkage. If omitted, link to global variable.
396 if ( @optionlist > 0 && ref($optionlist[0]) ) {
10e5c9cc 397 print STDERR ("=> link \"$linko\" to $optionlist[0]\n")
bb40d378
JV
398 if $debug;
399 if ( ref($optionlist[0]) =~ /^(SCALAR|CODE)$/ ) {
10e5c9cc 400 $linkage{$linko} = shift (@optionlist);
bb40d378
JV
401 }
402 elsif ( ref($optionlist[0]) =~ /^(ARRAY)$/ ) {
10e5c9cc 403 $linkage{$linko} = shift (@optionlist);
bb40d378
JV
404 $opctl{$o} .= '@'
405 if $opctl{$o} ne '' and $opctl{$o} !~ /\@$/;
406 $bopctl{$o} .= '@'
0b7031a2 407 if $bundling and defined $bopctl{$o} and
bb40d378
JV
408 $bopctl{$o} ne '' and $bopctl{$o} !~ /\@$/;
409 }
410 elsif ( ref($optionlist[0]) =~ /^(HASH)$/ ) {
10e5c9cc 411 $linkage{$linko} = shift (@optionlist);
bb40d378
JV
412 $opctl{$o} .= '%'
413 if $opctl{$o} ne '' and $opctl{$o} !~ /\%$/;
414 $bopctl{$o} .= '%'
0b7031a2 415 if $bundling and defined $bopctl{$o} and
bb40d378
JV
416 $bopctl{$o} ne '' and $bopctl{$o} !~ /\%$/;
417 }
418 else {
419 $error .= "Invalid option linkage for \"$opt\"\n";
420 }
421 }
422 else {
423 # Link to global $opt_XXX variable.
424 # Make sure a valid perl identifier results.
10e5c9cc 425 my $ov = $linko;
bb40d378
JV
426 $ov =~ s/\W/_/g;
427 if ( $c =~ /@/ ) {
10e5c9cc 428 print STDERR ("=> link \"$linko\" to \@$pkg","::opt_$ov\n")
bb40d378 429 if $debug;
10e5c9cc 430 eval ("\$linkage{\$linko} = \\\@".$pkg."::opt_$ov;");
bb40d378
JV
431 }
432 elsif ( $c =~ /%/ ) {
10e5c9cc 433 print STDERR ("=> link \"$linko\" to \%$pkg","::opt_$ov\n")
bb40d378 434 if $debug;
10e5c9cc 435 eval ("\$linkage{\$linko} = \\\%".$pkg."::opt_$ov;");
bb40d378
JV
436 }
437 else {
10e5c9cc 438 print STDERR ("=> link \"$linko\" to \$$pkg","::opt_$ov\n")
bb40d378 439 if $debug;
10e5c9cc 440 eval ("\$linkage{\$linko} = \\\$".$pkg."::opt_$ov;");
bb40d378
JV
441 }
442 }
443 }
444
445 # Bail out if errors found.
446 die ($error) if $error;
447 $error = 0;
448
449 # Sort the possible long option names.
450 @opctl = sort(keys (%opctl)) if $autoabbrev;
451
452 # Show the options tables if debugging.
453 if ( $debug ) {
454 my ($arrow, $k, $v);
455 $arrow = "=> ";
456 while ( ($k,$v) = each(%opctl) ) {
457 print STDERR ($arrow, "\$opctl{\"$k\"} = \"$v\"\n");
458 $arrow = " ";
459 }
460 $arrow = "=> ";
461 while ( ($k,$v) = each(%bopctl) ) {
462 print STDERR ($arrow, "\$bopctl{\"$k\"} = \"$v\"\n");
463 $arrow = " ";
464 }
465 }
466
467 # Process argument list
0b7031a2
GS
468 my $goon = 1;
469 while ( $goon && @ARGV > 0 ) {
bb40d378
JV
470
471 #### Get next argument ####
472
473 $opt = shift (@ARGV);
bb40d378
JV
474 print STDERR ("=> option \"", $opt, "\"\n") if $debug;
475
476 #### Determine what we have ####
477
478 # Double dash is option list terminator.
479 if ( $opt eq $argend ) {
480 # Finish. Push back accumulated arguments and return.
0b7031a2 481 unshift (@ARGV, @ret)
bb40d378
JV
482 if $order == $PERMUTE;
483 return ($error == 0);
484 }
485
486 my $tryopt = $opt;
e6d5c530
JV
487 my $found; # success status
488 my $dsttype; # destination type ('@' or '%')
0b7031a2 489 my $incr; # destination increment
e6d5c530
JV
490 my $key; # key (if hash type)
491 my $arg; # option argument
492
0b7031a2
GS
493 ($found, $opt, $arg, $dsttype, $incr, $key) =
494 FindOption ($genprefix, $argend, $opt,
e6d5c530 495 \%opctl, \%bopctl, \@opctl, \%aliases);
bb40d378 496
e6d5c530 497 if ( $found ) {
0b7031a2 498
e6d5c530 499 # FindOption undefines $opt in case of errors.
bb40d378
JV
500 next unless defined $opt;
501
502 if ( defined $arg ) {
10e5c9cc
JH
503 if ( defined $aliases{$opt} ) {
504 print STDERR ("=> alias \"$opt\" -> \"$aliases{$opt}\"\n")
505 if $debug;
506 $opt = $aliases{$opt};
507 }
bb40d378
JV
508
509 if ( defined $linkage{$opt} ) {
510 print STDERR ("=> ref(\$L{$opt}) -> ",
511 ref($linkage{$opt}), "\n") if $debug;
512
513 if ( ref($linkage{$opt}) eq 'SCALAR' ) {
e6d5c530
JV
514 if ( $incr ) {
515 print STDERR ("=> \$\$L{$opt} += \"$arg\"\n")
516 if $debug;
517 if ( defined ${$linkage{$opt}} ) {
518 ${$linkage{$opt}} += $arg;
519 }
520 else {
521 ${$linkage{$opt}} = $arg;
522 }
523 }
524 else {
525 print STDERR ("=> \$\$L{$opt} = \"$arg\"\n")
526 if $debug;
527 ${$linkage{$opt}} = $arg;
528 }
bb40d378
JV
529 }
530 elsif ( ref($linkage{$opt}) eq 'ARRAY' ) {
531 print STDERR ("=> push(\@{\$L{$opt}, \"$arg\")\n")
532 if $debug;
533 push (@{$linkage{$opt}}, $arg);
534 }
535 elsif ( ref($linkage{$opt}) eq 'HASH' ) {
536 print STDERR ("=> \$\$L{$opt}->{$key} = \"$arg\"\n")
537 if $debug;
538 $linkage{$opt}->{$key} = $arg;
539 }
540 elsif ( ref($linkage{$opt}) eq 'CODE' ) {
541 print STDERR ("=> &L{$opt}(\"$opt\", \"$arg\")\n")
542 if $debug;
0b7031a2
GS
543 local ($@);
544 eval {
545 &{$linkage{$opt}}($opt, $arg);
546 };
547 print STDERR ("=> die($@)\n") if $debug && $@ ne '';
bee0ef1e
GS
548 if ( $@ =~ /^!/ ) {
549 if ( $@ =~ /^!FINISH\b/ ) {
550 $goon = 0;
551 }
0b7031a2
GS
552 }
553 elsif ( $@ ne '' ) {
554 warn ($@);
555 $error++;
556 }
bb40d378
JV
557 }
558 else {
559 print STDERR ("Invalid REF type \"", ref($linkage{$opt}),
560 "\" in linkage\n");
e6d5c530 561 Croak ("Getopt::Long -- internal error!\n");
bb40d378
JV
562 }
563 }
564 # No entry in linkage means entry in userlinkage.
e6d5c530 565 elsif ( $dsttype eq '@' ) {
bb40d378
JV
566 if ( defined $userlinkage->{$opt} ) {
567 print STDERR ("=> push(\@{\$L{$opt}}, \"$arg\")\n")
568 if $debug;
569 push (@{$userlinkage->{$opt}}, $arg);
570 }
571 else {
572 print STDERR ("=>\$L{$opt} = [\"$arg\"]\n")
573 if $debug;
574 $userlinkage->{$opt} = [$arg];
575 }
576 }
e6d5c530 577 elsif ( $dsttype eq '%' ) {
bb40d378
JV
578 if ( defined $userlinkage->{$opt} ) {
579 print STDERR ("=> \$L{$opt}->{$key} = \"$arg\"\n")
580 if $debug;
581 $userlinkage->{$opt}->{$key} = $arg;
582 }
583 else {
584 print STDERR ("=>\$L{$opt} = {$key => \"$arg\"}\n")
585 if $debug;
586 $userlinkage->{$opt} = {$key => $arg};
587 }
588 }
589 else {
e6d5c530
JV
590 if ( $incr ) {
591 print STDERR ("=> \$L{$opt} += \"$arg\"\n")
592 if $debug;
593 if ( defined $userlinkage->{$opt} ) {
594 $userlinkage->{$opt} += $arg;
595 }
596 else {
597 $userlinkage->{$opt} = $arg;
598 }
599 }
600 else {
601 print STDERR ("=>\$L{$opt} = \"$arg\"\n") if $debug;
602 $userlinkage->{$opt} = $arg;
603 }
bb40d378
JV
604 }
605 }
606 }
607
608 # Not an option. Save it if we $PERMUTE and don't have a <>.
609 elsif ( $order == $PERMUTE ) {
610 # Try non-options call-back.
611 my $cb;
612 if ( (defined ($cb = $linkage{'<>'})) ) {
0b7031a2
GS
613 local ($@);
614 eval {
615 &$cb ($tryopt);
616 };
617 print STDERR ("=> die($@)\n") if $debug && $@ ne '';
bee0ef1e
GS
618 if ( $@ =~ /^!/ ) {
619 if ( $@ =~ /^!FINISH\b/ ) {
620 $goon = 0;
621 }
0b7031a2
GS
622 }
623 elsif ( $@ ne '' ) {
624 warn ($@);
625 $error++;
626 }
bb40d378
JV
627 }
628 else {
629 print STDERR ("=> saving \"$tryopt\" ",
630 "(not an option, may permute)\n") if $debug;
631 push (@ret, $tryopt);
632 }
633 next;
634 }
635
636 # ...otherwise, terminate.
637 else {
638 # Push this one back and exit.
639 unshift (@ARGV, $tryopt);
640 return ($error == 0);
641 }
642
643 }
644
645 # Finish.
646 if ( $order == $PERMUTE ) {
647 # Push back accumulated arguments
648 print STDERR ("=> restoring \"", join('" "', @ret), "\"\n")
649 if $debug && @ret > 0;
650 unshift (@ARGV, @ret) if @ret > 0;
651 }
652
653 return ($error == 0);
654}
655
e6d5c530
JV
656# Option lookup.
657sub FindOption ($$$$$$$) {
bb40d378 658
e6d5c530
JV
659 # returns (1, $opt, $arg, $dsttype, $incr, $key) if okay,
660 # returns (0) otherwise.
bb40d378 661
e6d5c530
JV
662 my ($prefix, $argend, $opt, $opctl, $bopctl, $names, $aliases) = @_;
663 my $key; # hash key for a hash option
664 my $arg;
bb40d378 665
e6d5c530 666 print STDERR ("=> find \"$opt\", prefix=\"$prefix\"\n") if $debug;
bb40d378 667
ea071ac9
JH
668 return 0 unless $opt =~ /^$prefix(.*)$/s;
669 return 0 if $opt eq "-" && !defined $opctl->{""};
bb40d378 670
3a0431da 671 $opt = $+;
bb40d378
JV
672 my ($starter) = $1;
673
674 print STDERR ("=> split \"$starter\"+\"$opt\"\n") if $debug;
675
676 my $optarg = undef; # value supplied with --opt=value
677 my $rest = undef; # remainder from unbundling
678
679 # If it is a long option, it may include the value.
680 if (($starter eq "--" || ($getopt_compat && !$bundling))
3a0431da 681 && $opt =~ /^([^=]+)=(.*)$/s ) {
bb40d378
JV
682 $opt = $1;
683 $optarg = $2;
0b7031a2 684 print STDERR ("=> option \"", $opt,
bb40d378
JV
685 "\", optarg = \"$optarg\"\n") if $debug;
686 }
687
688 #### Look it up ###
689
690 my $tryopt = $opt; # option to try
e6d5c530 691 my $optbl = $opctl; # table to look it up (long names)
bb40d378 692 my $type;
e6d5c530
JV
693 my $dsttype = '';
694 my $incr = 0;
bb40d378
JV
695
696 if ( $bundling && $starter eq '-' ) {
697 # Unbundle single letter option.
ea071ac9 698 $rest = length ($tryopt) > 0 ? substr ($tryopt, 1) : "";
bb40d378
JV
699 $tryopt = substr ($tryopt, 0, 1);
700 $tryopt = lc ($tryopt) if $ignorecase > 1;
701 print STDERR ("=> $starter$tryopt unbundled from ",
702 "$starter$tryopt$rest\n") if $debug;
703 $rest = undef unless $rest ne '';
e6d5c530 704 $optbl = $bopctl; # look it up in the short names table
bb40d378
JV
705
706 # If bundling == 2, long options can override bundles.
707 if ( $bundling == 2 and
f9a400e4 708 defined ($rest) and
e6d5c530 709 defined ($type = $opctl->{$tryopt.$rest}) ) {
bb40d378
JV
710 print STDERR ("=> $starter$tryopt rebundled to ",
711 "$starter$tryopt$rest\n") if $debug;
712 $tryopt .= $rest;
713 undef $rest;
714 }
0b7031a2 715 }
bb40d378
JV
716
717 # Try auto-abbreviation.
718 elsif ( $autoabbrev ) {
719 # Downcase if allowed.
720 $tryopt = $opt = lc ($opt) if $ignorecase;
721 # Turn option name into pattern.
722 my $pat = quotemeta ($opt);
723 # Look up in option names.
e6d5c530 724 my @hits = grep (/^$pat/, @{$names});
bb40d378 725 print STDERR ("=> ", scalar(@hits), " hits (@hits) with \"$pat\" ",
e6d5c530 726 "out of ", scalar(@{$names}), "\n") if $debug;
bb40d378
JV
727
728 # Check for ambiguous results.
729 unless ( (@hits <= 1) || (grep ($_ eq $opt, @hits) == 1) ) {
730 # See if all matches are for the same option.
731 my %hit;
732 foreach ( @hits ) {
e6d5c530 733 $_ = $aliases->{$_} if defined $aliases->{$_};
bb40d378
JV
734 $hit{$_} = 1;
735 }
736 # Now see if it really is ambiguous.
737 unless ( keys(%hit) == 1 ) {
e6d5c530 738 return (0) if $passthrough;
bb40d378
JV
739 warn ("Option ", $opt, " is ambiguous (",
740 join(", ", @hits), ")\n");
741 $error++;
742 undef $opt;
e6d5c530 743 return (1, $opt,$arg,$dsttype,$incr,$key);
bb40d378
JV
744 }
745 @hits = keys(%hit);
746 }
747
748 # Complete the option name, if appropriate.
749 if ( @hits == 1 && $hits[0] ne $opt ) {
750 $tryopt = $hits[0];
751 $tryopt = lc ($tryopt) if $ignorecase;
752 print STDERR ("=> option \"$opt\" -> \"$tryopt\"\n")
753 if $debug;
754 }
755 }
756
757 # Map to all lowercase if ignoring case.
758 elsif ( $ignorecase ) {
759 $tryopt = lc ($opt);
760 }
761
762 # Check validity by fetching the info.
763 $type = $optbl->{$tryopt} unless defined $type;
764 unless ( defined $type ) {
e6d5c530 765 return (0) if $passthrough;
bb40d378
JV
766 warn ("Unknown option: ", $opt, "\n");
767 $error++;
e6d5c530 768 return (1, $opt,$arg,$dsttype,$incr,$key);
bb40d378
JV
769 }
770 # Apparently valid.
771 $opt = $tryopt;
10e5c9cc 772 print STDERR ("=> found \"$type\" for \"", $opt, "\"\n") if $debug;
bb40d378
JV
773
774 #### Determine argument status ####
775
776 # If it is an option w/o argument, we're almost finished with it.
e6d5c530 777 if ( $type eq '' || $type eq '!' || $type eq '+' ) {
bb40d378 778 if ( defined $optarg ) {
e6d5c530 779 return (0) if $passthrough;
bb40d378
JV
780 warn ("Option ", $opt, " does not take an argument\n");
781 $error++;
782 undef $opt;
783 }
e6d5c530 784 elsif ( $type eq '' || $type eq '+' ) {
bb40d378 785 $arg = 1; # supply explicit value
e6d5c530 786 $incr = $type eq '+';
bb40d378
JV
787 }
788 else {
789 substr ($opt, 0, 2) = ''; # strip NO prefix
790 $arg = 0; # supply explicit value
791 }
792 unshift (@ARGV, $starter.$rest) if defined $rest;
e6d5c530 793 return (1, $opt,$arg,$dsttype,$incr,$key);
bb40d378
JV
794 }
795
796 # Get mandatory status and type info.
797 my $mand;
e6d5c530 798 ($mand, $type, $dsttype, $key) = $type =~ /^(.)(.)([@%]?)$/;
bb40d378
JV
799
800 # Check if there is an option argument available.
10e5c9cc
JH
801 if ( $gnu_compat ) {
802 return (1, $opt, $optarg, $dsttype, $incr, $key)
803 if defined $optarg;
804 return (1, $opt, $type eq "s" ? '' : 0, $dsttype, $incr, $key)
805 if $mand eq ':';
806 }
807
808 # Check if there is an option argument available.
809 if ( defined $optarg
810 ? ($optarg eq '')
bb40d378
JV
811 : !(defined $rest || @ARGV > 0) ) {
812 # Complain if this option needs an argument.
813 if ( $mand eq "=" ) {
e6d5c530 814 return (0) if $passthrough;
bb40d378
JV
815 warn ("Option ", $opt, " requires an argument\n");
816 $error++;
817 undef $opt;
818 }
10e5c9cc 819 return (1, $opt, $type eq "s" ? '' : 0, $dsttype, $incr, $key);
bb40d378
JV
820 }
821
822 # Get (possibly optional) argument.
823 $arg = (defined $rest ? $rest
824 : (defined $optarg ? $optarg : shift (@ARGV)));
825
826 # Get key if this is a "name=value" pair for a hash option.
827 $key = undef;
e6d5c530 828 if ($dsttype eq '%' && defined $arg) {
0b7031a2 829 ($key, $arg) = ($arg =~ /^([^=]*)=(.*)$/s) ? ($1, $2) : ($arg, 1);
bb40d378
JV
830 }
831
832 #### Check if the argument is valid for this option ####
833
834 if ( $type eq "s" ) { # string
0b7031a2 835 # A mandatory string takes anything.
e6d5c530 836 return (1, $opt,$arg,$dsttype,$incr,$key) if $mand eq "=";
bb40d378 837
0b7031a2
GS
838 # An optional string takes almost anything.
839 return (1, $opt,$arg,$dsttype,$incr,$key)
e6d5c530
JV
840 if defined $optarg || defined $rest;
841 return (1, $opt,$arg,$dsttype,$incr,$key) if $arg eq "-"; # ??
bb40d378
JV
842
843 # Check for option or option list terminator.
844 if ($arg eq $argend ||
e6d5c530 845 $arg =~ /^$prefix.+/) {
bb40d378
JV
846 # Push back.
847 unshift (@ARGV, $arg);
848 # Supply empty value.
849 $arg = '';
850 }
851 }
852
853 elsif ( $type eq "n" || $type eq "i" ) { # numeric/integer
0b7031a2 854 if ( $bundling && defined $rest && $rest =~ /^([-+]?[0-9]+)(.*)$/s ) {
bb40d378
JV
855 $arg = $1;
856 $rest = $2;
857 unshift (@ARGV, $starter.$rest) if defined $rest && $rest ne '';
858 }
0b7031a2 859 elsif ( $arg !~ /^[-+]?[0-9]+$/ ) {
bb40d378
JV
860 if ( defined $optarg || $mand eq "=" ) {
861 if ( $passthrough ) {
862 unshift (@ARGV, defined $rest ? $starter.$rest : $arg)
863 unless defined $optarg;
e6d5c530 864 return (0);
bb40d378
JV
865 }
866 warn ("Value \"", $arg, "\" invalid for option ",
867 $opt, " (number expected)\n");
868 $error++;
869 undef $opt;
870 # Push back.
871 unshift (@ARGV, $starter.$rest) if defined $rest;
872 }
873 else {
874 # Push back.
875 unshift (@ARGV, defined $rest ? $starter.$rest : $arg);
876 # Supply default value.
877 $arg = 0;
878 }
879 }
880 }
881
882 elsif ( $type eq "f" ) { # real number, int is also ok
883 # We require at least one digit before a point or 'e',
884 # and at least one digit following the point and 'e'.
885 # [-]NN[.NN][eNN]
886 if ( $bundling && defined $rest &&
0b7031a2 887 $rest =~ /^([-+]?[0-9]+(\.[0-9]+)?([eE][-+]?[0-9]+)?)(.*)$/s ) {
bb40d378 888 $arg = $1;
3a0431da 889 $rest = $+;
bb40d378
JV
890 unshift (@ARGV, $starter.$rest) if defined $rest && $rest ne '';
891 }
0b7031a2 892 elsif ( $arg !~ /^[-+]?[0-9.]+(\.[0-9]+)?([eE][-+]?[0-9]+)?$/ ) {
bb40d378
JV
893 if ( defined $optarg || $mand eq "=" ) {
894 if ( $passthrough ) {
895 unshift (@ARGV, defined $rest ? $starter.$rest : $arg)
896 unless defined $optarg;
e6d5c530 897 return (0);
bb40d378
JV
898 }
899 warn ("Value \"", $arg, "\" invalid for option ",
900 $opt, " (real number expected)\n");
901 $error++;
902 undef $opt;
903 # Push back.
904 unshift (@ARGV, $starter.$rest) if defined $rest;
905 }
906 else {
907 # Push back.
908 unshift (@ARGV, defined $rest ? $starter.$rest : $arg);
909 # Supply default value.
910 $arg = 0.0;
911 }
912 }
913 }
914 else {
e6d5c530 915 Croak ("GetOpt::Long internal error (Can't happen)\n");
bb40d378 916 }
e6d5c530
JV
917 return (1, $opt, $arg, $dsttype, $incr, $key);
918}
bb40d378 919
e6d5c530
JV
920# Getopt::Long Configuration.
921sub Configure (@) {
922 my (@options) = @_;
0b7031a2
GS
923
924 my $prevconfig =
925 [ $error, $debug, $major_version, $minor_version,
926 $autoabbrev, $getopt_compat, $ignorecase, $bundling, $order,
10e5c9cc 927 $gnu_compat, $passthrough, $genprefix ];
0b7031a2
GS
928
929 if ( ref($options[0]) eq 'ARRAY' ) {
930 ( $error, $debug, $major_version, $minor_version,
931 $autoabbrev, $getopt_compat, $ignorecase, $bundling, $order,
10e5c9cc 932 $gnu_compat, $passthrough, $genprefix ) = @{shift(@options)};
0b7031a2
GS
933 }
934
e6d5c530
JV
935 my $opt;
936 foreach $opt ( @options ) {
937 my $try = lc ($opt);
938 my $action = 1;
939 if ( $try =~ /^no_?(.*)$/s ) {
940 $action = 0;
941 $try = $+;
942 }
10e5c9cc
JH
943 if ( ($try eq 'default' or $try eq 'defaults') && $action ) {
944 ConfigDefaults ();
945 }
946 elsif ( ($try eq 'posix_default' or $try eq 'posix_defaults') ) {
947 local $ENV{POSIXLY_CORRECT};
948 $ENV{POSIXLY_CORRECT} = 1 if $action;
949 ConfigDefaults ();
e6d5c530
JV
950 }
951 elsif ( $try eq 'auto_abbrev' or $try eq 'autoabbrev' ) {
952 $autoabbrev = $action;
953 }
954 elsif ( $try eq 'getopt_compat' ) {
955 $getopt_compat = $action;
956 }
10e5c9cc
JH
957 elsif ( $try eq 'gnu_getopt' ) {
958 if ( $action ) {
959 $gnu_compat = 1;
960 $bundling = 1;
961 $getopt_compat = 0;
962 $permute = 1;
963 }
964 }
965 elsif ( $try eq 'gnu_compat' ) {
966 $gnu_compat = $action;
967 }
e6d5c530
JV
968 elsif ( $try eq 'ignorecase' or $try eq 'ignore_case' ) {
969 $ignorecase = $action;
970 }
971 elsif ( $try eq 'ignore_case_always' ) {
972 $ignorecase = $action ? 2 : 0;
973 }
974 elsif ( $try eq 'bundling' ) {
975 $bundling = $action;
976 }
977 elsif ( $try eq 'bundling_override' ) {
978 $bundling = $action ? 2 : 0;
979 }
980 elsif ( $try eq 'require_order' ) {
981 $order = $action ? $REQUIRE_ORDER : $PERMUTE;
982 }
983 elsif ( $try eq 'permute' ) {
984 $order = $action ? $PERMUTE : $REQUIRE_ORDER;
985 }
986 elsif ( $try eq 'pass_through' or $try eq 'passthrough' ) {
987 $passthrough = $action;
988 }
10e5c9cc 989 elsif ( $try =~ /^prefix=(.+)$/ && $action ) {
e6d5c530
JV
990 $genprefix = $1;
991 # Turn into regexp. Needs to be parenthesized!
992 $genprefix = "(" . quotemeta($genprefix) . ")";
993 eval { '' =~ /$genprefix/; };
994 Croak ("Getopt::Long: invalid pattern \"$genprefix\"") if $@;
995 }
10e5c9cc 996 elsif ( $try =~ /^prefix_pattern=(.+)$/ && $action ) {
e6d5c530
JV
997 $genprefix = $1;
998 # Parenthesize if needed.
0b7031a2 999 $genprefix = "(" . $genprefix . ")"
e6d5c530
JV
1000 unless $genprefix =~ /^\(.*\)$/;
1001 eval { '' =~ /$genprefix/; };
1002 Croak ("Getopt::Long: invalid pattern \"$genprefix\"") if $@;
1003 }
1004 elsif ( $try eq 'debug' ) {
1005 $debug = $action;
1006 }
1007 else {
1008 Croak ("Getopt::Long: unknown config parameter \"$opt\"")
1009 }
bb40d378 1010 }
0b7031a2 1011 $prevconfig;
e6d5c530 1012}
bb40d378 1013
e6d5c530
JV
1014# Deprecated name.
1015sub config (@) {
1016 Configure (@_);
1017}
bb40d378 1018
e6d5c530
JV
1019# To prevent Carp from being loaded unnecessarily.
1020sub Croak (@) {
1021 require 'Carp.pm';
1022 $Carp::CarpLevel = 1;
1023 Carp::croak(@_);
1024};
bb40d378 1025
e6d5c530 1026################ Documentation ################
bb40d378
JV
1027
1028=head1 NAME
1029
0b7031a2 1030Getopt::Long - Extended processing of command line options
bb40d378
JV
1031
1032=head1 SYNOPSIS
1033
1034 use Getopt::Long;
1035 $result = GetOptions (...option-descriptions...);
1036
1037=head1 DESCRIPTION
1038
1039The Getopt::Long module implements an extended getopt function called
1040GetOptions(). This function adheres to the POSIX syntax for command
1041line options, with GNU extensions. In general, this means that options
1042have long names instead of single letters, and are introduced with a
1043double dash "--". Support for bundling of command line options, as was
1044the case with the more traditional single-letter approach, is provided
0b7031a2
GS
1045but not enabled by default.
1046
1047=head1 Command Line Options, an Introduction
1048
1049Command line operated programs traditionally take their arguments from
1050the command line, for example filenames or other information that the
1051program needs to know. Besides arguments, these programs often take
1052command line I<options> as well. Options are not necessary for the
1053program to work, hence the name 'option', but are used to modify its
1054default behaviour. For example, a program could do its job quietly,
1055but with a suitable option it could provide verbose information about
1056what it did.
1057
1058Command line options come in several flavours. Historically, they are
1059preceded by a single dash C<->, and consist of a single letter.
1060
1061 -l -a -c
1062
1063Usually, these single-character options can be bundled:
1064
1065 -lac
1066
1067Options can have values, the value is placed after the option
1068character. Sometimes with whitespace in between, sometimes not:
1069
1070 -s 24 -s24
1071
1072Due to the very cryptic nature of these options, another style was
1073developed that used long names. So instead of a cryptic C<-l> one
1074could use the more descriptive C<--long>. To distinguish between a
1075bundle of single-character options and a long one, two dashes are used
1076to precede the option name. Early implementations of long options used
1077a plus C<+> instead. Also, option values could be specified either
10e5c9cc 1078like
0b7031a2
GS
1079
1080 --size=24
1081
1082or
1083
1084 --size 24
1085
1086The C<+> form is now obsolete and strongly deprecated.
1087
1088=head1 Getting Started with Getopt::Long
1089
1090Getopt::Long is the Perl5 successor of C<newgetopt.pl>. This was
10e5c9cc 1091the first Perl module that provided support for handling the new style
0b7031a2
GS
1092of command line options, hence the name Getopt::Long. This module
1093also supports single-character options and bundling. In this case, the
1094options are restricted to alphabetic characters only, and the
1095characters C<?> and C<->.
1096
1097To use Getopt::Long from a Perl program, you must include the
1098following line in your Perl program:
1099
1100 use Getopt::Long;
1101
1102This will load the core of the Getopt::Long module and prepare your
1103program for using it. Most of the actual Getopt::Long code is not
1104loaded until you really call one of its functions.
1105
1106In the default configuration, options names may be abbreviated to
1107uniqueness, case does not matter, and a single dash is sufficient,
1108even for long option names. Also, options may be placed between
1109non-option arguments. See L<Configuring Getopt::Long> for more
1110details on how to configure Getopt::Long.
1111
1112=head2 Simple options
1113
1114The most simple options are the ones that take no values. Their mere
1115presence on the command line enables the option. Popular examples are:
1116
1117 --all --verbose --quiet --debug
1118
1119Handling simple options is straightforward:
1120
1121 my $verbose = ''; # option variable with default value (false)
1122 my $all = ''; # option variable with default value (false)
1123 GetOptions ('verbose' => \$verbose, 'all' => \$all);
1124
1125The call to GetOptions() parses the command line arguments that are
1126present in C<@ARGV> and sets the option variable to the value C<1> if
1127the option did occur on the command line. Otherwise, the option
1128variable is not touched. Setting the option value to true is often
1129called I<enabling> the option.
1130
1131The option name as specified to the GetOptions() function is called
1132the option I<specification>. Later we'll see that this specification
1133can contain more than just the option name. The reference to the
1134variable is called the option I<destination>.
1135
1136GetOptions() will return a true value if the command line could be
1137processed successfully. Otherwise, it will write error messages to
1138STDERR, and return a false result.
1139
1140=head2 A little bit less simple options
1141
1142Getopt::Long supports two useful variants of simple options:
1143I<negatable> options and I<incremental> options.
1144
1145A negatable option is specified with a exclamation mark C<!> after the
1146option name:
1147
1148 my $verbose = ''; # option variable with default value (false)
1149 GetOptions ('verbose!' => \$verbose);
1150
1151Now, using C<--verbose> on the command line will enable C<$verbose>,
1152as expected. But it is also allowed to use C<--noverbose>, which will
1153disable C<$verbose> by setting its value to C<0>. Using a suitable
1154default value, the program can find out whether C<$verbose> is false
1155by default, or disabled by using C<--noverbose>.
1156
1157An incremental option is specified with a plus C<+> after the
1158option name:
1159
1160 my $verbose = ''; # option variable with default value (false)
1161 GetOptions ('verbose+' => \$verbose);
1162
1163Using C<--verbose> on the command line will increment the value of
1164C<$verbose>. This way the program can keep track of how many times the
1165option occurred on the command line. For example, each occurrence of
1166C<--verbose> could increase the verbosity level of the program.
1167
1168=head2 Mixing command line option with other arguments
1169
1170Usually programs take command line options as well as other arguments,
1171for example, file names. It is good practice to always specify the
1172options first, and the other arguments last. Getopt::Long will,
1173however, allow the options and arguments to be mixed and 'filter out'
1174all the options before passing the rest of the arguments to the
1175program. To stop Getopt::Long from processing further arguments,
1176insert a double dash C<--> on the command line:
1177
1178 --size 24 -- --all
1179
1180In this example, C<--all> will I<not> be treated as an option, but
1181passed to the program unharmed, in C<@ARGV>.
1182
1183=head2 Options with values
1184
1185For options that take values it must be specified whether the option
1186value is required or not, and what kind of value the option expects.
1187
1188Three kinds of values are supported: integer numbers, floating point
1189numbers, and strings.
1190
1191If the option value is required, Getopt::Long will take the
1192command line argument that follows the option and assign this to the
1193option variable. If, however, the option value is specified as
1194optional, this will only be done if that value does not look like a
1195valid command line option itself.
bb40d378 1196
0b7031a2
GS
1197 my $tag = ''; # option variable with default value
1198 GetOptions ('tag=s' => \$tag);
bb40d378 1199
0b7031a2
GS
1200In the option specification, the option name is followed by an equals
1201sign C<=> and the letter C<s>. The equals sign indicates that this
1202option requires a value. The letter C<s> indicates that this value is
1203an arbitrary string. Other possible value types are C<i> for integer
1204values, and C<f> for floating point values. Using a colon C<:> instead
1205of the equals sign indicates that the option value is optional. In
1206this case, if no suitable value is supplied, string valued options get
1207an empty string C<''> assigned, while numeric options are set to C<0>.
bb40d378 1208
0b7031a2 1209=head2 Options with multiple values
bb40d378 1210
0b7031a2
GS
1211Options sometimes take several values. For example, a program could
1212use multiple directories to search for library files:
bb40d378 1213
0b7031a2 1214 --library lib/stdlib --library lib/extlib
bb40d378 1215
0b7031a2
GS
1216To accomplish this behaviour, simply specify an array reference as the
1217destination for the option:
bb40d378 1218
0b7031a2
GS
1219 my @libfiles = ();
1220 GetOptions ("library=s" => \@libfiles);
bb40d378 1221
0b7031a2
GS
1222Used with the example above, C<@libfiles> would contain two strings
1223upon completion: C<"lib/srdlib"> and C<"lib/extlib">, in that order.
1224It is also possible to specify that only integer or floating point
1225numbers are acceptible values.
bb40d378 1226
0b7031a2
GS
1227Often it is useful to allow comma-separated lists of values as well as
1228multiple occurrences of the options. This is easy using Perl's split()
1229and join() operators:
bb40d378 1230
0b7031a2
GS
1231 my @libfiles = ();
1232 GetOptions ("library=s" => \@libfiles);
1233 @libfiles = split(/,/,join(',',@libfiles));
bb40d378 1234
0b7031a2
GS
1235Of course, it is important to choose the right separator string for
1236each purpose.
3cb6de81 1237
0b7031a2 1238=head2 Options with hash values
bb40d378 1239
0b7031a2
GS
1240If the option destination is a reference to a hash, the option will
1241take, as value, strings of the form I<key>C<=>I<value>. The value will
1242be stored with the specified key in the hash.
bb40d378 1243
0b7031a2
GS
1244 my %defines = ();
1245 GetOptions ("define=s" => \%defines);
bb40d378 1246
0b7031a2
GS
1247When used with command line options:
1248
1249 --define os=linux --define vendor=redhat
1250
1251the hash C<%defines> will contain two keys, C<"os"> with value
1252C<"linux> and C<"vendor"> with value C<"redhat">.
1253It is also possible to specify that only integer or floating point
1254numbers are acceptible values. The keys are always taken to be strings.
1255
1256=head2 User-defined subroutines to handle options
1257
1258Ultimate control over what should be done when (actually: each time)
1259an option is encountered on the command line can be achieved by
1260designating a reference to a subroutine (or an anonymous subroutine)
1261as the option destination. When GetOptions() encounters the option, it
1262will call the subroutine with two arguments: the name of the option,
1263and the value to be assigned. It is up to the subroutine to store the
1264value, or do whatever it thinks is appropriate.
1265
1266A trivial application of this mechanism is to implement options that
1267are related to each other. For example:
1268
1269 my $verbose = ''; # option variable with default value (false)
1270 GetOptions ('verbose' => \$verbose,
1271 'quiet' => sub { $verbose = 0 });
1272
1273Here C<--verbose> and C<--quiet> control the same variable
1274C<$verbose>, but with opposite values.
1275
1276If the subroutine needs to signal an error, it should call die() with
1277the desired error message as its argument. GetOptions() will catch the
1278die(), issue the error message, and record that an error result must
1279be returned upon completion.
1280
bee0ef1e
GS
1281If the text of the error message starts with an exclamantion mark C<!>
1282it is interpreted specially by GetOptions(). There is currently one
1283special command implemented: C<die("!FINISH")> will cause GetOptions()
1284to stop processing options, as if it encountered a double dash C<-->.
0b7031a2
GS
1285
1286=head2 Options with multiple names
1287
1288Often it is user friendly to supply alternate mnemonic names for
1289options. For example C<--height> could be an alternate name for
1290C<--length>. Alternate names can be included in the option
1291specification, separated by vertical bar C<|> characters. To implement
1292the above example:
1293
1294 GetOptions ('length|height=f' => \$length);
1295
1296The first name is called the I<primary> name, the other names are
1297called I<aliases>.
1298
1299Multiple alternate names are possible.
1300
1301=head2 Case and abbreviations
1302
1303Without additional configuration, GetOptions() will ignore the case of
1304option names, and allow the options to be abbreviated to uniqueness.
1305
1306 GetOptions ('length|height=f' => \$length, "head" => \$head);
1307
1308This call will allow C<--l> and C<--L> for the length option, but
1309requires a least C<--hea> and C<--hei> for the head and height options.
1310
1311=head2 Summary of Option Specifications
1312
1313Each option specifier consists of two parts: the name specification
10e5c9cc 1314and the argument specification.
0b7031a2
GS
1315
1316The name specification contains the name of the option, optionally
1317followed by a list of alternative names separated by vertical bar
10e5c9cc 1318characters.
0b7031a2
GS
1319
1320 length option name is "length"
1321 length|size|l name is "length", aliases are "size" and "l"
1322
1323The argument specification is optional. If omitted, the option is
1324considered boolean, a value of 1 will be assigned when the option is
1325used on the command line.
1326
1327The argument specification can be
1328
bbc7dcd2 1329=over 4
bb40d378
JV
1330
1331=item !
1332
0b7031a2
GS
1333The option does not take an argument and may be negated, i.e. prefixed
1334by "no". E.g. C<"foo!"> will allow C<--foo> (a value of 1 will be
265c41c2
GS
1335assigned) and C<--nofoo> (a value of 0 will be assigned). If the
1336option has aliases, this applies to the aliases as well.
1337
1338Using negation on a single letter option when bundling is in effect is
1339pointless and will result in a warning.
bb40d378 1340
e6d5c530
JV
1341=item +
1342
0b7031a2
GS
1343The option does not take an argument and will be incremented by 1
1344every time it appears on the command line. E.g. C<"more+">, when used
1345with C<--more --more --more>, will increment the value three times,
1346resulting in a value of 3 (provided it was 0 or undefined at first).
e6d5c530 1347
0b7031a2 1348The C<+> specifier is ignored if the option destination is not a scalar.
e6d5c530 1349
0b7031a2 1350=item = I<type> [ I<desttype> ]
bb40d378 1351
0b7031a2
GS
1352The option requires an argument of the given type. Supported types
1353are:
bb40d378 1354
bbc7dcd2 1355=over 4
bb40d378 1356
0b7031a2 1357=item s
bb40d378 1358
0b7031a2
GS
1359String. An arbitrary sequence of characters. It is valid for the
1360argument to start with C<-> or C<-->.
bb40d378 1361
0b7031a2 1362=item i
bb40d378 1363
0b7031a2
GS
1364Integer. An optional leading plus or minus sign, followed by a
1365sequence of digits.
bb40d378 1366
0b7031a2 1367=item f
bb40d378 1368
0b7031a2 1369Real number. For example C<3.14>, C<-6.23E24> and so on.
bb40d378 1370
0b7031a2
GS
1371=back
1372
1373The I<desttype> can be C<@> or C<%> to specify that the option is
1374list or a hash valued. This is only needed when the destination for
1375the option value is not otherwise specified. It should be omitted when
1376not needed.
1377
1378=item : I<type> [ I<desttype> ]
404cbe93 1379
0b7031a2
GS
1380Like C<=>, but designates the argument as optional.
1381If omitted, an empty string will be assigned to string values options,
1382and the value zero to numeric options.
404cbe93 1383
0b7031a2
GS
1384Note that if a string argument starts with C<-> or C<-->, it will be
1385considered an option on itself.
404cbe93
PP
1386
1387=back
1388
0b7031a2 1389=head1 Advanced Possibilities
404cbe93 1390
10e5c9cc
JH
1391=head2 Object oriented interface
1392
1393Getopt::Long can be used in an object oriented way as well:
1394
1395 use Getopt::Long;
1396 $p = new Getopt::Long::Parser;
1397 $p->configure(...configuration options...);
1398 if ($p->getoptions(...options descriptions...)) ...
1399
1400Configuration options can be passed to the constructor:
1401
1402 $p = new Getopt::Long::Parser
1403 config => [...configuration options...];
1404
1405For thread safety, each method call will acquire an exclusive lock to
1406the Getopt::Long module. So don't call these methods from a callback
1407routine!
1408
0b7031a2 1409=head2 Documentation and help texts
404cbe93 1410
0b7031a2
GS
1411Getopt::Long encourages the use of Pod::Usage to produce help
1412messages. For example:
404cbe93 1413
0b7031a2
GS
1414 use Getopt::Long;
1415 use Pod::Usage;
404cbe93 1416
0b7031a2
GS
1417 my $man = 0;
1418 my $help = 0;
404cbe93 1419
0b7031a2
GS
1420 GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
1421 pod2usage(1) if $help;
1422 pod2usage(-exitstatus => 0, -verbose => 2) if $man;
404cbe93 1423
0b7031a2 1424 __END__
404cbe93 1425
0b7031a2 1426 =head1 NAME
404cbe93 1427
0b7031a2 1428 sample - Using GetOpt::Long and Pod::Usage
404cbe93 1429
0b7031a2 1430 =head1 SYNOPSIS
404cbe93 1431
0b7031a2 1432 sample [options] [file ...]
404cbe93 1433
0b7031a2
GS
1434 Options:
1435 -help brief help message
1436 -man full documentation
381319f7 1437
0b7031a2 1438 =head1 OPTIONS
381319f7 1439
0b7031a2 1440 =over 8
381319f7 1441
0b7031a2 1442 =item B<-help>
381319f7 1443
0b7031a2 1444 Print a brief help message and exits.
404cbe93 1445
0b7031a2 1446 =item B<-man>
404cbe93 1447
0b7031a2 1448 Prints the manual page and exits.
404cbe93 1449
0b7031a2 1450 =back
404cbe93 1451
0b7031a2 1452 =head1 DESCRIPTION
404cbe93 1453
0b7031a2
GS
1454 B<This program> will read the given input file(s) and do someting
1455 useful with the contents thereof.
404cbe93 1456
0b7031a2 1457 =cut
535b5725 1458
0b7031a2 1459See L<Pod::Usage> for details.
535b5725 1460
0b7031a2 1461=head2 Storing options in a hash
404cbe93 1462
0b7031a2
GS
1463Sometimes, for example when there are a lot of options, having a
1464separate variable for each of them can be cumbersome. GetOptions()
1465supports, as an alternative mechanism, storing options in a hash.
404cbe93 1466
0b7031a2
GS
1467To obtain this, a reference to a hash must be passed I<as the first
1468argument> to GetOptions(). For each option that is specified on the
1469command line, the option value will be stored in the hash with the
1470option name as key. Options that are not actually used on the command
1471line will not be put in the hash, on other words,
1472C<exists($h{option})> (or defined()) can be used to test if an option
1473was used. The drawback is that warnings will be issued if the program
1474runs under C<use strict> and uses C<$h{option}> without testing with
1475exists() or defined() first.
381319f7 1476
0b7031a2
GS
1477 my %h = ();
1478 GetOptions (\%h, 'length=i'); # will store in $h{length}
f06db76b 1479
0b7031a2
GS
1480For options that take list or hash values, it is necessary to indicate
1481this by appending an C<@> or C<%> sign after the type:
f06db76b 1482
0b7031a2 1483 GetOptions (\%h, 'colours=s@'); # will push to @{$h{colours}}
f06db76b 1484
0b7031a2
GS
1485To make things more complicated, the hash may contain references to
1486the actual destinations, for example:
f06db76b 1487
0b7031a2
GS
1488 my $len = 0;
1489 my %h = ('length' => \$len);
1490 GetOptions (\%h, 'length=i'); # will store in $len
f06db76b 1491
0b7031a2 1492This example is fully equivalent with:
a11f5414 1493
0b7031a2
GS
1494 my $len = 0;
1495 GetOptions ('length=i' => \$len); # will store in $len
f06db76b 1496
0b7031a2
GS
1497Any mixture is possible. For example, the most frequently used options
1498could be stored in variables while all other options get stored in the
1499hash:
f06db76b 1500
0b7031a2
GS
1501 my $verbose = 0; # frequently referred
1502 my $debug = 0; # frequently referred
1503 my %h = ('verbose' => \$verbose, 'debug' => \$debug);
1504 GetOptions (\%h, 'verbose', 'debug', 'filter', 'size=i');
1505 if ( $verbose ) { ... }
1506 if ( exists $h{filter} ) { ... option 'filter' was specified ... }
f06db76b 1507
0b7031a2 1508=head2 Bundling
f06db76b 1509
0b7031a2
GS
1510With bundling it is possible to set several single-character options
1511at once. For example if C<a>, C<v> and C<x> are all valid options,
bb40d378 1512
0b7031a2 1513 -vax
bb40d378 1514
0b7031a2 1515would set all three.
f06db76b 1516
0b7031a2
GS
1517Getopt::Long supports two levels of bundling. To enable bundling, a
1518call to Getopt::Long::Configure is required.
bb40d378 1519
0b7031a2 1520The first level of bundling can be enabled with:
f06db76b 1521
0b7031a2 1522 Getopt::Long::Configure ("bundling");
404cbe93 1523
0b7031a2
GS
1524Configured this way, single-character options can be bundled but long
1525options B<must> always start with a double dash C<--> to avoid
1526abiguity. For example, when C<vax>, C<a>, C<v> and C<x> are all valid
1527options,
404cbe93 1528
0b7031a2 1529 -vax
381319f7 1530
10e5c9cc 1531would set C<a>, C<v> and C<x>, but
404cbe93 1532
0b7031a2 1533 --vax
404cbe93 1534
0b7031a2 1535would set C<vax>.
a11f5414 1536
0b7031a2
GS
1537The second level of bundling lifts this restriction. It can be enabled
1538with:
a11f5414 1539
0b7031a2 1540 Getopt::Long::Configure ("bundling_override");
a11f5414 1541
0b7031a2 1542Now, C<-vax> would set the option C<vax>.
a11f5414 1543
0b7031a2
GS
1544When any level of bundling is enabled, option values may be inserted
1545in the bundle. For example:
381319f7 1546
0b7031a2 1547 -h24w80
f06db76b 1548
0b7031a2 1549is equivalent to
f06db76b 1550
0b7031a2 1551 -h 24 -w 80
f06db76b 1552
0b7031a2
GS
1553When configured for bundling, single-character options are matched
1554case sensitive while long options are matched case insensitive. To
1555have the single-character options matched case insensitive as well,
1556use:
a0d0e21e 1557
0b7031a2 1558 Getopt::Long::Configure ("bundling", "ignorecase_always");
a0d0e21e 1559
0b7031a2 1560It goes without saying that bundling can be quite confusing.
404cbe93 1561
0b7031a2 1562=head2 The lonesome dash
404cbe93 1563
ea071ac9
JH
1564Normally, a lone dash C<-> on the command line will not be considered
1565an option. Option processing will terminate (unless "permute" is
1566configured) and the dash will be left in C<@ARGV>.
1567
1568It is possible to get special treatment for a lone dash. This can be
1569achieved by adding an option specification with an empty name, for
1570example:
a0d0e21e 1571
0b7031a2 1572 GetOptions ('' => \$stdio);
a11f5414 1573
ea071ac9
JH
1574A lone dash on the command line will now be a legal option, and using
1575it will set variable C<$stdio>.
a0d0e21e 1576
0b7031a2 1577=head2 Argument call-back
a0d0e21e 1578
0b7031a2
GS
1579A special option 'name' C<<>> can be used to designate a subroutine
1580to handle non-option arguments. When GetOptions() encounters an
1581argument that does not look like an option, it will immediately call this
1582subroutine and passes it the argument as a parameter.
a0d0e21e 1583
0b7031a2 1584For example:
a0d0e21e 1585
0b7031a2
GS
1586 my $width = 80;
1587 sub process { ... }
1588 GetOptions ('width=i' => \$width, '<>' => \&process);
a0d0e21e 1589
0b7031a2 1590When applied to the following command line:
a11f5414 1591
0b7031a2 1592 arg1 --width=72 arg2 --width=60 arg3
404cbe93 1593
10e5c9cc
JH
1594This will call
1595C<process("arg1")> while C<$width> is C<80>,
0b7031a2
GS
1596C<process("arg2")> while C<$width> is C<72>, and
1597C<process("arg3")> while C<$width> is C<60>.
381319f7 1598
0b7031a2
GS
1599This feature requires configuration option B<permute>, see section
1600L<Configuring Getopt::Long>.
a0d0e21e 1601
a0d0e21e 1602
0b7031a2
GS
1603=head1 Configuring Getopt::Long
1604
1605Getopt::Long can be configured by calling subroutine
1606Getopt::Long::Configure(). This subroutine takes a list of quoted
10e5c9cc
JH
1607strings, each specifying a configuration option to be enabled, e.g.
1608C<ignore_case>, or disabled, e.g. C<no_ignore_case>. Case does not
0b7031a2 1609matter. Multiple calls to Configure() are possible.
404cbe93 1610
10e5c9cc
JH
1611Alternatively, as of version 2.24, the configuration options may be
1612passed together with the C<use> statement:
1613
1614 use Getopt::Long qw(:config no_ignore_case bundling);
1615
bb40d378 1616The following options are available:
404cbe93 1617
bb40d378 1618=over 12
a0d0e21e 1619
bb40d378 1620=item default
a0d0e21e 1621
bb40d378
JV
1622This option causes all configuration options to be reset to their
1623default values.
404cbe93 1624
10e5c9cc
JH
1625=item posix_default
1626
1627This option causes all configuration options to be reset to their
1628default values as if the environment variable POSIXLY_CORRECT had
1629been set.
1630
bb40d378 1631=item auto_abbrev
404cbe93 1632
bb40d378 1633Allow option names to be abbreviated to uniqueness.
10e5c9cc
JH
1634Default is enabled unless environment variable
1635POSIXLY_CORRECT has been set, in which case C<auto_abbrev> is disabled.
404cbe93 1636
0b7031a2 1637=item getopt_compat
a0d0e21e 1638
0b7031a2 1639Allow C<+> to start options.
10e5c9cc
JH
1640Default is enabled unless environment variable
1641POSIXLY_CORRECT has been set, in which case C<getopt_compat> is disabled.
88e49c4e 1642
8ed53c8c
JH
1643=item gnu_compat
1644
1645C<gnu_compat> controls whether C<--opt=> is allowed, and what it should
1646do. Without C<gnu_compat>, C<--opt=> gives an error. With C<gnu_compat>,
1647C<--opt=> will give option C<opt> and empty value.
1648This is the way GNU getopt_long() does it.
1649
1650=item gnu_getopt
1651
1652This is a short way of setting C<gnu_compat> C<bundling> C<permute>
1653C<no_getopt_compat>. With C<gnu_getopt>, command line handling should be
1654fully compatible with GNU getopt_long().
1655
bb40d378 1656=item require_order
404cbe93 1657
0b7031a2 1658Whether command line arguments are allowed to be mixed with options.
10e5c9cc
JH
1659Default is disabled unless environment variable
1660POSIXLY_CORRECT has been set, in which case C<require_order> is enabled.
404cbe93 1661
0b7031a2 1662See also C<permute>, which is the opposite of C<require_order>.
a0d0e21e 1663
bb40d378 1664=item permute
404cbe93 1665
0b7031a2 1666Whether command line arguments are allowed to be mixed with options.
10e5c9cc
JH
1667Default is enabled unless environment variable
1668POSIXLY_CORRECT has been set, in which case C<permute> is disabled.
0b7031a2 1669Note that C<permute> is the opposite of C<require_order>.
a0d0e21e 1670
10e5c9cc 1671If C<permute> is enabled, this means that
a0d0e21e 1672
0b7031a2 1673 --foo arg1 --bar arg2 arg3
a0d0e21e 1674
bb40d378 1675is equivalent to
a0d0e21e 1676
0b7031a2 1677 --foo --bar arg1 arg2 arg3
a0d0e21e 1678
0b7031a2
GS
1679If an argument call-back routine is specified, C<@ARGV> will always be
1680empty upon succesful return of GetOptions() since all options have been
1681processed. The only exception is when C<--> is used:
a0d0e21e 1682
0b7031a2 1683 --foo arg1 --bar arg2 -- arg3
404cbe93 1684
bb40d378 1685will call the call-back routine for arg1 and arg2, and terminate
0b7031a2 1686GetOptions() leaving C<"arg2"> in C<@ARGV>.
381319f7 1687
10e5c9cc 1688If C<require_order> is enabled, options processing
bb40d378 1689terminates when the first non-option is encountered.
a0d0e21e 1690
0b7031a2 1691 --foo arg1 --bar arg2 arg3
381319f7 1692
bb40d378 1693is equivalent to
381319f7 1694
0b7031a2 1695 --foo -- arg1 --bar arg2 arg3
404cbe93 1696
ac634a9a
JH
1697If C<pass_through> is also enabled, options processing will terminate
1698at the first unrecognized option, or non-option, whichever comes
1699first.
1700
10e5c9cc 1701=item bundling (default: disabled)
404cbe93 1702
10e5c9cc 1703Enabling this option will allow single-character options to be bundled.
0b7031a2
GS
1704To distinguish bundles from long option names, long options I<must> be
1705introduced with C<--> and single-character options (and bundles) with
1706C<->.
bb40d378 1707
10e5c9cc 1708Note: disabling C<bundling> also disables C<bundling_override>.
a11f5414 1709
10e5c9cc 1710=item bundling_override (default: disabled)
381319f7 1711
10e5c9cc
JH
1712If C<bundling_override> is enabled, bundling is enabled as with
1713C<bundling> but now long option names override option bundles.
381319f7 1714
10e5c9cc 1715Note: disabling C<bundling_override> also disables C<bundling>.
381319f7 1716
bb40d378
JV
1717B<Note:> Using option bundling can easily lead to unexpected results,
1718especially when mixing long options and bundles. Caveat emptor.
381319f7 1719
10e5c9cc 1720=item ignore_case (default: enabled)
381319f7 1721
10e5c9cc 1722If enabled, case is ignored when matching long option names. Single
0b7031a2 1723character options will be treated case-sensitive.
381319f7 1724
10e5c9cc 1725Note: disabling C<ignore_case> also disables C<ignore_case_always>.
381319f7 1726
10e5c9cc 1727=item ignore_case_always (default: disabled)
a11f5414 1728
bb40d378 1729When bundling is in effect, case is ignored on single-character
10e5c9cc 1730options also.
381319f7 1731
10e5c9cc 1732Note: disabling C<ignore_case_always> also disables C<ignore_case>.
381319f7 1733
10e5c9cc 1734=item pass_through (default: disabled)
a0d0e21e 1735
0b7031a2
GS
1736Options that are unknown, ambiguous or supplied with an invalid option
1737value are passed through in C<@ARGV> instead of being flagged as
1738errors. This makes it possible to write wrapper scripts that process
1739only part of the user supplied command line arguments, and pass the
bb40d378 1740remaining options to some other program.
a0d0e21e 1741
ac634a9a
JH
1742If C<require_order> is enabled, options processing will terminate at
1743the first unrecognized option, or non-option, whichever comes first.
1744However, if C<permute> is enabled instead, results can become confusing.
16c18a90 1745
3a0431da
JV
1746=item prefix
1747
0b7031a2
GS
1748The string that starts options. If a constant string is not
1749sufficient, see C<prefix_pattern>.
3a0431da
JV
1750
1751=item prefix_pattern
1752
1753A Perl pattern that identifies the strings that introduce options.
1754Default is C<(--|-|\+)> unless environment variable
1755POSIXLY_CORRECT has been set, in which case it is C<(--|-)>.
1756
10e5c9cc 1757=item debug (default: disabled)
a0d0e21e 1758
10e5c9cc 1759Enable debugging output.
a0d0e21e 1760
bb40d378 1761=back
a0d0e21e 1762
0b7031a2 1763=head1 Return values and Errors
381319f7 1764
0b7031a2
GS
1765Configuration errors and errors in the option definitions are
1766signalled using die() and will terminate the calling program unless
1767the call to Getopt::Long::GetOptions() was embedded in C<eval { ...
1768}>, or die() was trapped using C<$SIG{__DIE__}>.
a0d0e21e 1769
10e5c9cc
JH
1770GetOptions returns true to indicate success.
1771It returns false when the function detected one or more errors during
1772option parsing. These errors are signalled using warn() and can be
1773trapped with C<$SIG{__WARN__}>.
a0d0e21e 1774
0b7031a2 1775Errors that can't happen are signalled using Carp::croak().
a0d0e21e 1776
0b7031a2 1777=head1 Legacy
a0d0e21e 1778
0b7031a2
GS
1779The earliest development of C<newgetopt.pl> started in 1990, with Perl
1780version 4. As a result, its development, and the development of
1781Getopt::Long, has gone through several stages. Since backward
1782compatibility has always been extremely important, the current version
1783of Getopt::Long still supports a lot of constructs that nowadays are
1784no longer necessary or otherwise unwanted. This section describes
1785briefly some of these 'features'.
a0d0e21e 1786
0b7031a2 1787=head2 Default destinations
a0d0e21e 1788
0b7031a2
GS
1789When no destination is specified for an option, GetOptions will store
1790the resultant value in a global variable named C<opt_>I<XXX>, where
1791I<XXX> is the primary name of this option. When a progam executes
1792under C<use strict> (recommended), these variables must be
1793pre-declared with our() or C<use vars>.
1794
1795 our $opt_length = 0;
1796 GetOptions ('length=i'); # will store in $opt_length
1797
1798To yield a usable Perl variable, characters that are not part of the
1799syntax for variables are translated to underscores. For example,
1800C<--fpp-struct-return> will set the variable
1801C<$opt_fpp_struct_return>. Note that this variable resides in the
1802namespace of the calling program, not necessarily C<main>. For
1803example:
1804
1805 GetOptions ("size=i", "sizes=i@");
1806
1807with command line "-size 10 -sizes 24 -sizes 48" will perform the
1808equivalent of the assignments
1809
1810 $opt_size = 10;
1811 @opt_sizes = (24, 48);
1812
1813=head2 Alternative option starters
1814
1815A string of alternative option starter characters may be passed as the
1816first argument (or the first argument after a leading hash reference
1817argument).
1818
1819 my $len = 0;
1820 GetOptions ('/', 'length=i' => $len);
1821
1822Now the command line may look like:
1823
1824 /length 24 -- arg
1825
1826Note that to terminate options processing still requires a double dash
1827C<-->.
1828
10e5c9cc
JH
1829GetOptions() will not interpret a leading C<< "<>" >> as option starters
1830if the next argument is a reference. To force C<< "<" >> and C<< ">" >> as
1831option starters, use C<< "><" >>. Confusing? Well, B<using a starter
0b7031a2
GS
1832argument is strongly deprecated> anyway.
1833
1834=head2 Configuration variables
1835
1836Previous versions of Getopt::Long used variables for the purpose of
10e5c9cc
JH
1837configuring. Although manipulating these variables still work, it is
1838strongly encouraged to use the C<Configure> routine that was introduced
1839in version 2.17. Besides, it is much easier.
1840
1841=head1 Trouble Shooting
1842
1843=head2 Warning: Ignoring '!' modifier for short option
1844
1845This warning is issued when the '!' modifier is applied to a short
1846(one-character) option and bundling is in effect. E.g.,
1847
1848 Getopt::Long::Configure("bundling");
1849 GetOptions("foo|f!" => \$foo);
1850
1851Note that older Getopt::Long versions did not issue a warning, because
1852the '!' modifier was applied to the first name only. This bug was
1853fixed in 2.22.
1854
1855Solution: separate the long and short names and apply the '!' to the
1856long names only, e.g.,
1857
1858 GetOptions("foo!" => \$foo, "f" => \$foo);
1859
1860=head2 GetOptions does not return a false result when an option is not supplied
1861
1862That's why they're called 'options'.
a0d0e21e 1863
bb40d378 1864=head1 AUTHOR
a11f5414 1865
10e5c9cc 1866Johan Vromans <jvromans@squirrel.nl>
a11f5414 1867
bb40d378 1868=head1 COPYRIGHT AND DISCLAIMER
a11f5414 1869
0b7031a2 1870This program is Copyright 2000,1990 by Johan Vromans.
bb40d378 1871This program is free software; you can redistribute it and/or
1a505819
GS
1872modify it under the terms of the Perl Artistic License or the
1873GNU General Public License as published by the Free Software
1874Foundation; either version 2 of the License, or (at your option) any
1875later version.
a11f5414 1876
bb40d378
JV
1877This program is distributed in the hope that it will be useful,
1878but WITHOUT ANY WARRANTY; without even the implied warranty of
1879MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1880GNU General Public License for more details.
a0d0e21e 1881
bb40d378 1882If you do not have a copy of the GNU General Public License write to
10e5c9cc 1883the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,
f9a400e4 1884MA 02139, USA.
a0d0e21e 1885
bb40d378 1886=cut
0b7031a2
GS
1887
1888# Local Variables:
0b7031a2
GS
1889# eval: (load-file "pod.el")
1890# End: