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