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