lib/Getopt/Long/CHANGES

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