1 Changes in version 2.38
2 -----------------------
4 * Bugfix for Ticket 35759: First arg to callback function evaluates
5 to false when used in bool context.
7 * Fix problem with prototypes of GetOptionsFrom* functions.
9 * Fix restoring default die handler.
11 * Bugfix for Ticket 24941: Autoabbrev with + incorrect.
13 Changes in version 2.37
14 -----------------------
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.
20 * Bugfix: With gnu_compat, --foo= will no longer trigger "Option
21 requires an argument" but return the empty string.
23 Changes in version 2.36
24 -----------------------
26 **************** WARNING -- EXPERIMENTAL CODE AHEAD ****************
28 * Parsing options from an arbitrary array
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.
34 use Getopt::Long qw(GetOptionsFromArray);
35 $ret = GetOptionsFromArray(\@myopts, ...);
37 * Parsing options from an arbitrary string
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.
43 use Getopt::Long qw(GetOptionsFromString);
44 $ret = GetOptionsFromString($optstring, ...);
46 Note that upon completion, no arguments may remain in the string.
47 If arguments may remain, call it in list context:
49 ($ret, $args) = GetOptionsFromString($optstring, ...);
51 @$args will have the remaining arguments.
53 **************** END EXPERIMENTAL CODE ****************
55 * Number values for options may include underscores for readability
56 (just like Perls numbers).
58 * Bugfix for Ticket #19432 (found and fixed by khali).
60 * Bugfix to make it cooperate with the bignum pragma. Thanks to Merijn
63 * Various small fixes to make the test suite run under 5.004_05.
65 * More examples (skeletons).
67 Changes in version 2.35
68 -----------------------
70 * long_prefix_pattern configuration variable.
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
79 instead of forcing people to use the short option style
83 This enhancement was suggested and implemented by Yves Orton.
85 * Bugfix for Ticket #11377 (bug found and fixed by Ryan).
86 * Bugfix for Ticket #12380.
88 * Options can take multiple values at once. E.g.,
90 --coordinates 52.2 16.4 --rgbcolor 255 255 149
92 To handle the above command line, the following call to GetOptions
95 GetOptions('coordinates=f{2}' => \@coor, 'rgbcolor=i{3}' => \@color);
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 }.
101 Changes in version 2.34
102 -----------------------
104 * Auto-vivification of array and hash refs
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
112 @ARGV = qw(--foo=xx);
113 GetOptions("foo=s@", \$var);
114 # Now $var->[0] eq "xx"
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".
121 * Cosmetic changes in some error messages.
123 Changes in version 2.33
124 -----------------------
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.
130 * Getopt::Long can automatically handle --version and --help options
131 if the calling program did not specify a handler explicitly.
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.
138 The new features will be enabled by default for programs that
139 explicitly require version 2.3203 or later.
141 Getopt::Long uses module Pod::Usage to produce the help message from
142 the SYNOPSIS section of the program's POD.
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
150 * Two subroutines can be exported on demand:
154 This subroutine prints the standard version message.
158 This subroutine prints the standard help message.
160 Both subroutines take the same arguments as Pod::Usage::pod2usage,
161 see its documentation for details.
165 use Getopt::Long 2.33 qw(GetOptions HelpMessage);
166 GetOptions(...) or HelpMessage(2);
168 * Subroutine Configure can now be exported on demand.
170 * Negatable options (with "!") now also support the "no-" prefix.
171 On request of Ed Avis.
173 * Some fixes with hashes and bundling.
174 Thanks to Anders Johnson and Andrei Gnepp.
175 Mandatory/optional status for hash values is now effective.
176 String valued options with no value now default to the empty string
178 NOTE: The hash options still remain more or less experimental.
180 * Fix a pass_through bug where the options terminator (normally "--")
181 was not passed through in @ARGV.
182 Thanks to Philippe Verdret.
184 * Add FAQ: I "use GetOpt::Long;" (Windows) and now it doesn't work.
186 Changes in version 2.32
187 -----------------------
189 * Fix a bug where the initial value for a optional numeric argument
190 was not used for value of a hash option.
192 * Remove 5.005 thread safety code. Getopt::Long is completely thread
193 safe when using the 5.8 ithreads.
195 Changes in version 2.31
196 -----------------------
198 * Fix a bug where calling the configure method on a
199 Getopt::Long::Parser object would bail out with
200 Undefined subroutine &Getopt::Long::Parser::Configure called at
201 Getopt/Long.pm line 186.
203 Changes in version 2.30
204 -----------------------
206 * Fix a problem where a 'die' from a 'warn' via a localized
207 $SIG{__WARN__} was not properly propagated from a callback.
208 Thanks to Diab Jerius.
210 Changes in version 2.29
211 -----------------------
213 * Fix a problem where options were not recognized when both
214 auto_abbrev and ignore_case were disabled. Thanks to Seth Robertson.
218 Changes in version 2.28
219 -----------------------
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
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).
229 Changes in version 2.27
230 -----------------------
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.
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.
241 * Fix several problems with internal and external use of 'die' and
244 * Fixed some bugs with subtle combinations of bundling_override and
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
251 * Eliminated the use of autoloading. Autoloading kept generating
252 problems during development, and when using perlcc.
254 * Avoid errors on references when an option is found in error, e.g.
255 GetOptions('fo$@#' => \$var).
256 Thanks to Wolfgang Laun.
258 * When an option is specified more than once, an error is now
259 generated. E.g., GetOptions('foo', 'foo').
260 Thanks to Wolfgang Laun.
262 * Lots of internal restructoring to make room for extensions.
264 * Redesigned the regression tests.
266 * Enhance the documentation to prevent common misunderstandings about
267 single character options.
269 Changes in version 2.26
270 -----------------------
272 * New option type: 'o'. It accepts all kinds of integral numbers in
273 Perl style, including decimal (24), octal (012), hexadecimal (0x2f)
276 * Fix problem with getopt_compat not matching +foo=bar.
278 * Remove $VERSION_STRING for production versions.
280 Changes in version 2.25
281 -----------------------
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.
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".
293 Changes in version 2.24
294 -----------------------
296 * Add object oriented interface:
299 $p = new Getopt::Long::Parser;
300 $p->configure(...configuration options...);
301 if ($p->getoptions(...options descriptions...)) ...
303 * Add configuration at 'use' time:
305 use Getopt::Long qw(:config no_ignore_case bundling);
307 * Add configuration options "gnu_getopt" and "gnu_compat".
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.
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.
318 * Correct warnings when the user specified an array or hash
319 destination using a non-lowercase option, e.g. "I=s@".
321 * Correct ambiguous use of 'set' and 'reset' in the Configuration
322 section of the documentation.
324 * Add configuration option "posix_default" to reset to defaults as if
325 POSIXLY_CORRECT were set.
327 * Disallow "no" prefix on configuration options "default", "prefix" and
330 * Add a section "Trouble Shooting" to the documentation, with
331 frequently asked questions.
333 Changes in version 2.23
334 -----------------------
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
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.
344 Changes in version 2.22
345 -----------------------
347 * Fixes a bug in the combination of aliases and negation.
349 Old: "foo|bar!" allowed negation on foo, but not on bar.
350 New: "foo|bar!" allows negation on foo and bar.
352 Caveat: "foo|f!", with bundling, issues the warning that negation on
353 a short option is ignored. To obtain the desired behaviour, use
355 "foo!" => \$opt_foo, "f" => \$opt_foo
357 "foo|f" => \$opt_foo, "nofoo" => sub { $opt_foo = 0 }
359 Remember that this is _only_ required when bundling is in effect.
361 Changes in version 2.21
362 -----------------------
366 * User defined subroutines should use 'die' to signal errors.
368 * User defined subroutines can preliminary terminate options
369 processing by calling die("FINISH");
371 * Correct erroneous install of Getopt::Long manpage.
372 Previous versions seem to install Getopt::GetoptLong instead of
375 Changes in version 2.20
376 -----------------------
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.
382 * Changed license: Getopt::Long may now also be used under the Perl
385 * Changed the file name of the distribution kit from "GetoptLong..."
386 to "Getopt-Long-..." to match the standards.
388 Changes in version 2.19
389 -----------------------
391 * Fix a warning bug with bundling_override.
393 There's no version 2.18
394 -----------------------
396 Changes in version 2.17
397 -----------------------
399 * Getopt::Long::config is renamed Getopt::Long::Configure. The old
400 name will remain supported without being documented.
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.
407 Getopt::Long::Configure("bundling");
408 GetOptions ("v+" => \$more);
409 print STDOUT ("more = $more\n");
411 will print "more = 3" when called with "-v", "more = 4" when called
412 with "-vv" (or "-v -v"), and so on.
414 * Getopt::Long now uses autoloading. This substantially reduces the
415 resources required to 'use Getopt::Long' (about 100 lines of over
418 * It is now documented that global option variables like $opt_foo
419 need to be declared using 'use vars ...' when running under 'use
422 * To install, it is now required to use the official procedure:
429 Changes in version 2.16
430 -----------------------
432 * A couple of small additional fixes to the $` $& $' fixes.
434 * The option prefix can be set using config("prefix=...") or, more
435 powerful, with config("prefix_pattern=..."); see the documentation
438 * More 'perl -w' warnings eliminated for obscure cases of bundling.
440 This version is identical to 2.15, which was not released.
442 There's no version 2.14
443 -----------------------
445 Changes in version 2.13
446 -----------------------
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
452 * Configuration errors are signalled using die() and will cause the
453 program to be terminated (unless eval{...} or $SIG{__DIE__} is
456 * Option parsing errors are now signalled with calls to warn().
458 * In option bundles, numeric values may be embedded in the bundle
461 * More 'perl -w' warnings eliminated for obscure cases of bundling.
463 * Removed non-standard version number matching. Version 1.121 is now
464 more than 1.12 but less than 1.13.
466 Changes in version 2.12
467 -----------------------
469 * A single question mark is allowed as an alias to an option, e.g.
471 GetOptions ("help|?", ...)
473 Changes in version 2.11
474 -----------------------
476 * User linkage may be an object, provided the object is really a hash.
481 sub new () { return bless {}; }
484 my $linkage = Foo->new();
486 GetOptions ($linkage, ... );
488 * Some bug fixes in handling obscure cases of pass-through.
490 Changes in version 2.9
491 ----------------------
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.
497 Getopt::Long::config ("no_auto_abbrev", "ignore_case");
499 Configuring by using the module local variables is deprecated, but
500 it will continue to work for backwark compatibility.
502 Changes in version 2.6
503 ----------------------
505 * Handle ignorecase even if autoabbrev is off.
509 Changes in version 2.4
510 ----------------------
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.
516 * Options can be of type HASH, now you can say
520 and have $opt_define{"foo"} set to "bar".
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.
527 Possible incompatibility in version 2.4
528 ---------------------------------------
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