From 0d82203803ef13c8b0ef151e90f9504216e3316a Mon Sep 17 00:00:00 2001 From: Lukas Mai Date: Sun, 28 Apr 2024 22:29:33 +0200 Subject: [PATCH] perldeprecation: clean up - Remove duplicate sections: File::Glob::glob, bare { in regexes, code points above 0xFF in string bitwise ops These were repeated for different perl versions, but none of the other sections list deprecations and removal separately (e.g. "Passing malformed strings was deprecated in Perl 5.18, and became fatal in Perl 5.26" only appears under Perl 5.26; the deprecation is not listed separately under Perl 5.18). - Fix some typos (e.g. "ballanced") - Fix (?) some grammar/punctuation Also use past tense to describe removed functions. - Fix some POD markup (C< > around variables, L< > for modules) --- pod/perldeprecation.pod | 85 +++++++++++++++-------------------------- 1 file changed, 30 insertions(+), 55 deletions(-) diff --git a/pod/perldeprecation.pod b/pod/perldeprecation.pod index 4317907d8578..21eae24c8fc4 100644 --- a/pod/perldeprecation.pod +++ b/pod/perldeprecation.pod @@ -18,19 +18,19 @@ which they will be removed. =head3 Unicode Delimiter Will be Paired -Some unicode delimiters used to be allowed as single characters but -in the future will be part of a ballanced pair. This deprecation category -is used to mark the ones that will change from being unpaired, to paired. +Some unicode delimiters used to be allowed as single characters, but +in the future will be part of a balanced pair. This deprecation category +is used to mark the ones that will change from being unpaired to paired. Category: "deprecated::delimiter_will_be_paired" =head3 Dot In Inc -The current working directory C<"."> used to be automatically included in +The current working directory C<.> used to be automatically included in C<@INC>, but in Perl 5.26 this was removed for security reasons. Ever since then we have produced a warning when a user uses C and C does not include a path, and the file was not found in any -directory in C<@INC> but I located C<".">. The file will not be loaded +directory in C<@INC> but I located in C<.>. The file will not be loaded but a deprecated warning will be generated. Category: "deprecated::dot_in_inc" @@ -47,7 +47,7 @@ of a loop or other block construct from outside. For instance goto LABEL; will produce a warning that this behavior is deprecated. In general you should -just avoid doing this, the people that maintain your code will be grateful for +just avoid doing this; the people that maintain your code will be grateful for your restraint. Category: "deprecated::goto_construct" @@ -140,8 +140,8 @@ Category: "deprecated::version_downgrade" The definition and documentation of three utility functions previously importable from L were moved to new package L in -Perl 5.36. While they remain importable from L in Perl 5.36, as of -Perl 5.38 they will only be importable, on request, from L. +Perl 5.36. While they remained importable from L in Perl 5.36, as +of Perl 5.38 they are only importable, on request, from L. =head2 Perl 5.34 @@ -156,7 +156,7 @@ You wrote something like my $var; $sub = sub () { $var }; -but $var is referenced elsewhere and could be modified after the C +but C<$var> is referenced elsewhere and could be modified after the C expression is evaluated. Either it is explicitly modified elsewhere (C<$var = 3>) or it is passed to a subroutine or to an operator like C or C, which may or may not modify the variable. @@ -232,7 +232,7 @@ Forcing literal C<{> characters to be escaped will enable the Perl language to be extended in various ways in future releases. To avoid needlessly breaking existing code, the restriction is not enforced in contexts where there are unlikely to ever be extensions that could -conflict with the use there of C<{> as a literal. A non-deprecation +conflict with the use of C<{> as a literal. A non-deprecation warning that the left brace is being taken literally is raised in contexts where there could be confusion about it. @@ -245,7 +245,7 @@ and were made fatal in 5.32. =head3 In XS code, use of various macros dealing with UTF-8 -The macros below now require an extra parameter than in versions prior +The macros below now require an extra parameter compared to versions prior to Perl 5.32. The final parameter in each one is a pointer into the string supplied by the first parameter beyond which the input will not be read. This prevents potential reading beyond the end of the buffer. @@ -296,7 +296,7 @@ This change was originally scheduled for 5.30, but was delayed until =head3 C<< File::Glob::glob() >> was removed -C<< File::Glob >> has a function called C<< glob >>, which just calls +C<< File::Glob >> had a function called C<< glob >>, which just called C<< bsd_glob >>. C<< File::Glob::glob() >> was deprecated in Perl 5.8. A deprecation @@ -311,13 +311,13 @@ C<< File::Glob::bsd_glob() >> instead. =head3 C<< $* >> is no longer supported Before Perl 5.10, setting C<< $* >> to a true value globally enabled -multi-line matching within a string. This relique from the past lost +multi-line matching within a string. This relic from the past lost its special meaning in 5.10. Use of this variable became a fatal error in Perl 5.30, freeing the variable up for a future special meaning. To enable multiline matching one should use the C<< /m >> regexp modifier (possibly in combination with C<< /s >>). This can be set -on a per match bases, or can be enabled per lexical scope (including +on a per match basis, or can be enabled per lexical scope (including a whole file) with C<< use re '/m' >>. =head3 C<< $# >> is no longer supported @@ -340,24 +340,6 @@ indexing operations. Setting this to a non-zero value has been deprecated since Perl 5.12 and throws a fatal error as of Perl 5.30. -=head3 C<< File::Glob::glob() >> will disappear - -C<< File::Glob >> has a function called C<< glob >>, which just calls -C<< bsd_glob >>. However, its prototype is different from the prototype -of C<< CORE::glob >>, and hence, C<< File::Glob::glob >> should not -be used. - -C<< File::Glob::glob() >> was deprecated in Perl 5.8. A deprecation -message was issued from Perl 5.26 onwards, and in Perl 5.30 this was -turned into a fatal error. - -Code using C<< File::Glob::glob() >> should call -C<< File::Glob::bsd_glob() >> instead. - -=head3 Unescaped left braces in regular expressions (for 5.30) - -See L above. - =head3 Unqualified C Use of C instead of C was deprecated in Perl 5.8, @@ -409,21 +391,21 @@ validation they can end up creating invalidly encoded scalars. Similarly, syswrite() and send() use only the C<:utf8> flag, otherwise ignoring any layers. If the flag is set, both write the value UTF-8 encoded, even if -the layer is some different encoding, such as the example above. +the layer is some different encoding, such as the UTF-16LE example above. Ideally, all of these operators would completely ignore the C<:utf8> state, working only with bytes, but this would result in silently breaking existing code. To avoid this a future version of perl will throw an exception when -any of sysread(), recv(), syswrite() or send() are called on handle with the +any of sysread(), recv(), syswrite() or send() are called on handles with the C<:utf8> layer. -As of Perl 5.30, it is no longer be possible to use sysread(), recv(), -syswrite() or send() to read or send bytes from/to :utf8 handles. +As of Perl 5.30, it is no longer possible to use sysread(), recv(), +syswrite() or send() to read or send bytes from/to C<:utf8> handles. =head3 Use of unassigned code point or non-standalone grapheme for a delimiter -A grapheme is what appears to a native-speaker of a language to be a +A grapheme is what appears to a native speaker of a language to be a character. In Unicode (and hence Perl) a grapheme may actually be several adjacent characters that together form a complete grapheme. For example, there can be a base character, like "R" and an accent, like a @@ -460,10 +442,10 @@ of your code. =head3 Bare here-document terminators -Perl has allowed you to use a bare here-document terminator to have the -here-document end at the first empty line. This practise was deprecated -in Perl 5.000; as of Perl 5.28, using a bare here-document terminator -throws a fatal error. +Perl has allowed you to use a bare here-document terminator C<<< << >>> to +have the here-document end at the first empty line. This practise was +deprecated in Perl 5.000; as of Perl 5.28, using a bare here-document +terminator throws a fatal error. You are encouraged to use the explicitly quoted form if you wish to use an empty line as the terminator of the here-document: @@ -483,10 +465,10 @@ different, less efficient and with very bad luck could have resulted in your file being split by a stringified form of the reference. In Perl 5.20.0 this was changed so that it would be B the same as -setting C<$/> to undef, with the exception that this warning would be +setting C<$/> to C, with the exception that this warning would be thrown. -As of Perl 5.28, setting C<$/> to a reference of a non-positive +As of Perl 5.28, setting C<$/> to a reference to a non-positive integer throws a fatal error. You are recommended to change your code to set C<$/> to C explicitly @@ -510,7 +492,7 @@ Perl 5.28 using a code point exceeding C throws a fatal error. If your code is to run on various platforms, keep in mind that the upper limit depends on the platform. It is much larger on 64-bit word sizes -than 32-bit ones. For 32-bit integers, C equals C<0x7FFFFFFF>, +than 32-bit ones. For 32-bit integers, C equals C<0x7FFFFFFF>; for 64-bit integers, C equals C<0x7FFFFFFFFFFFFFFF>. @@ -555,7 +537,7 @@ throws a fatal error as of Perl 5.28. This method, which just calls C<< B::Concise::b_terse >>, has been deprecated, and disappeared in Perl 5.28. Please use -C<< B::Concise >> instead. +L instead. @@ -566,7 +548,7 @@ up as methods (using the C<@ISA> hierarchy) even when the subroutines to be autoloaded were called as plain functions (e.g. C), not as methods (e.g. C<< Foo->bar() >> or C<< $obj->bar() >>). -This bug was deprecated in Perl 5.004, has been rectified in Perl 5.28 +This bug was deprecated in Perl 5.004 and has been rectified in Perl 5.28 by using method lookup only for methods' Cs. The simple rule is: Inheritance will not work when autoloading @@ -576,17 +558,10 @@ named C, execute C<*AUTOLOAD = \&BaseClass::AUTOLOAD> during startup. In code that currently says C -you should remove AutoLoader from @ISA and change C to +you should remove AutoLoader from C<@ISA> and change C to C. -=head3 Use of code points over 0xFF in string bitwise operators - -The string bitwise operators, C<&>, C<|>, C<^>, and C<~>, treat -their operands as strings of bytes. As such, values above 0xFF -are nonsensical. Using such code points with these operators -was deprecated in Perl 5.24, and is fatal as of Perl 5.28. - =head3 In XS code, use of C This function has been removed as of Perl 5.28; instead convert to call @@ -613,7 +588,7 @@ These old, perl3-era utilities have been deprecated in favour of C<< h2xs >> for a long time. As of Perl 5.26, they have been removed. -=head3 Trapping C<< $SIG {__DIE__} >> other than during program exit +=head3 Trapping C<< $SIG{__DIE__} >> other than during program exit The C<$SIG{__DIE__}> hook is called even inside an C. It was never intended to happen this way, but an implementation glitch made