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