This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Move Getopt::Long from ext/ to cpan/
[perl5.git] / cpan / Getopt-Long / CHANGES
CommitLineData
a19443d4
RGS
1Changes 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
6b3d80d9 13Changes in version 2.37
a4876a67 14-----------------------
6b3d80d9 15
a19443d4
RGS
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
6b3d80d9
SM
20* Bugfix: With gnu_compat, --foo= will no longer trigger "Option
21 requires an argument" but return the empty string.
22
8de02997
RGS
23Changes 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
d4ad7505
RGS
67Changes in version 2.35
68-----------------------
69
554627f6
RGS
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
8de02997 88* Options can take multiple values at once. E.g.,
d4ad7505
RGS
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
9e01bed8
JH
101Changes 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
10933be5
RGS
123Changes in version 2.33
124-----------------------
125
79d0183a
RGS
126The following new features are marked experimental. This means that if
127you are going to use them you _must_ watch out for the next release of
128Getopt::Long to see if the API has changed.
129
10933be5
RGS
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
79d0183a 165 use Getopt::Long 2.33 qw(GetOptions HelpMessage);
10933be5
RGS
166 GetOptions(...) or HelpMessage(2);
167
10933be5
RGS
168* Subroutine Configure can now be exported on demand.
169
170* Negatable options (with "!") now also support the "no-" prefix.
79d0183a 171 On request of Ed Avis.
10933be5
RGS
172
173* Some fixes with hashes and bundling.
79d0183a 174 Thanks to Anders Johnson and Andrei Gnepp.
10933be5
RGS
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.
79d0183a 182 Thanks to Philippe Verdret.
10933be5
RGS
183
184* Add FAQ: I "use GetOpt::Long;" (Windows) and now it doesn't work.
185
109cdaf9
JH
186Changes in version 2.32
187-----------------------
188
189* Fix a bug where the initial value for a optional numeric argument
190was not used for value of a hash option.
191
192* Remove 5.005 thread safety code. Getopt::Long is completely thread
193safe when using the 5.8 ithreads.
194
10933be5
RGS
195Changes in version 2.31
196-----------------------
197
198* Fix a bug where calling the configure method on a
9e01bed8
JH
199 Getopt::Long::Parser object would bail out with
200 Undefined subroutine &Getopt::Long::Parser::Configure called at
201 Getopt/Long.pm line 186.
10933be5
RGS
202
203Changes 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.
79d0183a 208 Thanks to Diab Jerius.
10933be5 209
eab822e5
JH
210Changes in version 2.29
211-----------------------
212
213* Fix a problem where options were not recognized when both
79d0183a 214 auto_abbrev and ignore_case were disabled. Thanks to Seth Robertson.
eab822e5
JH
215
216* Remove Carp.
217
bd444ebb
JH
218Changes 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
2d08fc49
JH
229Changes in version 2.27
230-----------------------
231
bd444ebb
JH
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
2d08fc49
JH
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
bd444ebb
JH
254* Avoid errors on references when an option is found in error, e.g.
255 GetOptions('fo$@#' => \$var).
79d0183a 256 Thanks to Wolfgang Laun.
bd444ebb
JH
257
258* When an option is specified more than once, an error is now
259 generated. E.g., GetOptions('foo', 'foo').
79d0183a 260 Thanks to Wolfgang Laun.
bd444ebb 261
2d08fc49
JH
262* Lots of internal restructoring to make room for extensions.
263
264* Redesigned the regression tests.
265
bd444ebb
JH
266* Enhance the documentation to prevent common misunderstandings about
267 single character options.
268
7d1b667f
JH
269Changes 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
7d1b667f
JH
280Changes 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
293Changes 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
333Changes 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
344Changes 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
361Changes 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
375Changes 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
388Changes in version 2.19
389-----------------------
390
391* Fix a warning bug with bundling_override.
392
393There's no version 2.18
394-----------------------
395
396Changes 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
429Changes 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
440This version is identical to 2.15, which was not released.
441
442There's no version 2.14
443-----------------------
444
445Changes 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
466Changes 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
473Changes 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
490Changes 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
502Changes in version 2.6
503----------------------
504
505* Handle ignorecase even if autoabbrev is off.
506
507* POD corrections.
508
509Changes 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
527Possible incompatibility in version 2.4
528---------------------------------------
529
530Previous versions of Getopt::Long always downcased the option variable
531names when ignorecase was in effect. This bug has been corrected. As a
532consequence, &GetOptions ("Foo") will now set variable $opt_Foo
533instead of $opt_foo.
534