Upgrade to Getopt::Long 2.28.

[p5sagit/p5-mst-13.2.git] / lib / Getopt / Long / CHANGES

Changes in version 2.28
-----------------------

* When an option is specified more than once, a warning is generated
  if perl is run with -w. This is a correction to 2.27, where it would
  unconditionally die.

  An example of duplicate specification is GetOptions('foo', 'foo'),
  but also GetOptions('foo=s', 'foo') and GetOptions('Foo', 'foo')
  (the latter only when ignore_case is in effect).

Changes in version 2.27
-----------------------

* You can now specify integer options to take an optional argument.
  that defaults to a specific value. E.g.,  GetOptions('foo:5' => \$var)
  will allow $var to get the value 5 when no value was specified with
  the -foo option on the command line.

  Instead of a value, a '+' may be specified. E.g.,
  GetOptions('foo:+' => \$var) will allow $var to be incremented when
  no value was specified with the -foo option on the command line.

* Fix several problems with internal and external use of 'die' and
  signal handlers.

* Fixed some bugs with subtle combinations of bundling_override and
  ignore_case.

* A callback routine that is associated with a hash-valued option will
  now have both the hask key and the value passed. It used to get only
  the value passed.

* Eliminated the use of autoloading. Autoloading kept generating
  problems during development, and when using perlcc.

* Avoid errors on references when an option is found in error, e.g.
  GetOptions('fo$@#' => \$var).
  Thanks to Wolfgang Laun <Wolfgang.Laun@alcatel.at>.

* When an option is specified more than once, an error is now
  generated. E.g., GetOptions('foo', 'foo').
  Thanks to Wolfgang Laun <Wolfgang.Laun@alcatel.at>.

* Lots of internal restructoring to make room for extensions.

* Redesigned the regression tests.

* Enhance the documentation to prevent common misunderstandings about
  single character options.

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.