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