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
1 Changes 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
45 Changes in version 2.35
46 -----------------------
47
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
66 * Options can take multiple values at once. E.g.,
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
79 Changes 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
101 Changes in version 2.33
102 -----------------------
103
104 The following new features are marked experimental. This means that if
105 you are going to use them you _must_ watch out for the next release of
106 Getopt::Long to see if the API has changed.
107
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
143     use Getopt::Long 2.33 qw(GetOptions HelpMessage);
144     GetOptions(...) or HelpMessage(2);
145
146 * Subroutine Configure can now be exported on demand.
147
148 * Negatable options (with "!") now also support the "no-" prefix.
149   On request of Ed Avis.
150
151 * Some fixes with hashes and bundling.
152   Thanks to Anders Johnson and Andrei Gnepp.
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.
160   Thanks to Philippe Verdret.
161
162 * Add FAQ: I "use GetOpt::Long;" (Windows) and now it doesn't work.
163
164 Changes in version 2.32
165 -----------------------
166
167 * Fix a bug where the initial value for a optional numeric argument
168 was not used for value of a hash option.
169
170 * Remove 5.005 thread safety code. Getopt::Long is completely thread
171 safe when using the 5.8 ithreads.
172
173 Changes in version 2.31
174 -----------------------
175
176 * Fix a bug where calling the configure method on a
177   Getopt::Long::Parser object would bail out with 
178   Undefined subroutine &Getopt::Long::Parser::Configure called at
179   Getopt/Long.pm line 186.
180
181 Changes 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.
186   Thanks to Diab Jerius.
187
188 Changes in version 2.29
189 -----------------------
190
191 * Fix a problem where options were not recognized when both
192   auto_abbrev and ignore_case were disabled. Thanks to Seth Robertson.
193
194 * Remove Carp.
195
196 Changes 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
207 Changes in version 2.27
208 -----------------------
209
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
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
232 * Avoid errors on references when an option is found in error, e.g.
233   GetOptions('fo$@#' => \$var).
234   Thanks to Wolfgang Laun.
235
236 * When an option is specified more than once, an error is now
237   generated. E.g., GetOptions('foo', 'foo').
238   Thanks to Wolfgang Laun.
239
240 * Lots of internal restructoring to make room for extensions.
241
242 * Redesigned the regression tests.
243
244 * Enhance the documentation to prevent common misunderstandings about
245   single character options.
246
247 Changes 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
258 Changes 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
271 Changes 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
311 Changes 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
322 Changes 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
339 Changes 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
353 Changes 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
366 Changes in version 2.19
367 -----------------------
368
369 * Fix a warning bug with bundling_override.
370
371 There's no version 2.18
372 -----------------------
373
374 Changes 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
407 Changes 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
418 This version is identical to 2.15, which was not released.
419
420 There's no version 2.14
421 -----------------------
422
423 Changes 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
444 Changes 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
451 Changes 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
468 Changes 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
480 Changes in version 2.6
481 ----------------------
482
483 * Handle ignorecase even if autoabbrev is off. 
484
485 * POD corrections.
486
487 Changes 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
505 Possible incompatibility in version 2.4
506 ---------------------------------------
507
508 Previous versions of Getopt::Long always downcased the option variable
509 names when ignorecase was in effect. This bug has been corrected. As a
510 consequence, &GetOptions ("Foo") will now set variable $opt_Foo
511 instead of $opt_foo.
512