[perl5.git] / pod / perldelta.pod

=encoding utf8

=for comment
This has been completed up to 9ac8a16, except for:
8629c11317 smueller Escape double-quotes in generated #line directives
8dc67a69b  shlomif  perl -d: display lines inside subroutines.
3dfd1b5cd2 leont    Export PerlIOBase_open

=head1 NAME

[ this is a template for a new perldelta file. Any text flagged as
XXX needs to be processed before release. ]

perldelta - what is new for perl v5.15.7

=head1 DESCRIPTION

This document describes differences between the 5.15.6 release and
the 5.15.7 release.

If you are upgrading from an earlier release such as 5.15.5, first read
L<perl5156delta>, which describes differences between 5.15.5 and
5.15.6.

=head1 Notice

XXX Any important notices here

=head1 Core Enhancements

XXX New core language features go here. Summarise user-visible core language
enhancements. Particularly prominent performance optimisations could go
here, but most should go in the L</Performance Enhancements> section.

[ List each enhancement as a =head2 entry ]

=head2 C<use charnames> no longer needed for C<\N{I<name>}>

The C<charnames> module is now automatically loaded when needed as if
the C<:full> and C<:short> options had been specified.  See
L<charnames>.

=head1 Security

XXX Any security-related notices go here.  In particular, any security
vulnerabilities closed should be noted here rather than in the
L</Selected Bug Fixes> section.

[ List each security issue as a =head2 entry ]

=head1 Incompatible Changes

XXX For a release on a stable branch, this section aspires to be:

    There are no changes intentionally incompatible with 5.XXX.XXX
    If any exist, they are bugs, and we request that you submit a
    report.  See L</Reporting Bugs> below.

[ List each incompatible change as a =head2 entry ]

=head1 Deprecations

XXX Any deprecated features, syntax, modules etc. should be listed here.
In particular, deprecated modules should be listed here even if they are
listed as an updated module in the L</Modules and Pragmata> section.

[ List each deprecation as a =head2 entry ]

=head2 Deprecated Modules

=over

=item L<Version::Requirements>

Version::Requirements is now DEPRECATED, use CPAN::Meta::Requirements,
which is a drop-in replacement. It will be deleted from perl.git blead
in v5.17.0.

=back

=head1 Performance Enhancements

XXX Changes which enhance performance without changing behaviour go here. There
may well be none in a stable release.

[ List each enhancement as a =item entry ]

=over 4

=item *

Version declarations with the C<use> keyword (e.g., C<use 5.012>) are now
faster, as they enable features without loading F<feature.pm>.

=back

=head1 Modules and Pragmata

XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
go here.  If Module::CoreList is updated, generate an initial draft of the
following sections using F<Porting/corelist-perldelta.pl>, which prints stub
entries to STDOUT.  Results can be pasted in place of the '=head2' entries
below.  A paragraph summary for important changes should then be added by hand.
In an ideal world, dual-life modules would have a F<Changes> file that could be
cribbed.

[ Within each section, list entries as a =item entry ]

=head2 New Modules and Pragmata

=over 4

=item *

XXX

=back

=head2 Updated Modules and Pragmata

=over 4

=item *

L<B::Deparse> has been upgraded from version 1.10 to version 1.11.

It now deparses C<open('random string')> correctly.  It used to omit the
quotation marks, which did not work if the string were not a valid
identifier [perl #91416].

A similar bug also affected hash and array elements such as
C<< 'random string'->[0] >>, which would deparse as C<$random string[0]>.
This has been fixed.

Those same syntaxes used to drop the package name from variables beginning
with a punctuation mark, as in C<< "foo::]"->{$key} >>.  This, too, has
been fixed.

B::Deparse no longer hangs when deparsing a program with stash
circularities, such as C<BEGIN { *Acme::Acme:: = *Acme:: }> [perl #91384].

C</$s[1]/> used to be deparsed as C<$s[1]> if @s were a lexical variable
[perl #81424].  Similarly, C</$#s/> would be deparsed as C<$#s> for both
lexical and package variables.  These has been fixed.

The C</applaud> regular expression flags are no longer omitted.

Feature hints are now deparsed with C<use feature> rather than C<%^H>
assignments.

A regression in 1.10 that caused C<ambient_pragmas> to disabled strict mode
in obscure cases has been fixed.

Strict mode is now fully deparsed, including subs and vars [perl #24027].

The global variables C<$(>, C<$|> and C<$)> are now deparsed with braces
(i.e., C<${(}>) in regular expressions [perl #86060].

=item *

L<CGI> has been upgraded from version 3.58 to version 3.59.

We no longer read from STDIN when the Content-Length is not set, preventing
requests with no Content-Length from freezing in some cases. This is consistent
with the CGI RFC 3875, and is also consistent with CGI::Simple. However, the old
behavior may have been expected by some command-line uses of CGI.pm.

=item *

L<CPAN::Meta> has been upgraded from version 2.112621 to version 2.113640.

Version::Requirements has now been merged as CPAN::Meta::Requirements.

=item *

L<CPANPLUS> has been upgraded from version 0.9113 to version 0.9116.

=item *

L<POSIX> has been upgraded from version 1.28 to version 1.29.
C<POSIX::sleep> is now a direct call into the underlying OS C<sleep>
function, instead of being a Perl wrapper on C<CORE::sleep>. C<POSIX::dup2>
now returns the correct value on Win32 (I<i.e.> the file descriptor).
C<POSIX::SigSet> C<sigsuspend> and C<sigpending> and C<POSIX::pause> now
dispatch safe signals immediately before returning to their caller.

=item *

L<Data::Dumper> has been upgraded from version 2.135_01 to version
2.135_03.

It can now dump vstrings [perl #101162].

The nameless typeglob (C<*{""}>) is now dumped properly.

=item *

L<diagnostics> has been upgraded from version 1.26 to version 1.27.

See the entry for splain in the L</Utility Changes> section, for the
changes.  The diagnostics module and the splain utility are actually one
and the same.

=item *

L<Module::Pluggable> has been upgraded from version 3.9 to version 4.0.

=item *

L<POSIX> has been upgraded from version 1.27 to version 1.28.

C<sigsuspend> and C<pause> now run signals handle before returning, as the
whole point of these two functions is to wait until a signal has
arrived, and then return I<after> it has been triggered.  Delayed, or
"safe", signals were preventing that from happening, possibly resulting in
race conditions [perl #107216].

=item *

L<Term::UI> has been upgraded from version 0.26 to version 0.30.

=item *

L<Tie::File> has been upgraded from version 0.96 to version 0.98.

=item *

L<Unicode::UCD> has been upgraded from version 0.37 to version 0.38.
This changes the output of C<prop_invmap()> for the Name_Alias property
to reflect the changes that are planned for Unicode 6.1, so that there
won't be a format change when upgrading to 6.1.  Briefly, a second
component of each alias is added that gives the type of alias it is.
Examples are at L<Unicode::UCD/prop_invmap()>.

=item *

L<Version::Requirements> has been upgraded from version 0.101020 to version 0.101021.

Version::Requirements is now DEPRECATED, use CPAN::Meta::Requirements,
which is a drop-in replacement.

=back

=head2 Removed Modules and Pragmata

=over 4

=item *

XXX

=back

=head1 Documentation

XXX Changes to files in F<pod/> go here.  Consider grouping entries by
file and be sure to link to the appropriate page, e.g. L<perlfunc>.

=head2 New Documentation

XXX Changes which create B<new> files in F<pod/> go here.

=head3 L<XXX>

XXX Description of the purpose of the new file here

=head2 Changes to Existing Documentation

XXX Changes which significantly change existing files in F<pod/> go here.
However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
section.

=head3 L<XXX>

=over 4

=item *

XXX Description of the change here

=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>.

XXX New or changed warnings emitted by the core's C<C> code go here. Also
include any changes in L<perldiag> that reconcile it to the C<C> code.

[ Within each section, list entries as a =item entry that links to perldiag,
  e.g.

  =item *

  L<Invalid version object|perldiag/"Invalid version object">
]

=head2 New Diagnostics

XXX Newly added diagnostic messages go here

=head3 New Errors

=over 4

=item *

L<Cannot set tied @DB::args|perldiag/"Cannot set tied @DB::args">

This error occurs when C<caller> tries to set C<@DB::args> but finds it
tied.  Before this error was added, it used to crash instead.

=item *

L<Cannot tie unreifiable array|perldiag/"Cannot tie unreifiable array">

This error is part of a safety check that the C<tie> operator does before
tying a special array like C<@_>.  You should never see this message.

=back

=head3 New Warnings

=over 4

=item *

XXX L<message|perldiag/"message">

=back

=head2 Changes to Existing Diagnostics

XXX Changes (i.e. rewording) of diagnostic messages go here

=over 4

=item *

XXX Describe change here

=back

=head1 Utility Changes

XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
here. Most of these are built within the directories F<utils> and F<x2p>.

[ List utility changes as a =head3 entry for each utility and =item
entries for each change
Use L<XXX> with program names to get proper documentation linking. ]

=head3 L<splain>

=over 4

=item *

splain no longer emits backtraces with the first line number repeated.
This:

    Uncaught exception from user code:
            Cannot fwiddle the fwuddle at -e line 1.
     at -e line 1
            main::baz() called at -e line 1
            main::bar() called at -e line 1
            main::foo() called at -e line 1

has become this:

    Uncaught exception from user code:
            Cannot fwiddle the fwuddle at -e line 1.
            main::baz() called at -e line 1
            main::bar() called at -e line 1
            main::foo() called at -e line 1

=item *

Some error message consist of multiple lines that are listed as separate
entries in L<perldiag>.  splain has been taught to find the separate
entries in these cases, instead of simply failing to find the message.

=back

=head1 Configuration and Compilation

XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
go here.  Any other changes to the Perl build process should be listed here.
However, any platform-specific changes should be listed in the
L</Platform Support> section, instead.

[ List changes as a =item entry ].

=over 4

=item *

The Pod files for the perl FAQ, L<perlxs>, L<perlxstut> and L<perldoc>
are once again correctly installed in the same directory as the other core
Pods.

=for 5.16.0 This isn't a regression from 5.14.x, so don't mention this.

=back

=head1 Testing

XXX Any significant changes to the testing of a freshly built perl should be
listed here.  Changes which create B<new> files in F<t/> go here as do any
large changes to the testing harness (e.g. when parallel testing was added).
Changes to existing files in F<t/> aren't worth summarising, although the bugs
that they represent may be covered elsewhere.

[ List each test improvement as a =item entry ]

=over 4

=item *

F<t/porting/utils.t> now tests that various utility scripts compile cleanly.
During development, this avoids the embarrassment of inadvertently pushing a
commit which breaks code which isn't otherwise tested by the regression test
suite. For example, F<installperl> and F<installman>, needed by
C<make install>, are tested here.

=back

=head1 Platform Support

XXX Any changes to platform support should be listed in the sections below.

[ Within the sections, list each platform as a =item entry with specific
changes as paragraphs below it. ]

=head2 New Platforms

XXX List any platforms that this version of perl compiles on, that previous
versions did not. These will either be enabled by new files in the F<hints/>
directories, or new subdirectories and F<README> files at the top level of the
source tree.

=over 4

=item XXX-some-platform

XXX

=back

=head2 Discontinued Platforms

XXX List any platforms that this version of perl no longer compiles on.

=over 4

=item XXX-some-platform

XXX

=back

=head2 Platform-Specific Notes

XXX List any changes for specific platforms. This could include configuration
and compilation changes or changes in portability/compatibility.  However,
changes within modules for platforms should generally be listed in the
L</Modules and Pragmata> section.

=over 4

=item XXX-some-platform

XXX

=back

=head1 Internal Changes

XXX Changes which affect the interface available to C<XS> code go here.
Other significant internal changes for future core maintainers should
be noted as well.

[ List each change as a =item entry ]

=over 4

=item *

There are now feature bundle hints in C<PL_hints> (C<$^H>) that version
declarations use, to avoid having to load F<feature.pm>.  One setting of
the hint bits indicates a "custom" feature bundle, which means that the
entries in C<%^H> still apply.  F<feature.pm> uses that.

The C<HINT_FEATURE_MASK> macro is defined in F<perl.h> along with other
hints.  Other macros for setting and testing features and bundles are in
the new F<feature.h>.  C<FEATURE_IS_ENABLED> (which has moved to
F<feature.h>) is no longer used throughout the codebase, but more specific
macros, e.g., C<FEATURE_SAY_IS_ENABLED>, that are defined in F<feature.h>.

=item *

F<lib/feature.pm> is now a generated file, created by the new
F<regen/feature.pl> script, which also generates F<feature.h>.

=item *

Tied arrays are now always C<AvREAL>.  If C<@_> or C<DB::args> is tied, it
is reified first, to make sure this is always the case.

=back

=head1 Selected Bug Fixes

XXX Important bug fixes in the core language are summarised here.
Bug fixes in files in F<ext/> and F<lib/> are best summarised in
L</Modules and Pragmata>.

[ List each fix as a =item entry ]

=over 4

=item * "b . COND" in the debugger has been fixed

Breaking on the current line with C<b . COND> was broken by previous work and
has now been fixed.

=item * Tying C<%^H>

Tying C<%^H> no longer causes perl to crash or ignore
the contents of C<%^H> when entering a compilation
scope [perl #106282].

=item * C<~> on vstrings

The bitwise complement operator (and possibly other operators, too) when
passed a vstring would leave vstring magic attached to the return value,
even though the string had changed.  This meant that
C<< version->new(~v1.2.3) >> would create a version looking like "v1.2.3"
even though the string passed to C<< version->new >> was actually
"\376\375\374".  This also caused L<B::Deparse> to deparse C<~v1.2.3>
incorrectly, without the C<~> [perl #29070].

=item * Vstrings blowing away magic

Assigning a vstring to a magic (e.g., tied, C<$!>) variable and then
assigning something else used to blow away all the magic.  This meant that
tied variables would come undone, C<$!> would stop getting updated on
failed system calls, C<$|> would stop setting autoflush, and other
mischief would take place.  This has been fixed.

=item * C<newHVhv> and tied hashes

The C<newHVhv> XS function now works on tied hashes, instead of crashing or
returning an empty hash.

=item * Hashes will null elements

It is possible from XS code to create hashes with elements that have no
values.  Perl itself sometimes creates such hashes, but they are rarely
visible to Perl code.  The hash element and slice operators used to crash
when handling these in lvalue context.  These have been fixed.  They now
produce a "Modification of non-creatable hash value attempted" error
message.

=item * No warning for C<open(foo::bar)>

When one writes C<open foo || die>, which used to work in Perl 4, a
"Precedence problem" warning is produced.  This warning used erroneously to
apply to fully-qualified bareword handle names as well.  This has been
corrected.

=item * C<select> and package aliasing

After package aliasing (C<*foo:: = *bar::>), C<select> with 0 or 1 argument
would sometimes return a name that could not be used to refer to the
filehandle, or sometimes it would return C<undef> even when a filehandle
was selected.  Now it returns a typeglob reference in such cases.

=item * C<PerlIO::get_layers> and tied variables

C<PerlIO::get_layers> no longer ignores FETCH on tied variables as it used
to most of the time [perl #97956].

=item * C<PerlIO::get_layers> and numbers

C<PerlIO::get_layers> no longer ignores some arguments that it thinks are
numeric, while treating others as filehandle names.  It is now consistent
for flat scalars (i.e., not references).

=item * Lvalue subs and strict mode

Lvalue sub calls that are not determined to be such at compile time
(C<&$name> or &{"name"}) are no longer exempt from strict refs if they
occur in the last statement of an lvalue subroutine [perl #102486].

=item * Non-lvalue sub calls in potentially lvalue context

Sub calls whose subs are not visible at compile time, if
they occurred in the last statement of an lvalue subroutine,
would reject non-lvalue subroutines and die with "Can't modify non-lvalue
subroutine call" [perl #102486].

Non-lvalue sub calls whose subs I<are> visible at compile time exhibited
the opposite bug.  If the call occurred in the last statement of an lvalue
subroutine, there would be no error when the lvalue sub was called in
lvalue context.  Perl would blindly assign to the temporary value returned
by the non-lvalue subroutine.

=item * AUTOLOADing lvalue subs

C<AUTOLOAD> routines used to take precedence over the actual sub being
called (i.e., when autoloading wasn't needed), for sub calls in lvalue or
potential lvalue context, if the subroutine was not visible at compile
time.

=item * C<caller> and tied C<@DB::args>

C<caller> sets C<@DB::args> to the subroutine arguments when called from
the DB package.  It used to crash when doing so if C<@DB::args> happened to
be tied.  Now it croaks instead.

=item * Tying C<@_>

Under debugging builds, this code:

  sub TIEARRAY{bless[]}
  sub {
    tie @_, "";
    \@_;
  }->(1);

use to produce an "av_reify called on tied array" warning.  It doesn't any
more.

=item * Unrecognised switches on C<#!> line

If a switch, such as B<-x>, that cannot occur on the C<#!> line is used
there, perl dies with "Can’t emulate...".

It used to produce the same message for switches that perl did not
recognise at all, whether on the command line or the C<#!> line.

Now it produces the "Unrecognized switch" error message [perl #104288].

=item * C<system> and SIGCHLD

C<system> now temporarily blocks the SIGCHLD signal handler, to prevent the
signal handler from stealing the exit status [perl #105700].

=item * Deleting methods via C<delete>

Deletion of methods via C<delete $Class::{method}> syntax used to update
method caches if called in void context, but not scalar or list context.
Now it always updates those caches.

=item * Hash element deletion and destructors

When hash elements are deleted in void context, the internal hash entry is
now freed before the value is freed, to prevent destructors call by that
latter freeing from seeing the hash in an inconsistent state.  It was
possible to cause double-frees if the destructor freed the hash itself
[perl #100340].

=item * C<(s)printf>'s %n formatting code

The %n formatting code, which causes the number of characters to be
assigned to the next argument to C<printf> or C<sprintf> now actually
assigns the number of characters, instead of the number of bytes.

It also works now with special lvalue functions like C<substr> and with
nonexistent hash and array elements [perl #103492].

=item * Typeglobs and threads

Typeglobs returned from threads are no longer cloned if the parent thread
already has a glob with the same name.  This means that returned
subroutines will now assign to the right package variables [perl #107366].

=back

=head1 Known Problems

XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
tests that had to be C<TODO>ed for the release would be noted here, unless
they were specific to a particular platform (see below).

This is a list of some significant unfixed bugs, which are regressions
from either 5.XXX.XXX or 5.XXX.XXX.

[ List each fix as a =item entry ]

=over 4

=item *

XXX

=back

=head1 Obituary

XXX If any significant core contributor has died, we've added a short obituary
here.

=head1 Acknowledgements

XXX Generate this with:

  perl Porting/acknowledgements.pl v5.15.6..HEAD

=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