path: root/pod/perldelta.pod

=encoding utf8

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

=head1 DESCRIPTION

This document describes differences between the 5.27.6 release and the 5.27.7
release.

If you are upgrading from an earlier release such as 5.27.5, first read
L<perl5276delta>, which describes differences between 5.27.5 and 5.27.6.

=head1 Notice

XXX Any important notices here

=head1 Core Enhancements

XXX New core language features go here.  Summarize 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  The C<sprintf> C<%j> format size modifier is now available with
pre-C99 compilers

The actual size used depends on the platform, so remains unportable.

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

=head2 Smartmatch and switch simplification

The experimental smart match operator (C<~~>) and switch
(C<given>/C<when>) constructs have been drastically simplified, in a
way that will require most uses of them to be updated.

The smart match operator no longer has its large table of matching rules.
Instead there is just one rule: the right-hand operand must overload
the operator.  Overloaded objects now bear the entire responsibility
for determining what kind of match to perform.  The operator also no
longer implicitly enreferences certain kinds of operand (such as arrays);
instead the operands get regular scalar context.

The C<when> construct no longer has its complicated rules about how
to treat its argument.  Instead it has been split into two distinct
constructs.  C<whereso> always uses the argument as a truth value,
and C<whereis> always smart matches.  Like the smart match operator,
these also no longer implicitly enreference certain kinds of argument,
instead supplying regular scalar context.

The C<default> construct, which was misleading and essentially useless,
has been removed.

The C<given> construct also no longer implicitly enreferences certain
kinds of arguments, instead supplying regular scalar context.  In this
case, the implicit enreferencement was undocumented anyway.

Flow control of switch constructs has been unified with loop flow
control.  The concept of "topicalizer" (referring to a C<given> block
or a C<foreach> loop acting on C<$_>) has been abolished.  A C<given>
construct now counts as a one-iteration loop, so responds to the loop
control keywords.  The C<break> keyword has consequently been removed,
in favour of using C<next> or C<last> to exit a C<given>.  The implicit
jump at the end of a C<when> block is now a C<next>, and so is applicable
not just to C<given> and some kinds of C<foreach> but to any loop.

It is known that these changes will break some users of L<autodie>,
the documentation of which has long recommended some uses of these
experimental features that are not portable across these changes.

=head2 Over-radix digits in floating point literals

Octal and binary floating point literals used to permit any hexadecimal
digit to appear after the radix point.  The digits are now restricted
to those appropriate for the radix, as digits before the radix point
always were.

=head2 Return type of C<unpackstring()>

The return types of the C API functions C<unpackstring()> and
C<unpack_str()> have changed from C<I32> to C<SSize_t>, in order to
accommodate datasets of more than two billion items.

=head1 Deprecations

XXX Any deprecated features, syntax, modules etc. should be listed here.

=head2 Assignment to C<$[> will be fatal in Perl 5.30

Assigning a non-zero value to L<C<$[>|perlvar/$[> has been deprecated
since Perl 5.12, but was never given a deadline for removal.  This has
now been scheduled for Perl 5.30.

=head2 hostname() won't accept arguments in Perl 5.32

Passing arguments to C<Sys::Hostname::hostname()> was already deprecated,
but didn't have a removal date.  This has now been scheduled for Perl
5.32.  [perl #124349]

=head2 Module removals

XXX Remove this section if not applicable.

The following modules will be removed from the core distribution in a
future release, and will at that time need to be installed from CPAN.
Distributions on CPAN which require these modules will need to list them as
prerequisites.

The core versions of these modules will now issue C<"deprecated">-category
warnings to alert you to this fact.  To silence these deprecation warnings,
install the modules in question from CPAN.

Note that these are (with rare exceptions) fine modules that you are encouraged
to continue to use.  Their disinclusion from core primarily hinges on their
necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
not usually on concerns over their design.

=over

=item L<Locale::Codes> and its associated Country, Currency and Language modules

XXX Note that deprecated modules should be listed here even if they are listed
as an updated module in the L</Modules and Pragmata> section.

=back

[ List each other deprecation as a =head2 entry ]

=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 an =item entry ]

=over 4

=item *

XXX

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

The list of new and updated modules is modified automatically as part of
preparing a Perl release, so the only reason to manually add entries here is if
you're summarising the important changes in the module update. (Also, if the
manually-added details don't match the automatically-generated ones, the
release manager will have to investigate the situation carefully.)

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

=head2 New Modules and Pragmata

=over 4

=item *

XXX Remove this section if not applicable.

=back

=head2 Updated Modules and Pragmata

=over 4

=item *

L<Locale::Codes> has been upgraded from version 3.54 to 3.55

B<NOTE>: L<Locale::Codes> is deprecated in core and will be removed
from Perl 5.30.

=item *

L<threads> has been upgraded from version 2.19 to 2.20.
The documentation now better describes the problems that arise when
returning values from threads, and no longer warns about creating threads
in C<BEGIN> blocks.  [perl #96538]

=item *

L<Data::Dumper> has been upgraded from version 2.167_02 to 2.169.
Quoting of glob names now obeys the Useqq option [perl #119831].
Attempts to set an option to C<undef> through a combined getter/setter
method are no longer mistaken for getter calls [perl #113090].

=item *

L<Pod::Html> has been upgraded from version 1.2203 to 1.23.
A title for the HTML document will now be automatically generated by
default from a "NAME" section in the POD document, as it used to be
before the module was rewritten to use L<Pod::Simple::XHTML> to do the
core of its job.  [perl #110520]

=item *

L<GDBM_File> has been upgraded from version 1.16 to 1.17.
Its documentation now explains that C<each> and C<delete> don't mix in
hashes tied to this module [perl #117449].
It will now retry opening with an acceptable block size if asking gdbm
to default the block size failed [perl #119623].

=item *

L<XSLoader> has been upgraded from version 0.28 to 0.29.
Its documentation now shows the use of C<__PACKAGE__>, and direct object
syntax for example C<DynaLoader> usage [perl #132247].

=item *

L<DynaLoader> has been upgraded from version 1.44 to 1.45.
Its documentation now shows the use of C<__PACKAGE__> and direct object
syntax [perl #132247].

=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

We have attempted to update the documentation to reflect the changes
listed in this document.  If you find any we have missed, send email
to L<perlbug@perl.org|mailto:perlbug@perl.org>.

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.

Additionally, the following selected changes have been made:

=head3 L<perlapi>

The API functions C<perl_parse()>, C<perl_run()>, and C<perl_destruct()>
are now documented comprehensively, where previously the only
documentation was a reference to the L<perlembed> tutorial.

The documentation of C<newGIVENOP()> has been belatedly updated to
account for the removal of lexical C<$_>.

The API functions C<newCONSTSUB()> and C<newCONSTSUB_flags()> are
documented much more comprehensively than before.

=head3 L<perlop>

The general explanation of operator precedence and associativity has
been corrected and clarified.  [perl #127391]

The documentation for the C<\> referencing operator now explains the
unusual context that it supplies to its operand.  [perl #131061]

=head3 L<perlsyn>

The means to disambiguate between code blocks and hash constructors,
already documented in L<perlref>, are now documented in L<perlsyn> too.
[perl #130958]

=head3 L<perlfunc>

There is now a note that warnings generated by built-in functions are
documented in L<perldiag> and L<warnings>.  [perl #116080]

The documentation for the C<exists> operator no longer says that
autovivification behaviour "may be fixed in a future release".
We've determined that we're not going to change the default behaviour.
[perl #127712]

A couple of small details in the documentation for the C<bless> operator
have been clarified.  [perl #124428]

The description of C<@INC> hooks in the documentation for C<require>
has been corrected to say that filter subroutines receive a useless
first argument.  [perl #115754]

The documentation of C<ref> has been rewritten for clarity.

The documentation of C<use> now explains what syntactically qualifies
as a version number for its module version checking feature.

The documentation of C<warn> has been updated to reflect that since Perl
5.14 it has treated complex exception objects in a manner equivalent
to C<die>.  [perl #121372]

The documentation of C<die> and C<warn> has been revised for clarity.

=head3 L<perluniprops>

For each binary table or property, the documentation now includes which
characters in the range C<\x00-\xFF> it matches, as well as a list of
the first few ranges of code points matched above that.

=head3 L<perlobj>

The documentation about C<DESTROY> methods has been corrected, updated,
and revised, especially in regard to how they interact with exceptions.
[perl #122753]

=head3 L<perlsec>

The documentation about set-id scripts has been updated and revised.
[perl #74142]

A section about using C<sudo> to run Perl scripts has been added.

=head3 L<perlembed>

The examples in L<perlembed> have been made more portable in the way
they exit, and the example that gets an exit code from the embedded Perl
interpreter now gets it from the right place.  The examples that pass
a constructed argv to Perl now show the mandatory null C<argv[argc]>.

=head3 L<perldebguts>

The description of the conditions under which C<DB::sub()> will be called
has been clarified.  [perl #131672]

=head3 L<perlintern>

The internal functions C<newXS_len_flags()> and C<newATTRSUB_x()> are
now documented.

=head3 L<perlgit>

The precise rules for identifying C<smoke-me> branches are now stated.

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

=head2 New Diagnostics

XXX Newly added diagnostic messages go under here, separated into New Errors
and New Warnings

=head3 New Errors

=over 4

=item *

L<Can't "goto" into a "given" block|perldiag/"Can't E<quot>gotoE<quot> into a E<quot>givenE<quot> block">

(F) A "goto" statement was executed to jump into the middle of a C<given>
block.  You can't get there from here.  See L<perlfunc/goto>.

=back

=head3 New Warnings

=over 4

=item *

L<Old package separator used in string|perldiag/"Old package separator used in string">

(W syntax) You used the old package separator, "'", in a variable
named inside a double-quoted string; e.g., C<"In $name's house">.  This
is equivalent to C<"In $name::s house">.  If you meant the former, put
a backslash before the apostrophe (C<"In $name\'s house">).

=back

=head2 Changes to Existing Diagnostics

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

=over 4

=item *

XXX Describe change here

=item *

The warning about useless use of a concatenation operator in void context
is now generated for expressions with multiple concatenations, such as
C<$a.$b.$c>, which used to mistakenly not warn.  [perl #6997]

=item *

Warnings that a variable or subroutine "masks earlier declaration in same
...", or that an C<our> variable has been redeclared, have been moved to a
new warnings category "shadow".  Previously they were in category "misc".

=item *

The deprecation warning from C<Sys::Hostname::hostname()> saying that
it doesn't accept arguments now states the Perl version in which the
warning will be upgraded to an error.  [perl #124349]

=item *

The L<perldiag> entry for the error regarding a set-id script has been
expanded to make clear that the error is reporting a specific security
vulnerability, and to advise how to fix it.

=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 directory F<utils>.

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

=head2 L<XXX>

=over 4

=item *

XXX

=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 an =item entry ].

=over 4

=item *

XXX

=item *

Where an HTML version of the doucmentation is installed, the HTML
documents now use relative links to refer to each other.  Links from
the index page of L<perlipc> to the individual section documents are
now correct.  [perl #110056]

=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 summarizing, although the bugs
that they represent may be covered elsewhere.

XXX If there were no significant test changes, say this:

Tests were added and changed to reflect the other additions and changes
in this release.

XXX If instead there were significant changes, say this:

Tests were added and changed to reflect the other additions and
changes in this release.  Furthermore, these significant changes were
made:

[ List each test improvement as an =item entry ]

=over 4

=item *

XXX

=back

=head1 Platform Support

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

[ Within the sections, list each platform as an =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 Windows

We now set C<$Config{libpth}> correctly for 64-bit builds using Visual C++
versions earlier than 14.1.

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

=over 4

=item *

XS modules can now automatically get reentrant versions of system
functions on threaded perls.

By saying

 #define PERL_REENTRANT

near the beginning of an C<XS> file, it will be compiled so that
whatever reentrant functions perl knows about on that system will
automatically and invisibly be used instead of the plain, non-reentrant
versions.  For example, if you write C<getpwnam()> in your code, on a
system that has C<pwnam_r()> all calls to the former will be translated
invisibly into the latter.  This does not happen except on threaded
perls, as they aren't needed otherwise.  Be aware that which functions
have reentrant versions varies from system to system.

=back

=head1 Selected Bug Fixes

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

[ List each fix as an =item entry ]

=over 4

=item *

XXX

=item *

C<pack> and C<unpack> can now handle repeat counts and lengths that
exceed two billion.  [perl #119367]

=item *

Digits past the radix point in octal and binary floating point literals
now have the correct weight on platforms where a floating point
significand doesn't fit into an integer type.

=item *

C<exit(0)> in a C<UNITCHECK> or C<CHECK> block no longer permits the
main program to run, and C<exit(0)> in a C<BEGIN> block no longer permits
C<INIT> blocks to run before exiting.  [perl #2754]

=item *

The canonical truth value no longer has a spurious special meaning as
a callable.  It used to be a magic placeholder for a missing C<import>
or C<unimport> method.  It is now treated like any other string C<1>.
[perl #126042]

=item *

C<system> now reduces its arguments to strings in the parent process, so
any effects of stringifying them (such as overload methods being called
or warnings being emitted) are visible in the way the program expects.
[perl #121105]

=item *

The C<readpipe()> built-in function now checks at compile time that
it has only one parameter expression, and puts it in scalar context,
thus ensuring that it doesn't corrupt the stack at runtime.  [perl #4574]

=item *

C<sort> now performs correct reference counting when aliasing C<$a> and
C<$b>, thus avoiding premature destruction and leakage of scalars if they
are re-aliased during execution of the sort comparator.  [perl #92264]

=item *

C<reverse> with no operand, reversing C<$_> by default, is no longer in
danger of corrupting the stack.  [perl #132544]

=item *

C<exec>, C<system>, et al are no longer liable to have their argument
lists corrupted by reentrant calls and by magic such as tied scalars.
[perl #129888]

=item *

Perl's own C<malloc> no longer gets confused by attempts to allocate
more than a gigabyte on a 64-bit platform.  [perl #119829]

=item *

Stacked file test operators in a sort comparator expression no longer
cause a crash.  [perl #129347]

=item *

An identity C<tr///> transformation on a reference is no longer mistaken
for that reference for the purposes of deciding whether it can be
assigned to.  [perl #130578]

=item *

Lengthy hexadecimal, octal, or binary floating point literals no
longer cause undefined behaviour when parsing digits that are of such
low significance that they can't affect the floating point value.
[perl #131894]

=item *

C<open $$scalarref...> and similar invocations no longer leak the file
handle.  [perl #115814]

=item *

Some convoluted kinds of regexp no longer cause an arithmetic overflow
when compiled.  [perl #131893]

=item *

The default typemap, by avoiding C<newGVgen>, now no longer leaks when
XSUBs return file handles (C<PerlIO *> or C<FILE *>).  [perl #115814]

=item *

Creating a C<BEGIN> block as an XS subroutine with a prototype no longer
crashes because of the early freeing of the subroutine.

=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.  Unfixed
platform specific bugs also go here.

[ List each fix as an =item entry ]

=over 4

=item *

XXX

=back

=head1 Errata From Previous Releases

=over 4

=item *

XXX Add anything here that we forgot to add, or were mistaken about, in
the perldelta of a previous release.

=back

=head1 Obituary

XXX If any significant core contributor or member of the CPAN community has
died, add a short obituary here.

=head1 Acknowledgements

XXX Generate this with:

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

=head1 Reporting Bugs

If you find what you think is a bug, you might check the perl bug database
at L<https://rt.perl.org/> .  There may also be information at
L<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 see
L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
for details of how to report the issue.

=head1 Give Thanks

If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
you can do so by running the C<perlthanks> program:

    perlthanks

This will send an email to the Perl 5 Porters list with your show of thanks.

=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