lib/Getopt/Long/CHANGES

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