Upgrade to Getopt::Long 2.26.

p4raw-id: //depot/perl@11587

2 files changed, 473 insertions, 0 deletions

diff --git a/lib/Getopt/Long/CHANGES b/lib/Getopt/Long/CHANGES
new file mode 100644
index 0000000000..b43606a5d6
--- /dev/null
+++ b/lib/Getopt/Long/CHANGES
@@ -0,0 +1,277 @@
+Changes in version 2.26
+-----------------------
+
+* New option type: 'o'. It accepts all kinds of integral numbers in
+  Perl style, including decimal (24), octal (012), hexadecimal (0x2f)
+  and binary (0b1001).
+
+* Fix problem with getopt_compat not matching +foo=bar.
+
+* Remove $VERSION_STRING for production versions.
+
+Changes in version 2.26
+-----------------------
+
+* New option type: 'o'. It accepts all kinds of integral numbers in
+  Perl style, including decimal (24), octal (012), hexadecimal (0x2f)
+  and binary (0b1001).
+
+* Fix problem with getopt_compat not matching +foo=bar.
+
+* Remove $VERSION_STRING for production versions.
+
+Changes in version 2.25
+-----------------------
+
+* Change handling of a lone "-" on the command line. It will now be
+  treated as a non-option unless an explicit specification was passed
+  to GetOptions. See the manual.
+  In the old implementation an error was signalled, so no
+  compatibility breaks are expected from this change.
+
+* Add $VERSION_STRING. This is the string form of $VERSION. Usually
+  they are identical, unless it is a pre-release in which case
+  $VERSION will be (e.g.) 2.2403 and $VERSION_STRING will be "2.24_03".
+
+Changes in version 2.24
+-----------------------
+
+* Add object oriented interface:
+
+    use Getopt::Long;
+    $p = new Getopt::Long::Parser;
+    $p->configure(...configuration options...);
+    if ($p->getoptions(...options descriptions...)) ...
+
+* Add configuration at 'use' time:
+
+    use Getopt::Long qw(:config no_ignore_case bundling);
+
+* Add configuration options "gnu_getopt" and "gnu_compat".
+
+  "gnu_compat" controls whether --opt= is allowed, and what it should
+  do. Without "gnu_compat", --opt= gives an error. With "gnu_compat", 
+  --opt= will give option "opt" and empty value.
+  This is the way GNU getopt_long does it.
+
+  "gnu_getopt" is a short way of setting "gnu_compat bundling permute
+  no_getopt_compat. With "gnu_getopt", command line handling should be
+  fully compatible with GNU getopt_long.
+
+* Correct warnings when the user specified an array or hash
+  destination using a non-lowercase option, e.g. "I=s@".
+
+* Correct ambiguous use of 'set' and 'reset' in the Configuration
+  section of the documentation. 
+
+* Add configuration option "posix_default" to reset to defaults as if
+  POSIXLY_CORRECT were set.
+
+* Disallow "no" prefix on configuration options "default", "prefix" and
+  "prefix_pattern". 
+
+* Add a section "Trouble Shooting" to the documentation, with
+  frequently asked questions.
+
+Changes in version 2.23
+-----------------------
+
+* When a call-back routine issues 'die', messages starting with "!"
+  are treated specially. Currently, only "!FINISH" is recognised (see
+  the next bullet point). Other messages that start with "!" are
+  ignored.
+
+* Change 'die("FINISH") (see changes in 2.21) to die("!FINISH"). This
+  is an incompatible change, but I guess noone is using this yet.
+
+Changes in version 2.22
+-----------------------
+
+* Fixes a bug in the combination of aliases and negation.
+
+  Old:  "foo|bar!" allowed negation on foo, but not on bar.
+  New:  "foo|bar!" allows negation on foo and bar.
+
+  Caveat: "foo|f!", with bundling, issues the warning that negation on
+  a short option is ignored. To obtain the desired behaviour, use
+
+	"foo!" => \$opt_foo, "f" => \$opt_foo
+  or
+	"foo|f" => \$opt_foo, "nofoo" => sub { $opt_foo = 0 }
+
+  Remember that this is _only_ required when bundling is in effect.
+
+Changes in version 2.21
+-----------------------
+
+* New documentation.
+
+* User defined subroutines should use 'die' to signal errors.
+
+* User defined subroutines can preliminary terminate options
+  processing by calling die("FINISH");
+
+* Correct erroneous install of Getopt::Long manpage.
+  Previous versions seem to install Getopt::GetoptLong instead of
+  Getopt::Long.
+
+Changes in version 2.20
+-----------------------
+
+* Prevent the magic argument "<>" from being interpreted as option
+  starter characters if it is the first argument passed.
+  To use the characters "<>" as option starters, pass "><" instead.
+
+* Changed license: Getopt::Long may now also be used under the Perl
+  Artistic License.
+
+* Changed the file name of the distribution kit from "GetoptLong..."
+  to "Getopt-Long-..." to match the standards.
+
+Changes in version 2.19
+-----------------------
+
+* Fix a warning bug with bundling_override.
+
+There's no version 2.18
+-----------------------
+
+Changes in version 2.17
+-----------------------
+
+* Getopt::Long::config is renamed Getopt::Long::Configure. The old
+  name will remain supported without being documented.
+
+* Options can have the specifier '+' to denote that the option value
+  must be incremented each time the option occurs on the command line.
+  For example:
+
+     my $more = 2;
+     Getopt::Long::Configure("bundling");
+     GetOptions ("v+" => \$more);
+     print STDOUT ("more = $more\n");
+
+  will print "more = 3" when called with "-v", "more = 4" when called
+  with "-vv" (or "-v -v"), and so on.
+
+* Getopt::Long now uses autoloading. This substantially reduces the
+  resources required to 'use Getopt::Long' (about 100 lines of over
+  1300 total).
+
+* It is now documented that global option variables like $opt_foo
+  need to be declared using 'use vars ...' when running under 'use
+  strict'. 
+
+* To install, it is now required to use the official procedure:
+
+     perl Makefile.PL
+     make
+     make test
+     make install
+
+Changes in version 2.16
+-----------------------
+
+* A couple of small additional fixes to the $` $& $' fixes.
+
+* The option prefix can be set using config("prefix=...") or, more
+  powerful, with config("prefix_pattern=..."); see the documentation
+  for details.
+
+* More 'perl -w' warnings eliminated for obscure cases of bundling.
+
+This version is identical to 2.15, which was not released.
+
+There's no version 2.14
+-----------------------
+
+Changes in version 2.13
+-----------------------
+
+* All regexps are changed to avoid the use of $`, $& and $'. Using one
+  of these causes all pattern matches in the program to be much slower
+  than necessary.
+
+* Configuration errors are signalled using die() and will cause the
+  program to be terminated (unless eval{...} or $SIG{__DIE__} is
+  used).
+
+* Option parsing errors are now signalled with calls to warn().
+
+* In option bundles, numeric values may be embedded in the bundle
+  (e.g. -al24w80).
+
+* More 'perl -w' warnings eliminated for obscure cases of bundling.
+
+* Removed non-standard version number matching. Version 1.121 is now
+  more than 1.12 but less than 1.13. 
+
+Changes in version 2.12
+-----------------------
+
+* A single question mark is allowed as an alias to an option, e.g. 
+
+    GetOptions ("help|?", ...)
+
+Changes in version 2.11
+-----------------------
+
+* User linkage may be an object, provided the object is really a hash.
+
+  For example:
+
+    {	package Foo;
+	sub new () { return bless {}; }
+    }
+
+    my $linkage = Foo->new();
+
+    GetOptions ($linkage, ... );
+
+* Some bug fixes in handling obscure cases of pass-through.
+
+Changes in version 2.9
+----------------------
+
+* A new way to configure Getopt::Long. Instead of setting module local
+  variables, routine Getopt::Long::config can be called with the names
+  of options to be set or reset, e.g.
+
+    Getopt::Long::config ("no_auto_abbrev", "ignore_case");
+
+  Configuring by using the module local variables is deprecated, but
+  it will continue to work for backwark compatibility.
+
+Changes in version 2.6
+----------------------
+
+* Handle ignorecase even if autoabbrev is off. 
+
+* POD corrections.
+
+Changes in version 2.4
+----------------------
+
+* Pass-through of unrecognized options. Makes it easy to write wrapper
+  programs that process some of the command line options but pass the
+  others to another program.
+
+* Options can be of type HASH, now you can say
+
+    --define foo=bar
+
+  and have $opt_define{"foo"} set to "bar".
+
+* An enhanced skeleton program, skel2.pl, that combines the power of
+  Getopt::Long with Pod::Usage. 
+  Module Pod::Usage can be obtained from CPAN,
+  http://www.perl.com/CPAN/authors/Brad_Appleton. 
+
+Possible incompatibility in version 2.4
+---------------------------------------
+
+Previous versions of Getopt::Long always downcased the option variable
+names when ignorecase was in effect. This bug has been corrected. As a
+consequence, &GetOptions ("Foo") will now set variable $opt_Foo
+instead of $opt_foo.
+
diff --git a/lib/Getopt/Long/README b/lib/Getopt/Long/README
new file mode 100644
index 0000000000..1a2dc10c4a
--- /dev/null
+++ b/lib/Getopt/Long/README
@@ -0,0 +1,196 @@
+Module Getopt::Long - extended processing of command line options
+=================================================================
+
+Module Getopt::Long implements an extended getopt function called
+GetOptions(). This function implements the POSIX standard for command
+line options, with GNU extensions, while still capable of handling
+the traditional one-letter options.
+In general, this means that command line options can have long names
+instead of single letters, and are introduced with a double dash `--'.
+
+Optionally, Getopt::Long can support the traditional bundling of
+single-letter command line options.
+
+Getopt::Long::GetOptions() is part of the Perl 5 distribution. It is
+the successor of 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.
+
+For complete documentation, see the Getopt::Long POD document or use
+the command
+
+    perldoc Getopt::Long
+
+FEATURES
+========
+
+* Long option names
+
+Major advantage of using long option names is that it is much easier
+to memorize the option names. Using single-letter names one quickly
+runs into the problem that there is no logical relationship between
+the semantics of the selected option and its option letter.
+Disadvantage is that it requires more typing. Getopt::Long provides
+for option name abbreviation, so option names may be abbreviated to
+uniqueness. Also, modern shells like Cornell's tcsh support option
+name completion. As a rule of thumb, you can use abbreviations freely
+while running commands interactively but always use the full names in
+scripts. 
+
+Examples (POSIX):
+
+    --long --width=80 --height=24
+
+Extensions:
+
+    -long (convenience) +width=80 (deprecated) -height 24 (traditional)
+
+By default, long option names are case insensitive.
+
+* Single-letter options and bundling
+
+When single-letter options are requested, Getopt::Long allows the
+option names to be bundled, e.g. "-abc" is equivalent to "-a -b -c".
+In this case, long option names must be introduced with the POSIX "--"
+introducer.
+
+Examples:
+
+    -lgAd (bundle) -xw 80 (bundle, w takes a value) -xw80 (same)
+    even -l24w80 (l = 24 and w = 80)
+
+By default, single-letter option names are case sensitive.
+
+* Flexibility:
+
+  - options can have alternative names, using an alternative name
+    will behave as if the primary name was used;
+  - options can be negatable, e.g. "debug" will switch it on, while
+    "nodebug" will switch it off.    
+  - options can set values, but also add values producing an array
+    of values instead of a single scalar value, or set values in a hash.
+
+* Options linkage
+
+Using Getopt::Long gives the programmer ultimate control over the
+command line options and how they must be handled:
+
+  - by setting a global variable in the calling program;
+  - by setting a specified variable;
+  - by entering the option name and the value in an associative array
+    (hash) or object (if it is a blessed hash);
+  - by calling a user-specified subroutine with the option name and
+    the value as arguments;
+  - combinations of the above.
+
+* Customization:
+
+The module contains a special method, Getopt::Long::Configure, to
+control configuration variables to activate (or de-activate) specific
+behavior. It can be called with one or more names of options:
+
+  - default
+
+	Restore default settings.
+
+  - auto_abbrev      
+
+	Allow option names to be abbreviated to uniqueness. 
+
+  - getopt_compat   
+
+	Allow '+' to start options.
+
+  - gnu_compat
+
+	Compatibility with GNU getopt_long().
+
+  - permute
+  - require_order           
+
+	Whether non-options are allowed to be mixed with options.
+
+	permute means that 
+
+	    -foo arg1 -bar arg2 arg3
+
+	is equivalent to
+
+	    -foo -bar arg1 arg2 arg3
+
+	(provided -foo does not take an argument value).
+
+	require_order means that options processing
+	terminates when the first non-option is encountered.
+
+	    -foo arg1 -bar arg2 arg3
+
+	is equivalent to
+
+	    -foo -- arg1 -bar arg2 arg3
+
+  - bundling
+
+	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 
+	"--" and single-character options (and bundles) with "-".
+
+  - ignore_case      
+
+	Ignore case when matching options.
+
+  - pass_through
+
+	Do not issue error messages for unknown options, but leave
+	them (pass-through) in @ARGV.
+
+  - prefix
+
+	The string that starts options. See also prefix_pattern.
+
+  - prefix_pattern
+
+	A Perl pattern that identifies the strings that introduce
+	options. Default is (--|-|\+) unless environment variable
+	POSIXLY_CORRECT has been set, in which case it is (--|-).
+
+  - debug
+
+	Enable copious debugging output.
+
+* Object oriented interface:
+
+Using the object oriented interface, multiple parser objects can be
+instantiated, each having their own configuration settings:
+
+    $p1 = new Getopt::Long::Parser (config => ["posix"]);
+    $p2 = new Getopt::Long::Parser (config => ["no_posix"]);
+    if ($p1->getoptions(...options descriptions...)) ...
+
+AVAILABILITY
+============
+
+The official version for module Getopt::Long comes with the Perl 5
+distribution. 
+Newer versions will be made available on the Comprehensive Perl Archive
+Network (CPAN), see "http://www.perl.com/CPAN/authors/Johan_Vromans".
+Or use the CPAN search engine:
+  http://search.cpan.org/search?mode=module&query=Getopt::Long
+  http://search.cpan.org/search?module=Getopt::Long
+
+COPYRIGHT AND DISCLAIMER
+========================
+
+Module Getopt::Long is Copyright 2001,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
+Foundation; either version 2 of the License, or (at your option) any
+later version.
+
+-------------------------------------------------------------------
+Johan Vromans                                  jvromans@squirrel.nl
+Squirrel Consultancy                       Haarlem, the Netherlands
+http://www.squirrel.nl       http://www.squirrel.nl/people/jvromans
+------------------ "Arms are made for hugging" --------------------