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