Merge branch 'data-dumper-testing' into blead

[perl5.git] / pod / perldiag.pod

diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index 64527f8..ed88545 100644 (file)
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -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.
 
 (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.
 =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.
 
 (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
 
 (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
 
 
 =item Bit vector size > 32 non-portable
 


@@ -663,7 +673,7 @@ Something like this will reproduce the error:
 
 =item Can't chdir to %s
 
 
 =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
 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.
 
 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
 =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.
 
 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.
 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).
 
 (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
 =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>.
 
 (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.
 =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.
 
 
 (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 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/
 
 =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.
 
 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>
 =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.
 
 "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
 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.
 
 (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
 <-- 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>.
 
 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
 
 (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.
 
 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}.
 
 (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.
 
 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
 =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>.
 
 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
 
 (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>.
 
 (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[][]
 =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.
 
 (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
 =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.
 
 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>,
 =item Useless use of \E
 
 (W misc) You have a \E in a double-quotish string without a C<\U>,