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