add v5.19.2 epigraph

[perl5.git] / pod / perldelta.pod

=encoding utf8

=head1 NAME

perldelta - what is new for perl v5.19.2

=head1 DESCRIPTION

This document describes differences between the 5.19.1 release and the 5.19.2
release.

If you are upgrading from an earlier release such as 5.19.0, first read
L<perl5191delta>, which describes differences between 5.19.0 and 5.19.1.

=head1 Core Enhancements

=head2 More consistent prototype parsing

Multiple semicolons in subroutine prototypes have long been tolerated and
treated as a single semicolon.  There was one case where this did not
happen.  A subroutine whose prototype begins with "*" or ";*" can affect
whether a bareword is considered a method name or sub call.  This now
applies also to ";;;*".

Whitespace has long been allowed inside subroutine prototypes, so
C<sub( $ $ )> is equivalent to C<sub($$)>, but until now it was stripped
when the subroutine was parsed.  Hence, whitespace was I<not> allowed in
prototypes set by C<Scalar::Util::set_prototype>.  Now it is permitted,
and the parser no longer strips whitespace.  This means
C<prototype &mysub> returns the original prototype, whitespace and all.

=head1 Performance Enhancements

=over 4

=item *

Precomputed hash values are now used in more places during method lookup.

=back

=head1 Modules and Pragmata

=head2 Updated Modules and Pragmata

=over 4

=item *

L<autodie> has been upgraded from version 2.19 to 2.20.

=item *

L<B> has been upgraded from version 1.43 to 1.44.

=item *

L<B::Concise> has been upgraded from version 0.96 to 0.98.

=item *

L<B::Deparse> has been upgraded from version 1.21 to 1.22.

=item *

L<base> has been upgraded from version 2.18 to 2.19.

=item *

L<Benchmark> has been upgraded from version 1.16 to 1.17.

=item *

L<Class::Struct> has been upgraded from version 0.64 to 0.65.

=item *

L<Data::Dumper> has been upgraded from version 2.146 to 2.147.

=item *

L<DB_File> has been upgraded from version 1.828 to 1.829.

=item *

L<DBM_Filter> has been upgraded from version 0.05 to 0.06.

=item *

L<Devel::Peek> has been upgraded from version 1.11 to 1.12.

=item *

L<Digest::MD5> has been upgraded from version 2.52 to 2.53.

=item *

L<Digest::SHA> has been upgraded from version 5.84 to 5.85.

=item *

L<English> has been upgraded from version 1.06 to 1.07.

=item *

L<Errno> has been upgraded from version 1.18 to 1.19.

=item *

L<ExtUtils::Embed> has been upgraded from version 1.30 to 1.31

The generated C<C> code now incorporates bug fixes present in
F<miniperlmain.c>, and has whitespace changes. It now uses
C<#include "..."> for header files instead of C<< #include <...> >>.
This should not make any difference, unless programs embedding C<libperl>
happen to have local and incompatible files named F<EXTERN.h>, F<XSUB.h> or
F<perl.h>, as these will now be picked up instead of the installed Perl
headers.

The C<canon()> function now correctly handles packages with multiple C<::>
separators when the I<$as> parameter is not I</>. Given that it used to
generate strings which would likely be syntax errors or pathnames instead of
filenames, we infer that from the complete lack of bug reports no-one was
using this functionality. (C<ExtUtils::Miniperl> is now using it.)

=item *

L<ExtUtils::Miniperl> has been upgraded and given a version of 1.
Previously it did not have a version number.

C<writemain()> now takes an optional first argument. A reference to a scalar
is treated as a filename to be opened and written to. Any other reference is
used as the filehandle to write to. Otherwise the existing default remains,
to write to C<STDOUT>.

C<writemain()> has been refactored to use functions from L<ExtUtils::Embed>,
reducing code size and duplication. The internal function C<canon()> has been
deleted.

=item *

L<ExtUtils::ParseXS> has been upgraded from version 3.19 to 3.21.

=item *

L<File::Basename> has been upgraded from version 2.84 to 2.85.

=item *

L<Getopt::Long> has been upgraded from version 2.4 to 2.41.

=item *

L<Getopt::Std> has been upgraded from version 1.08 to 1.09.

=item *

L<Hash::Util::FieldHash> has been upgraded from version 1.11 to 1.12.

=item *

L<HTTP::Tiny> has been upgraded from version 0.031 to 0.034.

=item *

L<I18N::Langinfo> has been upgraded from version 0.10 to 0.11.

=item *

L<if> has been upgraded from version 0.0602 to 0.0603.

=item *

L<IPC::Cmd> has been upgraded from version 0.80 to 0.82.

=item *

L<MIME::Base64> has been upgraded from version 3.13 to 3.14.

=item *

L<Module::CoreList> has been upgraded from version 2.92 to 2.94.

=item *

L<Params::Check> has been upgraded from version 0.36 to 0.38.

=item *

L<Parse::CPAN::Meta> has been upgraded from version 1.4404 to 1.4405.

=item *

L<Pod::Functions> has been upgraded from version 1.06 to 1.07.

=item *

L<Pod::Html> has been upgraded from version 1.19 to 1.2.

=item *

L<POSIX> has been upgraded from version 1.33 to 1.34.

C<POSIX::AUTOLOAD> will no longer infinitely recurse if the shared
object fails to load.

=item *

L<Safe> has been upgraded from version 2.36 to 2.37.

=item *

L<Socket> has been upgraded from version 2.009 to 2.010.

=item *

L<Storable> has been upgraded from version 2.43 to 2.45.

Calling C<STORABLE_attach> hooks no longer leaks memory. [perl #118829]

=item *

L<Text::ParseWords> has been upgraded from version 3.28 to 3.29.

=item *

L<Tie::Hash> has been upgraded from version 1.04 to 1.05.

=item *

L<Time::Piece> has been upgraded from version 1.2002 to 1.21.

=back

=head1 Documentation

=head2 Changes to Existing Documentation

=head3 L<perlexperiment>

=over 4

=item *

Code in regular expressions, regular expression backtracking verbs,
and lvalue subroutines are no longer listed as experimental.  (This
also affects L<perlre> and L<perlsub>.)

=back

=head3 L<perlfunc>

=over 4

=item *

Since Perl v5.10, it has been possible for subroutines in @INC to return
a reference to a scalar holding initial source code to prepend to the file.
This is now documented.

=back

=head3 L<perlop>

=over 4

=item *

The language design of Perl has always called for monomorphic operators.
This is now mentioned explicitly.

=back

=head3 L<perlre>

=over 4

=item *

The fact that the regexp engine makes no effort to call (?{}) and (??{})
constructs any specified number of times (although it will basically DWIM
in case of a successful match) has been documented.

=back

=head1 Diagnostics

The following additions or changes have been made to diagnostic output,
including warnings and fatal error messages.  For the complete list of
diagnostic messages, see L<perldiag>.

=head2 New Diagnostics

=head3 New Warnings

=over 4

=item *

L<Missing ']' in prototype for %s : %s|perldiag/"Missing ']' in prototype
for %s : %s">

(W illegalproto) A grouping was started with C<[> but never closed with
C<]>.

=back

=head2 Changes to Existing Diagnostics

=over 4

=item *

Under rare circumstances, one could get a "Can't coerce readonly REF to
string" instead of the customary "Modification of a read-only value".  This
alternate error message has been removed.

=item *

"Ambiguous use of * resolved as operator *": This and similar warnings
about "%" and "&" used to occur in some circumstances where there was no
operator of the type cited, so the warning was completely wrong.  This has
been fixed [perl #117535, #76910].

=item *

Warnings about malformed subroutine prototypes are now more consistent in
how the prototypes are rendered.  Some of these warnings would truncate
prototypes containing nulls.  In other cases one warning would suppress
another.  The warning about illegal characters in prototypes no longer says
"after '_'" if the bad character came before the underscore.

=item *

L<Perl folding rules are not up-to-date for 0x%X; please use the perlbug
utility to report; in regex; marked by <-- HERE in
mE<sol>%sE<sol>|perldiag/"Perl folding rules are not up-to-date for 0x%X;
please use the perlbug utility to report; in regex; marked by <-- HERE in
m/%s/">

This message is now only in the regexp category, and not in the deprecated
category.  It is still a default (i.e., severe) warning [perl #89648].

=item *

The debugger's "n" command now respects lvalue subroutines and steps over
them [perl #118839].

=back

=head1 Configuration and Compilation

=over 4

=item *

F<installperl> and F<installman>'s option handling has been refactored to use
L<Getopt::Long>. Both are used by the F<Makefile> C<install> targets, and
are not installed, so these changes are only likely to affect custom
installation scripts.

=over 4

=item *

single letter options now also have long names

=item *

invalid options are now rejected

=item *

command line arguments that are not options are now rejected

=item *

Each now has a C<--help> option to display the usage message.

=back

The behaviour for all valid documented invocations is unchanged.

=back

=head1 Platform Support

=head2 Platform-Specific Notes

=over 4

=item MidnightBSD

C<objformat> was removed from version 0.4-RELEASE of MidnightBSD and had been
deprecated on earlier versions.  This caused the build environment to be
erroneously configured for C<a.out> rather than C<elf>.  This has been now
been corrected.

=back

=head1 Internal Changes

=over 4

=item *

The Makefile shortcut targets for many rarely (or never) used testing and
profiling targets have been removed, or merged into the only other Makefile
target that uses them.  Specifically, these targets are gone, along with
documentation that referenced them or explained how to use them:

    check.third check.utf16 check.utf8 coretest minitest.prep
    minitest.utf16 perl.config.dashg perl.config.dashpg
    perl.config.gcov perl.gcov perl.gprof perl.gprof.config
    perl.pixie perl.pixie.atom perl.pixie.config perl.pixie.irix
    perl.third perl.third.config perl.valgrind.config purecovperl
    pureperl quantperl test.deparse test.taintwarn test.third
    test.torture test.utf16 test.utf8 test_notty.deparse
    test_notty.third test_notty.valgrind test_prep.third
    test_prep.valgrind torturetest ucheck ucheck.third ucheck.utf16
    ucheck.valgrind utest utest.third utest.utf16 utest.valgrind

It's still possible to run the relevant commands by "hand" - no underlying
functionality has been removed.

=item *

It is now possible to keep Perl from initializing locale handling.
For the most part, Perl doesn't pay attention to locale.  (See
L<perllocale>.)  Nonetheless, until now, on startup, it has always
initialized locale handling to the system default, just in case the
program being executed ends up using locales.  (This is one of the first
things a locale-aware program should do, long before Perl knows if it
will actually be needed or not.)  This works well except when Perl is
embedded in another application which wants a locale that isn't the
system default.  Now, if the environment variable
C<PERL_SKIP_LOCALE_INIT> is set at the time Perl is started, this
initialization step is skipped.  Prior to this, on Windows platforms,
the only workaround for this deficiency was to use a hacked-up copy of
internal Perl code.  Applications that need to use older Perls can
discover if the embedded Perl they are using needs the workaround by
testing that the C preprocessor symbol C<HAS_SKIP_LOCALE_INIT> is not
defined.  (RT #38193)

=item *

C<BmRARE> and C<BmPREVIOUS> have been removed.  They were not used anywhere
and are not part of the API.  For XS modules, they are now #defined as 0.

=item *

C<sv_force_normal>, which usually croaks on read-only values, used to allow
read-only values to be modified at compile time.  This has been changed to
croak on read-only values regardless.  This change uncovered several core
bugs.

=back

=head1 Selected Bug Fixes

=over 4

=item *

There have been several fixes related to Perl's handling of locales.  perl
#38193 was described above in L</Internal Changes>.
Also fixed is #112208 in which the error string in C<$!> displayed as
garbage in many UTF-8 locales;
#118197, where the radix (decimal point) character had to be an ASCII
character (which doesn't work for some non-Western languages);
and #115808, in which C<POSIX::setlocale()> on failure returned an
C<undef> which didn't warn about not being defined even if those
warnings were enabled.

=item *

The dtrace sub-entry probe now works with lexical subs, instead of
crashing [perl #118305].

=item *

Compiling a C<split> operator whose third argument is a named constant
evaulating to 0 no longer causes the constant's value to change.

=item *

A named constant used as the second argument to C<index> no longer gets
coerced to a string if it is a reference, regular expression, dualvar, etc.

=item *

A named constant evaluating to the undefined value used as the second
argument to C<index> no longer produces "uninitialized" warnings at compile
time.  It will still produce them at run time.

=item *

When a scalar was returned from a subroutine in @INC, the referenced scalar
was magically converted into an IO thingy, possibly resulting in "Bizarre
copy" errors if that scalar continued to be used elsewhere.  Now Perl uses
an internal copy of the scalar instead.

=item *

Undefining an inlinable lexical subroutine (C<my sub foo() { 42 } undef
&foo>) would result in a crash if warnings were turned on.

=item *

Certain uses of the C<sort> operator are optimised to modify an array in
place, such as C<@a = sort @a>.  During the sorting, the array is made
read-only.  If a sort block should happen to die, then the array remained
read-only even outside the C<sort>.  This has been fixed.

=item *

C<$a> and C<$b> inside a sort block are aliased to the actual arguments to
C<sort>, so they can be modified through those two variables.  This did not
always work, e.g., for lvalue subs and C<$#ary>, and probably many other
operators.  It works now.

=item *

The arguments to C<sort> are now all in list context.  If the C<sort>
itself were called in void or scalar context, then I<some>, but not all, of
the arguments used to be in void or scalar context.

=item *

Subroutine prototypes with Unicode characters above U+00FF were getting
mangled during closure cloning.  This would happen with subroutines closing
over lexical variables declared outside, and with lexical subs.

=item *

In regular expressions containing multiple code blocks, the values of
C<$1>, C<$2>, etc., set by nested regular expression calls would leak from
one block to the next.  Now these variables always refer to the outer
regular expression at the start of an embedded block [perl #117917].

=item *

C<UNIVERSAL::can> now treats its first argument the same way that method
calls do: Typeglobs and glob references with non-empty IO slots are treated
as handles, and strings are treated as filehandles, rather than packages,
if a handle with that name exists [perl #113932].

=item *

Method calls on typeglobs (e.g., C<< *ARGV->getline >>) used to stringify
the typeglob and then look it up again.  Combined with changes in Perl
5.18.0, this allowed C<< *foo->bar >> to call methods on the "foo" package
(like C<< foo->bar >>).  In some cases it could cause the method to be
called on the wrong handle.  Now a typeglob argument is treated as a
handle (just like C<< (\*foo)->bar >>), or, if its IO slot is empty, an
error is raised.

=item *

Under copy-on-write builds (the default as of 5.19.1) C<< ${'_<-e'}[0] >>
no longer gets mangled.  This is the first line of input saved for the
debugger's use for one-liners [perl #118627].

=item *

Assigning a vstring to a tied variable or to a subroutine argument aliased
to a nonexistent hash or array element now works, without flattening the
vstring into a regular string.

=item *

C<pos>, C<tie>, C<tied> and C<untie> did not work
properly on subroutine arguments aliased to nonexistent
hash and array elements [perl #77814, #27010].

=item *

The C<< => >> fat arrow operator can now quote built-in keywords even if it
occurs on the next line, making it consistent with how it treats other
barewords.

=back

=head1 Known Problems

=over 4

=item *

One of the bug fixes has accidentally thrown line numbers off in rare
cases, causing test failures for some CPAN modules.  This will hopefully be
fixed soon [perl #118931].

=back

=head1 Acknowledgements

Perl 5.19.2 represents approximately 4 weeks of development since Perl 5.19.1
and contains approximately 15,000 lines of changes across 400 files from 40
authors.

Perl continues to flourish into its third decade thanks to a vibrant community
of users and developers. The following people are known to have contributed the
improvements that became Perl 5.19.2:

Abhijit Menon-Sen, Alexandr Ciornii, Andy Dougherty, Aristotle Pagaltzis, Brian
Fraser, Brian Gottreu, Chris 'BinGOs' Williams, Craig A. Berry, Dagfinn Ilmari
Mannsåker, Daniel Dragan, David Golden, David Mitchell, Ed Avis, Father
Chrysostomos, Graham Knop, H.Merijn Brand, Hojung Youn, James E Keenan, Johan
Vromans, Karl Williamson, Keedi Kim, Kent Fredric, Lukas Mai, Moritz Lenz,
Nathan Trapuzzano, Neil Bowers, Nicholas Clark, Niels Thykier, Niko Tyni,
Olivier Mengué, Peter Martini, Petr Písař, Reini Urban, Ricardo Signes,
Ruslan Zakirov, Slaven Rezic, Steffen Müller, Tony Cook, Vladimir Timofeev,
Yves Orton.

The list above is almost certainly incomplete as it is automatically generated
from version control history. In particular, it does not include the names of
the (very much appreciated) contributors who reported issues to the Perl bug
tracker.

Many of the changes included in this version originated in the CPAN modules
included in Perl's core. We're grateful to the entire CPAN community for
helping Perl to flourish.

For a more complete list of all of Perl's historical contributors, please see
the F<AUTHORS> file in the Perl source distribution.

=head1 Reporting Bugs

If you find what you think is a bug, you might check the articles recently
posted to the comp.lang.perl.misc newsgroup and the perl bug database at
http://rt.perl.org/perlbug/ .  There may also be information at
http://www.perl.org/ , the Perl Home Page.

If you believe you have an unreported bug, please run the L<perlbug> program
included with your release.  Be sure to trim your bug down to a tiny but
sufficient test case.  Your bug report, along with the output of C<perl -V>,
will be sent off to perlbug@perl.org to be analysed by the Perl porting team.

If the bug you are reporting has security implications, which make it
inappropriate to send to a publicly archived mailing list, then please send it
to perl5-security-report@perl.org.  This points to a closed subscription
unarchived mailing list, which includes all the core committers, who will be
able to help assess the impact of issues, figure out a resolution, and help
co-ordinate the release of patches to mitigate or fix the problem across all
platforms on which Perl is supported.  Please only use this address for
security issues in the Perl core, not for modules independently distributed on
CPAN.

=head1 SEE ALSO

The F<Changes> file for an explanation of how to view exhaustive details on
what changed.

The F<INSTALL> file for how to build Perl.

The F<README> file for general stuff.

The F<Artistic> and F<Copying> files for copyright information.

=cut