Getopt-Long v2.21 update (from Johan Vromans)

p4raw-id: //depot/perl@5557

1 files changed, 695 insertions, 358 deletions

diff --git a/lib/Getopt/Long.pm b/lib/Getopt/Long.pm
index 06fb1963ea..4e9ef8b6a0 100644
--- a/lib/Getopt/Long.pm
+++ b/lib/Getopt/Long.pm
@@ -2,17 +2,17 @@
 
 package Getopt::Long;
 
-# RCS Status      : $Id: GetoptLong.pl,v 2.21 1999-08-04 10:33:07+02 jv Exp $
+# RCS Status      : $Id: GetoptLong.pl,v 2.22 2000-03-05 21:08:03+01 jv Exp $
 # Author          : Johan Vromans
 # Created On      : Tue Sep 11 15:00:12 1990
 # Last Modified By: Johan Vromans
-# Last Modified On: Wed Aug  4 10:08:50 1999
-# Update Count    : 709
+# Last Modified On: Sun Mar  5 21:08:55 2000
+# Update Count    : 720
 # Status          : Released
 
 ################ Copyright ################
 
-# This program is Copyright 1990,1999 by Johan Vromans.
+# This program is Copyright 1990,2000 by Johan Vromans.
 # This program is free software; you can redistribute it and/or
 # modify it under the terms of the Perl Artistic License or the
 # GNU General Public License as published by the Free Software
@@ -23,9 +23,9 @@ package Getopt::Long;
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
-# 
+#
 # If you do not have a copy of the GNU General Public License write to
-# the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, 
+# the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,
 # MA 02139, USA.
 
 ################ Module Preamble ################
@@ -36,7 +36,7 @@ BEGIN {
     require 5.004;
     use Exporter ();
     use vars     qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
-    $VERSION     = "2.20";
+    $VERSION     = "2.21";
 
     @ISA         = qw(Exporter);
     @EXPORT      = qw(&GetOptions $REQUIRE_ORDER $PERMUTE $RETURN_IN_ORDER);
@@ -52,14 +52,14 @@ use vars qw($error $debug $major_version $minor_version);
 use vars qw($autoabbrev $getopt_compat $ignorecase $bundling $order
 	    $passthrough);
 # Official invisible variables.
-use vars qw($genprefix);
+use vars qw($genprefix $caller);
 
-# Public subroutines. 
+# Public subroutines.
 sub Configure (@);
 sub config (@);			# deprecated name
 sub GetOptions;
 
-# Private subroutines. 
+# Private subroutines.
 sub ConfigDefaults ();
 sub FindOption ($$$$$$$);
 sub Croak (@);			# demand loading the real Croak
@@ -98,8 +98,76 @@ sub ConfigDefaults () {
 # Version major/minor numbers.
 ($major_version, $minor_version) = $VERSION =~ /^(\d+)\.(\d+)/;
 
-# Set defaults.
-ConfigDefaults ();
+ConfigDefaults();
+
+################ Object Oriented routines ################
+
+=experimental
+
+# NOTE: The object oriented routines use $error for thread locking.
+eval "sub lock{}" if $] < 5.005;
+
+# Store a copy of the default configuration. Since ConfigDefaults has
+# just been called, what we get from Configure is the default.
+my $default_config = do { lock ($error); Configure () };
+
+sub new {
+    my $that = shift;
+    my $class = ref($that) || $that;
+
+    # Register the callers package.
+    my $self = { caller => (caller)[0] };
+
+    bless ($self, $class);
+
+    # Process construct time configuration.
+    if ( @_ > 0 ) {
+	lock ($error);
+	my $save = Configure ($default_config, @_);
+	$self->{settings} = Configure ($save);
+    }
+    # Else use default config.
+    else {
+	$self->{settings} = $default_config;
+    }
+
+    $self;
+}
+
+sub configure {
+    my ($self) = shift;
+
+    lock ($error);
+
+    # Restore settings, merge new settings in.
+    my $save = Configure ($self->{settings}, @_);
+
+    # Restore orig config and save the new config.
+    $self->{settings} = Configure ($save);
+}
+
+sub getoptions {
+    my ($self) = shift;
+
+    lock ($error);
+
+    # Restore config settings.
+    my $save = Configure ($self->{settings});
+
+    # Call main routine.
+    my $ret = 0;
+    $caller = $self->{caller};
+    eval { $ret = GetOptions (@_); };
+
+    # Restore saved settings.
+    Configure ($save);
+
+    # Handle errors and return value.
+    die ($@) if $@;
+    return $ret;
+}
+
+=cut
 
 ################ Package return ################
 
@@ -109,12 +177,12 @@ __END__
 
 ################ AutoLoading subroutines ################
 
-# RCS Status      : $Id: GetoptLongAl.pl,v 2.22 1999-07-07 12:57:05+02 jv Exp $
+# RCS Status      : $Id: GetoptLongAl.pl,v 2.25 2000-03-05 21:08:03+01 jv Exp $
 # Author          : Johan Vromans
 # Created On      : Fri Mar 27 11:50:30 1998
 # Last Modified By: Johan Vromans
-# Last Modified On: Wed Jul  7 12:47:57 1999
-# Update Count    : 28
+# Last Modified On: Sat Mar  4 16:33:02 2000
+# Update Count    : 49
 # Status          : Released
 
 sub GetOptions {
@@ -123,7 +191,7 @@ sub GetOptions {
     my $argend = '--';		# option list terminator
     my %opctl = ();		# table of arg.specs (long and abbrevs)
     my %bopctl = ();		# table of arg.specs (bundles)
-    my $pkg = (caller)[0];	# current context
+    my $pkg = $caller || (caller)[0];	# current context
 				# Needed if linkage is omitted.
     my %aliases= ();		# alias table
     my @ret = ();		# accum for non-options
@@ -138,7 +206,7 @@ sub GetOptions {
     print STDERR ("GetOpt::Long $Getopt::Long::VERSION ",
 		  "called from package \"$pkg\".",
 		  "\n  ",
-		  'GetOptionsAl $Revision: 2.22 $ ',
+		  'GetOptionsAl $Revision: 2.25 $ ',
 		  "\n  ",
 		  "ARGV: (@ARGV)",
 		  "\n  ",
@@ -153,9 +221,9 @@ sub GetOptions {
 		  "\n")
 	if $debug;
 
-    # Check for ref HASH as first argument. 
+    # Check for ref HASH as first argument.
     # First argument may be an object. It's OK to use this as long
-    # as it is really a hash underneath. 
+    # as it is really a hash underneath.
     $userlinkage = undef;
     if ( ref($optionlist[0]) and
 	 "$optionlist[0]" =~ /^(?:.*\=)?HASH\([^\(]*\)$/ ) {
@@ -192,7 +260,7 @@ sub GetOptions {
 		&& ref($userlinkage->{$opt}) ) {
 		unshift (@optionlist, $userlinkage->{$opt});
 	    }
-	    unless ( @optionlist > 0 
+	    unless ( @optionlist > 0
 		    && ref($optionlist[0]) && ref($optionlist[0]) eq 'CODE' ) {
 		$error .= "Option spec <> requires a reference to a subroutine\n";
 		next;
@@ -220,7 +288,7 @@ sub GetOptions {
 	    # Force an alias if the option name is not locase.
 	    $a = $o unless $o eq lc($o);
 	    $o = lc ($o)
-		if $ignorecase > 1 
+		if $ignorecase > 1
 		    || ($ignorecase
 			&& ($bundling ? length($o) > 1  : 1));
 
@@ -283,7 +351,7 @@ sub GetOptions {
 		$opctl{$o} .= '@'
 		  if $opctl{$o} ne '' and $opctl{$o} !~ /\@$/;
 		$bopctl{$o} .= '@'
-		  if $bundling and defined $bopctl{$o} and 
+		  if $bundling and defined $bopctl{$o} and
 		    $bopctl{$o} ne '' and $bopctl{$o} !~ /\@$/;
 	    }
 	    elsif ( ref($optionlist[0]) =~ /^(HASH)$/ ) {
@@ -291,7 +359,7 @@ sub GetOptions {
 		$opctl{$o} .= '%'
 		  if $opctl{$o} ne '' and $opctl{$o} !~ /\%$/;
 		$bopctl{$o} .= '%'
-		  if $bundling and defined $bopctl{$o} and 
+		  if $bundling and defined $bopctl{$o} and
 		    $bopctl{$o} ne '' and $bopctl{$o} !~ /\%$/;
 	    }
 	    else {
@@ -344,7 +412,8 @@ sub GetOptions {
     }
 
     # Process argument list
-    while ( @ARGV > 0 ) {
+    my $goon = 1;
+    while ( $goon && @ARGV > 0 ) {
 
 	#### Get next argument ####
 
@@ -356,7 +425,7 @@ sub GetOptions {
 	# Double dash is option list terminator.
 	if ( $opt eq $argend ) {
 	    # Finish. Push back accumulated arguments and return.
-	    unshift (@ARGV, @ret) 
+	    unshift (@ARGV, @ret)
 		if $order == $PERMUTE;
 	    return ($error == 0);
 	}
@@ -364,16 +433,16 @@ sub GetOptions {
 	my $tryopt = $opt;
 	my $found;		# success status
 	my $dsttype;		# destination type ('@' or '%')
-	my $incr;		# destination increment 
+	my $incr;		# destination increment
 	my $key;		# key (if hash type)
 	my $arg;		# option argument
 
-	($found, $opt, $arg, $dsttype, $incr, $key) = 
-	  FindOption ($genprefix, $argend, $opt, 
+	($found, $opt, $arg, $dsttype, $incr, $key) =
+	  FindOption ($genprefix, $argend, $opt,
 		      \%opctl, \%bopctl, \@opctl, \%aliases);
 
 	if ( $found ) {
-	    
+
 	    # FindOption undefines $opt in case of errors.
 	    next unless defined $opt;
 
@@ -414,7 +483,18 @@ sub GetOptions {
 		    elsif ( ref($linkage{$opt}) eq 'CODE' ) {
 			print STDERR ("=> &L{$opt}(\"$opt\", \"$arg\")\n")
 			    if $debug;
-			&{$linkage{$opt}}($opt, $arg);
+			local ($@);
+			eval {
+			    &{$linkage{$opt}}($opt, $arg);
+			};
+			print STDERR ("=> die($@)\n") if $debug && $@ ne '';
+			if ( $@ =~ /^FINISH\b/ ) {
+			    $goon = 0;
+			}
+			elsif ( $@ ne '' ) {
+			    warn ($@);
+			    $error++;
+			}
 		    }
 		    else {
 			print STDERR ("Invalid REF type \"", ref($linkage{$opt}),
@@ -471,7 +551,18 @@ sub GetOptions {
 	    # Try non-options call-back.
 	    my $cb;
 	    if ( (defined ($cb = $linkage{'<>'})) ) {
-		&$cb ($tryopt);
+		local ($@);
+		eval {
+		    &$cb ($tryopt);
+		};
+		print STDERR ("=> die($@)\n") if $debug && $@ ne '';
+		if ( $@ =~ /^FINISH\b/ ) {
+		    $goon = 0;
+		}
+		elsif ( $@ ne '' ) {
+		    warn ($@);
+		    $error++;
+		}
 	    }
 	    else {
 		print STDERR ("=> saving \"$tryopt\" ",
@@ -528,7 +619,7 @@ sub FindOption ($$$$$$$) {
 	&& $opt =~ /^([^=]+)=(.*)$/s ) {
 	$opt = $1;
 	$optarg = $2;
-	print STDERR ("=> option \"", $opt, 
+	print STDERR ("=> option \"", $opt,
 		      "\", optarg = \"$optarg\"\n") if $debug;
     }
 
@@ -559,7 +650,7 @@ sub FindOption ($$$$$$$) {
 	    $tryopt .= $rest;
 	    undef $rest;
 	}
-    } 
+    }
 
     # Try auto-abbreviation.
     elsif ( $autoabbrev ) {
@@ -645,7 +736,7 @@ sub FindOption ($$$$$$$) {
     ($mand, $type, $dsttype, $key) = $type =~ /^(.)(.)([@%]?)$/;
 
     # Check if there is an option argument available.
-    if ( defined $optarg ? ($optarg eq '') 
+    if ( defined $optarg ? ($optarg eq '')
 	 : !(defined $rest || @ARGV > 0) ) {
 	# Complain if this option needs an argument.
 	if ( $mand eq "=" ) {
@@ -667,17 +758,17 @@ sub FindOption ($$$$$$$) {
     # Get key if this is a "name=value" pair for a hash option.
     $key = undef;
     if ($dsttype eq '%' && defined $arg) {
-	($key, $arg) = ($arg =~ /^(.*)=(.*)$/s) ? ($1, $2) : ($arg, 1);
+	($key, $arg) = ($arg =~ /^([^=]*)=(.*)$/s) ? ($1, $2) : ($arg, 1);
     }
 
     #### Check if the argument is valid for this option ####
 
     if ( $type eq "s" ) {	# string
-	# A mandatory string takes anything. 
+	# A mandatory string takes anything.
 	return (1, $opt,$arg,$dsttype,$incr,$key) if $mand eq "=";
 
-	# An optional string takes almost anything. 
-	return (1, $opt,$arg,$dsttype,$incr,$key) 
+	# An optional string takes almost anything.
+	return (1, $opt,$arg,$dsttype,$incr,$key)
 	  if defined $optarg || defined $rest;
 	return (1, $opt,$arg,$dsttype,$incr,$key) if $arg eq "-"; # ??
 
@@ -692,12 +783,12 @@ sub FindOption ($$$$$$$) {
     }
 
     elsif ( $type eq "n" || $type eq "i" ) { # numeric/integer
-	if ( $bundling && defined $rest && $rest =~ /^(-?[0-9]+)(.*)$/s ) {
+	if ( $bundling && defined $rest && $rest =~ /^([-+]?[0-9]+)(.*)$/s ) {
 	    $arg = $1;
 	    $rest = $2;
 	    unshift (@ARGV, $starter.$rest) if defined $rest && $rest ne '';
 	}
-	elsif ( $arg !~ /^-?[0-9]+$/ ) {
+	elsif ( $arg !~ /^[-+]?[0-9]+$/ ) {
 	    if ( defined $optarg || $mand eq "=" ) {
 		if ( $passthrough ) {
 		    unshift (@ARGV, defined $rest ? $starter.$rest : $arg)
@@ -725,12 +816,12 @@ sub FindOption ($$$$$$$) {
 	# and at least one digit following the point and 'e'.
 	# [-]NN[.NN][eNN]
 	if ( $bundling && defined $rest &&
-	     $rest =~ /^(-?[0-9]+(\.[0-9]+)?([eE]-?[0-9]+)?)(.*)$/s ) {
+	     $rest =~ /^([-+]?[0-9]+(\.[0-9]+)?([eE][-+]?[0-9]+)?)(.*)$/s ) {
 	    $arg = $1;
 	    $rest = $+;
 	    unshift (@ARGV, $starter.$rest) if defined $rest && $rest ne '';
 	}
-	elsif ( $arg !~ /^-?[0-9.]+(\.[0-9]+)?([eE]-?[0-9]+)?$/ ) {
+	elsif ( $arg !~ /^[-+]?[0-9.]+(\.[0-9]+)?([eE][-+]?[0-9]+)?$/ ) {
 	    if ( defined $optarg || $mand eq "=" ) {
 		if ( $passthrough ) {
 		    unshift (@ARGV, defined $rest ? $starter.$rest : $arg)
@@ -761,6 +852,18 @@ sub FindOption ($$$$$$$) {
 # Getopt::Long Configuration.
 sub Configure (@) {
     my (@options) = @_;
+
+    my $prevconfig =
+      [ $error, $debug, $major_version, $minor_version,
+	$autoabbrev, $getopt_compat, $ignorecase, $bundling, $order,
+	$passthrough, $genprefix ];
+
+    if ( ref($options[0]) eq 'ARRAY' ) {
+	( $error, $debug, $major_version, $minor_version,
+	  $autoabbrev, $getopt_compat, $ignorecase, $bundling, $order,
+	  $passthrough, $genprefix ) = @{shift(@options)};
+    }
+
     my $opt;
     foreach $opt ( @options ) {
 	my $try = lc ($opt);
@@ -809,7 +912,7 @@ sub Configure (@) {
 	elsif ( $try =~ /^prefix_pattern=(.+)$/ ) {
 	    $genprefix = $1;
 	    # Parenthesize if needed.
-	    $genprefix = "(" . $genprefix . ")" 
+	    $genprefix = "(" . $genprefix . ")"
 	      unless $genprefix =~ /^\(.*\)$/;
 	    eval { '' =~ /$genprefix/; };
 	    Croak ("Getopt::Long: invalid pattern \"$genprefix\"") if $@;
@@ -821,6 +924,7 @@ sub Configure (@) {
 	    Croak ("Getopt::Long: unknown config parameter \"$opt\"")
 	}
     }
+    $prevconfig;
 }
 
 # Deprecated name.
@@ -839,7 +943,7 @@ sub Croak (@) {
 
 =head1 NAME
 
-GetOptions - extended processing of command line options
+Getopt::Long - Extended processing of command line options
 
 =head1 SYNOPSIS
 
@@ -854,353 +958,544 @@ line options, with GNU extensions. In general, this means that options
 have long names instead of single letters, and are introduced with a
 double dash "--". Support for bundling of command line options, as was
 the case with the more traditional single-letter approach, is provided
-but not enabled by default. For example, the UNIX "ps" command can be
-given the command line "option"
+but not enabled by default.
+
+=head1 Command Line Options, an Introduction
+
+Command line operated programs traditionally take their arguments from
+the command line, for example filenames or other information that the
+program needs to know. Besides arguments, these programs often take
+command line I<options> as well. Options are not necessary for the
+program to work, hence the name 'option', but are used to modify its
+default behaviour. For example, a program could do its job quietly,
+but with a suitable option it could provide verbose information about
+what it did.
+
+Command line options come in several flavours. Historically, they are
+preceded by a single dash C<->, and consist of a single letter.
+
+    -l -a -c
+
+Usually, these single-character options can be bundled:
+
+    -lac
+
+Options can have values, the value is placed after the option
+character. Sometimes with whitespace in between, sometimes not:
+
+    -s 24 -s24
+
+Due to the very cryptic nature of these options, another style was
+developed that used long names. So instead of a cryptic C<-l> one
+could use the more descriptive C<--long>. To distinguish between a
+bundle of single-character options and a long one, two dashes are used
+to precede the option name. Early implementations of long options used
+a plus C<+> instead. Also, option values could be specified either
+like 
+
+    --size=24
+
+or
+
+    --size 24
+
+The C<+> form is now obsolete and strongly deprecated.
+
+=head1 Getting Started with Getopt::Long
+
+Getopt::Long is the Perl5 successor of C<newgetopt.pl>. This was
+the firs Perl module that provided support for handling the new style
+of command line options, hence the name Getopt::Long. This module
+also supports single-character options and bundling. In this case, the
+options are restricted to alphabetic characters only, and the
+characters C<?> and C<->.
+
+To use Getopt::Long from a Perl program, you must include the
+following line in your Perl program:
+
+    use Getopt::Long;
+
+This will load the core of the Getopt::Long module and prepare your
+program for using it. Most of the actual Getopt::Long code is not
+loaded until you really call one of its functions.
+
+In the default configuration, options names may be abbreviated to
+uniqueness, case does not matter, and a single dash is sufficient,
+even for long option names. Also, options may be placed between
+non-option arguments. See L<Configuring Getopt::Long> for more
+details on how to configure Getopt::Long.
+
+=head2 Simple options
+
+The most simple options are the ones that take no values. Their mere
+presence on the command line enables the option. Popular examples are:
+
+    --all --verbose --quiet --debug
+
+Handling simple options is straightforward:
+
+    my $verbose = '';	# option variable with default value (false)
+    my $all = '';	# option variable with default value (false)
+    GetOptions ('verbose' => \$verbose, 'all' => \$all);
+
+The call to GetOptions() parses the command line arguments that are
+present in C<@ARGV> and sets the option variable to the value C<1> if
+the option did occur on the command line. Otherwise, the option
+variable is not touched. Setting the option value to true is often
+called I<enabling> the option.
+
+The option name as specified to the GetOptions() function is called
+the option I<specification>. Later we'll see that this specification
+can contain more than just the option name. The reference to the
+variable is called the option I<destination>.
+
+GetOptions() will return a true value if the command line could be
+processed successfully. Otherwise, it will write error messages to
+STDERR, and return a false result.
+
+=head2 A little bit less simple options
+
+Getopt::Long supports two useful variants of simple options:
+I<negatable> options and I<incremental> options.
+
+A negatable option is specified with a exclamation mark C<!> after the
+option name:
+
+    my $verbose = '';	# option variable with default value (false)
+    GetOptions ('verbose!' => \$verbose);
+
+Now, using C<--verbose> on the command line will enable C<$verbose>,
+as expected. But it is also allowed to use C<--noverbose>, which will
+disable C<$verbose> by setting its value to C<0>. Using a suitable
+default value, the program can find out whether C<$verbose> is false
+by default, or disabled by using C<--noverbose>.
+
+An incremental option is specified with a plus C<+> after the
+option name:
+
+    my $verbose = '';	# option variable with default value (false)
+    GetOptions ('verbose+' => \$verbose);
+
+Using C<--verbose> on the command line will increment the value of
+C<$verbose>. This way the program can keep track of how many times the
+option occurred on the command line. For example, each occurrence of
+C<--verbose> could increase the verbosity level of the program.
+
+=head2 Mixing command line option with other arguments
+
+Usually programs take command line options as well as other arguments,
+for example, file names. It is good practice to always specify the
+options first, and the other arguments last. Getopt::Long will,
+however, allow the options and arguments to be mixed and 'filter out'
+all the options before passing the rest of the arguments to the
+program. To stop Getopt::Long from processing further arguments,
+insert a double dash C<--> on the command line:
+
+    --size 24 -- --all
+
+In this example, C<--all> will I<not> be treated as an option, but
+passed to the program unharmed, in C<@ARGV>.
+
+=head2 Options with values
+
+For options that take values it must be specified whether the option
+value is required or not, and what kind of value the option expects.
+
+Three kinds of values are supported: integer numbers, floating point
+numbers, and strings.
+
+If the option value is required, Getopt::Long will take the
+command line argument that follows the option and assign this to the
+option variable. If, however, the option value is specified as
+optional, this will only be done if that value does not look like a
+valid command line option itself.
 
-  -vax
+    my $tag = '';	# option variable with default value
+    GetOptions ('tag=s' => \$tag);
 
-which means the combination of B<-v>, B<-a> and B<-x>. With the new
-syntax B<--vax> would be a single option, probably indicating a
-computer architecture. 
+In the option specification, the option name is followed by an equals
+sign C<=> and the letter C<s>. The equals sign indicates that this
+option requires a value. The letter C<s> indicates that this value is
+an arbitrary string. Other possible value types are C<i> for integer
+values, and C<f> for floating point values. Using a colon C<:> instead
+of the equals sign indicates that the option value is optional. In
+this case, if no suitable value is supplied, string valued options get
+an empty string C<''> assigned, while numeric options are set to C<0>.
 
-Command line options can be used to set values. These values can be
-specified in one of two ways:
+=head2 Options with multiple values
 
-  --size 24
-  --size=24
+Options sometimes take several values. For example, a program could
+use multiple directories to search for library files:
 
-GetOptions is called with a list of option-descriptions, each of which
-consists of two elements: the option specifier and the option linkage.
-The option specifier defines the name of the option and, optionally,
-the value it can take. The option linkage is usually a reference to a
-variable that will be set when the option is used. For example, the
-following call to GetOptions:
+    --library lib/stdlib --library lib/extlib
 
-  GetOptions("size=i" => \$offset);
+To accomplish this behaviour, simply specify an array reference as the
+destination for the option:
 
-will accept a command line option "size" that must have an integer
-value. With a command line of "--size 24" this will cause the variable
-$offset to get the value 24.
+    my @libfiles = ();
+    GetOptions ("library=s" => \@libfiles);
 
-Alternatively, the first argument to GetOptions may be a reference to
-a HASH describing the linkage for the options, or an object whose
-class is based on a HASH. The following call is equivalent to the
-example above:
+Used with the example above, C<@libfiles> would contain two strings
+upon completion: C<"lib/srdlib"> and C<"lib/extlib">, in that order.
+It is also possible to specify that only integer or floating point
+numbers are acceptible values.
 
-  %optctl = ("size" => \$offset);
-  GetOptions(\%optctl, "size=i");
+Often it is useful to allow comma-separated lists of values as well as
+multiple occurrences of the options. This is easy using Perl's split()
+and join() operators:
 
-Linkage may be specified using either of the above methods, or both.
-Linkage specified in the argument list takes precedence over the
-linkage specified in the HASH.
+    my @libfiles = ();
+    GetOptions ("library=s" => \@libfiles);
+    @libfiles = split(/,/,join(',',@libfiles));
 
-The command line options are taken from array @ARGV. Upon completion
-of GetOptions, @ARGV will contain the rest (i.e. the non-options) of
-the command line.
+Of course, it is important to choose the right separator string for
+each purpose.
 
-Each option specifier designates the name of the option, optionally
-followed by an argument specifier.
+=head2 Options with hash values
 
-Options that do not take arguments will have no argument specifier. 
-The option variable will be set to 1 if the option is used.
+If the option destination is a reference to a hash, the option will
+take, as value, strings of the form I<key>C<=>I<value>. The value will
+be stored with the specified key in the hash.
 
-For the other options, the values for argument specifiers are:
+    my %defines = ();
+    GetOptions ("define=s" => \%defines);
 
-=over 8
+When used with command line options:
+
+    --define os=linux --define vendor=redhat
+
+the hash C<%defines> will contain two keys, C<"os"> with value
+C<"linux> and C<"vendor"> with value C<"redhat">.
+It is also possible to specify that only integer or floating point
+numbers are acceptible values. The keys are always taken to be strings.
+
+=head2 User-defined subroutines to handle options
+
+Ultimate control over what should be done when (actually: each time)
+an option is encountered on the command line can be achieved by
+designating a reference to a subroutine (or an anonymous subroutine)
+as the option destination. When GetOptions() encounters the option, it
+will call the subroutine with two arguments: the name of the option,
+and the value to be assigned. It is up to the subroutine to store the
+value, or do whatever it thinks is appropriate.
+
+A trivial application of this mechanism is to implement options that
+are related to each other. For example:
+
+    my $verbose = '';	# option variable with default value (false)
+    GetOptions ('verbose' => \$verbose,
+	        'quiet'   => sub { $verbose = 0 });
+
+Here C<--verbose> and C<--quiet> control the same variable
+C<$verbose>, but with opposite values.
+
+If the subroutine needs to signal an error, it should call die() with
+the desired error message as its argument. GetOptions() will catch the
+die(), issue the error message, and record that an error result must
+be returned upon completion.
+
+It is also possible for a user-defined subroutine to preliminary
+terminate options processing by calling die() with argument
+C<"FINISH">. GetOptions will react as if it encountered a double dash
+C<-->.
+
+=head2 Options with multiple names
+
+Often it is user friendly to supply alternate mnemonic names for
+options. For example C<--height> could be an alternate name for
+C<--length>. Alternate names can be included in the option
+specification, separated by vertical bar C<|> characters. To implement
+the above example:
+
+    GetOptions ('length|height=f' => \$length);
+
+The first name is called the I<primary> name, the other names are
+called I<aliases>.
+
+Multiple alternate names are possible.
+
+=head2 Case and abbreviations
+
+Without additional configuration, GetOptions() will ignore the case of
+option names, and allow the options to be abbreviated to uniqueness.
+
+    GetOptions ('length|height=f' => \$length, "head" => \$head);
+
+This call will allow C<--l> and C<--L> for the length option, but
+requires a least C<--hea> and C<--hei> for the head and height options.
+
+=head2 Summary of Option Specifications
+
+Each option specifier consists of two parts: the name specification
+and the argument specification. 
+
+The name specification contains the name of the option, optionally
+followed by a list of alternative names separated by vertical bar
+characters. 
+
+    length	      option name is "length"
+    length|size|l     name is "length", aliases are "size" and "l"
+
+The argument specification is optional. If omitted, the option is
+considered boolean, a value of 1 will be assigned when the option is
+used on the command line.
+
+The argument specification can be
+
+=over
 
 =item !
 
-Option does not take an argument and may be negated, i.e. prefixed by
-"no". E.g. "foo!" will allow B<--foo> (with value 1) and B<-nofoo>
-(with value 0).
-The option variable will be set to 1, or 0 if negated.
+The option does not take an argument and may be negated, i.e. prefixed
+by "no". E.g. C<"foo!"> will allow C<--foo> (a value of 1 will be
+assigned) and C<--nofoo> (a value of 0 will be assigned).
 
 =item +
 
-Option does not take an argument and will be incremented by 1 every
-time it appears on the command line. E.g. "more+", when used with
-B<--more --more --more>, will set the option variable to 3 (provided
-it was 0 or undefined at first).
+The option does not take an argument and will be incremented by 1
+every time it appears on the command line. E.g. C<"more+">, when used
+with C<--more --more --more>, will increment the value three times,
+resulting in a value of 3 (provided it was 0 or undefined at first).
 
-The B<+> specifier is ignored if the option destination is not a SCALAR.
+The C<+> specifier is ignored if the option destination is not a scalar.
 
-=item =s
+=item = I<type> [ I<desttype> ]
 
-Option takes a mandatory string argument.
-This string will be assigned to the option variable.
-Note that even if the string argument starts with B<-> or B<-->, it
-will not be considered an option on itself.
+The option requires an argument of the given type. Supported types
+are:
 
-=item :s
+=over
 
-Option takes an optional string argument.
-This string will be assigned to the option variable.
-If omitted, it will be assigned "" (an empty string).
-If the string argument starts with B<-> or B<-->, it
-will be considered an option on itself.
+=item s
 
-=item =i
+String. An arbitrary sequence of characters. It is valid for the
+argument to start with C<-> or C<-->.
 
-Option takes a mandatory integer argument.
-This value will be assigned to the option variable.
-Note that the value may start with B<-> to indicate a negative
-value. 
+=item i
 
-=item :i
+Integer. An optional leading plus or minus sign, followed by a
+sequence of digits.
 
-Option takes an optional integer argument.
-This value will be assigned to the option variable.
-If omitted, the value 0 will be assigned.
-Note that the value may start with B<-> to indicate a negative
-value.
+=item f
 
-=item =f
+Real number. For example C<3.14>, C<-6.23E24> and so on.
 
-Option takes a mandatory real number argument.
-This value will be assigned to the option variable.
-Note that the value may start with B<-> to indicate a negative
-value.
+=back
+
+The I<desttype> can be C<@> or C<%> to specify that the option is
+list or a hash valued. This is only needed when the destination for
+the option value is not otherwise specified. It should be omitted when
+not needed.
+
+=item : I<type> [ I<desttype> ]
 
-=item :f
+Like C<=>, but designates the argument as optional.
+If omitted, an empty string will be assigned to string values options,
+and the value zero to numeric options.
 
-Option takes an optional real number argument.
-This value will be assigned to the option variable.
-If omitted, the value 0 will be assigned.
+Note that if a string argument starts with C<-> or C<-->, it will be
+considered an option on itself.
 
 =back
 
-A lone dash B<-> is considered an option, the corresponding option
-name is the empty string.
+=head1 Advanced Possibilities
 
-A double dash on itself B<--> signals end of the options list.
+=head2 Documentation and help texts
 
-=head2 Linkage specification
+Getopt::Long encourages the use of Pod::Usage to produce help
+messages. For example:
 
-The linkage specifier is optional. If no linkage is explicitly
-specified but a ref HASH is passed, GetOptions will place the value in
-the HASH. For example:
+    use Getopt::Long;
+    use Pod::Usage;
 
-  %optctl = ();
-  GetOptions (\%optctl, "size=i");
+    my $man = 0;
+    my $help = 0;
 
-will perform the equivalent of the assignment
+    GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
+    pod2usage(1) if $help;
+    pod2usage(-exitstatus => 0, -verbose => 2) if $man;
 
-  $optctl{"size"} = 24;
+    __END__
 
-For array options, a reference to an array is used, e.g.:
+    =head1 NAME
 
-  %optctl = ();
-  GetOptions (\%optctl, "sizes=i@");
+    sample - Using GetOpt::Long and Pod::Usage
 
-with command line "-sizes 24 -sizes 48" will perform the equivalent of
-the assignment
+    =head1 SYNOPSIS
 
-  $optctl{"sizes"} = [24, 48];
+    sample [options] [file ...]
 
-For hash options (an option whose argument looks like "name=value"),
-a reference to a hash is used, e.g.:
+     Options:
+       -help            brief help message
+       -man             full documentation
 
-  %optctl = ();
-  GetOptions (\%optctl, "define=s%");
+    =head1 OPTIONS
 
-with command line "--define foo=hello --define bar=world" will perform the
-equivalent of the assignment
+    =over 8
 
-  $optctl{"define"} = {foo=>'hello', bar=>'world')
+    =item B<-help>
 
-If no linkage is explicitly specified and no ref HASH is passed,
-GetOptions will put the value in a global variable named after the
-option, prefixed by "opt_". To yield a usable Perl variable,
-characters that are not part of the syntax for variables are
-translated to underscores. For example, "--fpp-struct-return" will set
-the variable $opt_fpp_struct_return. Note that this variable resides
-in the namespace of the calling program, not necessarily B<main>.
-For example:
+    Print a brief help message and exits.
 
-  GetOptions ("size=i", "sizes=i@");
+    =item B<-man>
 
-with command line "-size 10 -sizes 24 -sizes 48" will perform the
-equivalent of the assignments
+    Prints the manual page and exits.
 
-  $opt_size = 10;
-  @opt_sizes = (24, 48);
+    =back
 
-A lone dash B<-> is considered an option, the corresponding Perl
-identifier is $opt_ .
+    =head1 DESCRIPTION
 
-The linkage specifier can be a reference to a scalar, a reference to
-an array, a reference to a hash or a reference to a subroutine.
+    B<This program> will read the given input file(s) and do someting
+    useful with the contents thereof.
 
-Note that, if your code is running under the recommended C<use strict
-'vars'> pragma, it may be helpful to declare these package variables
-via C<use vars> perhaps something like this:
+    =cut
 
-  use vars qw/ $opt_size @opt_sizes $opt_bar /;
+See L<Pod::Usage> for details.
 
-If a REF SCALAR is supplied, the new value is stored in the referenced
-variable. If the option occurs more than once, the previous value is
-overwritten. 
+=head2 Storing options in a hash
 
-If a REF ARRAY is supplied, the new value is appended (pushed) to the
-referenced array. 
+Sometimes, for example when there are a lot of options, having a
+separate variable for each of them can be cumbersome. GetOptions()
+supports, as an alternative mechanism, storing options in a hash.
 
-If a REF HASH is supplied, the option value should look like "key" or
-"key=value" (if the "=value" is omitted then a value of 1 is implied).
-In this case, the element of the referenced hash with the key "key"
-is assigned "value". 
+To obtain this, a reference to a hash must be passed I<as the first
+argument> to GetOptions(). For each option that is specified on the
+command line, the option value will be stored in the hash with the
+option name as key. Options that are not actually used on the command
+line will not be put in the hash, on other words,
+C<exists($h{option})> (or defined()) can be used to test if an option
+was used. The drawback is that warnings will be issued if the program
+runs under C<use strict> and uses C<$h{option}> without testing with
+exists() or defined() first.
 
-If a REF CODE is supplied, the referenced subroutine is called with
-two arguments: the option name and the option value.
-The option name is always the true name, not an abbreviation or alias.
+    my %h = ();
+    GetOptions (\%h, 'length=i');	# will store in $h{length}
 
-=head2 Aliases and abbreviations
+For options that take list or hash values, it is necessary to indicate
+this by appending an C<@> or C<%> sign after the type:
 
-The option name may actually be a list of option names, separated by
-"|"s, e.g. "foo|bar|blech=s". In this example, "foo" is the true name
-of this option. If no linkage is specified, options "foo", "bar" and
-"blech" all will set $opt_foo. For convenience, the single character
-"?" is allowed as an alias, e.g. "help|?".
+    GetOptions (\%h, 'colours=s@');	# will push to @{$h{colours}}
 
-Option names may be abbreviated to uniqueness, depending on
-configuration option B<auto_abbrev>.
+To make things more complicated, the hash may contain references to
+the actual destinations, for example:
 
-=head2 Non-option call-back routine
+    my $len = 0;
+    my %h = ('length' => \$len);
+    GetOptions (\%h, 'length=i');	# will store in $len
 
-A special option specifier, E<lt>E<gt>, can be used to designate a subroutine
-to handle non-option arguments. GetOptions will immediately call this
-subroutine for every non-option it encounters in the options list.
-This subroutine gets the name of the non-option passed.
-This feature requires configuration option B<permute>, see section
-CONFIGURATION OPTIONS.
+This example is fully equivalent with:
 
-See also the examples.
+    my $len = 0;
+    GetOptions ('length=i' => \$len);	# will store in $len
 
-=head2 Option starters
+Any mixture is possible. For example, the most frequently used options
+could be stored in variables while all other options get stored in the
+hash:
 
-On the command line, options can start with B<-> (traditional), B<-->
-(POSIX) and B<+> (GNU, now being phased out). The latter is not
-allowed if the environment variable B<POSIXLY_CORRECT> has been
-defined.
+    my $verbose = 0;			# frequently referred
+    my $debug = 0;			# frequently referred
+    my %h = ('verbose' => \$verbose, 'debug' => \$debug);
+    GetOptions (\%h, 'verbose', 'debug', 'filter', 'size=i');
+    if ( $verbose ) { ... }
+    if ( exists $h{filter} ) { ... option 'filter' was specified ... }
 
-Options that start with "--" may have an argument appended, separated
-with an "=", e.g. "--foo=bar".
+=head2 Bundling
 
-=head2 Return values and Errors
+With bundling it is possible to set several single-character options
+at once. For example if C<a>, C<v> and C<x> are all valid options,
 
-Configuration errors and errors in the option definitions are
-signalled using C<die()> and will terminate the calling
-program unless the call to C<Getopt::Long::GetOptions()> was embedded
-in C<eval { ... }> or C<die()> was trapped using C<$SIG{__DIE__}>.
+    -vax
 
-A return value of 1 (true) indicates success.
+would set all three.
 
-A return status of 0 (false) indicates that the function detected one
-or more errors during option parsing. These errors are signalled using
-C<warn()> and can be trapped with C<$SIG{__WARN__}>.
+Getopt::Long supports two levels of bundling. To enable bundling, a
+call to Getopt::Long::Configure is required.
 
-Errors that can't happen are signalled using C<Carp::croak()>.
+The first level of bundling can be enabled with:
 
-=head1 COMPATIBILITY
+    Getopt::Long::Configure ("bundling");
 
-Getopt::Long::GetOptions() is the successor of
-B<newgetopt.pl> that came with Perl 4. It is fully upward compatible.
-In fact, the Perl 5 version of newgetopt.pl is just a wrapper around
-the module.
+Configured this way, single-character options can be bundled but long
+options B<must> always start with a double dash C<--> to avoid
+abiguity. For example, when C<vax>, C<a>, C<v> and C<x> are all valid
+options,
 
-If an "@" sign is appended to the argument specifier, the option is
-treated as an array. Value(s) are not set, but pushed into array
-@opt_name. If explicit linkage is supplied, this must be a reference
-to an ARRAY.
+    -vax
 
-If an "%" sign is appended to the argument specifier, the option is
-treated as a hash. Value(s) of the form "name=value" are set by
-setting the element of the hash %opt_name with key "name" to "value"
-(if the "=value" portion is omitted it defaults to 1). If explicit
-linkage is supplied, this must be a reference to a HASH.
+would set C<a>, C<v> and C<x>, but 
 
-If configuration option B<getopt_compat> is set (see section
-CONFIGURATION OPTIONS), options that start with "+" or "-" may also
-include their arguments, e.g. "+foo=bar". This is for compatiblity
-with older implementations of the GNU "getopt" routine.
+    --vax
 
-If the first argument to GetOptions (after the optional linkage
-specification) is a string consisting of only non-alphanumeric
-characters, it is taken to specify the option starter characters.
-Everything starting with one of these characters from the starter will
-be considered an option. GetOptions will not interpret a leading
-"<>" as option starters if the next argument is a reference. To
-force "<" and ">" as option starters, use "><". Confusing? Well,
-B<using a starter argument is strongly deprecated.>
+would set C<vax>.
 
-For convenience, option specifiers may have a leading B<-> or B<-->,
-so it is possible to write:
+The second level of bundling lifts this restriction. It can be enabled
+with:
 
-   GetOptions qw(-foo=s --bar=i --ar=s);
+    Getopt::Long::Configure ("bundling_override");
 
-=head1 EXAMPLES
+Now, C<-vax> would set the option C<vax>.
 
-If the option specifier is "one:i" (i.e. takes an optional integer
-argument), then the following situations are handled:
+When any level of bundling is enabled, option values may be inserted
+in the bundle. For example:
 
-   -one -two		-> $opt_one = '', -two is next option
-   -one -2		-> $opt_one = -2
+    -h24w80
 
-Also, assume specifiers "foo=s" and "bar:s" :
+is equivalent to
 
-   -bar -xxx		-> $opt_bar = '', '-xxx' is next option
-   -foo -bar		-> $opt_foo = '-bar'
-   -foo --		-> $opt_foo = '--'
+    -h 24 -w 80
 
-In GNU or POSIX format, option names and values can be combined:
+When configured for bundling, single-character options are matched
+case sensitive while long options are matched case insensitive. To
+have the single-character options matched case insensitive as well,
+use:
 
-   +foo=blech		-> $opt_foo = 'blech'
-   --bar=		-> $opt_bar = ''
-   --bar=--		-> $opt_bar = '--'
+    Getopt::Long::Configure ("bundling", "ignorecase_always");
 
-Example of using variable references:
+It goes without saying that bundling can be quite confusing.
 
-   $ret = GetOptions ('foo=s', \$foo, 'bar=i', 'ar=s', \@ar);
+=head2 The lonesome dash
 
-With command line options "-foo blech -bar 24 -ar xx -ar yy" 
-this will result in:
+Some applications require the option C<-> (that's a lone dash). This
+can be achieved by adding an option specification with an empty name:
 
-   $foo = 'blech'
-   $opt_bar = 24
-   @ar = ('xx','yy')
+    GetOptions ('' => \$stdio);
 
-Example of using the E<lt>E<gt> option specifier:
+A lone dash on the command line will now be legal, and set options
+variable C<$stdio>.
 
-   @ARGV = qw(-foo 1 bar -foo 2 blech);
-   GetOptions("foo=i", \$myfoo, "<>", \&mysub);
+=head2 Argument call-back
 
-Results:
+A special option 'name' C<<>> can be used to designate a subroutine
+to handle non-option arguments. When GetOptions() encounters an
+argument that does not look like an option, it will immediately call this
+subroutine and passes it the argument as a parameter.
 
-   mysub("bar") will be called (with $myfoo being 1)
-   mysub("blech") will be called (with $myfoo being 2)
+For example:
 
-Compare this with:
+    my $width = 80;
+    sub process { ... }
+    GetOptions ('width=i' => \$width, '<>' => \&process);
 
-   @ARGV = qw(-foo 1 bar -foo 2 blech);
-   GetOptions("foo=i", \$myfoo);
+When applied to the following command line:
 
-This will leave the non-options in @ARGV:
+    arg1 --width=72 arg2 --width=60 arg3
 
-   $myfoo -> 2
-   @ARGV -> qw(bar blech)
+This will call 
+C<process("arg1")> while C<$width> is C<80>, 
+C<process("arg2")> while C<$width> is C<72>, and
+C<process("arg3")> while C<$width> is C<60>.
 
-=head1 CONFIGURATION OPTIONS
+This feature requires configuration option B<permute>, see section
+L<Configuring Getopt::Long>.
 
-B<GetOptions> can be configured by calling subroutine
-B<Getopt::Long::Configure>. This subroutine takes a list of quoted
-strings, each specifying a configuration option to be set, e.g.
-B<ignore_case>. Options can be reset by prefixing with B<no_>, e.g.
-B<no_ignore_case>. Case does not matter. Multiple calls to B<config>
-are possible.
 
-Previous versions of Getopt::Long used variables for the purpose of
-configuring. Although manipulating these variables still work, it
-is strongly encouraged to use the new B<config> routine. Besides, it
-is much easier.
+=head1 Configuring Getopt::Long
+
+Getopt::Long can be configured by calling subroutine
+Getopt::Long::Configure(). This subroutine takes a list of quoted
+strings, each specifying a configuration option to be set, e.g.
+C<ignore_case>, or reset, e.g. C<no_ignore_case>. Case does not
+matter. Multiple calls to Configure() are possible.
 
 The following options are available:
 
@@ -1215,122 +1510,102 @@ default values.
 
 Allow option names to be abbreviated to uniqueness.
 Default is set unless environment variable
-POSIXLY_CORRECT has been set, in which case B<auto_abbrev> is reset.
+POSIXLY_CORRECT has been set, in which case C<auto_abbrev> is reset.
 
-=item getopt_compat   
+=item getopt_compat
 
-Allow '+' to start options.
+Allow C<+> to start options.
 Default is set unless environment variable
-POSIXLY_CORRECT has been set, in which case B<getopt_compat> is reset.
+POSIXLY_CORRECT has been set, in which case C<getopt_compat> is reset.
 
 =item require_order
 
-Whether non-options are allowed to be mixed with
-options.
+Whether command line arguments are allowed to be mixed with options.
 Default is set unless environment variable
-POSIXLY_CORRECT has been set, in which case b<require_order> is reset.
+POSIXLY_CORRECT has been set, in which case C<require_order> is reset.
 
-See also B<permute>, which is the opposite of B<require_order>.
+See also C<permute>, which is the opposite of C<require_order>.
 
 =item permute
 
-Whether non-options are allowed to be mixed with
-options.
+Whether command line arguments are allowed to be mixed with options.
 Default is set unless environment variable
-POSIXLY_CORRECT has been set, in which case B<permute> is reset.
-Note that B<permute> is the opposite of B<require_order>.
+POSIXLY_CORRECT has been set, in which case C<permute> is reset.
+Note that C<permute> is the opposite of C<require_order>.
 
-If B<permute> is set, this means that 
+If C<permute> is set, this means that 
 
-    -foo arg1 -bar arg2 arg3
+    --foo arg1 --bar arg2 arg3
 
 is equivalent to
 
-    -foo -bar arg1 arg2 arg3
+    --foo --bar arg1 arg2 arg3
 
-If a non-option call-back routine is specified, @ARGV will always be
-empty upon succesful return of GetOptions since all options have been
-processed, except when B<--> is used:
+If an argument call-back routine is specified, C<@ARGV> will always be
+empty upon succesful return of GetOptions() since all options have been
+processed. The only exception is when C<--> is used:
 
-    -foo arg1 -bar arg2 -- arg3
+    --foo arg1 --bar arg2 -- arg3
 
 will call the call-back routine for arg1 and arg2, and terminate
-leaving arg2 in @ARGV.
+GetOptions() leaving C<"arg2"> in C<@ARGV>.
 
-If B<require_order> is set, options processing
+If C<require_order> is set, options processing
 terminates when the first non-option is encountered.
 
-    -foo arg1 -bar arg2 arg3
+    --foo arg1 --bar arg2 arg3
 
 is equivalent to
 
-    -foo -- arg1 -bar arg2 arg3
+    --foo -- arg1 --bar arg2 arg3
 
 =item bundling (default: reset)
 
-Setting this variable to a non-zero value will allow single-character
-options to be bundled. To distinguish bundles from long option names,
-long options must be introduced with B<--> and single-character
-options (and bundles) with B<->. For example,
-
-    ps -vax --vax
-
-would be equivalent to
-
-    ps -v -a -x --vax
-
-provided "vax", "v", "a" and "x" have been defined to be valid
-options. 
-
-Bundled options can also include a value in the bundle; for strings
-this value is the rest of the bundle, but integer and floating values
-may be combined in the bundle, e.g.
+Setting this option will allow single-character options to be bundled.
+To distinguish bundles from long option names, long options I<must> be
+introduced with C<--> and single-character options (and bundles) with
+C<->.
 
-    scale -h24w80
-
-is equivalent to
-
-    scale -h 24 -w 80
-
-Note: resetting B<bundling> also resets B<bundling_override>.
+Note: resetting C<bundling> also resets C<bundling_override>.
 
 =item bundling_override (default: reset)
 
-If B<bundling_override> is set, bundling is enabled as with
-B<bundling> but now long option names override option bundles. In the
-above example, B<-vax> would be interpreted as the option "vax", not
-the bundle "v", "a", "x".
+If C<bundling_override> is set, bundling is enabled as with
+C<bundling> but now long option names override option bundles. 
 
-Note: resetting B<bundling_override> also resets B<bundling>.
+Note: resetting C<bundling_override> also resets C<bundling>.
 
 B<Note:> Using option bundling can easily lead to unexpected results,
 especially when mixing long options and bundles. Caveat emptor.
 
 =item ignore_case  (default: set)
 
-If set, case is ignored when matching options.
+If set, case is ignored when matching long option names. Single
+character options will be treated case-sensitive.
 
-Note: resetting B<ignore_case> also resets B<ignore_case_always>.
+Note: resetting C<ignore_case> also resets C<ignore_case_always>.
 
 =item ignore_case_always (default: reset)
 
 When bundling is in effect, case is ignored on single-character
 options also. 
 
-Note: resetting B<ignore_case_always> also resets B<ignore_case>.
+Note: resetting C<ignore_case_always> also resets C<ignore_case>.
 
 =item pass_through (default: reset)
 
-Unknown options are passed through in @ARGV instead of being flagged
-as errors. This makes it possible to write wrapper scripts that
-process only part of the user supplied options, and passes the
+Options that are unknown, ambiguous or supplied with an invalid option
+value are passed through in C<@ARGV> instead of being flagged as
+errors. This makes it possible to write wrapper scripts that process
+only part of the user supplied command line arguments, and pass the
 remaining options to some other program.
 
-This can be very confusing, especially when B<permute> is also set.
+This can be very confusing, especially when C<permute> is also set.
 
 =item prefix
 
-The string that starts options. See also B<prefix_pattern>.
+The string that starts options. If a constant string is not
+sufficient, see C<prefix_pattern>.
 
 =item prefix_pattern
 
@@ -1344,27 +1619,84 @@ Enable copious debugging output.
 
 =back
 
-=head1 OTHER USEFUL VARIABLES
+=head1 Return values and Errors
 
-=over 12
+Configuration errors and errors in the option definitions are
+signalled using die() and will terminate the calling program unless
+the call to Getopt::Long::GetOptions() was embedded in C<eval { ...
+}>, or die() was trapped using C<$SIG{__DIE__}>.
 
-=item $Getopt::Long::VERSION
+A return value of 1 (true) indicates success.
 
-The version number of this Getopt::Long implementation in the format
-C<major>.C<minor>. This can be used to have Exporter check the
-version, e.g.
+A return status of 0 (false) indicates that the function detected one
+or more errors during option parsing. These errors are signalled using
+warn() and can be trapped with C<$SIG{__WARN__}>.
 
-    use Getopt::Long 3.00;
+Errors that can't happen are signalled using Carp::croak().
 
-You can inspect $Getopt::Long::major_version and
-$Getopt::Long::minor_version for the individual components.
+=head1 Legacy
 
-=item $Getopt::Long::error
+The earliest development of C<newgetopt.pl> started in 1990, with Perl
+version 4. As a result, its development, and the development of
+Getopt::Long, has gone through several stages. Since backward
+compatibility has always been extremely important, the current version
+of Getopt::Long still supports a lot of constructs that nowadays are
+no longer necessary or otherwise unwanted. This section describes
+briefly some of these 'features'.
 
-Internal error flag. May be incremented from a call-back routine to
-cause options parsing to fail.
+=head2 Default destinations
 
-=back
+When no destination is specified for an option, GetOptions will store
+the resultant value in a global variable named C<opt_>I<XXX>, where
+I<XXX> is the primary name of this option. When a progam executes
+under C<use strict> (recommended), these variables must be
+pre-declared with our() or C<use vars>.
+
+    our $opt_length = 0;
+    GetOptions ('length=i');	# will store in $opt_length
+
+To yield a usable Perl variable, characters that are not part of the
+syntax for variables are translated to underscores. For example,
+C<--fpp-struct-return> will set the variable
+C<$opt_fpp_struct_return>. Note that this variable resides in the
+namespace of the calling program, not necessarily C<main>. For
+example:
+
+    GetOptions ("size=i", "sizes=i@");
+
+with command line "-size 10 -sizes 24 -sizes 48" will perform the
+equivalent of the assignments
+
+    $opt_size = 10;
+    @opt_sizes = (24, 48);
+
+=head2 Alternative option starters
+
+A string of alternative option starter characters may be passed as the
+first argument (or the first argument after a leading hash reference
+argument).
+
+    my $len = 0;
+    GetOptions ('/', 'length=i' => $len);
+
+Now the command line may look like:
+
+    /length 24 -- arg
+
+Note that to terminate options processing still requires a double dash
+C<-->.
+
+GetOptions() will not interpret a leading C<"<>"> as option starters
+if the next argument is a reference. To force C<"<"> and C<">"> as
+option starters, use C<"><">. Confusing? Well, B<using a starter
+argument is strongly deprecated> anyway.
+
+=head2 Configuration variables
+
+Previous versions of Getopt::Long used variables for the purpose of
+configuring. Although manipulating these variables still work, it
+is strongly encouraged to use the new C<config> routine. Besides, it
+is much easier.
 
 =head1 AUTHOR
 
@@ -1372,7 +1704,7 @@ Johan Vromans E<lt>jvromans@squirrel.nlE<gt>
 
 =head1 COPYRIGHT AND DISCLAIMER
 
-This program is Copyright 1990,1999 by Johan Vromans.
+This program is Copyright 2000,1990 by Johan Vromans.
 This program is free software; you can redistribute it and/or
 modify it under the terms of the Perl Artistic License or the
 GNU General Public License as published by the Free Software
@@ -1389,3 +1721,8 @@ the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,
 MA 02139, USA.
 
 =cut
+
+# Local Variables:
+# mode: perl
+# eval: (load-file "pod.el")
+# End: