lib/Getopt/Long/CHANGES

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