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 b8e1b13..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
@@ -2288,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.
@@ -2592,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.
 
@@ -2617,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
@@ -2672,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.
 
@@ -2774,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) 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) 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 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]
 
@@ -3405,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
@@ -3420,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
@@ -4044,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
 
@@ -4279,21 +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.  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 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/
 
@@ -5192,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
@@ -5636,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
@@ -5648,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
@@ -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
@@ -6965,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
@@ -7047,12 +7085,6 @@ 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 not allowed
 
@@ -7244,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>.