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