lib/Getopt/Long/CHANGES

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