lib/Getopt/Long/CHANGES

   1 Changes in version 2.38
   2 -----------------------
   3
   4 * Bugfix for Ticket 35759: First arg to callback function evaluates
   5   to false when used in bool context.
   6
   7 * Fix problem with prototypes of GetOptionsFrom* functions.
   8
   9 * Fix restoring default die handler.
  10
  11 * Bugfix for Ticket 24941: Autoabbrev with + incorrect.
  12
  13 Changes in version 2.37
  14 -----------------------
  15
  16 * The first argument to callback function is now an object and will
  17   get methods for finer control in the future. The object stringifies
  18   to the option name, so current code should not notice a difference.
  19
  20 * Bugfix: With gnu_compat, --foo= will no longer trigger "Option
  21   requires an argument" but return the empty string.
  22
  23 Changes in version 2.36
  24 -----------------------
  25
  26 **************** WARNING -- EXPERIMENTAL CODE AHEAD ****************
  27
  28 * Parsing options from an arbitrary array
  29
  30   The entry point GetOptionsFromArray (exported on demand) can be used
  31   to parse command line options that are not passed in via @ARGV, but
  32   using an arbitrary array.
  33
  34     use Getopt::Long qw(GetOptionsFromArray);
  35     $ret = GetOptionsFromArray(\@myopts, ...);
  36
  37 * Parsing options from an arbitrary string
  38
  39   The entry point GetOptionsFromString (exported on demand) can be
  40   used to parse command line options that are not passed in via @ARGV,
  41   but using an arbitrary string.
  42
  43     use Getopt::Long qw(GetOptionsFromString);
  44     $ret = GetOptionsFromString($optstring, ...);
  45
  46   Note that upon completion, no arguments may remain in the string.
  47   If arguments may remain, call it in list context:
  48
  49     ($ret, $args) = GetOptionsFromString($optstring, ...);
  50
  51   @$args will have the remaining arguments.
  52
  53 **************** END EXPERIMENTAL CODE ****************
  54
  55 * Number values for options may include underscores for readability
  56   (just like Perls numbers).
  57
  58 * Bugfix for Ticket #19432 (found and fixed by khali).
  59
  60 * Bugfix to make it cooperate with the bignum pragma. Thanks to Merijn
  61   and Yves.
  62
  63 * Various small fixes to make the test suite run under 5.004_05.
  64
  65 * More examples (skeletons).
  66
  67 Changes in version 2.35
  68 -----------------------
  69
  70 * long_prefix_pattern configuration variable.
  71
  72   prefix_pattern has now been complemented by a new configuration
  73   option 'long_prefix_pattern' that allows the user to specify what
  74   prefix patterns should have long option style sematics applied.
  75   This will enable people to do things like
  76
  77     foo.pl /option=value
  78
  79   instead of forcing people to use the short option style
  80
  81     foo.pl /option value
  82
  83   This enhancement was suggested and implemented by Yves Orton.
  84
  85 * Bugfix for Ticket #11377 (bug found and fixed by Ryan).
  86 * Bugfix for Ticket #12380.
  87
  88 * Options can take multiple values at once. E.g.,
  89
  90     --coordinates 52.2 16.4 --rgbcolor 255 255 149
  91
  92   To handle the above command line, the following call to GetOptions
  93   can be used:
  94
  95     GetOptions('coordinates=f{2}' => \@coor, 'rgbcolor=i{3}' => \@color);
  96
  97   You can specify the minimum and maximum number of values desired.
  98   The syntax for this is similar to that of regular expression
  99   patterns: { min , max }.
 100
 101 Changes in version 2.34
 102 -----------------------
 103
 104 * Auto-vivification of array and hash refs
 105
 106   If an option is specified to require an array or hash ref, and a
 107   scalar reference is passed, this is auto-vivified to array or hash
 108   ref.
 109
 110   Example:
 111
 112         @ARGV = qw(--foo=xx);
 113         GetOptions("foo=s@", \$var);
 114         # Now $var->[0] eq "xx"
 115
 116 * Auto-supplied verbose and help options are no longer taken into
 117   account when determining option ambiguity. This eliminates the
 118   common problem that you suddenly get an ambiguous option warning
 119   when you have an option "verbose" and run your program with "-v".
 120
 121 * Cosmetic changes in some error messages.
 122
 123 Changes in version 2.33
 124 -----------------------
 125
 126 The following new features are marked experimental. This means that if
 127 you are going to use them you _must_ watch out for the next release of
 128 Getopt::Long to see if the API has changed.
 129
 130 * Getopt::Long can automatically handle --version and --help options
 131   if the calling program did not specify a handler explicitly.
 132
 133   Two configuration parameters have been added: 'auto_help' (or
 134   'help') and 'auto_version' (or 'version'). If set, Getopt::Long will
 135   itself take care of --help and --version options. Otherwise,
 136   everything is exactly as it was before.
 137
 138   The new features will be enabled by default for programs that
 139   explicitly require version 2.3203 or later.
 140
 141   Getopt::Long uses module Pod::Usage to produce the help message from
 142   the SYNOPSIS section of the program's POD.
 143
 144   Using a --help (or -?) command line option will write the SYNOPSIS
 145   section of the program's POD to STDOUT, and exit with status 0.
 146   However, an illegal option will produce the help text to STDERR,
 147   and exit with status 2. This is in accordance with current
 148   conventions.
 149
 150 * Two subroutines can be exported on demand:
 151
 152   - VersionMessage
 153
 154     This subroutine prints the standard version message.
 155
 156   - HelpMessage
 157
 158     This subroutine prints the standard help message.
 159
 160   Both subroutines take the same arguments as Pod::Usage::pod2usage,
 161   see its documentation for details.
 162
 163   Example:
 164
 165     use Getopt::Long 2.33 qw(GetOptions HelpMessage);
 166     GetOptions(...) or HelpMessage(2);
 167
 168 * Subroutine Configure can now be exported on demand.
 169
 170 * Negatable options (with "!") now also support the "no-" prefix.
 171   On request of Ed Avis.
 172
 173 * Some fixes with hashes and bundling.
 174   Thanks to Anders Johnson and Andrei Gnepp.
 175   Mandatory/optional status for hash values is now effective.
 176   String valued options with no value now default to the empty string
 177   instead of 1 (one).
 178   NOTE: The hash options still remain more or less experimental.
 179
 180 * Fix a pass_through bug where the options terminator (normally "--")
 181   was not passed through in @ARGV.
 182   Thanks to Philippe Verdret.
 183
 184 * Add FAQ: I "use GetOpt::Long;" (Windows) and now it doesn't work.
 185
 186 Changes in version 2.32
 187 -----------------------
 188
 189 * Fix a bug where the initial value for a optional numeric argument
 190 was not used for value of a hash option.
 191
 192 * Remove 5.005 thread safety code. Getopt::Long is completely thread
 193 safe when using the 5.8 ithreads.
 194
 195 Changes in version 2.31
 196 -----------------------
 197
 198 * Fix a bug where calling the configure method on a
 199   Getopt::Long::Parser object would bail out with
 200   Undefined subroutine &Getopt::Long::Parser::Configure called at
 201   Getopt/Long.pm line 186.
 202
 203 Changes in version 2.30
 204 -----------------------
 205
 206 * Fix a problem where a 'die' from a 'warn' via a localized
 207   $SIG{__WARN__} was not properly propagated from a callback.
 208   Thanks to Diab Jerius.
 209
 210 Changes in version 2.29
 211 -----------------------
 212
 213 * Fix a problem where options were not recognized when both
 214   auto_abbrev and ignore_case were disabled. Thanks to Seth Robertson.
 215
 216 * Remove Carp.
 217
 218 Changes in version 2.28
 219 -----------------------
 220
 221 * When an option is specified more than once, a warning is generated
 222   if perl is run with -w. This is a correction to 2.27, where it would
 223   unconditionally die.
 224
 225   An example of duplicate specification is GetOptions('foo', 'foo'),
 226   but also GetOptions('foo=s', 'foo') and GetOptions('Foo', 'foo')
 227   (the latter only when ignore_case is in effect).
 228
 229 Changes in version 2.27
 230 -----------------------
 231
 232 * You can now specify integer options to take an optional argument.
 233   that defaults to a specific value. E.g.,  GetOptions('foo:5' => \$var)
 234   will allow $var to get the value 5 when no value was specified with
 235   the -foo option on the command line.
 236
 237   Instead of a value, a '+' may be specified. E.g.,
 238   GetOptions('foo:+' => \$var) will allow $var to be incremented when
 239   no value was specified with the -foo option on the command line.
 240
 241 * Fix several problems with internal and external use of 'die' and
 242   signal handlers.
 243
 244 * Fixed some bugs with subtle combinations of bundling_override and
 245   ignore_case.
 246
 247 * A callback routine that is associated with a hash-valued option will
 248   now have both the hask key and the value passed. It used to get only
 249   the value passed.
 250
 251 * Eliminated the use of autoloading. Autoloading kept generating
 252   problems during development, and when using perlcc.
 253
 254 * Avoid errors on references when an option is found in error, e.g.
 255   GetOptions('fo$@#' => \$var).
 256   Thanks to Wolfgang Laun.
 257
 258 * When an option is specified more than once, an error is now
 259   generated. E.g., GetOptions('foo', 'foo').
 260   Thanks to Wolfgang Laun.
 261
 262 * Lots of internal restructoring to make room for extensions.
 263
 264 * Redesigned the regression tests.
 265
 266 * Enhance the documentation to prevent common misunderstandings about
 267   single character options.
 268
 269 Changes in version 2.26
 270 -----------------------
 271
 272 * New option type: 'o'. It accepts all kinds of integral numbers in
 273   Perl style, including decimal (24), octal (012), hexadecimal (0x2f)
 274   and binary (0b1001).
 275
 276 * Fix problem with getopt_compat not matching +foo=bar.
 277
 278 * Remove $VERSION_STRING for production versions.
 279
 280 Changes in version 2.25
 281 -----------------------
 282
 283 * Change handling of a lone "-" on the command line. It will now be
 284   treated as a non-option unless an explicit specification was passed
 285   to GetOptions. See the manual.
 286   In the old implementation an error was signalled, so no
 287   compatibility breaks are expected from this change.
 288
 289 * Add $VERSION_STRING. This is the string form of $VERSION. Usually
 290   they are identical, unless it is a pre-release in which case
 291   $VERSION will be (e.g.) 2.2403 and $VERSION_STRING will be "2.24_03".
 292
 293 Changes in version 2.24
 294 -----------------------
 295
 296 * Add object oriented interface:
 297
 298     use Getopt::Long;
 299     $p = new Getopt::Long::Parser;
 300     $p->configure(...configuration options...);
 301     if ($p->getoptions(...options descriptions...)) ...
 302
 303 * Add configuration at 'use' time:
 304
 305     use Getopt::Long qw(:config no_ignore_case bundling);
 306
 307 * Add configuration options "gnu_getopt" and "gnu_compat".
 308
 309   "gnu_compat" controls whether --opt= is allowed, and what it should
 310   do. Without "gnu_compat", --opt= gives an error. With "gnu_compat",
 311   --opt= will give option "opt" and empty value.
 312   This is the way GNU getopt_long does it.
 313
 314   "gnu_getopt" is a short way of setting "gnu_compat bundling permute
 315   no_getopt_compat. With "gnu_getopt", command line handling should be
 316   fully compatible with GNU getopt_long.
 317
 318 * Correct warnings when the user specified an array or hash
 319   destination using a non-lowercase option, e.g. "I=s@".
 320
 321 * Correct ambiguous use of 'set' and 'reset' in the Configuration
 322   section of the documentation.
 323
 324 * Add configuration option "posix_default" to reset to defaults as if
 325   POSIXLY_CORRECT were set.
 326
 327 * Disallow "no" prefix on configuration options "default", "prefix" and
 328   "prefix_pattern".
 329
 330 * Add a section "Trouble Shooting" to the documentation, with
 331   frequently asked questions.
 332
 333 Changes in version 2.23
 334 -----------------------
 335
 336 * When a call-back routine issues 'die', messages starting with "!"
 337   are treated specially. Currently, only "!FINISH" is recognised (see
 338   the next bullet point). Other messages that start with "!" are
 339   ignored.
 340
 341 * Change 'die("FINISH") (see changes in 2.21) to die("!FINISH"). This
 342   is an incompatible change, but I guess noone is using this yet.
 343
 344 Changes in version 2.22
 345 -----------------------
 346
 347 * Fixes a bug in the combination of aliases and negation.
 348
 349   Old:  "foo|bar!" allowed negation on foo, but not on bar.
 350   New:  "foo|bar!" allows negation on foo and bar.
 351
 352   Caveat: "foo|f!", with bundling, issues the warning that negation on
 353   a short option is ignored. To obtain the desired behaviour, use
 354
 355         "foo!" => \$opt_foo, "f" => \$opt_foo
 356   or
 357         "foo|f" => \$opt_foo, "nofoo" => sub { $opt_foo = 0 }
 358
 359   Remember that this is _only_ required when bundling is in effect.
 360
 361 Changes in version 2.21
 362 -----------------------
 363
 364 * New documentation.
 365
 366 * User defined subroutines should use 'die' to signal errors.
 367
 368 * User defined subroutines can preliminary terminate options
 369   processing by calling die("FINISH");
 370
 371 * Correct erroneous install of Getopt::Long manpage.
 372   Previous versions seem to install Getopt::GetoptLong instead of
 373   Getopt::Long.
 374
 375 Changes in version 2.20
 376 -----------------------
 377
 378 * Prevent the magic argument "<>" from being interpreted as option
 379   starter characters if it is the first argument passed.
 380   To use the characters "<>" as option starters, pass "><" instead.
 381
 382 * Changed license: Getopt::Long may now also be used under the Perl
 383   Artistic License.
 384
 385 * Changed the file name of the distribution kit from "GetoptLong..."
 386   to "Getopt-Long-..." to match the standards.
 387
 388 Changes in version 2.19
 389 -----------------------
 390
 391 * Fix a warning bug with bundling_override.
 392
 393 There's no version 2.18
 394 -----------------------
 395
 396 Changes in version 2.17
 397 -----------------------
 398
 399 * Getopt::Long::config is renamed Getopt::Long::Configure. The old
 400   name will remain supported without being documented.
 401
 402 * Options can have the specifier '+' to denote that the option value
 403   must be incremented each time the option occurs on the command line.
 404   For example:
 405
 406      my $more = 2;
 407      Getopt::Long::Configure("bundling");
 408      GetOptions ("v+" => \$more);
 409      print STDOUT ("more = $more\n");
 410
 411   will print "more = 3" when called with "-v", "more = 4" when called
 412   with "-vv" (or "-v -v"), and so on.
 413
 414 * Getopt::Long now uses autoloading. This substantially reduces the
 415   resources required to 'use Getopt::Long' (about 100 lines of over
 416   1300 total).
 417
 418 * It is now documented that global option variables like $opt_foo
 419   need to be declared using 'use vars ...' when running under 'use
 420   strict'.
 421
 422 * To install, it is now required to use the official procedure:
 423
 424      perl Makefile.PL
 425      make
 426      make test
 427      make install
 428
 429 Changes in version 2.16
 430 -----------------------
 431
 432 * A couple of small additional fixes to the $` $& $' fixes.
 433
 434 * The option prefix can be set using config("prefix=...") or, more
 435   powerful, with config("prefix_pattern=..."); see the documentation
 436   for details.
 437
 438 * More 'perl -w' warnings eliminated for obscure cases of bundling.
 439
 440 This version is identical to 2.15, which was not released.
 441
 442 There's no version 2.14
 443 -----------------------
 444
 445 Changes in version 2.13
 446 -----------------------
 447
 448 * All regexps are changed to avoid the use of $`, $& and $'. Using one
 449   of these causes all pattern matches in the program to be much slower
 450   than necessary.
 451
 452 * Configuration errors are signalled using die() and will cause the
 453   program to be terminated (unless eval{...} or $SIG{__DIE__} is
 454   used).
 455
 456 * Option parsing errors are now signalled with calls to warn().
 457
 458 * In option bundles, numeric values may be embedded in the bundle
 459   (e.g. -al24w80).
 460
 461 * More 'perl -w' warnings eliminated for obscure cases of bundling.
 462
 463 * Removed non-standard version number matching. Version 1.121 is now
 464   more than 1.12 but less than 1.13.
 465
 466 Changes in version 2.12
 467 -----------------------
 468
 469 * A single question mark is allowed as an alias to an option, e.g.
 470
 471     GetOptions ("help|?", ...)
 472
 473 Changes in version 2.11
 474 -----------------------
 475
 476 * User linkage may be an object, provided the object is really a hash.
 477
 478   For example:
 479
 480     {   package Foo;
 481         sub new () { return bless {}; }
 482     }
 483
 484     my $linkage = Foo->new();
 485
 486     GetOptions ($linkage, ... );
 487
 488 * Some bug fixes in handling obscure cases of pass-through.
 489
 490 Changes in version 2.9
 491 ----------------------
 492
 493 * A new way to configure Getopt::Long. Instead of setting module local
 494   variables, routine Getopt::Long::config can be called with the names
 495   of options to be set or reset, e.g.
 496
 497     Getopt::Long::config ("no_auto_abbrev", "ignore_case");
 498
 499   Configuring by using the module local variables is deprecated, but
 500   it will continue to work for backwark compatibility.
 501
 502 Changes in version 2.6
 503 ----------------------
 504
 505 * Handle ignorecase even if autoabbrev is off.
 506
 507 * POD corrections.
 508
 509 Changes in version 2.4
 510 ----------------------
 511
 512 * Pass-through of unrecognized options. Makes it easy to write wrapper
 513   programs that process some of the command line options but pass the
 514   others to another program.
 515
 516 * Options can be of type HASH, now you can say
 517
 518     --define foo=bar
 519
 520   and have $opt_define{"foo"} set to "bar".
 521
 522 * An enhanced skeleton program, skel2.pl, that combines the power of
 523   Getopt::Long with Pod::Usage.
 524   Module Pod::Usage can be obtained from CPAN,
 525   http://www.perl.com/CPAN/authors/Brad_Appleton.
 526
 527 Possible incompatibility in version 2.4
 528 ---------------------------------------
 529
 530 Previous versions of Getopt::Long always downcased the option variable
 531 names when ignorecase was in effect. This bug has been corrected. As a
 532 consequence, &GetOptions ("Foo") will now set variable $opt_Foo
 533 instead of $opt_foo.
 534