This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Merge branch 'data-dumper-testing' into blead
[perl5.git] / pod / perldiag.pod
index 64527f8..ed88545 100644 (file)
@@ -219,6 +219,14 @@ result of the value of the environment variable PERLIO.
 (D deprecated) Really old Perl let you omit the @ on array names in some
 spots.  This is now heavily deprecated.
 
+=item A sequence of multiple spaces in a charnames alias definition is deprecated
+
+(D) You defined a character name which had multiple space characters in
+a row.  Change them to single spaces.  Usually these names are 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 assertion botched: %s
 
 (X) The malloc package that comes with Perl had an internal failure.
@@ -528,13 +536,15 @@ check the return value of your socket() call?  See L<perlfunc/bind>.
 (W unopened) You tried binmode() on a filehandle that was never opened.
 Check your control flow and number of arguments.
 
-=item "\b{" is deprecated; use "\b\{" instead
+=item "\b{" is deprecated; use "\b\{" or "\b[{]" instead in regex; marked by <-- HERE in m/%s/
 
-=item "\B{" is deprecated; use "\B\{" instead
+=item "\B{" is deprecated; use "\B\{" or "\B[{]" instead in regex; marked by <-- HERE in m/%s/
 
 (W deprecated, regexp) Use of an unescaped "{" immediately following a
 C<\b> or C<\B> is now deprecated so as to reserve its use for Perl
-itself in a future release.
+itself in a future release.  You can either precede the brace with a
+backslash, or enclose it in square brackets; the latter is the way to go
+if the pattern delimiters are C<{}>.
 
 =item Bit vector size > 32 non-portable
 
@@ -663,7 +673,7 @@ Something like this will reproduce the error:
 
 =item Can't chdir to %s
 
-(F) You called C<perl -x/foo/bar>, but C</foo/bar> is not a directory
+(F) You called C<perl -x/foo/bar>, but F</foo/bar> is not a directory
 that you can chdir to, possibly because it doesn't exist.
 
 =item Can't check filesystem of script "%s" for nosuid
@@ -1789,6 +1799,23 @@ single form when it must operate on them directly.  Either you've passed
 an invalid file specification to Perl, or you've found a case the
 conversion routines don't handle.  Drat.
 
+=item Escape literal pattern white space under /x
+
+(D deprecated) You compiled a regular expression pattern with C</x> to
+ignore white space, and you used, as a literal, one of the characters
+that Perl plans to eventually treat as white space.  The character must
+be escaped somehow, or it will work differently on a future Perl that
+does treat it as white space.  The easiest way is to insert a backslash
+immediately before it, or to enclose it with square brackets.  This
+change is to bring Perl into conformance with Unicode recommendations.
+Here are the five characters that generate this warning:
+U+0085 NEXT LINE,
+U+200E LEFT-TO-RIGHT MARK,
+U+200F RIGHT-TO-LEFT MARK,
+U+2028 LINE SEPARATOR,
+and
+U+2029 PARAGRAPH SEPARATOR.
+
 =item Eval-group in insecure regular expression
 
 (F) Perl detected tainted data when trying to compile a regular
@@ -2131,9 +2158,9 @@ about 250 characters for simple names, and somewhat more for compound
 names (like C<$A::B>).  You've exceeded Perl's limits.  Future versions
 of Perl are likely to eliminate these arbitrary limitations.
 
-=item Ignoring zero length \N{} in character class
+=item Ignoring zero length \N{} in character class in regex; marked by <-- HERE in m/%s/
 
-(W) Named Unicode character escapes C<(\N{...})> may return a zero-length
+(W regexp) Named Unicode character escapes C<(\N{...})> may return a zero-length
 sequence.  When such an escape is used in a character class its
 behaviour is not well defined.  Check that the correct escape has
 been used, and the correct charname handler is in scope.
@@ -2517,17 +2544,6 @@ with 'useperlio'.
 (F) Your machine doesn't implement the sockatmark() functionality,
 neither as a system call nor an ioctl call (SIOCATMARK).
 
-=item It is deprecated to pass malformed UTF-8 to character classification macros, for "%s"
-
-(D deprecated, utf8) 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.  If C<utf8> warnings are enabled, a further message is raised,
-giving details of the malformation.
-
 =item $* is no longer supported
 
 (D deprecated, syntax) The special variable C<$*>, deprecated in older
@@ -3396,6 +3412,12 @@ call, or call a constructor from the FileHandle package.
 (W unopened) You tried to invoke a file test operator on a filehandle
 that isn't open.  Check your control flow.  See also L<perlfunc/-X>.
 
+=item Strings with code points over 0xFF may not be mapped into in-memory file handles
+
+(W utf8) You tried to open a reference to a scalar for read or append
+where the scalar contained code points over 0xFF.  In-memory files
+model on-disk files and can only contain bytes.
+
 =item oops: oopsAV
 
 (S internal) An internal warning that the grammar is screwed up.
@@ -3787,11 +3809,34 @@ to even) byte length.
 
 (P) The lexer got into a bad state while processing a case modifier.
 
+=item Parentheses missing around "%s" list
+
+(W parenthesis) You said something like
+
+    my $foo, $bar = @_;
+
+when you meant
+
+    my ($foo, $bar) = @_;
+
+Remember that "my", "our", "local" and "state" bind tighter than comma.
+
 =item Parsing code internal error (%s)
 
 (F) Parsing code supplied by an extension violated the parser's API in
 a detectable way.
 
+=item Passing malformed UTF-8 to "%s" is deprecated
+
+(D deprecated, utf8) 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.  If C<utf8> warnings are enabled, a further message is raised,
+giving details of the malformation.
+
 =item Pattern subroutine nesting without pos change exceeded limit in regex; 
 marked by <-- HERE in m/%s/
 
@@ -3802,18 +3847,6 @@ the nesting limit is exceeded.
 The <-- HERE shows whereabouts in the regular expression the problem was
 discovered.
 
-=item Parentheses missing around "%s" list
-
-(W parenthesis) You said something like
-
-    my $foo, $bar = @_;
-
-when you meant
-
-    my ($foo, $bar) = @_;
-
-Remember that "my", "our", "local" and "state" bind tighter than comma.
-
 =item C<-p> destination: %s
 
 (F) An error occurred during the implicit output invoked by the C<-p>
@@ -3826,10 +3859,10 @@ redirected it with select().)
 "Can't locate object method \"%s\" via package \"%s\"".  It often means
 that a method requires a package that has not been loaded.
 
-=item Perl folding rules are not up-to-date for 0x%x; please use the perlbug 
-utility to report;
+=item Perl folding rules are not up-to-date for 0x%X; please use the perlbug 
+utility to report; in regex; marked by <-- HERE in m/%s/
 
-(W regex, deprecated) You used a regular expression with
+(W regexp, deprecated) You used a regular expression with
 case-insensitive matching, and there is a bug in Perl in which the
 built-in regular expression folding rules are not accurate.  This may
 lead to incorrect results.  Please report this as a bug using the
@@ -3926,7 +3959,7 @@ not C<isprint>.  See L<perlre>.
 (F) Your system has POSIX getpgrp(), which takes no argument, unlike
 the BSD version, which takes a pid.
 
-=item POSIX syntax [%s] belongs inside character classes in regex; marked by 
+=item POSIX syntax [%c %c] belongs inside character classes in regex; marked by 
 <-- HERE in m/%s/
 
 (W regexp) The character class constructs [: :], [= =], and [. .]  go
@@ -4129,8 +4162,8 @@ expression the problem was discovered.  See L<perlre>.
 the {min,max} construct.  The <-- HERE shows whereabouts in the regular
 expression the problem was discovered.  See L<perlre>.
 
-=item Quantifier unexpected on zero-length expression; marked by <-- HERE in 
-m/%s/
+=item Quantifier unexpected on zero-length expression in regex; marked by <-- 
+HERE in m/%s/
 
 (W regexp) You applied a regular expression quantifier in a place where
 it makes no sense, such as on a zero-width assertion.  Try putting the
@@ -4141,7 +4174,7 @@ C</abc(?=(?:xyz){3})/>, not C</abc(?=xyz){3}/>.
 The <-- HERE shows whereabouts in the regular expression the problem was
 discovered.
 
-=item Quantifier {n,m} with n > m can't match in regex
+=item Quantifier {n,m} with n > m can't match in regex; marked by <-- HERE in m/%s/
 
 (W regexp) Minima should be less than or equal to maxima.  If you really
 want your regexp to match something 0 times, just put {0}.
@@ -4305,6 +4338,15 @@ terminates.  You might use ^# instead.  See L<perlform>.
 search list.  So the additional elements in the replacement list
 are meaningless.
 
+=item '%s' resolved to '\o{%s}%d'
+
+(W misc, regexp)  You wrote something like C<\08>, or C<\179> in a
+double-quotish string.  All but the last digit is treated as a single
+character, specified in octal.  The last digit is the next character in
+the string.  To tell Perl that this is indeed what you want, you can use
+the C<\o{ }> syntax, or use exactly three digits to specify the octal
+for the character.
+
 =item Reversed %s= operator
 
 (W syntax) You wrote your assignment operator backwards.  The = must
@@ -4822,7 +4864,7 @@ as a compiler directive.  You may say only one of
 This is to prevent the problem of one module changing the array base out
 from under another module inadvertently.  See L<perlvar/$[> and L<arybase>.
 
-=item The crypt() function is unimplemented due to excessive paranoia
+=item The crypt() function is unimplemented due to excessive paranoia.
 
 (F) Configure couldn't find the crypt() function on your machine,
 probably because your vendor didn't supply it, probably because they
@@ -4956,6 +4998,14 @@ Check the #! line, or manually feed your script into Perl yourself.
 (F) The regular expression ends with an unbackslashed backslash.
 Backslash it.   See L<perlre>.
 
+=item Trailing white-space in a charnames alias definition is deprecated
+
+(D) You defined a character name which ended in a space character.
+Remove the trailing space(s).  Usually these names are 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 Transliteration pattern not terminated
 
 (F) The lexer couldn't find the interior delimiter of a tr/// or tr[][]
@@ -5068,17 +5118,6 @@ C<undef *foo>.
 (A) You've accidentally run your script through B<csh> instead of Perl.
 Check the #! line, or manually feed your script into Perl yourself.
 
-=item Unescaped left brace in regex is deprecated, passed through
-
-(D) You used a literal C<"{"> character in a regular expression pattern.
-You should change to use C<"\{"> instead, because a future version of
-Perl (tentatively v5.20) will consider this to be a syntax error.  If
-the pattern delimiters are also braces, any matching right brace
-(C<"}">) should also be escaped to avoid confusing the parser, for
-example,
-
-    qr{abc\{def\}ghi}
-
 =item unexec of %s into %s failed!
 
 (F) The unexec() routine failed for some reason.  See your local FSF
@@ -5442,6 +5481,31 @@ discovered.  See L<perlre>.
 same length as the replacelist.  See L<perlop> for more information
 about the /d modifier.
 
+=item Useless use of '\'; doesn't escape metacharacter '%c'
+
+(D deprecated) You wrote a regular expression pattern something like
+one of these:
+
+ m{ \x\{FF\} }x
+ m{foo\{1,3\}}
+ qr(foo\(bar\))
+ s[foo\[a-z\]bar][baz]
+
+The interior braces, square brackets, and parentheses are treated as
+metacharacters even though they are backslashed; instead write:
+
+ m{ \x{FF} }x
+ m{foo{1,3}}
+ qr(foo(bar))
+ s[foo[a-z]bar][baz]
+
+The backslashes have no effect when a regular expression pattern is
+delimitted by C<{}>, C<[]>, or C<()>, which ordinarily are
+metacharacters, and the delimiters are also used, paired, within the
+interior of the pattern.  It is planned that a future Perl release will
+change the meaning of constructs like these so that the backslashes
+will have an effect, so remove them from your code.
+
 =item Useless use of \E
 
 (W misc) You have a \E in a double-quotish string without a C<\U>,