path: root/pod/perl5377delta.pod

=encoding utf8

=head1 NAME

perl5377delta - what is new for perl v5.37.7

=head1 DESCRIPTION

This document describes differences between the 5.37.6 release and the 5.37.7
release.

If you are upgrading from an earlier release such as 5.37.5, first read
L<perl5376delta>, which describes differences between 5.37.5 and 5.37.6.

=head1 Core Enhancements

=head2 Defined-or and logical-or assignment default expressions to signatures

The default expression for a subroutine signature parameter can now be
assigned using the C<//=> or C<||=> operators, to apply the defaults whenever
the caller provided an undefined or false value (respectively), rather than
simply when the parameter is missing entirely.  For more detail see the
documentation in L<perlsub>.

=head2 @INC Hook Enhancements and $INC and INCDIR

The internals for C<@INC> hooks have been hardened to handle various
edge cases and should no longer segfault or throw assert failures when
hooks modify C<@INC> during a require operation.  As part of this we
now ensure that any given hook is executed at most once during a require
call, and that any duplicate directories do not trigger additional
directory probes.

To provide developers more control over dynamic module lookup, a new hook
method C<INCDIR> is now supported. An object supporting this method may be
injected into the C<@INC> array, and when it is encountered in the module
search process it will be executed, just like how INC hooks are executed,
and its return value used as a list of directories to search for the
module. Returning an empty list acts as a no-op. Note that since any
references returned by this hook will be stringified and used as strings,
you may not return a hook to be executed later via this API.

When an C<@INC> hook (either C<INC> or C<INCDIR>) is called during
require, the C<$INC> variable will be localized to be the value of the
index of C<@INC> that the hook came from. If the hook wishes to override
what the "next" index in C<@INC> should be it may update C<$INC> to be one
less than the desired index (C<undef> is equivalent to C<-1>). This
allows an C<@INC> hook to completely rewrite the C<@INC> array and have
perl restart its directory probes from the beginning of C<@INC>.

Blessed CODE references in C<@INC> that do not support the C<INC> or
C<INCDIR> methods will no longer trigger an exception, and instead will
be treated the same as unblessed coderefs are, and executed as though
they were an C<INC> hook.

=head2 Forbidden control flow out of C<defer> or C<finally> now detected at compile-time

It is forbidden to attempt to leave a C<defer> or C<finally> block by means
of control flow such as C<return> or C<goto>. Previous versions of perl could
only detect this when actually attempted at runtime.

This version of perl adds compile-time detection for many cases that can be
statically determined. This may mean that code which compiled successfully on
a previous version of perl is now reported as a compile-time error with this
one. This only happens in cases where it would have been an error to actually
execute the code anyway; the error simply happens at an earlier time.

=head1 Modules and Pragmata

=head2 Updated Modules and Pragmata

=over 4

=item *

L<B::Deparse> has been upgraded from version 1.71 to 1.72.

=item *

L<experimental> has been upgraded from version 0.029 to 0.030.

=item *

L<ExtUtils::Miniperl> has been upgraded from version 1.12 to 1.13.

=item *

L<ExtUtils::ParseXS> has been upgraded from version 3.48 to 3.49.

=item *

L<ExtUtils::Typemaps> has been upgraded from version 3.48 to 3.49.

=item *

L<feature> has been upgraded from version 1.77 to 1.78.

=item *

L<File::Glob> has been upgraded from version 1.38 to 1.39.

=item *

L<File::Spec> has been upgraded from version 3.86 to 3.88.

=item *

L<Module::CoreList> has been upgraded from version 5.20221120 to 5.20221220.

=item *

L<Opcode> has been upgraded from version 1.62 to 1.63.

=item *

L<parent> has been upgraded from version 0.238 to 0.239.

=item *

L<Pod::Html> has been upgraded from version 1.33 to 1.34.  Three auxiliary
subroutines previously importable from Pod::Html must now be imported from
Pod::Html::Util.

=item *

L<podlators> has been upgraded from version 4.14 to 5.00.

=item *

L<POSIX> has been upgraded from version 2.08 to 2.10.  All fields known
to the platform in L<localeconv(3)> are now returned by
L<POSIX/localeconv>.  Previously, empty string fields and numeric fields
that aren't applicable to the current locale were omitted.

=item *

L<threads> has been upgraded from version 2.32 to 2.33.

=item *

L<XS::APItest> has been upgraded from version 1.27 to 1.28.

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

=over 4

=item *

L<Object with arguments in @INC does not support a hook method
 |perldiag/"Object with arguments in @INC does not support a hook method">

=back

=head2 Changes to Existing Diagnostics

=over 4

=item *

The error message that is produced when a C<require> or C<use> statement
fails has been changed. It used to contain the words C<@INC contains:>,
and it used to show the state of C<@INC> *after* the require had
completed and failed. The error message has been changed to say C<@INC
entries checked:> and to reflect the actual directories or hooks that
were executed during the require statement. For example:

    perl -e'push @INC, sub {@INC=()}; eval "require Frobnitz"
        or die $@'
    Can't locate Frobnitz.pm in @INC (you may need to install the
    Frobnitz module) (@INC contains:) at (eval 1) line 1.

Will change to (with some output elided for clarity):

    perl -e'push @INC, sub {@INC=()}; eval "require Frobnitz"
        or die $@'
    Can't locate Frobnitz.pm in @INC (you may need to install the
    Frobnitz module) (@INC entries checked:
    .../site_perl/5.37.7/x86_64-linux .../site_perl/5.37.7
    .../5.37.7/x86_64-linux .../5.37.7 CODE(0x562745e684b8))
    at (eval 1) line 1.

thus showing the actual directories checked. Code that checks for
C<@INC contains:> in error messages should be hardened against any future
wording changes between the C<@INC> and C<:>, for instance use
C<qr/\@INC[ \w]+:/> instead of using C<qr/\@INC contains:/> or
C<qr/\@INC entries checked:/> in tests as this will ensure both forward
and backward compatibility.

=back

=head1 Testing

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

=head1 Internal Changes

=over 4

=item *

The regex engine compilation code was split up into smaller sized compilation
units. No functionality changes were made. This was just to make it easier
to maintain the codebase.

=back

=head1 Selected Bug Fixes

=over 4

=item *

Correctly handle C<OP_ANONCODE> ops generated by CPAN modules that
don't include the OPf_REF flag when propagating lvalue context.
L<[GH #20532]|https://github.com/Perl/perl5/pull/20532>

=item *

L<POSIX::strxfrm|POSIX/strxfrm> now uses the C<LC_CTYPE> locale category
to specify its collation, ignoring any differing C<LC_COLLATE>.  It
doesn't make sense for a string to be encoded in one locale (say,
ISO-8859-6, Arabic) and to collate it based on another (like ISO-8859-7,
Greek).  Perl assumes that the current C<LC_CTYPE> locale correctly
represents the encoding, and collates accordingly.

Also, embedded C<NUL> characters are now allowed in the input.

If locale collation is not enabled on the platform (C<LC_COLLATE>), the
input is returned unchanged.

=item *

Double FETCH during stringification of tied scalars returning an
overloaded object have been fixed. The FETCH method should only be
called once, but prior to this release was actually called twice.
L<[GH #20574]|https://github.com/Perl/perl5/pull/20574>

=back

=head1 Known Problems

=over 4

=item *

CPAN modules not yet aware of new OPs

L<Devel::Caller>
L<[RT #144051]|https://rt.cpan.org/Ticket/Display.html?id=144051>
has not yet been updated to add awareness of new OPs introduced in
this development cycle.
L<[GH #20114]|https://github.com/Perl/perl5/issues/20114>. A patch has
been submitted upstream but this has not been incorporated into a new
release yet.

L<Test::Vars>
L<[Test-Vars/GH #47]|https://github.com/houseabsolute/p5-Test-Vars/issues/47>
also requires updating, but since this module's own tests are not
failing, it is harder to determine how the new OPs should be
accounted for. A potential patch has been submitted upstream, but
awaits maintainer assessment.

L<Data::Alias>
L<[RT #145279]|https://rt.cpan.org/Ticket/Display.html?id=145279> also
requires updating to add awareness of new OPs. Investigation is pending
and no patch has yet been submitted upstream.

=back

=head1 Acknowledgements

Perl 5.37.7 represents approximately 4 weeks of development since Perl
5.37.6 and contains approximately 42,000 lines of changes across 250 files
from 20 authors.

Excluding auto-generated files, documentation and release tools, there were
approximately 33,000 lines of changes to 140 .pm, .t, .c and .h files.

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

Bart Van Assche, Craig A. Berry, Eric Herman, Felipe Gasper, Graham Knop,
James E Keenan, Karl Williamson, Leon Timmermans, Matthew O. Persico, Max
Maischein, Paul Evans, Philippe Bruhat (BooK), Richard Leach, Russ Allbery,
Scott Baker, Tomasz Konojacki, Tony Cook, Tsuyoshi Watanabe, Yves Orton,
Zakariyya Mughal.

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 perl bug database
at L<https://github.com/Perl/perl5/issues>.  There may also be information at
L<http://www.perl.org/>, the Perl Home Page.

If you believe you have an unreported bug, please open an issue at
L<https://github.com/Perl/perl5/issues>.  Be sure to trim your bug down to a
tiny but sufficient test case.

If the bug you are reporting has security implications which make it
inappropriate to send to a public issue tracker, 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