This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Move File::Path from ext/ to cpan/
[perl5.git] / ext / 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