This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta: update updated modules
[perl5.git] / pod / perldiag.pod
index a6f59e7..b069fb1 100644 (file)
@@ -656,6 +656,13 @@ the warning.  See L<perlsub>.
 
 (F) You passed an invalid number (like an infinity or not-a-number) to C<chr>.
 
+=item Cannot complete in-place edit of %s: %s
+
+(F) Your perl script appears to have changed directory while
+performing an in-place edit of a file specified by a relative path,
+and your system doesn't include the directory relative POSIX functions
+needed to handle that.
+
 =item Cannot compress %f in pack
 
 (F) You tried compressing an infinity or not-a-number as an unsigned
@@ -690,6 +697,20 @@ be directly assigned to.
 (S io) You tried to apply an encoding that did not exist to a filehandle,
 either with open() or binmode().
 
+=item Cannot open %s as a dirhandle: it is already open as a filehandle
+
+(F) You tried to use opendir() to associate a dirhandle to a symbol (glob
+or scalar) that already holds a filehandle.  Since this idiom might render
+your code confusing, it was deprecated in Perl 5.10.  As of Perl 5.28, it
+is a fatal error.
+
+=item Cannot open %s as a filehandle: it is already open as a dirhandle
+
+(F) You tried to use open() to associate a filehandle to a symbol (glob
+or scalar) that already holds a dirhandle.  Since this idiom might render
+your code confusing, it was deprecated in Perl 5.10.  As of Perl 5.28, it
+is a fatal error.
+
 =item Cannot pack %f with '%c'
 
 (F) You tried converting an infinity or not-a-number to an integer,
@@ -1166,6 +1187,8 @@ a NULL.
 
 =item Can't modify non-lvalue subroutine call of &%s
 
+=item Can't modify non-lvalue subroutine call of &%s in %s
+
 (F) Subroutines meant to be used in lvalue context should be declared as
 such.  See L<perlsub/"Lvalue subroutines">.
 
@@ -1295,9 +1318,14 @@ the modified file.  The file was left unmodified.
 
 =item Can't rename %s to %s: %s, skipping file
 
-(S inplace) The rename done by the B<-i> switch failed for some reason,
+(F) The rename done by the B<-i> switch failed for some reason,
 probably because you don't have write permission to the directory.
 
+=item Can't rename in-place work file '%s' to '%s': %s
+
+(F) When closed implicitly, the temporary file for in-place editing
+couldn't be renamed to the original filename.
+
 =item Can't reopen input pipe (name: %s) in binary mode
 
 (P) An error peculiar to VMS.  Perl thought stdin was a pipe, and tried
@@ -1508,6 +1536,11 @@ expression pattern.  Trying to do this in ordinary Perl code produces a
 value that prints out looking like SCALAR(0xdecaf).  Use the $1 form
 instead.
 
+=item Can't unweaken a nonreference
+
+(F) You attempted to unweaken something that was not a reference.  Only
+references can be unweakened.
+
 =item Can't weaken a nonreference
 
 (F) You attempted to weaken something that was not a reference.  Only
@@ -1619,7 +1652,8 @@ uses the character values modulus 256 instead, as if you had provided:
 
    unpack("s", "\x{f3}b")
 
-=item charnames alias definitions may not contain a sequence of multiple spaces
+=item charnames alias definitions may not contain a sequence of multiple
+spaces; marked by S<<-- HERE> in %s
 
 (F) You defined a character name which had multiple space characters
 in a row.  Change them to single spaces.  Usually these names are
@@ -1627,7 +1661,8 @@ defined in the C<:alias> import argument to C<use charnames>, but they
 could be defined by a translator installed into C<$^H{charnames}>.  See
 L<charnames/CUSTOM ALIASES>.
 
-=item charnames alias definitions may not contain trailing white-space
+=item charnames alias definitions may not contain trailing white-space;
+marked by S<<-- HERE> in %s
 
 (F) You defined a character name which ended in a space
 character.  Remove the trailing space(s).  Usually these names are
@@ -2112,12 +2147,13 @@ unlikely to be what you want.
 described in L<perlunicode> and L<perlre>.  You used C<\p> or C<\P> in
 a regular expression without specifying the property name.
 
-=item ${^ENCODING} is no longer supported. Its use will be fatal in Perl 5.28
+=item ${^ENCODING} is no longer supported
 
-(D deprecated) The special variable C<${^ENCODING}>, formerly used to implement
+(F) The special variable C<${^ENCODING}>, formerly used to implement
 the C<encoding> pragma, is no longer supported as of Perl 5.26.0.
 
-Setting this variable will become a fatal error in Perl 5.28.
+Setting it to anything other than C<undef> is a fatal error as of Perl
+5.28.
 
 =item entering effective %s failed
 
@@ -2287,7 +2323,7 @@ Check the #! line, or manually feed your script into Perl yourself.
 CHECK, INIT, or END subroutine.  Processing of the remainder of the
 queue of such routines has been prematurely ended.
 
-=item Failed to close in-place edit file %s: %s
+=item Failed to close in-place work file %s: %s
 
 (F) Closing an output file from in-place editing, as with the C<-i>
 command-line switch, failed.
@@ -2591,7 +2627,7 @@ zero-length sequence.  When such an escape is used in a character
 class its behavior is not well defined.  Check that the correct
 escape has been used, and the correct charname handler is in scope.
 
-=item Illegal binary digit %s
+=item Illegal binary digit '%c'
 
 (F) You used a digit other than 0 or 1 in a binary number.
 
@@ -2616,6 +2652,17 @@ this error when Perl was built using standard options.  For some
 reason, your version of Perl appears to have been built without
 this support.  Talk to your Perl administrator.
 
+=item Illegal operator following parameter in a subroutine signature
+
+(F) A parameter in a subroutine signature, was followed by something
+other than C<=> introducing a default, C<,> or C<)>.
+
+    use feature 'signatures';
+    sub foo ($=1) {}           # legal
+    sub foo ($a = 1) {}        # legal
+    sub foo ($a += 1) {}       # illegal
+    sub foo ($a == 1) {}       # illegal
+
 =item Illegal character following sigil in a subroutine signature
 
 (F) A parameter in a subroutine signature contained an unexpected character
@@ -2671,7 +2718,7 @@ numbers don't take to this kindly.
 (F) The number of bits in vec() (the third argument) must be a power of
 two from 1 to 32 (or 64, if your platform supports that).
 
-=item Illegal octal digit %s
+=item Illegal octal digit '%c'
 
 (F) You used an 8 or 9 in an octal number.
 
@@ -2773,12 +2820,19 @@ not match 8 spaces.
 text.  You should check the pattern to ensure that recursive patterns
 either consume text or fail.
 
-=item Initialization of state variables in list context currently forbidden
+=item Infinite recursion via empty pattern
+
+(F) You tried to use the empty pattern inside of a regex code block,
+for instance C</(?{ s!!! })/>, which resulted in re-executing
+the same pattern, which is an infinite loop which is broken by
+throwing an exception.
+
+=item Initialization of state variables in list currently forbidden
 
-(F) C<state> only permits initializing a single scalar variable, in scalar
-context.  So C<state $a = 42> is allowed, but not C<state ($a) = 42>.  To apply
-state semantics to a hash or array, store a hash or array reference in a
-scalar variable.
+(F) C<state> only permits initializing a single variable, specified
+without parentheses.  So C<state $a = 42> and C<state @a = qw(a b c)> are
+allowed, but not C<state ($a) = 42> or C<(state $a) = 42>.  To initialize
+more than one C<state> variable, initialize them one at a time.
 
 =item %%s[%s] in scalar context better written as $%s[%s]
 
@@ -3130,9 +3184,8 @@ syswrite() or send() to read or send bytes from/to :utf8 handles.
 
 (W regexp) (only under C<S<use re 'strict'>> or within C<(?[...])>)
 
-You specified a character that has the given plainer way of writing it,
-and which is also portable to platforms running with different character
-sets.
+You specified a character that has the given plainer way of writing it, and
+which is also portable to platforms running with different character sets.
 
 =item $* is no longer supported. Its use will be fatal in Perl 5.30
 
@@ -3392,13 +3445,12 @@ platform (overflows).  Details as to the exact malformation are given in
 the variable, C<%s>, part of the message.
 
 One possible cause is that you set the UTF8 flag yourself for data that
-you thought to be in UTF-8 but it wasn't (it was for example legacy
-8-bit data).  To guard against this, you can use C<Encode::decode('UTF-8', ...)>.
+you thought to be in UTF-8 but it wasn't (it was for example legacy 8-bit
+data).  To guard against this, you can use C<Encode::decode('UTF-8', ...)>.
 
 If you use the C<:encoding(UTF-8)> PerlIO layer for input, invalid byte
-sequences are handled gracefully, but if you use C<:utf8>, the flag is
-set without validating the data, possibly resulting in this error
-message.
+sequences are handled gracefully, but if you use C<:utf8>, the flag is set
+without validating the data, possibly resulting in this error message.
 
 See also L<Encode/"Handling Malformed Data">.
 
@@ -3406,6 +3458,19 @@ See also L<Encode/"Handling Malformed Data">.
 
 (F) The charnames handler returned malformed UTF-8.
 
+=item Malformed UTF-8 string in "%s"
+
+(F) This message indicates a bug either in the Perl core or in XS
+code. Such code was trying to find out if a character, allegedly
+stored internally encoded as UTF-8, was of a given type, such as
+being punctuation or a digit.  But the character was not encoded
+in legal UTF-8.  The C<%s> is replaced by a string that can be used
+by knowledgeable people to determine what the type being checked
+against was.
+
+Passing malformed strings was deprecated in Perl 5.18, and
+became fatal in Perl 5.26.
+
 =item Malformed UTF-8 string in '%c' format in unpack
 
 (F) You tried to unpack something that didn't comply with UTF-8 encoding
@@ -3421,19 +3486,6 @@ rules and perl was unable to guess how to make more progress.
 (F) You tried to unpack something that didn't comply with UTF-8 encoding
 rules and perl was unable to guess how to make more progress.
 
-=item Malformed UTF-8 string in "%s"
-
-(F) This message indicates a bug either in the Perl core or in XS
-code. Such code was trying to find out if a character, allegedly
-stored internally encoded as UTF-8, was of a given type, such as
-being punctuation or a digit.  But the character was not encoded
-in legal UTF-8.  The C<%s> is replaced by a string that can be used
-by knowledgeable people to determine what the type being checked
-against was.
-
-Passing malformed strings was deprecated in Perl 5.18, and
-became fatal in Perl 5.26.
-
 =item Malformed UTF-16 surrogate
 
 (F) Perl thought it was reading UTF-16 encoded character data but while
@@ -3527,6 +3579,11 @@ ended earlier on the current line.
 (W syntax) An underscore (underbar) in a numeric constant did not
 separate two digits.
 
+=item Missing argument for %n in %s
+
+(F) A C<%n> was used in a format string with no corresponding argument for
+perl to write the current string length to.
+
 =item Missing argument in %s
 
 (W missing) You called a function with fewer arguments than other
@@ -4040,11 +4097,13 @@ doesn't know where you wanted to redirect stdout.
 redirection, and found a '>' or a '>>' on the command line, but can't
 find the name of the file to which to write data destined for stdout.
 
+=item No package name allowed for subroutine %s in "our"
+
 =item No package name allowed for variable %s in "our"
 
-(F) Fully qualified variable names are not allowed in "our"
-declarations, because that doesn't make much sense under existing
-rules.  Such syntax is reserved for future extensions.
+(F) Fully qualified subroutine and variable names are not allowed in "our"
+declarations, because that doesn't make much sense under existing rules.
+Such syntax is reserved for future extensions.
 
 =item No Perl script found in input
 
@@ -4275,22 +4334,6 @@ that isn't open.  Check your control flow.  See also L<perlfunc/-X>.
 
 (S internal) An internal warning that the grammar is screwed up.
 
-=item Cannot open %s as a filehandle: it is already open as a dirhandle
-
-(F) You tried to use open() to associate a filehandle to
-a symbol (glob or scalar) that already holds a dirhandle.
-This idiom might render your code confusing
-and this was deprecated in Perl 5.10. As of Perl 5.28, this
-is a fatal error.
-
-=item Cannot open %s as a dirhandle: it is already open as a filehandle
-
-(F) You tried to use opendir() to associate a dirhandle to
-a symbol (glob or scalar) that already holds a filehandle.
-This idiom might render your code confusing
-and this was deprecated in Perl 5.10. As of Perl 5.28, this
-is a fatal error.
-
 =item Operand with no preceding operator in regex; marked by S<<-- HERE> in
 m/%s/
 
@@ -5189,6 +5232,11 @@ to use parens.  In any case, a hash requires key/value B<pairs>.
 (W misc) You have attempted to weaken a reference that is already weak.
 Doing so has no effect.
 
+=item Reference is not weak
+
+(W misc) You have attempted to unweaken a reference that is not weak.
+Doing so has no effect.
+
 =item Reference to invalid group 0 in regex; marked by S<<-- HERE> in m/%s/
 
 (F) You used C<\g0> or similar in a regular expression.  You may refer
@@ -5552,19 +5600,18 @@ L<perlfunc/setsockopt>.
 
 =item Setting $/ to a reference to %s is forbidden
 
-(F) You assigned a reference to a scalar to C<$/> where the
-referenced item is not a positive integer.  In older perls this B<appeared>
-to work the same as setting it to C<undef> but was in fact internally
-different, less efficient and with very bad luck could have resulted in
-your file being split by a stringified form of the reference.
+(F) You assigned a reference to a scalar to C<$/> where the referenced item is
+not a positive integer.  In older perls this B<appeared> to work the same as
+setting it to C<undef> but was in fact internally 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<exactly> the same as
-setting C<$/> to undef, with the exception that this warning would be
-thrown.
+setting C<$/> to undef, with the exception that this warning would be thrown.
 
-You are recommended to change your code to set C<$/> to C<undef> explicitly
-if you wish to slurp the file.  As of Perl 5.28 assigning C<$/> to a
-reference to an integer which isn't positive is a fatal error.
+You are recommended to change your code to set C<$/> to C<undef> explicitly if
+you wish to slurp the file.  As of Perl 5.28 assigning C<$/> to a reference
+to an integer which isn't positive is a fatal error.
 
 =item Setting $/ to %s reference is forbidden
 
@@ -5634,11 +5681,6 @@ Perl.  Particularly, its current behavior is noticed for being
 unnecessarily complex and unintuitive, and is very likely to be
 overhauled.
 
-=item sort is now a reserved word
-
-(F) An ancient error message that almost nobody ever runs into anymore.
-But before sort was a keyword, people sometimes used it as a filehandle.
-
 =item Sorry, hash keys must be smaller than 2**31 bytes
 
 (F) You tried to create a hash containing a very large key, where "very
@@ -5646,6 +5688,11 @@ large" means that it needs at least 2 gigabytes to store. Unfortunately,
 Perl doesn't yet handle such large hash keys. You should
 reconsider your design to avoid hashing such a long string directly.
 
+=item sort is now a reserved word
+
+(F) An ancient error message that almost nobody ever runs into anymore.
+But before sort was a keyword, people sometimes used it as a filehandle.
+
 =item Source filters apply only to byte streams
 
 (F) You tried to activate a source filter (usually by loading a
@@ -6082,13 +6129,12 @@ system call to call, silly dilly.
 
 =item Too few arguments for subroutine '%s'
 
-(F) A subroutine using a signature received too few arguments than
-required by the signature.  The caller of the subroutine is presumably
-at fault.
+(F) A subroutine using a signature fewer arguments than required by the
+signature.  The caller of the subroutine is presumably at fault.
 
-The message attempts to include the name of the called subroutine. If the
-subroutine has been aliased, the subroutine's original name will be shown,
-regardless of what name the caller used.
+The message attempts to include the name of the called subroutine.  If
+the subroutine has been aliased, the subroutine's original name will be
+shown, regardless of what name the caller used.
 
 =item Too late for "-%s" option
 
@@ -6122,9 +6168,8 @@ BEGIN block.
 
 =item Too many arguments for subroutine '%s'
 
-(F) A subroutine using a signature received too many arguments than
-required by the signature.  The caller of the subroutine is presumably
-at fault.
+(F) A subroutine using a signature received more arguments than permitted
+by the signature.  The caller of the subroutine is presumably at fault.
 
 The message attempts to include the name of the called subroutine. If the
 subroutine has been aliased, the subroutine's original name will be shown,
@@ -6511,7 +6556,7 @@ iterating over it, and someone else stuck a message in the stream of
 data Perl expected.  Someone's very confused, or perhaps trying to
 subvert Perl's population of %ENV for nefarious purposes.
 
-=item Unknown regex modifier "%s"
+=item Unknown regexp modifier "/%s"
 
 (F) Alphanumerics immediately following the closing delimiter
 of a regular expression pattern are interpreted by Perl as modifier
@@ -6926,12 +6971,11 @@ is deprecated.  See L<perlvar/"$[">.
 
 =item Use of bare << to mean <<"" is forbidden
 
-(F) You are now required to use the explicitly quoted
-form if you wish to use an empty line as the terminator of the
-here-document.
+(F) You are now required to use the explicitly quoted form if you wish
+to use an empty line as the terminator of the here-document.
 
-Use of a bare terminator was deprecated in Perl 5.000, and
-is a fatal error as of Perl 5.28.
+Use of a bare terminator was deprecated in Perl 5.000, and is a fatal
+error as of Perl 5.28.
 
 =item Use of /c modifier is meaningless in s///
 
@@ -6966,13 +7010,6 @@ became a fatal error in Perl 5.28.
 it may skip items, or visit items more than once.  Consider using
 C<keys()> instead of C<each()>.
 
-=item Infinite recursion via empty pattern
-
-(F) You tried to use the empty pattern inside of a regex code block,
-for instance C</(?{ s!!! })/>, which resulted in re-executing
-the same pattern, which is an infinite loop which is broken by
-throwing an exception.
-
 =item Use of := for an empty attribute list is not allowed
 
 (F) The construction C<my $x := 42> used to parse as equivalent to
@@ -7017,31 +7054,14 @@ scope is deprecated and should be avoided.
 
 This was deprecated in Perl 5.12.
 
-=item Use of inherited AUTOLOAD for non-method %s() is deprecated. This will be fatal in Perl 5.28
-
-(D deprecated) As an (ahem) accidental feature, C<AUTOLOAD>
-subroutines are looked up as methods (using the C<@ISA> hierarchy)
-even when the subroutines to be autoloaded were called as plain
-functions (e.g. C<Foo::bar()>), not as methods (e.g. C<< Foo->bar() >> or
-C<< $obj->bar() >>).
+=item Use of inherited AUTOLOAD for non-method %s::%s() is no longer allowed
 
-This bug will be rectified in future by using method lookup only for
-methods' C<AUTOLOAD>s.  However, there is a significant base of existing
-code that may be using the old behavior.  So, as an interim step, Perl
-currently issues an optional warning when non-methods use inherited
-C<AUTOLOAD>s.
+(F) As an accidental feature, C<AUTOLOAD> subroutines were looked up as
+methods (using the C<@ISA> hierarchy), even when the subroutines to be
+autoloaded were called as plain functions (e.g. C<Foo::bar()>), not as
+methods (e.g. C<< Foo->bar() >> or C<< $obj->bar() >>).
 
-The simple rule is:  Inheritance will not work when autoloading
-non-methods.  The simple fix for old code is:  In any module that used
-to depend on inheriting C<AUTOLOAD> for non-methods from a base class
-named C<BaseClass>, execute C<*AUTOLOAD = \&BaseClass::AUTOLOAD> during
-startup.
-
-In code that currently says C<use AutoLoader; @ISA = qw(AutoLoader);>
-you should remove AutoLoader from @ISA and change C<use AutoLoader;> to
-C<use AutoLoader 'AUTOLOAD';>.
-
-This feature was deprecated in Perl 5.004, and will be fatal in Perl 5.28.
+This was deprecated in Perl 5.004, and was made fatal in Perl 5.28.
 
 =item Use of %s in printf format not supported
 
@@ -7065,21 +7085,15 @@ C<$array[0+$ref]>.  This warning is not given for overloaded objects,
 however, because you can overload the numification and stringification
 operators and then you presumably know what you are doing.
 
-=item Use of state $_ is experimental
-
-(S experimental::lexical_topic) Lexical $_ is an experimental feature and
-its behavior may change or even be removed in any future release of perl.
-See the explanation under L<perlvar/$_>.
-
 =item Use of strings with code points over 0xFF as arguments to %s
-operator is deprecated. This will be a fatal error in Perl 5.28
+operator is not allowed
 
-(D deprecated) You tried to use one of the string bitwise operators
-(C<&> or C<|> or C<^> or C<~>) on a string containing a code point over
-0xFF.  The string bitwise operators treat their operands as strings of
-bytes, and values beyond 0xFF are nonsensical in this context.
+(F) You tried to use one of the string bitwise operators (C<&> or C<|> or C<^> or
+C<~>) on a string containing a code point over 0xFF.  The string bitwise
+operators treat their operands as strings of bytes, and values beyond
+0xFF are nonsensical in this context.
 
-Such usage will be a fatal error in Perl 5.28.
+This became fatal in Perl 5.28.
 
 =item Use of strings with code points over 0xFF as arguments to C<vec>
 is deprecated. This will be a fatal error in Perl 5.32
@@ -7262,14 +7276,42 @@ known at compile time.  For positive lookbehind, you can use the C<\K>
 regex construct as a way to get the equivalent functionality.  See
 L<(?<=pattern) and \K in perlre|perlre/\K>.
 
-There are non-obvious Unicode rules under C</i> that can match variably,
-but which you might not think could.  For example, the substring C<"ss">
-can match the single character LATIN SMALL LETTER SHARP S.  There are
-other sequences of ASCII characters that can match single ligature
-characters, such as LATIN SMALL LIGATURE FFI matching C<qr/ffi/i>.
-Starting in Perl v5.16, if you only care about ASCII matches, adding the
-C</aa> modifier to the regex will exclude all these non-obvious matches,
-thus getting rid of this message.  You can also say C<S<use re qw(/aa)>>
+Starting in Perl 5.18, there are non-obvious Unicode rules under C</i>
+that can match variably, but which you might not think could.  For
+example, the substring C<"ss"> can match the single character LATIN
+SMALL LETTER SHARP S.  Here's a complete list of the current ones
+affecting ASCII characters:
+
+   ASCII
+  sequence      Matches single letter under /i
+    FF          U+FB00 LATIN SMALL LIGATURE FF
+    FFI         U+FB03 LATIN SMALL LIGATURE FFI
+    FFL         U+FB04 LATIN SMALL LIGATURE FFL
+    FI          U+FB01 LATIN SMALL LIGATURE FI
+    FL          U+FB02 LATIN SMALL LIGATURE FL
+    SS          U+00DF LATIN SMALL LETTER SHARP S
+                U+1E9E LATIN CAPITAL LETTER SHARP S
+    ST          U+FB06 LATIN SMALL LIGATURE ST
+                U+FB05 LATIN SMALL LIGATURE LONG S T
+
+This list is subject to change, but is quite unlikely to.
+Each ASCII sequence can be any combination of upper- and lowercase.
+
+You can avoid this by using a bracketed character class in the
+lookbehind assertion, like
+
+ (?<![sS]t)
+ (?<![fF]f[iI])
+
+This fools Perl into not matching the ligatures.
+
+Another option for Perls starting with 5.16, if you only care about
+ASCII matches, is to add the C</aa> modifier to the regex.  This will
+exclude all these non-obvious matches, thus getting rid of this message.
+You can also say
+
+ use if $] ge 5.016, re => '/aa';
+
 to apply C</aa> to all regular expressions compiled within its scope.
 See L<re>.