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