Add created_as_... builtins to perldelta

[perl5.git] / pod / perl5359delta.pod

=encoding utf8

=head1 NAME

perl5359delta - what is new for perl v5.35.9

=head1 DESCRIPTION

This document describes differences between the 5.35.8 release and the 5.35.9
release.

If you are upgrading from an earlier release such as 5.35.7, first read
L<perl5358delta>, which describes differences between 5.35.7 and 5.35.8.

=head1 Core Enhancements

=head2 Subroutine signatures are no longer experimental

Introduced in Perl version 5.20.0, and modified several times since, the
subroutine signatures feature (C<use feature 'signatures'>) is now no longer
considered experimental. It is now considered a stable language feature and
is included in the C<:5.36> feature bundle, enabled automatically by
C<use v5.36>, and no longer prints a warning.

    use v5.36;

    sub add ($x, $y) {
      return $x + $y;
    }

Despite this, certain elements of signatured subroutines remain
experimental; see below.

=head2 @_ is now experimental within signatured subs

Even though subroutine signatures are now stable, use of the default arguments
array (C<@_>) with a subroutine that has a signature remains experimental,
with its own warning category.  Silencing the C<experimental::signatures>
warning category is not sufficient to dismiss this.  The new warning is
emitted with the category name C<experimental::args_array_with_signatures>.

Any subroutine that has a signature and tries to make use of the defaults
argument array or an element thereof (C<@_> or C<$_[INDEX]>), either
explicitly or implicitly (such as C<shift> or C<pop> with no argument) will
provoke a warning at compile-time:

    use v5.36;

    sub f ($x, $y = 123) {
      say "The first argument is $_[0]";
    }

Z<>

    Use of @_ in array element with signatured subroutine is experimental
    at file.pl line 4.

The behaviour of code which attempts to do this is no longer specified, and
may be subject to change in a future version.

=head2 The C<isa> operator is no longer experimental

Introduced in Perl version 5.32.0, this operator has remained unchanged
since then. The operator is now considered a stable language feature and is
included in the C<:5.36> feature bundle, enabled automatically by
C<use v5.36>.

For more detail see L<perlop/Class Instance Operator>.

=head2 -g command-line flag

A new command-line flag, -g, is available. It is a simpler alias for -0777.

For more information, see L<perlrun/-g>.

=head1 Deprecations

=head2 Downgrading a C<use VERSION> statement to below v5.11

Attempting to issue a second C<use VERSION> statement that requests a version
lower than C<v5.11> when an earlier statement that requested a version at
least C<v5.11> has already been seen, will now print a deprecation warning.

For example:

    use v5.14;
    say "The say statement is permitted";
    use v5.8;                               # This will print a warning
    print "We must use print\n";

This is because of an intended related change to the interaction between
C<use VERSION> and C<use strict>. If you specify a version >= 5.11, strict is
enabled implicitly. If you request a version < 5.11, strict will become
disabled I<even if you had previously written> C<use strict>. This was not
the previous behaviour of C<use VERSION>, which at present will track
explicitly-enabled strictness flags independently.

Code which wishes to mix versions in this manner should use lexical scoping
with block syntax to ensure that the differently versioned regions remain
lexically isolated.

    {
        use v5.14;
        say "The say statement is permitted";
    }
    {
        use v5.8;                           # No warning is emitted
        print "We must use print\n";
    }

=head1 Modules and Pragmata

=head2 Updated Modules and Pragmata

=over 4

=item *

L<B::Deparse> has been upgraded from version 1.61 to 1.62.

=item *

L<charnames> has been upgraded from version 1.49 to 1.50.

=item *

L<CPAN> has been upgraded from version 2.29 to 2.33.

=item *

L<Devel::PPPort> has been upgraded from version 3.63 to 3.64.

=item *

L<experimental> has been upgraded from version 0.025 to 0.027.

=item *

L<feature> has been upgraded from version 1.69 to 1.70.

=item *

L<File::Copy> has been upgraded from version 2.38 to 2.39.

=item *

L<Hash::Util> has been upgraded from version 0.27 to 0.28.

=item *

L<Hash::Util::FieldHash> has been upgraded from version 1.25 to 1.26.

=item *

L<Module::CoreList> has been upgraded from version 5.20220120 to 5.20220220.

=item *

L<Opcode> has been upgraded from version 1.55 to 1.56.

=item *

L<overload> has been upgraded from version 1.34 to 1.35.

=item *

L<re> has been upgraded from version 0.41 to 0.42.

=item *

L<Scalar::Util> has been upgraded from version 1.60 to 1.61.

=item *

L<sigtrap> has been upgraded from version 1.09 to 1.10.

=item *

L<Tie::SubstrHash> has been upgraded from version 1.00 to 1.01.

=item *

L<warnings> has been upgraded from version 1.56 to 1.57.

=item *

L<XS::APItest> has been upgraded from version 1.20 to 1.21.

=back

=head1 Diagnostics

=head2 New Diagnostics

=head3 New Warnings

=over 4

=item *

L<Built-in function '%s' is experimental|perldiag/"Built-in function '%s' is experimental">

A call is being made to a function in the
C<builtin::> namespace, which is currently experimental.

=item *

L<Implicit use of @_ in %s with signatured subroutine is experimental|perldiag/"Implicit use of @_ in %s with signatured subroutine is experimental">

An expression that implicitly involves the C<@_> arguments array was found in
a subroutine that uses a signature.

=item *

L<Use of @_ in %s with signatured subroutine is experimental|perldiag/"Use of @_ in %s with signatured subroutine is experimental">

An expression involving the C<@_> arguments array was found in a subroutine that uses a signature.

=item *

L<Downgrading a use VERSION declaration to below v5.11 is deprecated|perldiag/"Downgrading a use VERSION declaration to below v5.11 is deprecated">

This warning is emitted on a C<use VERSION> statement that
requests a version below v5.11 (when the effects of C<use strict> would be
disabled), after a previous declaration of one having a larger number (which
would have enabled these effects)

=back

=head2 Changes to Existing Diagnostics

=over 4

=item *

L<Subroutine %s redefined|perldiag/"Subroutine %s redefined">

Localized subroutine redefinitions no longer trigger this warning.

=back

=head1 Internal Changes

=over 4

=item *

New equality-test functions C<sv_numeq> and C<sv_streq> have been added, along
with C<..._flags>-suffixed variants.  These expose a simple and consistent API
to perform numerical or string comparison which is aware of operator
overloading.

=item *

Reading the string form of an integer value no longer sets the flag C<SVf_POK>.
The string form is still cached internally, and still re-read directly by the
macros C<SvPV(sv)> I<etc> (inline, without calling a C function). XS code that
already calls the APIs to get values will not be affected by this change. XS
code that accesses flags directly instead of using API calls to express its
intent I<might> break, but such code likely is already buggy if passed some
other values, such as floating point values or objects with string overloading.

This small change permits code (such as JSON serializers) to reliably determine
between

=over 4

=item *

a value that was initially B<written> as an integer, but then B<read> as a string

    my $answer = 42;
    print "The answer is $answer\n";

=item *

that same value that was initially B<written> as a string, but then B<read> as an integer

    my $answer = "42";
    print "That doesn't look right\n"
        unless $answer == 6 * 9;

=back

For the first case (originally written as an integer), we now have:

    use Devel::Peek;
    my $answer = 42;
    Dump ($answer);
    my $void = "$answer";
    print STDERR "\n";
    Dump($answer)


    SV = IV(0x562538925778) at 0x562538925788
      REFCNT = 1
      FLAGS = (IOK,pIOK)
      IV = 42

    SV = PVIV(0x5625389263c0) at 0x562538925788
      REFCNT = 1
      FLAGS = (IOK,pIOK,pPOK)
      IV = 42
      PV = 0x562538919b50 "42"\0
      CUR = 2
      LEN = 10

For the second (originally written as a string), we now have:

    use Devel::Peek;
    my $answer = "42";
    Dump ($answer);
    my $void = $answer == 6 * 9;
    print STDERR "\n";
    Dump($answer)'


    SV = PV(0x5586ffe9bfb0) at 0x5586ffec0788
      REFCNT = 1
      FLAGS = (POK,IsCOW,pPOK)
      PV = 0x5586ffee7fd0 "42"\0
      CUR = 2
      LEN = 10
      COW_REFCNT = 1

    SV = PVIV(0x5586ffec13c0) at 0x5586ffec0788
      REFCNT = 1
      FLAGS = (IOK,POK,IsCOW,pIOK,pPOK)
      IV = 42
      PV = 0x5586ffee7fd0 "42"\0
      CUR = 2
      LEN = 10
      COW_REFCNT = 1

(One can't rely on the presence or absence of the flag C<SVf_IsCOW> to
determine the history of operations on a scalar.)

Previously both cases would be indistinguishable, with all 4 flags set:

    SV = PVIV(0x55d4d62edaf0) at 0x55d4d62f0930
      REFCNT = 1
      FLAGS = (IOK,POK,pIOK,pPOK)
      IV = 42
      PV = 0x55d4d62e1740 "42"\0
      CUR = 2
      LEN = 10

(and possibly C<SVf_IsCOW>, but not always)

This now means that if XS code I<really> needs to determine which form a value
was first written as, it should implement logic roughly

    if (flags & SVf_IOK|SVf_NOK) && !(flags & SVf_POK)
        serialize as number
    else if (flags & SVf_POK)
        serialize as string
    else
        the existing guesswork ...

Note that this doesn't cover "dualvars" - scalars that report different
values when asked for their string form or number form (such as C<$!>).
Most serialization formats cannot represent such duplicity.

I<The existing guesswork> remains because as well as dualvars, values might
be C<undef>, references, overloaded references, typeglobs and other things that
Perl itself can represent but do not map one-to-one into external formats, so
need some amount of approximation or encapsulation.

=item *

Memory for hash iterator state (C<struct xpvhv_aux>) is now allocated as part
of the hash body, instead of as part of the block of memory allocated for the
main hash array.

Nothing else changes - memory for this structure is still allocated only when
needed, is still accessed via the C<HvAUX()> macro, and the macro should only
be called when C<SvOOK()> is true. Hashes are still always of type C<SVt_PVHV>,
hash bodies are still allocated from arenas, and the address of the hash
doesn't change, because the address is the pointer to the head structure, which
never moves.

Internally, a second arena (the arena with index 1) is used to allocate larger
bodies with space for C<struct xpvhv_aux>, the body "upgraded", and the "head"
structure updated to reflect this (much the same way that the bodies of scalars
are upgraded). We already re-purpose arenas - arena with index 0 is used for
C<HE *>s.

None of this affects documented public XS interfaces. The only code changes are
in F<hv.c> and F<sv.c>. As the rest of the core itself uses these macros but
needed no changes, likely no code on CPAN will be affected either.

=back

=head1 Acknowledgements

Perl 5.35.9 represents approximately 4 weeks of development since Perl
5.35.8 and contains approximately 8,700 lines of changes across 280 files
from 22 authors.

Excluding auto-generated files, documentation and release tools, there were
approximately 3,000 lines of changes to 110 .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.35.9:

Branislav Zahradník, Christopher Yeleighton, Dagfinn Ilmari Mannsåker,
Dave Cross, David Cantrell, Hugo van der Sanden, James E Keenan, James
Raspass, Karl Williamson, Leon Timmermans, Max Maischein, Michiel Beijen,
Nicholas Clark, Nicolas R., Paul Evans, Renee Baecker, Ricardo Signes,
Sergey Zhmylove, TAKAI Kousuke, Tomasz Konojacki, Tony Cook, 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 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