1 Changes in version 2.35
2 -----------------------
4 * long_prefix_pattern configuration variable.
6 prefix_pattern has now been complemented by a new configuration
7 option 'long_prefix_pattern' that allows the user to specify what
8 prefix patterns should have long option style sematics applied.
9 This will enable people to do things like
13 instead of forcing people to use the short option style
17 This enhancement was suggested and implemented by Yves Orton.
19 * Bugfix for Ticket #11377 (bug found and fixed by Ryan).
20 * Bugfix for Ticket #12380.
22 **************** WARNING -- EXPERIMENTAL CODE AHEAD ****************
24 * [Experimental] Options can take multiple values at once. E.g.,
26 --coordinates 52.2 16.4 --rgbcolor 255 255 149
28 To handle the above command line, the following call to GetOptions
31 GetOptions('coordinates=f{2}' => \@coor, 'rgbcolor=i{3}' => \@color);
33 You can specify the minimum and maximum number of values desired.
34 The syntax for this is similar to that of regular expression
35 patterns: { min , max }.
37 **************** END EXPERIMENTAL CODE ****************
39 Changes in version 2.34
40 -----------------------
42 * Auto-vivification of array and hash refs
44 If an option is specified to require an array or hash ref, and a
45 scalar reference is passed, this is auto-vivified to array or hash
51 GetOptions("foo=s@", \$var);
52 # Now $var->[0] eq "xx"
54 * Auto-supplied verbose and help options are no longer taken into
55 account when determining option ambiguity. This eliminates the
56 common problem that you suddenly get an ambiguous option warning
57 when you have an option "verbose" and run your program with "-v".
59 * Cosmetic changes in some error messages.
61 Changes in version 2.33
62 -----------------------
64 The following new features are marked experimental. This means that if
65 you are going to use them you _must_ watch out for the next release of
66 Getopt::Long to see if the API has changed.
68 * Getopt::Long can automatically handle --version and --help options
69 if the calling program did not specify a handler explicitly.
71 Two configuration parameters have been added: 'auto_help' (or
72 'help') and 'auto_version' (or 'version'). If set, Getopt::Long will
73 itself take care of --help and --version options. Otherwise,
74 everything is exactly as it was before.
76 The new features will be enabled by default for programs that
77 explicitly require version 2.3203 or later.
79 Getopt::Long uses module Pod::Usage to produce the help message from
80 the SYNOPSIS section of the program's POD.
82 Using a --help (or -?) command line option will write the SYNOPSIS
83 section of the program's POD to STDOUT, and exit with status 0.
84 However, an illegal option will produce the help text to STDERR,
85 and exit with status 2. This is in accordance with current
88 * Two subroutines can be exported on demand:
92 This subroutine prints the standard version message.
96 This subroutine prints the standard help message.
98 Both subroutines take the same arguments as Pod::Usage::pod2usage,
99 see its documentation for details.
103 use Getopt::Long 2.33 qw(GetOptions HelpMessage);
104 GetOptions(...) or HelpMessage(2);
106 * Subroutine Configure can now be exported on demand.
108 * Negatable options (with "!") now also support the "no-" prefix.
109 On request of Ed Avis.
111 * Some fixes with hashes and bundling.
112 Thanks to Anders Johnson and Andrei Gnepp.
113 Mandatory/optional status for hash values is now effective.
114 String valued options with no value now default to the empty string
116 NOTE: The hash options still remain more or less experimental.
118 * Fix a pass_through bug where the options terminator (normally "--")
119 was not passed through in @ARGV.
120 Thanks to Philippe Verdret.
122 * Add FAQ: I "use GetOpt::Long;" (Windows) and now it doesn't work.
124 Changes in version 2.32
125 -----------------------
127 * Fix a bug where the initial value for a optional numeric argument
128 was not used for value of a hash option.
130 * Remove 5.005 thread safety code. Getopt::Long is completely thread
131 safe when using the 5.8 ithreads.
133 Changes in version 2.31
134 -----------------------
136 * Fix a bug where calling the configure method on a
137 Getopt::Long::Parser object would bail out with
138 Undefined subroutine &Getopt::Long::Parser::Configure called at
139 Getopt/Long.pm line 186.
141 Changes in version 2.30
142 -----------------------
144 * Fix a problem where a 'die' from a 'warn' via a localized
145 $SIG{__WARN__} was not properly propagated from a callback.
146 Thanks to Diab Jerius.
148 Changes in version 2.29
149 -----------------------
151 * Fix a problem where options were not recognized when both
152 auto_abbrev and ignore_case were disabled. Thanks to Seth Robertson.
156 Changes in version 2.28
157 -----------------------
159 * When an option is specified more than once, a warning is generated
160 if perl is run with -w. This is a correction to 2.27, where it would
163 An example of duplicate specification is GetOptions('foo', 'foo'),
164 but also GetOptions('foo=s', 'foo') and GetOptions('Foo', 'foo')
165 (the latter only when ignore_case is in effect).
167 Changes in version 2.27
168 -----------------------
170 * You can now specify integer options to take an optional argument.
171 that defaults to a specific value. E.g., GetOptions('foo:5' => \$var)
172 will allow $var to get the value 5 when no value was specified with
173 the -foo option on the command line.
175 Instead of a value, a '+' may be specified. E.g.,
176 GetOptions('foo:+' => \$var) will allow $var to be incremented when
177 no value was specified with the -foo option on the command line.
179 * Fix several problems with internal and external use of 'die' and
182 * Fixed some bugs with subtle combinations of bundling_override and
185 * A callback routine that is associated with a hash-valued option will
186 now have both the hask key and the value passed. It used to get only
189 * Eliminated the use of autoloading. Autoloading kept generating
190 problems during development, and when using perlcc.
192 * Avoid errors on references when an option is found in error, e.g.
193 GetOptions('fo$@#' => \$var).
194 Thanks to Wolfgang Laun.
196 * When an option is specified more than once, an error is now
197 generated. E.g., GetOptions('foo', 'foo').
198 Thanks to Wolfgang Laun.
200 * Lots of internal restructoring to make room for extensions.
202 * Redesigned the regression tests.
204 * Enhance the documentation to prevent common misunderstandings about
205 single character options.
207 Changes in version 2.26
208 -----------------------
210 * New option type: 'o'. It accepts all kinds of integral numbers in
211 Perl style, including decimal (24), octal (012), hexadecimal (0x2f)
214 * Fix problem with getopt_compat not matching +foo=bar.
216 * Remove $VERSION_STRING for production versions.
218 Changes in version 2.25
219 -----------------------
221 * Change handling of a lone "-" on the command line. It will now be
222 treated as a non-option unless an explicit specification was passed
223 to GetOptions. See the manual.
224 In the old implementation an error was signalled, so no
225 compatibility breaks are expected from this change.
227 * Add $VERSION_STRING. This is the string form of $VERSION. Usually
228 they are identical, unless it is a pre-release in which case
229 $VERSION will be (e.g.) 2.2403 and $VERSION_STRING will be "2.24_03".
231 Changes in version 2.24
232 -----------------------
234 * Add object oriented interface:
237 $p = new Getopt::Long::Parser;
238 $p->configure(...configuration options...);
239 if ($p->getoptions(...options descriptions...)) ...
241 * Add configuration at 'use' time:
243 use Getopt::Long qw(:config no_ignore_case bundling);
245 * Add configuration options "gnu_getopt" and "gnu_compat".
247 "gnu_compat" controls whether --opt= is allowed, and what it should
248 do. Without "gnu_compat", --opt= gives an error. With "gnu_compat",
249 --opt= will give option "opt" and empty value.
250 This is the way GNU getopt_long does it.
252 "gnu_getopt" is a short way of setting "gnu_compat bundling permute
253 no_getopt_compat. With "gnu_getopt", command line handling should be
254 fully compatible with GNU getopt_long.
256 * Correct warnings when the user specified an array or hash
257 destination using a non-lowercase option, e.g. "I=s@".
259 * Correct ambiguous use of 'set' and 'reset' in the Configuration
260 section of the documentation.
262 * Add configuration option "posix_default" to reset to defaults as if
263 POSIXLY_CORRECT were set.
265 * Disallow "no" prefix on configuration options "default", "prefix" and
268 * Add a section "Trouble Shooting" to the documentation, with
269 frequently asked questions.
271 Changes in version 2.23
272 -----------------------
274 * When a call-back routine issues 'die', messages starting with "!"
275 are treated specially. Currently, only "!FINISH" is recognised (see
276 the next bullet point). Other messages that start with "!" are
279 * Change 'die("FINISH") (see changes in 2.21) to die("!FINISH"). This
280 is an incompatible change, but I guess noone is using this yet.
282 Changes in version 2.22
283 -----------------------
285 * Fixes a bug in the combination of aliases and negation.
287 Old: "foo|bar!" allowed negation on foo, but not on bar.
288 New: "foo|bar!" allows negation on foo and bar.
290 Caveat: "foo|f!", with bundling, issues the warning that negation on
291 a short option is ignored. To obtain the desired behaviour, use
293 "foo!" => \$opt_foo, "f" => \$opt_foo
295 "foo|f" => \$opt_foo, "nofoo" => sub { $opt_foo = 0 }
297 Remember that this is _only_ required when bundling is in effect.
299 Changes in version 2.21
300 -----------------------
304 * User defined subroutines should use 'die' to signal errors.
306 * User defined subroutines can preliminary terminate options
307 processing by calling die("FINISH");
309 * Correct erroneous install of Getopt::Long manpage.
310 Previous versions seem to install Getopt::GetoptLong instead of
313 Changes in version 2.20
314 -----------------------
316 * Prevent the magic argument "<>" from being interpreted as option
317 starter characters if it is the first argument passed.
318 To use the characters "<>" as option starters, pass "><" instead.
320 * Changed license: Getopt::Long may now also be used under the Perl
323 * Changed the file name of the distribution kit from "GetoptLong..."
324 to "Getopt-Long-..." to match the standards.
326 Changes in version 2.19
327 -----------------------
329 * Fix a warning bug with bundling_override.
331 There's no version 2.18
332 -----------------------
334 Changes in version 2.17
335 -----------------------
337 * Getopt::Long::config is renamed Getopt::Long::Configure. The old
338 name will remain supported without being documented.
340 * Options can have the specifier '+' to denote that the option value
341 must be incremented each time the option occurs on the command line.
345 Getopt::Long::Configure("bundling");
346 GetOptions ("v+" => \$more);
347 print STDOUT ("more = $more\n");
349 will print "more = 3" when called with "-v", "more = 4" when called
350 with "-vv" (or "-v -v"), and so on.
352 * Getopt::Long now uses autoloading. This substantially reduces the
353 resources required to 'use Getopt::Long' (about 100 lines of over
356 * It is now documented that global option variables like $opt_foo
357 need to be declared using 'use vars ...' when running under 'use
360 * To install, it is now required to use the official procedure:
367 Changes in version 2.16
368 -----------------------
370 * A couple of small additional fixes to the $` $& $' fixes.
372 * The option prefix can be set using config("prefix=...") or, more
373 powerful, with config("prefix_pattern=..."); see the documentation
376 * More 'perl -w' warnings eliminated for obscure cases of bundling.
378 This version is identical to 2.15, which was not released.
380 There's no version 2.14
381 -----------------------
383 Changes in version 2.13
384 -----------------------
386 * All regexps are changed to avoid the use of $`, $& and $'. Using one
387 of these causes all pattern matches in the program to be much slower
390 * Configuration errors are signalled using die() and will cause the
391 program to be terminated (unless eval{...} or $SIG{__DIE__} is
394 * Option parsing errors are now signalled with calls to warn().
396 * In option bundles, numeric values may be embedded in the bundle
399 * More 'perl -w' warnings eliminated for obscure cases of bundling.
401 * Removed non-standard version number matching. Version 1.121 is now
402 more than 1.12 but less than 1.13.
404 Changes in version 2.12
405 -----------------------
407 * A single question mark is allowed as an alias to an option, e.g.
409 GetOptions ("help|?", ...)
411 Changes in version 2.11
412 -----------------------
414 * User linkage may be an object, provided the object is really a hash.
419 sub new () { return bless {}; }
422 my $linkage = Foo->new();
424 GetOptions ($linkage, ... );
426 * Some bug fixes in handling obscure cases of pass-through.
428 Changes in version 2.9
429 ----------------------
431 * A new way to configure Getopt::Long. Instead of setting module local
432 variables, routine Getopt::Long::config can be called with the names
433 of options to be set or reset, e.g.
435 Getopt::Long::config ("no_auto_abbrev", "ignore_case");
437 Configuring by using the module local variables is deprecated, but
438 it will continue to work for backwark compatibility.
440 Changes in version 2.6
441 ----------------------
443 * Handle ignorecase even if autoabbrev is off.
447 Changes in version 2.4
448 ----------------------
450 * Pass-through of unrecognized options. Makes it easy to write wrapper
451 programs that process some of the command line options but pass the
452 others to another program.
454 * Options can be of type HASH, now you can say
458 and have $opt_define{"foo"} set to "bar".
460 * An enhanced skeleton program, skel2.pl, that combines the power of
461 Getopt::Long with Pod::Usage.
462 Module Pod::Usage can be obtained from CPAN,
463 http://www.perl.com/CPAN/authors/Brad_Appleton.
465 Possible incompatibility in version 2.4
466 ---------------------------------------
468 Previous versions of Getopt::Long always downcased the option variable
469 names when ignorecase was in effect. This bug has been corrected. As a
470 consequence, &GetOptions ("Foo") will now set variable $opt_Foo