pod/perldelta.pod - updates for 5.37.10

Also trim some whitespace from perlvar.pod

2 files changed, 212 insertions, 200 deletions

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index 1953ca6e55..2cfa97c3ab 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -2,9 +2,6 @@
 
 =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.37.10
 
 =head1 DESCRIPTION
@@ -15,18 +12,8 @@ release.
 If you are upgrading from an earlier release such as 5.37.8, first read
 L<perl5379delta>, which describes differences between 5.37.8 and 5.37.9.
 
-=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 Some C<goto>s are now permitted in C<defer> and C<finally> blocks
 
 Perl version 5.36.0 added C<defer> blocks and permitted the C<finally> keyword
@@ -62,71 +49,40 @@ can be rewritten as follows
 
 and it will do the exactly same thing.
 
-=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.
+=head2 Deprecation warnings now have specific subcategories
 
-[ List each incompatible change as a =head2 entry ]
+As of 5.37.10 all deprecation warnings will have their own specific
+deprecation category which can be disabled individually. You can see a
+list of all deprecated features in L<perldeprecation>, and in
+L<warnings>. The following list is from L<warnings>:
 
-=head1 Deprecations
+         +- deprecated ----+
+         |                 |
+         |                 +- deprecated::apostrophe_as_package_separator
+         |                 |
+         |                 +- deprecated::delimiter_will_be_paired
+         |                 |
+         |                 +- deprecated::dot_in_inc
+         |                 |
+         |                 +- deprecated::goto_construct
+         |                 |
+         |                 +- deprecated::smartmatch
+         |                 |
+         |                 +- deprecated::unicode_property_name
+         |                 |
+         |                 +- deprecated::version_downgrade
 
-XXX Any deprecated features, syntax, modules etc. should be listed here.
+It is still possible to disable all deprecation warnings in a single
+statement with
 
-=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 XXX
-
-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
+    no warnings 'deprecated';
 
-[ List each other deprecation as a =head2 entry ]
+but as of 5.37.10 it is possible to have a finer grained control. As
+has historically been the case these warnings are automatically
+enabled with
 
-=head1 Performance Enhancements
+    use warnings;
 
-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
 
@@ -160,209 +116,227 @@ XXX Remove this section if Porting/corelist-perldelta.pl did not add any content
 
 =item *
 
-L<XXX> has been upgraded from version A.xx to B.yy.
+L<Module::CoreList> has been upgraded from version 5.20230220 to 5.20230320.
 
-XXX If there was something important to note about this change, include that here.
+=item *
 
-=back
+L<Config::Perl::V> has been upgraded from version 0.35 to 0.36
 
-=head2 Removed Modules and Pragmata
+=item *
 
-=over 4
+L<Digest::SHA> has been upgraded from version 6.03 to 6.04
 
 =item *
 
-XXX Remove this section if Porting/corelist-perldelta.pl did not add any content here.
+L<Test::More> has been upgraded from version 1.302192 to 1.302194
 
 =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, open an issue
 at L<https://github.com/Perl/perl5/issues>.
 
-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<XXX>
+=head3 F<pod/perldebguts.pod>
 
 =over 4
 
 =item *
 
-XXX Description of the change here
+Updates to regex internals documentation.
 
 =back
 
-=head1 Diagnostics
+=head3 F<pod/perldeprecation.pod>
 
-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>.
+=over 4
 
-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.
+=item *
 
-=head2 New Diagnostics
+Added information about unscheduled deprecations and their categories.
 
-XXX Newly added diagnostic messages go under here, separated into New Errors
-and New Warnings
+=item *
 
-=head3 New Errors
+Added category information for existing scheduled deprecations.
+
+=item *
+
+Added smartmatch and apostrophe as a package separator deprecation data.
+
+=back
+
+=head3 F<pod/perlexperiment.pod>
 
 =over 4
 
 =item *
 
-XXX L<message|perldiag/"message">
+Smartmatch has been moved from experimental status to deprecated status.
+Unfortunately the experiment did not work out.
 
 =back
 
-=head3 New Warnings
+=head3 F<pod/perlexperiment.pod>
 
 =over 4
 
 =item *
 
-XXX L<message|perldiag/"message">
+Documented new require hooks.
 
 =back
 
-=head2 Changes to Existing Diagnostics
-
-XXX Changes (i.e. rewording) of diagnostic messages go here
+=head3 F<pod/perlguts.pod>
 
 =over 4
 
 =item *
 
-XXX Describe change here
+Documented new magic types C<PERL_MAGIC_destruct>, C<PERL_MAGIC_hook> and
+C<PERL_MAGIC_hookelem>.
+
+=item *
+
+Documented several new or existing save stack macros: C<SAVERCPV()>,
+C<SAVEGENERICSV()>, C<SAVEFREEPV()>, C<SAVEFREERCPV()>
+
+=item *
+
+Documented new mortalization callback macros: C<MORTALSVFUNC_X()>,
+C<MORTALDESTRUCTOR_SV()>
 
 =back
 
-=head1 Utility Changes
+=head3 F<pod/perlop.pod>
 
-XXX Changes to installed programs such as F<perldoc> and F<xsubpp> go here.
-Most of these are built within the directory F<utils>.
+=over 4
 
-[ 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. ]
+=item *
 
-=head2 L<XXX>
+Document the behavior of matching the empty pattern better and specify
+its relationship to the new C<${^LAST_SUCCESSFUL_PATTERN}> properly.
+
+=back
+
+=head3 F<pod/perlvar.pod>
 
 =over 4
 
 =item *
 
-XXX
+Added information on the new C<%{^HOOK}> interface, and the new
+C<require__before> and C<require__after> hooks which it exposes.
+
+=item *
+
+Correct information on the regex variables C<${^PREMATCH}>, C<${^MATCH}>
+and C<${^POSTMATCH}>, all of which were incorrectly documented due to an
+oversight. Specifically they only work properly after a regex operation
+that used the /p modifier to enable them.
+
+=item *
+
+Added information on the new regex variable C<${^LAST_SUCCESSFUL_PATTERN}>,
+which represents the pattern of the last successful regex match in scope.
 
 =back
 
-=head1 Configuration and Compilation
+=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.
 
-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.
+=head2 New Diagnostics
 
-[ List changes as an =item entry ].
+XXX Newly added diagnostic messages go under here, separated into New Errors
+and New Warnings
+
+=head3 New Errors
 
 =over 4
 
 =item *
 
-XXX
+L<${^HOOK}{%s} may only be a CODE reference or undef|perldiag/"${^HOOK}{%s} may only be a CODE reference or undef">
 
-=back
+=item *
 
-=head1 Testing
+L<Attempt to set unknown hook '%s' in %{^HOOK}|perldiag/"Attempt to set unknown hook '%s' in %{^HOOK}">
 
-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.
+=item *
 
-XXX If there were no significant test changes, say this:
+L<Missing or undefined argument to %s via %{^HOOK}{require__before}|perldiag/"Missing or undefined argument to %s via %{^HOOK}{require__before}">
 
-Tests were added and changed to reflect the other additions and changes
-in this release.
+=item *
 
-XXX If instead there were significant changes, say this:
+L<Too many capture groups (limit is %d) in regex mE<sol>%sE<sol>|perldiag/"Too many capture groups (limit is %d) in regex m/%s/">
 
-Tests were added and changed to reflect the other additions and
-changes in this release.  Furthermore, these significant changes were
-made:
+=back
 
-[ List each test improvement as an =item entry ]
+=head3 New Warnings
 
 =over 4
 
 =item *
 
-XXX
+L<Can't call destructor for 0x%p in global destruction|perldiag/"Can't call destructor for 0x%p in global destruction">
 
 =back
 
-=head1 Platform Support
+=head2 Changes to Existing Diagnostics
 
-XXX Any changes to platform support should be listed in the sections below.
+=over 4
 
-[ Within the sections, list each platform as an =item entry with specific
-changes as paragraphs below it. ]
+=item *
 
-=head2 New Platforms
+L<given is deprecated|perldiag/"given is deprecated"> replaces C<given is experimental>.
 
-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.
+=item *
 
-=over 4
+L<when is deprecated|perldiag/"when is deprecated"> replaces C<when is experimental>.
 
-=item XXX-some-platform
+=item *
 
-XXX
+L<Smartmatch is deprecated|perldiag/"Smartmatch is deprecated"> replaces C<Smartmatch is experimental>.
 
 =back
 
-=head2 Discontinued Platforms
+=head1 Testing
 
-XXX List any platforms that this version of perl no longer compiles on.
+Tests were added and changed to reflect the other additions and
+changes in this release.  Furthermore, these significant changes were
+made:
 
 =over 4
 
-=item XXX-some-platform
+=item *
+
+Added t/op/hook/ for testing C<%{^HOOK}> related functionality. Specifically
+the F<t/op/hook/require.t> for testing the new require hooks.
+
+=item *
 
-XXX
+Added F<t/op/deprecation.t> to test that our deprecation policies are being
+followed properly.
+
+=item *
+
+Fixed bugs in F<t/harness> and F<t/TEST> that meant that tests in F<t/test_pl> and
+F<t/class> were not being run during normal testing.
 
 =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
@@ -383,29 +357,54 @@ Closing a busy pipe could cause Perl to hang. [GH #19963]
 
 =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
 
-[ List each change as an =item entry ]
+=item *
 
-=over 4
+Added C<SAVERCPV()> and C<SAVEFREERCPV()> for better support for working
+with C<RCPV> (reference counted string/pointer value) structures which
+currently are used in opcodes to share filename and warning bit data in
+a memory efficient manner.
 
 =item *
 
-XXX
+Added C<MORTALSVFUNC_SV()> and C<MORTALDESTRUCTOR_SV()> macros, which
+make it possible to create a destructor which is fired at the end of
+the current statement. This uses the C<PERL_MAGIC_destruct> magic to
+use "free" magic to trigger an action when a variable is freed. The
+action can be specified as a C function or as a Perl code reference.
 
-=back
+=item *
 
-=head1 Selected Bug Fixes
+Added the C<%{^HOOK}> api and related C<PERL_MAGIC_hook> and
+C<PERL_MAGIC_hookelem> for providing ways to hook selected perl functions
+which for one reason or another are problematic to wrap with a customized
+subroutine.
+
+=item *
+
+Added support for C<${^HOOK}{require__before}> which can be used to
+rewrite the filename that C<require> will try to load, and also to block
+C<require> from loading a specific module, even via fully qualified
+filename. The hook can also be used to perform "pre-require" and
+"post-require" actions.
 
-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>.
+=item *
+
+Added support for C<${^HOOK}{require__after}> which can be used to
+track what modules have been required after the fact.
 
-Include references to GitHub issues and PRs as: [GH #12345] and the release
-manager will later use a regex to expand these into links.
+=item *
 
-[ List each fix as an =item entry ]
+Regular expression opcodes (regops) now use a standardized structure
+layout that uses unions to expose data in different format. This means
+it should be much easier to extend or modify regops to use more memory.
+This has been used to make a number of regops track how many parens
+they contain.
+
+=back
+
+=head1 Selected Bug Fixes
 
 =over 4
 
@@ -417,47 +416,60 @@ error when using the unit class syntax.
 
 =item *
 
-XXX
+A number of bugs related to capture groups in quantified groups in regular
+expression have been fixed, especially in alternations. For example in
+a pattern like:
 
-=back
+	"foobazfoobar" =~ /((foo)baz|foo(bar))+/
+
+the regex variable C<$2> will not be "foo" as it once was, it will be undef.
 
-=head1 Known Problems
+=item *
 
-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.
+Bugs with regex backreference operators that are inside of a capture
+group have been fixed. For instance:
 
-[ List each fix as an =item entry ]
+    "xa=xaaa" =~ /^(xa|=?\1a){2}\z/
 
-=over 4
+will now correctly not match. [GH #10073]
 
 =item *
 
-XXX
+C<SSGROW()> and C<SSCHECK()> have been reworked to ensure that the requested
+space is actually allocated. C<SSCHECK()> is now an alias for C<SSGROW()>.
 
 =back
 
-=head1 Errata From Previous Releases
-
-=over 4
-
-=item *
+=head1 Acknowledgements
 
-XXX Add anything here that we forgot to add, or were mistaken about, in
-the perldelta of a previous release.
+Perl 5.37.10 represents approximately 4 weeks of development since Perl
+5.37.9 and contains approximately 23,000 lines of changes across 360 files
+from 21 authors.
 
-=back
+Excluding auto-generated files, documentation and release tools, there were
+approximately 6,000 lines of changes to 220 .pm, .t, .c and .h files.
 
-=head1 Obituary
+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.10:
 
-XXX If any significant core contributor or member of the CPAN community has
-died, add a short obituary here.
+Arne Johannessen, Craig A. Berry, Dan Jacobson, David Mitchell, Elvin
+Aslanov, Graham Knop, James E Keenan, James Raspass, Jon Gentle, Karen
+Etheridge, Karl Williamson, Leon Timmermans, Lukas Mai, Paul Evans, Philippe
+Bruhat (BooK), Richard Leach, Steve Hay, Tomasz Konojacki, Tony Cook, Yves
+Orton, Zefram.
 
-=head1 Acknowledgements
+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.
 
-XXX Generate this with:
+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.
 
-  perl Porting/acknowledgements.pl v5.37.9..HEAD
+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
 
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index 25dbd05a9b..abbfc50ca8 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -1452,7 +1452,7 @@ and
         s/${^LAST_SUCCESSFUL_PATTERN}/BLAH/;
     }
 
-are equivalent. 
+are equivalent.
 
 You can use this to debug which pattern matched last, or to match with it again.