Commit | Line | Data |
a19443d4 |
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 |
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 |
20 | * Bugfix: With gnu_compat, --foo= will no longer trigger "Option |
21 | requires an argument" but return the empty string. |
22 | |
8de02997 |
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 |
67 | Changes in version 2.35 |
68 | ----------------------- |
69 | |
554627f6 |
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 |
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 |
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 |
123 | Changes in version 2.33 |
124 | ----------------------- |
125 | |
79d0183a |
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 |
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 |
166 | GetOptions(...) or HelpMessage(2); |
167 | |
10933be5 |
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 |
172 | |
173 | * Some fixes with hashes and bundling. |
79d0183a |
174 | Thanks to Anders Johnson and Andrei Gnepp. |
10933be5 |
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 |
183 | |
184 | * Add FAQ: I "use GetOpt::Long;" (Windows) and now it doesn't work. |
185 | |
109cdaf9 |
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 |
195 | Changes in version 2.31 |
196 | ----------------------- |
197 | |
198 | * Fix a bug where calling the configure method on a |
9e01bed8 |
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 |
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 |
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 |
215 | |
216 | * Remove Carp. |
217 | |
bd444ebb |
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 |
229 | Changes in version 2.27 |
230 | ----------------------- |
231 | |
bd444ebb |
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 |
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 |
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 |
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 |
262 | * Lots of internal restructoring to make room for extensions. |
263 | |
264 | * Redesigned the regression tests. |
265 | |
bd444ebb |
266 | * Enhance the documentation to prevent common misunderstandings about |
267 | single character options. |
268 | |
7d1b667f |
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 |
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 | |