=head1 NAME
-perldelta - what's new for perl v5.6 (as of v5.005_62)
+perldelta - what's new for perl v5.6 (as of v5.005_64)
=head1 DESCRIPTION
=head2 Perl Source Incompatibilities
-Beware that any new warnings that have been added are B<not> considered
-incompatible changes.
+Beware that any new warnings that have been added or old ones
+that have been enhanced are B<not> considered incompatible changes.
Since all new warnings must be explicitly requested via the C<-w>
switch or the C<warnings> pragma, it is ultimately the programmer's
=over 4
+=item CHECK is a new keyword
+
+In addition to C<BEGIN>, C<INIT>, C<END>, C<DESTROY> and C<AUTOLOAD>,
+subroutines named C<CHECK> are now special. These are queued up during
+compilation and behave similar to END blocks, except they are called at
+the end of compilation rather than at the end of execution. They cannot
+be called directly.
+
+=item Treatment of list slices of undef has changed
+
+When taking a slice of a literal list (as opposed to a slice of
+an array or hash), Perl used to return an empty list if the
+result happened to be composed of all undef values.
+
+The new behavior is to produce an empty list if (and only if)
+the original list was empty. Consider the following example:
+
+ @a = (1,undef,undef,2)[2,1,2];
+
+The old behavior would have resulted in @a having no elements.
+The new behavior ensures it has three undefined elements.
+
+Note in particular that the behavior of slices of the following
+cases remains unchanged:
+
+ @a = ()[1,2];
+ @a = (getpwent)[7,0];
+ @a = (anything_returning_empty_list())[2,1,2];
+ @a = @b[2,1,2];
+ @a = @c{'a','b','c'};
+
+See L<perldata>.
+
=item Possibly changed pseudo-random number generator
In 5.005_0x and earlier, perl's rand() function used the C library
rand(3) function. As of 5.005_52, Configure tests for drand48(),
random(), and rand() (in that order) and picks the first one it finds.
Perl programs that depend on reproducing a specific set of pseudo-random
-numbers will now likely produce different output.
+numbers will now likely produce different output. You can use
+C<sh Configure -Drandfunc=rand> to obtain the old behavior.
=item Hashing function for hash keys has changed
In Perl 5.6 and later, C<"$$1"> always means C<"${$1}">.
-=item values(%h) and C<\(%h)> operate on aliases to values, not copies
+=item delete(), values() and C<\(%h)> operate on aliases to values, not copies
-each(), values() and hashes in a list context return the actual
+delete(), each(), values() and hashes in a list context return the actual
values in the hash, instead of copies (as they used to in earlier
versions). Typical idioms for using these constructs copy the
-returned values, but this is can make a significant difference when
+returned values, but this can make a significant difference when
creating references to the returned values.
Keys in the hash are still returned as copies when iterating on
-on a hash.
+a hash.
=item vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS
-vec() generates a run-time error if the BITS arguments is not
+vec() generates a run-time error if the BITS argument is not
a valid power-of-two integer.
=item Text of some diagnostic output has changed
has been removed, because it could potentially result in memory
leaks.
+=item Parenthesized not() behaves like a list operator
+
+The C<not> operator now falls under the "if it looks like a function,
+it behaves like a function" rule.
+
+As a result, the parenthesized form can be used with C<grep> and C<map>.
+The following construct used to be a syntax error before, but it works
+as expected now:
+
+ grep not($_), @things;
+
+On the other hand, using C<not> with a literal list slice may not
+work. The following previously allowed construct:
+
+ print not (1,2,3)[0];
+
+needs to be written with additional parentheses now:
+
+ print not((1,2,3)[0]);
+
+The behavior remains unaffected when C<not> is not followed by parentheses.
+
+=item Semantics of bareword prototype C<(*)> have changed
+
+Arguments prototyped as C<*> will now be visible within the subroutine
+as either a simple scalar or as a reference to a typeglob. Perl 5.005
+always coerced simple scalar arguments to a typeglob, which wasn't useful
+in situations where the subroutine must distinguish between a simple
+scalar and a typeglob. See L<perlsub/Prototypes>.
+
=back
=head2 C Source Incompatibilities
=item C<PERL_IMPLICIT_CONTEXT>
+PERL_IMPLICIT_CONTEXT is automatically enabled whenever Perl is built
+with one of -Dusethreads, -Dusemultiplicity, or both. It is not
+intended to be enabled by users at this time.
+
This new build option provides a set of macros for all API functions
such that an implicit interpreter/thread context argument is passed to
every API function. As a result of this, something like C<sv_setsv(foo,bar)>
Perl, whose interfaces continue to match those of prior versions
(but subject to the other options described here).
-PERL_IMPLICIT_CONTEXT is automatically enabled whenever Perl is built
-with one of -Dusethreads, -Dusemultiplicity, or both.
-
See L<perlguts/"The Perl API"> for detailed information on the
ramifications of building Perl using this option.
Note that these functions do B<not> constitute Perl's memory allocation API.
See L<perlguts/"Memory Allocation"> for further information about that.
-=item C<PL_na> and C<dTHR> Issues
-
-The C<PL_na> global is now thread local, so a C<dTHR> declaration is needed
-in the scope in which the global appears. XSUBs should handle this automatically,
-but if you have used C<PL_na> in support functions, you either need to
-change the C<PL_na> to a local variable (which is recommended), or put in
-a C<dTHR>.
-
=back
=head2 Compatible C Source API Changes
by running Configure with C<-Dflag>.
usemultiplicity
+
+ uselongdouble
usemorebits
uselargefiles
- [what others?]
-[TODO - Jarkko Hietaniemi <jhi@iki.fi>]
+=head2 -Dusethreads and -Duse64bits now more daring
+
+The Configure options enabling the use of threads and the use of
+64-bitness are now more daring in the sense that they no more have
+an explicit list of operating systems of known threads/64-bit
+capabilities. In other words: if your operating system has the
+necessary APIs, you should be able just to go ahead and use them.
+See also L<"64-bit support">.
+
+=head2 Long Doubles
+
+Some platforms have "long doubles", floating point numbers of even
+larger range than ordinary "doubles". To enable using long doubles for
+Perl's scalars, use -Duselongdouble.
+
+=head2 -Dusemorebits
+
+You can enable both -Duse64bits and -Dlongdouble by -Dusemorebits.
+See also L<"64-bit support">.
+
+=head2 -Duselargefiles
+
+Some platforms support large files, files larger than two gigabytes.
+See L<"Large file support"> for more information.
=head2 installusrbinperl
=head2 SOCKS support
You can use "Configure -Dusesocks" which causes Perl to probe
-for the SOCKS proxy protocol library, http://www.socks.nec.com/
+for the SOCKS (v5, not v4) proxy protocol library,
+http://www.socks.nec.com/
=head2 C<-A> flag
hints files have been processed but before the actual configuration
process starts. Run C<Configure -h> to find out the full C<-A> syntax.
+=head2 Enhanced Installation Directories
+
+The installation structure has been enriched to improve the support for
+maintaining multiple versions of perl, to provide locations for
+vendor-supplied modules and scripts, and to ease maintenance of
+locally-added modules and scripts. See the section on Installation
+Directories in the INSTALL file for complete details. For most users
+building and installing from source, the defaults should be fine.
+
=head1 Core Changes
=head2 Unicode and UTF-8 support
strings. The C<utf8> pragma enables this support in the current lexical
scope. See L<utf8> for more information.
+=head2 Interpreter threads
+
+WARNING: This is an experimental feature in a pre-alpha state. Use
+at your own risk.
+
+Perl 5.005_63 introduces the beginnings of support for running multiple
+interpreters concurrently in different threads. In conjunction with
+the perl_clone() API call, which can be used to selectively duplicate
+the state of any given interpreter, it is possible to compile a
+piece of code once in an interpreter, clone that interpreter
+one or more times, and run all the resulting interpreters in distinct
+threads.
+
+On Windows, this feature is used to emulate fork() at the interpreter
+level. See L<perlfork>.
+
+This feature is still in evolution. It is eventually meant to be used
+to selectively clone a subroutine and data reachable from that
+subroutine in a separate interpreter and run the cloned subroutine
+in a separate thread. Since there is no shared data between the
+interpreters, little or no locking will be needed (unless parts of
+the symbol table are explicitly shared). This is obviously intended
+to be an easy-to-use replacement for the existing threads support.
+
+Support for cloning interpreters must currently be manually enabled
+by defining the cpp macro USE_ITHREADS on non-Windows platforms.
+(See win32/Makefile for how to enable it on Windows.) The resulting
+perl executable will be functionally identical to one that was built
+without USE_ITHREADS, but the perl_clone() API call will only be
+available in the former.
+
+USE_ITHREADS enables Perl source code changes that provide a clear
+separation between the op tree and the data it operates with. The
+former is considered immutable, and can therefore be shared between
+an interpreter and all of its clones, while the latter is considered
+local to each interpreter, and is therefore copied for each clone.
+
+Note that building Perl with the -Dusemultiplicity Configure option
+is adequate if you wish to run multiple B<independent> interpreters
+concurrently in different threads. USE_ITHREADS only needs to be
+enabled if you wish to obtain access to perl_clone() and cloned
+interpreters.
+
+[XXX TODO - the Compiler backends may be broken when USE_ITHREADS is
+enabled.]
+
=head2 Lexically scoped warning categories
You can now control the granularity of warnings emitted by perl at a finer
[TODO - Tuomas Lukka <lukka@fas.harvard.edu>]
+=head2 File globbing implemented internally
+
+WARNING: This is currently an experimental feature. Interfaces and
+implementation are likely to change.
+
+Perl now uses the File::Glob implementation of the glob() operator
+automatically. This avoids using an external csh process and the
+problems associated with it.
+
=head2 Binary numbers supported
Binary numbers are now supported as literals, in s?printf formats, and
C<$foo[10]->{'foo'}>. Note however, that the arrow is still
required for C<foo(10)->('bar')>.
+=head2 exists() is supported on subroutine names
+
+The exists() builtin now works on subroutine names. A subroutine
+is considered to exist if it has been declared (even if implicitly).
+See L<perlfunc/exists> for examples.
+
+=head2 exists() and delete() are supported on array elements
+
+The exists() and delete() builtins now work on simple arrays as well.
+The behavior is similar to that on hash elements.
+
+exists() can be used to check whether an array element has been
+initialized without autovivifying it. If the array is tied, the
+EXISTS() method in the corresponding tied package will be invoked.
+
+delete() may be used to remove an element from the array and return
+it. The array element at that position returns to its unintialized
+state, so that testing for the same element with exists() will return
+false. If the element happens to be the one at the end, the size of
+the array also shrinks by one. If the array is tied, the DELETE() method
+in the corresponding tied package will be invoked.
+
+See L<perlfunc/exists> and L<perlfunc/delete> for examples.
+
=head2 syswrite() ease-of-use
The length argument of C<syswrite()> has become optional.
-=head2 Filehandles can be autovivified
+=head2 File and directory handles can be autovivified
-The construct C<open(my $fh, ...)> can be used to create filehandles
-more easily. The filehandle will be automatically closed at the end
-of the scope of $fh, provided there are no other references to it. This
-largely eliminates the need for typeglobs when opening filehandles
-that must be passed around, as in the following example:
+Similar to how constructs such as C<$x->[0]> autovivify a reference,
+handle constructors (open(), opendir(), pipe(), socketpair(), sysopen(),
+socket(), and accept()) now autovivify a file or directory handle
+if the handle passed to them is an uninitialized scalar variable. This
+allows the constructs such as C<open(my $fh, ...)> and C<open(local $fh,...)>
+to be used to create filehandles that will conveniently be closed
+automatically when the scope ends, provided there are no other references
+to them. This largely eliminates the need for typeglobs when opening
+filehandles that must be passed around, as in the following example:
sub myopen {
open my $fh, "@_"
If you have filesystems that support "large files" (files larger than
2 gigabytes), you may now also be able to create and access them from
Perl. You have to use Configure -Duselargefiles. Turning on the
-large file support turns on also the 64-bit support, for obvious reasons.
+large file support turns on also the 64-bit support on many platforms.
+Beware that unless your filesystem also supports "sparse files" seeking
+to umpteen petabytes may be unadvisable.
Note that in addition to requiring a proper file system to do large
files you may also need to adjust your per-process (or your
included with the standard Perl distribution) may also be of use, it
offers the getrlimit/setrlimit interface that can be used to adjust
process resource usage limits, including the maximum filesize limit.
-
+
=head2 Long doubles
In some systems you may be able to use long doubles to enhance the
-range of precision of your double precision floating point numbers
+range and precision of your double precision floating point numbers
(that is, Perl's numbers). Use Configure -Duselongdouble to enable
this support (if it is available).
=head2 "more bits"
-You can Configure -Dusemorebits to turn on both the 64-bit support
+You can "Configure -Dusemorebits" to turn on both the 64-bit support
and the long double support.
+=head2 Enhanced support for sort() subroutines
+
+Perl subroutines with a prototype of C<($$)> and XSUBs in general can
+now be used as sort subroutines. In either case, the two elements to
+be compared are passed as normal parameters in @_. See L<perlfunc/sort>.
+
+For unprototyped sort subroutines, the historical behavior of passing
+the elements to be compared as the global variables $a and $b remains
+unchanged.
+
=head2 Better syntax checks on parenthesized unary operators
Expressions such as:
change#4052
[TODO - Ilya Zakharevich <ilya@math.ohio-state.edu>]
-=head2 Experimental support form user-hooks in @INC
+=head2 Experimental support for user-hooks in @INC
[TODO - Ken Fox <kfox@ford.com>]
=head2 New variable $^C reflects C<-c> switch
-C<$^C> contains a boolean that reflects whether perl is being run
+C<$^C> has a boolean value that reflects whether perl is being run
in compile-only mode (i.e. via the C<-c> switch). Since
BEGIN blocks are executed under such conditions, this variable
enables perl code to determine whether actions that make sense
=head2 E<lt>HANDLEE<gt> on empty files
-With C<$/> set to C<undef>, slurping an empty file returns a string of
+With C<$/> set to C<undef>, "slurping" an empty file returns a string of
zero length (instead of C<undef>, as it used to) the first time the
-HANDLE is read. Further reads yield C<undef>.
+HANDLE is read after C<$/> is set to C<undef>. Further reads yield
+C<undef>.
This means that the following will append "foo" to an empty file (it used
to do nothing):
The mechanism for reporting such errors has been reimplemented
to queue compile-time errors and report them at the end of the
compilation as true errors rather than as warnings. This fixes
-error messages that used to leak through as warnings when code
-was compiled at run time using C<eval STRING>, and allows such
-errors to be reliably trapped using __DIE__ hooks.
+cases where error messages leaked through in the form of warnings
+when code was compiled at run time using C<eval STRING>, and
+also allows such errors to be reliably trapped using __DIE__ hooks.
=head2 Automatic flushing of output buffers
on C<OLD>. Formerly, it would have returned the data from the start
of the following disk block instead.
+=head2 eof() has the same old magic as <>
+
+C<eof()> would return true if no attempt to read from C<E<lt>E<gt>> had
+yet been made. C<eof()> has been changed to have a little magic of its
+own, it now opens the C<E<lt>E<gt>> files.
+
=head2 system(), backticks and pipe open now reflect exec() failure
On Unix and similar platforms, system(), qx() and open(FOO, "cmd |")
since the exec() happened to be in a different process.
The child process now communicates with the parent about the
-error in launching the external command, which allow these
+error in launching the external command, which allows these
constructs to return with their usual error value and set $!.
=head2 Implicitly closed filehandles are safer
When applied to a pseudo-hash element, exists() now reports whether
the specified value exists, not merely if the key is valid.
+delete() now works on pseudo-hashes. When given a pseudo-hash element
+or slice it deletes the values corresponding to the keys (but not the keys
+themselves). See L<perlref/"Pseudo-hashes: Using an array as a hash">.
+
=head2 C<goto &sub> and AUTOLOAD
-C<goto &sub> construct works correctly when C<&sub> happens
+The C<goto &sub> construct works correctly when C<&sub> happens
to be autoloaded.
=head2 C<-bareword> allowed under C<use integer>
=head2 C<sort $coderef @foo> allowed
sort() did not accept a subroutine reference as the comparison
-function in earlier versions. This has been fixed.
+function in earlier versions. This is now permitted.
=head2 Failures in DESTROY()
=head2 Locale bugs fixed
-change#3542
-[TODO - Jarkko Hietaniemi <jhi@iki.fi>]
+printf() and sprintf() previously reset the numeric locale
+back to the default "C" locale. This has been fixed.
+
+Numbers formatted according to the local numeric locale
+(such as using a decimal comma instead of a decimal dot) caused
+"isn't numeric" warnings, even while the operations accessing
+those numbers produced correct results. The warnings are gone.
=head2 Memory leaks
Prior versions used to run BEGIN B<and> END blocks when Perl was
run in compile-only mode. Since this is typically not the expected
-behavior, END blocks are not executed when the C<-c> switch
+behavior, END blocks are not executed anymore when the C<-c> switch
is used.
-Note that something resembling the previous behavior can still be
-obtained by putting C<BEGIN { $^C = 0; exit; } at the very end of
-the top level source file.
+See L<CHECK blocks> for how to run things when the compile phase ends.
=head2 Potential to leak DATA filehandles
=head2 Other fixes for better diagnostics
-Line numbers are suppressed no more (under most likely circumstances)
+Line numbers are no longer suppressed (under most likely circumstances)
during the global destruction phase.
Diagnostics emitted from code running in threads other than the main
$foo::a and $foo::b are now exempt from "possible typo" warnings only
if sort() is encountered in package foo.
-Unrecognized alphabetic escapes encountered when parsing quoting
+Unrecognized alphabetic escapes encountered when parsing quote
constructs now generate a warning, since they may take on new
semantics in later versions of Perl.
=head2 Simple sort() using { $a <=> $b } and the like are optimized
-Many common sort() opertions using a simple inlined block are now
+Many common sort() operations using a simple inlined block are now
optimized for faster performance.
=head2 Optimized assignments to lexical variables
=head2 DOS
-[TODO - Laszlo Molnar <laszlo.molnar@eth.ericsson.se>]
+=over 4
+
+=item *
+
+Perl now works with djgpp 2.02 (and 2.03 alpha).
+
+=item *
+
+Environment variable names are not converted to uppercase any more.
+
+=item *
+
+Wrong exit code from backticks now fixed.
+
+=item *
+
+This port is still using its own builtin globbing.
+
+=back
=head2 OS/2
The C<Shell> module is supported.
+Rudimentary support for building under command.com in Windows 95
+has been added.
+
+Scripts are read in binary mode by default to allow ByteLoader (and
+the filter mechanism in general) to work properly. For compatibility,
+the DATA filehandle will be set to text mode if a carriage return is
+detected at the end of the line containing the __END__ or __DATA__
+token; if not, the DATA filehandle will be left open in binary mode.
+Earlier versions always opened the DATA filehandle in text mode.
+
[TODO - GSAR]
=head1 New tests
Verify operations that access pad objects (lexicals and temporaries).
+=item op/exists_sub
+
+Verify C<exists &sub> operations.
+
=back
=head1 Modules and Pragmata
=item B
+The Perl Compiler suite has been extensively reworked for this
+release.
+
[TODO - Vishal Bhatia <vishal@gol.com>,
Nick Ing-Simmons <nick@ni-s.u-net.com>]
The ByteLoader is a dedicated extension to generate and run
Perl bytecode. See L<ByteLoader>.
-=item B
+=item constant
-The Perl Compiler suite has been extensively reworked for this
-release.
+References can now be used.
-=item constant
+The new version also allows a leading underscore in constant names, but
+disallows a double leading underscore (as in "__LINE__"). Some other names
+are disallowed or warned against, including BEGIN, END, etc. Some names
+which were forced into main:: used to fail silently in some cases; now they're
+fatal (outside of main::) and an optional warning (inside of main::).
+The ability to detect whether a constant had been set with a given name has
+been added.
-References can now be used. See L<constant>.
+See L<constant>.
=item charnames
=item Data::Dumper
A C<Maxdepth> setting can be specified to avoid venturing
-too deeply into data structures that may be very deep.
-See L<Data::Dumper>.
+too deeply into deep data structures. See L<Data::Dumper>.
Dumping C<qr//> objects works correctly.
=item DB_File
-[TODO - Paul Marquess <paul.marquess@bt.com>]
+DB_File can now be built with Berkeley DB versions 1, 2 or 3.
+See C<ext/DB_File/Changes>.
=item Devel::DProf
-Devel::DProf, a Perl source code profiler has been added. See L<DProf>.
+Devel::DProf, a Perl source code profiler has been added. See
+L<Devel::DProf> and L<dprofpp>.
=item Dumpvalue
-Added Dumpvalue module provides screen dumps of Perl data.
+The Dumpvalue module provides screen dumps of Perl data.
=item Benchmark
+Overall, Benchmark results exhibit lower average error and better timing
+accuracy.
+
You can now run tests for I<n> seconds instead of guessing the right
number of tests to run: e.g. timethese(-5, ...) will run each
code for at least 5 CPU seconds. Zero as the "number of repetitions"
means "for at least 3 CPU seconds". The output format has also
changed. For example:
-use Benchmark;$x=3;timethese(-5,{a=>sub{$x*$x},b=>sub{$x**2}})
+ use Benchmark;$x=3;timethese(-5,{a=>sub{$x*$x},b=>sub{$x**2}})
will now output something like this:
-Benchmark: running a, b, each for at least 5 CPU seconds...
- a: 5 wallclock secs ( 5.77 usr + 0.00 sys = 5.77 CPU) @ 200551.91/s (n=1156516)
- b: 4 wallclock secs ( 5.00 usr + 0.02 sys = 5.02 CPU) @ 159605.18/s (n=800686)
+ Benchmark: running a, b, each for at least 5 CPU seconds...
+ a: 5 wallclock secs ( 5.77 usr + 0.00 sys = 5.77 CPU) @ 200551.91/s (n=1156516)
+ b: 4 wallclock secs ( 5.00 usr + 0.02 sys = 5.02 CPU) @ 159605.18/s (n=800686)
New features: "each for at least N CPU seconds...", "wallclock secs",
and the "@ operations/CPU second (n=operations)".
-change#4265,4266,4292
-[TODO - Barrie Slaymaker <barries@slaysys.com>]
+timethese() now returns a reference to a hash of Benchmark objects containing
+the test results, keyed on the names of the tests.
+
+timethis() now returns the iterations field in the Benchmark result object
+instead of 0.
+
+timethese(), timethis(), and the new cmpthese() (see below) can also take
+a format specifier of 'none' to suppress output.
+
+A new function countit() is just like timeit() except that it takes a
+TIME instead of a COUNT.
+
+A new function cmpthese() prints a chart comparing the results of each test
+returned from a timethese() call. For each possible pair of tests, the
+percentage speed difference (iters/sec or seconds/iter) is shown.
+
+For other details, see L<Benchmark>.
=item Devel::Peek
=item Fcntl
More Fcntl constants added: F_SETLK64, F_SETLKW64, O_LARGEFILE for
-large (more than 4G) file access (64-bit support is not yet
-working, though, so no need to get overly excited), Free/Net/OpenBSD
-locking behaviour flags F_FLOCK, F_POSIX, Linux F_SHLCK, and
-O_ACCMODE: the mask of O_RDONLY, O_WRONLY, and O_RDWR.
+large file (more than 4GB) access Note that the O_LARGEFILE is
+automatically/transparently added to sysopen() flags if large file
+support has been configured), Free/Net/OpenBSD locking behaviour flags
+F_FLOCK, F_POSIX, Linux F_SHLCK, and O_ACCMODE: the combined mask of
+O_RDONLY, O_WRONLY, and O_RDWR. Also SEEK_SET, SEEK_CUR, and SEEK_END
+added for one-stop shopping of the seek/sysseek constants.
=item File::Compare
File::Find now works correctly when the wanted() function is either
autoloaded or is a symbolic reference.
-A bug that cause File::Find to lose track of the working directory
+A bug that caused File::Find to lose track of the working directory
when pruning top-level directories has been fixed.
+File::Find now also supports several other options to control its
+behavior. It can follow symbolic links if the C<follow> option is
+specified. Enabling the C<no_chdir> option will make File::Find skip
+changing the current directory when walking directories. The C<untaint>
+flag can be useful when running with taint checks enabled.
+
+See L<File::Find>.
+
+=item File::Glob
+
+This extension implements BSD-style file globbing. By default,
+it will also be used for the internal implementation of the glob()
+operator. See L<File::Glob>.
+
=item File::Spec
New methods have been added to the File::Spec module: devnull() returns
=item Getopt::Long
-[TODO - Johan Vromans <jvromans@squirrel.nl>]
+Getopt::Long licensing has changed to allow the Perl Artistic License
+as well as the GPL. It used to be GPL only, which got in the way of
+non-GPL applications that wanted to use Getopt::Long.
+
+Getopt::Long encourages the use of Pod::Usage to produce help
+messages. For example:
+
+ use Getopt::Long;
+ use Pod::Usage;
+ my $man = 0;
+ my $help = 0;
+ GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
+ pod2usage(1) if $help;
+ pod2usage(-exitstatus => 0, -verbose => 2) if $man;
+
+ __END__
+
+ =head1 NAME
+
+ sample - Using GetOpt::Long and Pod::Usage
+
+ =head1 SYNOPSIS
+
+ sample [options] [file ...]
+
+ Options:
+ -help brief help message
+ -man full documentation
+
+ =head1 OPTIONS
+
+ =over 8
+
+ =item B<-help>
+
+ Print a brief help message and exits.
+
+ =item B<-man>
+
+ Prints the manual page and exits.
+
+ =back
+
+ =head1 DESCRIPTION
+
+ B<This program> will read the given input file(s) and do someting
+ useful with the contents thereof.
+
+ =cut
+
+See L<Pod::Usage> for details.
+
+A bug that prevented the non-option call-back E<lt>E<gt> from being
+specified as the first argument has been fixed.
+
+To specify the characters E<lt> and E<gt> as option starters, use
+E<gt>E<lt>. Note, however, that changing option starters is strongly
+deprecated.
=item IO
Java Perl Lingo is now distributed with Perl. See jpl/README
for more information.
+=item lib
+
+C<use lib> now weeds out any trailing duplicate entries.
+C<no lib> removes all named entries.
+
=item Math::BigInt
-The logical operations C<E<lt>E<lt>>, C<E<gt>E<gt>>, C<&>, C<|>,
+The bitwise operations C<E<lt>E<lt>>, C<E<gt>E<gt>>, C<&>, C<|>,
and C<~> are now supported on bigints.
=item Math::Complex
=item Time::Local
The timelocal() and timegm() functions used to silently return bogus
-results when the date exceeded the machine's integer range. They
+results when the date fell outside the machine's integer range. They
now consistently croak() if the date falls in an unsupported range.
=item Win32
The new Win32::GetFullPathName(FILENAME) returns the full absolute
pathname for FILENAME in scalar context. In list context it returns
a two-element list containing the fully qualified directory name and
-the filename.
+the filename. See L<Win32>.
=item DBM Filters
=head2 Pragmata
-C<use attrs> is now obsolescent, and is only provided for
+C<use attrs> is now obsolete, and is only provided for
backward-compatibility. It's been replaced by the C<sub : attributes>
syntax. See L<perlsub/"Subroutine Attributes"> and L<attributes>.
Lexical warnings pragma, C<use warnings;>, to control optional warnings.
See L<perllexwarn>.
-C<use filetest> to control the behaviour of filetests (C<-r> C<-w> ...).
-Currently only one subpragma implemented, "use filetest 'access';",
-that enables the use of access(2) or equivalent to check
-permissions instead of using stat(2) as usual. This matters
-in filesystems where there are ACLs (access control lists): the
-stat(2) might lie, but access(2) knows better.
+C<use filetest> to control the behaviour of filetests (C<-r> C<-w>
+...). Currently only one subpragma implemented, "use filetest
+'access';", that uses access(2) or equivalent to check permissions
+instead of using stat(2) as usual. This matters in filesystems
+where there are ACLs (access control lists): the stat(2) might lie,
+but access(2) knows better.
=head1 Utility Changes
=over 4
+=item perlcompile.pod
+
+An introduction to using the Perl Compiler suite.
+
+=item perlfilter.pod
+
+An introduction to writing Perl source filters.
+
+=item perlhack.pod
+
+Some guidelines for hacking the Perl source code.
+
=item perlopentut.pod
A tutorial on using open() effectively.
A tutorial on managing class data for object modules.
-=item perlcompile.pod
+=back
-An introduction to using the Perl Compiler suite.
+=head1 New or Changed Diagnostics
-=back
+=over 4
+
+=item "%s" variable %s masks earlier declaration in same %s
-=head1 New Diagnostics
+(W) A "my" or "our" variable has been redeclared in the current scope or statement,
+effectively eliminating all access to the previous instance. This is almost
+always a typographical error. Note that the earlier variable will still exist
+until the end of the scope or until all closure referents to it are
+destroyed.
=item "my sub" not yet implemented
(F) Lexically scoped subroutines are not yet implemented. Don't try that
yet.
+=item "our" variable %s redeclared
+
+(W) You seem to have already declared the same global once before in the
+current lexical scope.
+
+=item '!' allowed only after types %s
+
+(F) The '!' is allowed in pack() and unpack() only after certain types.
+See L<perlfunc/pack>.
+
+=item / cannot take a count
+
+(F) You had an unpack template indicating a counted-length string,
+but you have also specified an explicit size for the string.
+See L<perlfunc/pack>.
+
+=item / must be followed by a, A or Z
+
+(F) You had an unpack template indicating a counted-length string,
+which must be followed by one of the letters a, A or Z
+to indicate what sort of string is to be unpacked.
+See L<perlfunc/pack>.
+
+=item / must be followed by a*, A* or Z*
+
+(F) You had a pack template indicating a counted-length string,
+Currently the only things that can have their length counted are a*, A* or Z*.
+See L<perlfunc/pack>.
+
+=item / must follow a numeric type
+
+(F) You had an unpack template that contained a '#',
+but this did not follow some numeric unpack specification.
+See L<perlfunc/pack>.
+
+=item /%s/: Unrecognized escape \\%c passed through
+
+(W) You used a backslash-character combination which is not recognized
+by Perl. This combination appears in an interpolated variable or a
+C<'>-delimited regular expression. The character was understood literally.
+
+=item /%s/: Unrecognized escape \\%c in character class passed through
+
+(W) You used a backslash-character combination which is not recognized
+by Perl inside character classes. The character was understood literally.
+
+=item /%s/ should probably be written as "%s"
+
+(W) You have used a pattern where Perl expected to find a string,
+as in the first argument to C<join>. Perl will treat the true
+or false result of matching the pattern against $_ as the string,
+which is probably not what you had in mind.
+
+=item %s() called too early to check prototype
+
+(W) You've called a function that has a prototype before the parser saw a
+definition or declaration for it, and Perl could not check that the call
+conforms to the prototype. You need to either add an early prototype
+declaration for the subroutine in question, or move the subroutine
+definition ahead of the call to get proper prototype checking. Alternatively,
+if you are certain that you're calling the function correctly, you may put
+an ampersand before the name to avoid the warning. See L<perlsub>.
+
+=item %s argument is not a HASH or ARRAY element
+
+(F) The argument to exists() must be a hash or array element, such as:
+
+ $foo{$bar}
+ $ref->[12]->["susie"]
+
+=item %s argument is not a HASH or ARRAY element or slice
+
+(F) The argument to delete() must be either a hash or array element, such as:
+
+ $foo{$bar}
+ $ref->[12]->["susie"]
+
+or a hash or array slice, such as:
+
+ @foo[$bar, $baz, $xyzzy]
+ @{$ref->[12]}{"susie", "queue"}
+
+=item %s argument is not a subroutine name
+
+(F) The argument to exists() for C<exists &sub> must be a subroutine
+name, and not a subroutine call. C<exists &sub()> will generate this error.
+
=item %s package attribute may clash with future reserved word: %s
(W) A lowercase attribute name was used that had a package-specific handler.
doesn't yet. Perhaps you should use a mixed-case attribute name, instead.
See L<attributes>.
-=item /%s/: Unrecognized escape \\%c passed through
+=item (in cleanup) %s
-(W) You used a backslash-character combination which is not recognized
-by Perl. This combination appears in an interpolated variable or a
-C<'>-delimited regular expression.
+(W) This prefix usually indicates that a DESTROY() method raised
+the indicated exception. Since destructors are usually called by
+the system at arbitrary points during execution, and often a vast
+number of times, the warning is issued only once for any number
+of failures that would otherwise result in the same message being
+repeated.
+
+Failure of user callbacks dispatched using the C<G_KEEPERR> flag
+could also result in this warning. See L<perlcall/G_KEEPERR>.
+
+=item <> should be quotes
+
+(F) You wrote C<require E<lt>fileE<gt>> when you should have written
+C<require 'file'>.
+
+=item Attempt to join self
+
+(F) You tried to join a thread from within itself, which is an
+impossible task. You may be joining the wrong thread, or you may
+need to move the join() to some other thread.
+
+=item Bad evalled substitution pattern
+
+(F) You've used the /e switch to evaluate the replacement for a
+substitution, but perl found a syntax error in the code to evaluate,
+most likely an unexpected right brace '}'.
+
+=item Bad realloc() ignored
+
+(S) An internal routine called realloc() on something that had never been
+malloc()ed in the first place. Mandatory, but can be disabled by
+setting environment variable C<PERL_BADFREE> to 1.
+
+=item Binary number > 0b11111111111111111111111111111111 non-portable
+
+(W) The binary number you specified is larger than 2**32-1
+(4294967295) and therefore non-portable between systems. See
+L<perlport> for more on portability concerns.
+
+=item Bit vector size > 32 non-portable
+
+(W) Using bit vector sizes larger than 32 is non-portable.
+
+=item Buffer overflow in prime_env_iter: %s
+
+(W) A warning peculiar to VMS. While Perl was preparing to iterate over
+%ENV, it encountered a logical name or symbol definition which was too long,
+so it was truncated to the string shown.
+
+=item Can't check filesystem of script "%s"
+
+(P) For some reason you can't check the filesystem of the script for nosuid.
+
+=item Can't declare class for non-scalar %s in "%s"
+
+(S) Currently, only scalar variables can declared with a specific class
+qualifier in a "my" or "our" declaration. The semantics may be extended
+for other types of variables in future.
+
+=item Can't declare %s in "%s"
+
+(F) Only scalar, array, and hash variables may be declared as "my" or
+"our" variables. They must have ordinary identifiers as names.
+
+=item Can't ignore signal CHLD, forcing to default
+
+(W) Perl has detected that it is being run with the SIGCHLD signal
+(sometimes known as SIGCLD) disabled. Since disabling this signal
+will interfere with proper determination of exit status of child
+processes, Perl has reset the signal to its default value.
+This situation typically indicates that the parent program under
+which Perl may be running (e.g. cron) is being very careless.
+
+=item Can't modify non-lvalue subroutine call
+
+(F) Subroutines meant to be used in lvalue context should be declared as
+such, see L<perlsub/"Lvalue subroutines">.
+
+=item Can't read CRTL environ
+
+(S) A warning peculiar to VMS. Perl tried to read an element of %ENV
+from the CRTL's internal environment array and discovered the array was
+missing. You need to figure out where your CRTL misplaced its environ
+or define F<PERL_ENV_TABLES> (see L<perlvms>) so that environ is not searched.
+
+=item Can't remove %s: %s, skipping file
+
+(S) You requested an inplace edit without creating a backup file. Perl
+was unable to remove the original file to replace it with the modified
+file. The file was left unmodified.
+
+=item Can't return %s from lvalue subroutine
+
+(F) Perl detected an attempt to return illegal lvalues (such
+as temporary or readonly values) from a subroutine used as an lvalue.
+This is not allowed.
+
+=item Can't weaken a nonreference
+
+(F) You attempted to weaken something that was not a reference. Only
+references can be weakened.
+
+=item Character class [:%s:] unknown
+
+(F) The class in the character class [: :] syntax is unknown.
+See L<perlre>.
+
+=item Character class syntax [%s] belongs inside character classes
+
+(W) The character class constructs [: :], [= =], and [. .] go
+I<inside> character classes, the [] are part of the construct,
+for example: /[012[:alpha:]345]/. Note that [= =] and [. .]
+are not currently implemented; they are simply placeholders for
+future extensions.
+
+=item Constant is not %s reference
+
+(F) A constant value (perhaps declared using the C<use constant> pragma)
+is being dereferenced, but it amounts to the wrong type of reference. The
+message indicates the type of reference that was expected. This usually
+indicates a syntax error in dereferencing the constant value.
+See L<perlsub/"Constant Functions"> and L<constant>.
+
+=item constant(%s): %%^H is not localized
+
+(F) When setting compile-time-lexicalized hash %^H one should set the
+corresponding bit of $^H as well.
+
+=item constant(%s): %s
+
+(F) Compile-time-substitutions (such as overloaded constants and
+character names) were not correctly set up.
+
+=item defined(@array) is deprecated
+
+(D) defined() is not usually useful on arrays because it checks for an
+undefined I<scalar> value. If you want to see if the array is empty,
+just use C<if (@array) { # not empty }> for example.
+
+=item defined(%hash) is deprecated
+
+(D) defined() is not usually useful on hashes because it checks for an
+undefined I<scalar> value. If you want to see if the hash is empty,
+just use C<if (%hash) { # not empty }> for example.
+
+=item Did not produce a valid header
+
+See Server error.
+
+=item Did you mean "local" instead of "our"?
+
+(W) Remember that "our" does not localize the declared global variable.
+You have declared it again in the same lexical scope, which seems superfluous.
+
+=item Document contains no data
+
+See Server error.
+
+=item entering effective %s failed
+
+(F) While under the C<use filetest> pragma, switching the real and
+effective uids or gids failed.
+
+=item false [] range "%s" in regexp
+
+(W) A character class range must start and end at a literal character, not
+another character class like C<\d> or C<[:alpha:]>. The "-" in your false
+range is interpreted as a literal "-". Consider quoting the "-", "\-".
+See L<perlre>.
=item Filehandle %s opened only for output
(W) You tried to read from a filehandle opened only for writing. If you
-intended it to be a read-write filehandle, you needed to open it with
+intended it to be a read/write filehandle, you needed to open it with
"+E<lt>" or "+E<gt>" or "+E<gt>E<gt>" instead of with "E<lt>" or nothing. If
you intended only to read from the file, use "E<lt>". See
L<perlfunc/open>.
+=item flock() on closed filehandle %s
+
+(W) The filehandle you're attempting to flock() got itself closed some
+time before now. Check your logic flow. flock() operates on filehandles.
+Are you attempting to call flock() on a dirhandle by the same name?
+
+=item Global symbol "%s" requires explicit package name
+
+(F) You've said "use strict vars", which indicates that all variables
+must either be lexically scoped (using "my"), declared beforehand using
+"our", or explicitly qualified to say which package the global variable
+is in (using "::").
+
+=item Hexadecimal number > 0xffffffff non-portable
+
+(W) The hexadecimal number you specified is larger than 2**32-1
+(4294967295) and therefore non-portable between systems. See
+L<perlport> for more on portability concerns.
+
+=item Ill-formed CRTL environ value "%s"
+
+(W) A warning peculiar to VMS. Perl tried to read the CRTL's internal
+environ array, and encountered an element without the C<=> delimiter
+used to spearate keys from values. The element is ignored.
+
+=item Ill-formed message in prime_env_iter: |%s|
+
+(W) A warning peculiar to VMS. Perl tried to read a logical name
+or CLI symbol definition when preparing to iterate over %ENV, and
+didn't see the expected delimiter between key and value, so the
+line was ignored.
+
+=item Illegal binary digit %s
+
+(F) You used a digit other than 0 or 1 in a binary number.
+
+=item Illegal binary digit %s ignored
+
+(W) You may have tried to use a digit other than 0 or 1 in a binary number.
+Interpretation of the binary number stopped before the offending digit.
+
+=item Illegal number of bits in vec
+
+(F) The number of bits in vec() (the third argument) must be a power of
+two from 1 to 32 (or 64, if your platform supports that).
+
+=item Integer overflow in %s number
+
+(W) The hexadecimal, octal or binary number you have specified either
+as a literal or as an argument to hex() or oct() is too big for your
+architecture, and has been converted to a floating point number. On a
+32-bit architecture the largest hexadecimal, octal or binary number
+representable without overflow is 0xFFFFFFFF, 037777777777, or
+0b11111111111111111111111111111111 respectively. Note that Perl
+transparently promotes all numbers to a floating point representation
+internally--subject to loss of precision errors in subsequent
+operations.
+
=item Invalid %s attribute: %s
The indicated attribute for a subroutine or variable was not recognized
The indicated attributes for a subroutine or variable were not recognized
by Perl or by a user-supplied handler. See L<attributes>.
+=item invalid [] range "%s" in regexp
+
+The offending range is now explicitly displayed.
+
=item Invalid separator character %s in attribute list
(F) Something other than a comma or whitespace was seen between the
had a parenthesised parameter list, perhaps that list was terminated
too soon. See L<attributes>.
+=item Invalid separator character %s in subroutine attribute list
+
+(F) Something other than a comma or whitespace was seen between the
+elements of a subroutine attribute list. If the previous attribute
+had a parenthesised parameter list, perhaps that list was terminated
+too soon.
+
+=item leaving effective %s failed
+
+(F) While under the C<use filetest> pragma, switching the real and
+effective uids or gids failed.
+
+=item Lvalue subs returning %s not implemented yet
+
+(F) Due to limitations in the current implementation, array and hash
+values cannot be returned in subroutines used in lvalue context.
+See L<perlsub/"Lvalue subroutines">.
+
+=item Method %s not permitted
+
+See Server error.
+
+=item Missing %sbrace%s on \N{}
+
+(F) Wrong syntax of character name literal C<\N{charname}> within
+double-quotish context.
+
=item Missing command in piped open
(W) You used the C<open(FH, "| command")> or C<open(FH, "command |")>
(F) The reserved syntax for lexically scoped subroutines requires that they
have a name with which they can be found.
+=item No %s specified for -%c
+
+(F) The indicated command line switch needs a mandatory argument, but
+you haven't specified one.
+
+=item No package name allowed for variable %s in "our"
+
+(F) Fully qualified variable names are not allowed in "our" declarations,
+because that doesn't make much sense under existing semantics. Such
+syntax is reserved for future extensions.
+
+=item No space allowed after -%c
+
+(F) The argument to the indicated command line switch must follow immediately
+after the switch, without intervening spaces.
+
+=item no UTC offset information; assuming local time is UTC
+
+(S) A warning peculiar to VMS. Perl was unable to find the local
+timezone offset, so it's assuming that local system time is equivalent
+to UTC. If it's not, define the logical name F<SYS$TIMEZONE_DIFFERENTIAL>
+to translate to the number of seconds which need to be added to UTC to
+get local time.
+
+=item Octal number > 037777777777 non-portable
+
+(W) The octal number you specified is larger than 2**32-1 (4294967295)
+and therefore non-portable between systems. See L<perlport> for more
+on portability concerns.
+
+See also L<perlport> for writing portable code.
+
+=item panic: del_backref
+
+(P) Failed an internal consistency check while trying to reset a weak
+reference.
+
+=item panic: kid popen errno read
+
+(F) forked child returned an incomprehensible message about its errno.
+
+=item panic: magic_killbackrefs
+
+(P) Failed an internal consistency check while trying to reset all weak
+references to an object.
+
+=item Parentheses missing around "%s" list
+
+(W) You said something like
+
+ my $foo, $bar = @_;
+
+when you meant
+
+ my ($foo, $bar) = @_;
+
+Remember that "my", "our" and "local" bind closer than comma.
+
+=item Possible Y2K bug: %s
+
+(W) You are concatenating the number 19 with another number, which
+could be a potential Year 2000 problem.
+
+=item Premature end of script headers
+
+See Server error.
+
+=item Repeat count in pack overflows
+
+(F) You can't specify a repeat count so large that it overflows
+your signed integers. See L<perlfunc/pack>.
+
+=item Repeat count in unpack overflows
+
+(F) You can't specify a repeat count so large that it overflows
+your signed integers. See L<perlfunc/unpack>.
+
+=item realloc() of freed memory ignored
+
+(S) An internal routine called realloc() on something that had already
+been freed.
+
+=item Reference is already weak
+
+(W) You have attempted to weaken a reference that is already weak.
+Doing so has no effect.
+
+=item setpgrp can't take arguments
+
+(F) Your system has the setpgrp() from BSD 4.2, which takes no arguments,
+unlike POSIX setpgid(), which takes a process ID and process group ID.
+
+=item Strange *+?{} on zero-length expression
+
+(W) You applied a regular expression quantifier in a place where it
+makes no sense, such as on a zero-width assertion.
+Try putting the quantifier inside the assertion instead. For example,
+the way to match "abc" provided that it is followed by three
+repetitions of "xyz" is C</abc(?=(?:xyz){3})/>, not C</abc(?=xyz){3}/>.
+
+=item switching effective %s is not implemented
+
+(F) While under the C<use filetest> pragma, we cannot switch the
+real and effective uids or gids.
+
+=item This Perl can't reset CRTL environ elements (%s)
+
+=item This Perl can't set CRTL environ elements (%s=%s)
+
+(W) Warnings peculiar to VMS. You tried to change or delete an element
+of the CRTL's internal environ array, but your copy of Perl wasn't
+built with a CRTL that contained the setenv() function. You'll need to
+rebuild Perl with a CRTL that does, or redefine F<PERL_ENV_TABLES> (see
+L<perlvms>) so that the environ array isn't the target of the change to
+%ENV which produced the warning.
+
+=item Unknown open() mode '%s'
+
+(F) The second argument of 3-argument open() is not among the list
+of valid modes: C<L<lt>>, C<L<gt>>, C<E<gt>E<gt>>, C<+L<lt>>,
+C<+L<gt>>, C<+E<gt>E<gt>>, C<-|>, C<|->.
+
+=item Unknown process %x sent message to prime_env_iter: %s
+
+(P) An error peculiar to VMS. Perl was reading values for %ENV before
+iterating over it, and someone else stuck a message in the stream of
+data Perl expected. Someone's very confused, or perhaps trying to
+subvert Perl's population of %ENV for nefarious purposes.
+
=item Unrecognized escape \\%c passed through
(W) You used a backslash-character combination which is not recognized
-by Perl.
+by Perl. The character was understood literally.
=item Unterminated attribute parameter in attribute list
block. Perhaps you terminated the parameter list of the previous attribute
too soon. See L<attributes>.
-=item defined(@array) is deprecated
-
-(D) defined() is not usually useful on arrays because it checks for an
-undefined I<scalar> value. If you want to see if the array is empty,
-just use C<if (@array) { # not empty }> for example.
-
-=item defined(%hash) is deprecated
-
-(D) defined() is not usually useful on hashes because it checks for an
-undefined I<scalar> value. If you want to see if the hash is empty,
-just use C<if (%hash) { # not empty }> for example.
-
-=item Invalid separator character %s in subroutine attribute list
-
-(F) Something other than a comma or whitespace was seen between the
-elements of a subroutine attribute list. If the previous attribute
-had a parenthesised parameter list, perhaps that list was terminated
-too soon.
-
-=item Possible Y2K bug: %s
-
-(W) You are concatenating the number 19 with another number, which
-could be a potential Year 2000 problem.
-
=item Unterminated attribute parameter in subroutine attribute list
(F) The lexer saw an opening (left) parenthesis character while parsing a
block. Perhaps you terminated the parameter list of the previous attribute
too soon.
-=item /%s/ should probably be written as "%s"
+=item Value of CLI symbol "%s" too long
-(W) You have used a pattern where Perl expected to find a string,
-like in the first argument to C<join>. Perl will treat the true
-or false result of matching the pattern against $_ as the string,
-which is probably not what you had in mind.
+(W) A warning peculiar to VMS. Perl tried to read the value of an %ENV
+element from a CLI symbol table, and found a resultant string longer
+than 1024 characters. The return value has been truncated to 1024
+characters.
-=item %s() called too early to check prototype
+=item Version number must be a constant number
-(W) You've called a function that has a prototype before the parser saw a
-definition or declaration for it, and Perl could not check that the call
-conforms to the prototype. You need to either add an early prototype
-declaration for the subroutine in question, or move the subroutine
-definition ahead of the call to get proper prototype checking. Alternatively,
-if you are certain that you're calling the function correctly, you may put
-an ampersand before the name to avoid the warning. See L<perlsub>.
+(P) The attempt to translate a C<use Module n.n LIST> statement into
+its equivalent C<BEGIN> block found an internal inconsistency with
+the version number.
+
+=back
=head1 Obsolete Diagnostics
-Todo.
+=over 4
+
+=item Character class syntax [: :] is reserved for future extensions
+
+(W) Within regular expression character classes ([]) the syntax beginning
+with "[:" and ending with ":]" is reserved for future extensions.
+If you need to represent those character sequences inside a regular
+expression character class, just quote the square brackets with the
+backslash: "\[:" and ":\]".
+
+=item Ill-formed logical name |%s| in prime_env_iter
+
+(W) A warning peculiar to VMS. A logical name was encountered when preparing
+to iterate over %ENV which violates the syntactic rules governing logical
+names. Because it cannot be translated normally, it is skipped, and will not
+appear in %ENV. This may be a benign occurrence, as some software packages
+might directly modify logical name tables and introduce nonstandard names,
+or it may indicate that a logical name table has been corrupted.
+
+=item regexp too big
+
+(F) The current implementation of regular expressions uses shorts as
+address offsets within a string. Unfortunately this means that if
+the regular expression compiles to longer than 32767, it'll blow up.
+Usually when you want a regular expression this big, there is a better
+way to do it with multiple statements. See L<perlre>.
+
+=item Use of "$$<digit>" to mean "${$}<digit>" is deprecated
+
+(D) Perl versions before 5.004 misinterpreted any type marker followed
+by "$" and a digit. For example, "$$0" was incorrectly taken to mean
+"${$}0" instead of "${$0}". This bug is (mostly) fixed in Perl 5.004.
+
+However, the developers of Perl 5.004 could not fix this bug completely,
+because at least two widely-used modules depend on the old meaning of
+"$$0" in a string. So Perl 5.004 still interprets "$$<digit>" in the
+old (broken) way inside strings; but it generates this message as a
+warning. And in Perl 5.005, this special treatment will cease.
+
+=back
=head1 BUGS
-If you find what you think is a bug, you might check the headers of
+If you find what you think is a bug, you might check the
articles recently posted to the comp.lang.perl.misc newsgroup.
There may also be information at http://www.perl.com/perl/, the Perl
Home Page.