POD tweak to 'require' in perlfunc relating to putting Perl code in @INC
[p5sagit/p5-mst-13.2.git] / pod / perldiag.pod
index 4a12889..1d3b55c 100644 (file)
@@ -1159,11 +1159,6 @@ that is already inside a group with a byte-order modifier.
 For example you cannot force little-endianness on a type that
 is inside a big-endian group.
 
-=item Can't use keyword '%s' as a label
-
-(F) You attempted to use a reserved keyword, such as C<print> or C<BEGIN>,
-as a statement label. This is disallowed since Perl 5.11.0.
-
 =item Can't use "my %s" in sort comparison
 
 (F) The global variables $a and $b are reserved for sort comparisons.
@@ -1216,6 +1211,10 @@ references can be weakened.
 with an assignment operator, which implies modifying the value itself.
 Perhaps you need to copy the value to a temporary, and repeat that.
 
+=item Character following "\\c" must be ASCII
+
+(F) In C<\cI<X>>, I<X> must be an ASCII character.
+
 =item Character in 'C' format wrapped in pack
 
 (W pack) You said
@@ -1424,6 +1423,12 @@ valid magic number.
 you have also specified an explicit size for the string.  See
 L<perlfunc/pack>.
 
+=item \\c%c" more clearly written simply as "%c
+
+(D deprecated) The C<\cI<X>> construct is intended to be a way to specify
+non-printable characters.  You used it for a printable one, which is better
+written as simply itself.
+
 =item Deep recursion on subroutine "%s"
 
 (W recursion) This subroutine has called itself (directly or indirectly)
@@ -1457,6 +1462,14 @@ there are neither package declarations nor a C<$VERSION>.
 long for Perl to handle.  You have to be seriously twisted to write code
 that triggers this error.
 
+=item Deprecated character in \\N{...}; marked by <-- HERE  in \\N{%s<-- HERE %s
+
+(D deprecated) Just about anything is legal for the C<...> in C<\N{...}>.
+But starting in 5.12, non-reasonable ones that don't look like names are
+deprecated.  A reasonable name begins with an alphabetic character and
+continues with any combination of alphanumerics, dashes, spaces, parentheses or
+colons.
+
 =item Deprecated use of my() in false conditional
 
 (D deprecated) You used a declaration similar to C<my $x if 0>.
@@ -1497,8 +1510,8 @@ do.  See L<perlfunc/require>.
 
 =item (Did you mean &%s instead?)
 
-(W) You probably referred to an imported subroutine &FOO as $FOO or some
-such.
+(W misc) You probably referred to an imported subroutine &FOO as $FOO or
+some such.
 
 =item (Did you mean "local" instead of "our"?)
 
@@ -1521,6 +1534,18 @@ you called it with no args and both C<$@> and C<$_> were empty.
 
 See Server error.
 
+=item Dot after %s literal is deprecated concatenation
+
+(D deprecated, syntax) You had something like 0x123.456 in your code.
+This is currently
+parsed as the hexadecimal number 0x123 concatenated with the decimal
+number 456, not the fraction 0x123 + 0x456/0x1000 -- we only support decimal
+fractions.  If you meant it to be a fraction, you'll need to use
+Math::BigFloat's from_hex (or friends).  If you meant it to be
+concatenation, just put spaces around the dot to make it clearer.  In
+5.14.0, we expect to change this to mean a hex fraction.  (Of course,
+everything above applies to octal and binary constants, too.)
+
 =item %s does not define %s::VERSION--version check failed
 
 (F) You said something like "use Module 42" but the Module did not
@@ -1912,7 +1937,7 @@ 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
 
 (W) Named Unicode character escapes (\N{...}) may return a
 zero length sequence.  When such an escape is used in a character class
@@ -2474,7 +2499,10 @@ immediately after the switch, without intervening spaces.
 =item Missing braces on \N{}
 
 (F) Wrong syntax of character name literal C<\N{charname}> within
-double-quotish context.
+double-quotish context.  This can also happen when there is a space (or
+comment) between the C<\N> and the C<{> in a regex with the C</x> modifier.
+This modifier does not change the requirement that the brace immediately follow
+the C<\N>.
 
 =item Missing comma after first argument to %s function
 
@@ -2524,18 +2552,18 @@ double-quoted strings and regular expression patterns.  In patterns, it doesn't
 have the meaning an unescaped C<*> does.
 
 Starting in Perl 5.12.0, C<\N> also can have an additional meaning (only) in
-patterns, namely to match a non-newline character.  (This is like C<.> but is
-not affected by the C</s> modifier.)
+patterns, namely to match a non-newline character.  (This is short for
+C<[^\n]>, and like C<.> but is not affected by the C</s> regex modifier.)
 
 This can lead to some ambiguities.  When C<\N> is not followed immediately by a
-left brace, Perl assumes the "match non-newline character" meaning.  Also, if
+left brace, Perl assumes the C<[^\n]> meaning.  Also, if
 the braces form a valid quantifier such as C<\N{3}> or C<\N{5,}>, Perl assumes
 that this means to match the given quantity of non-newlines (in these examples,
 3; and 5 or more, respectively).  In all other case, where there is a C<\N{>
 and a matching C<}>, Perl assumes that a character name is desired.
 
 However, if there is no matching C<}>, Perl doesn't know if it was mistakenly
-omitted, or if "match non-newline" followed by "match a C<{>" was desired, and
+omitted, or if C<[^\n]{> was desired, and
 raises this error.  If you meant the former, add the right brace; if you meant
 the latter, escape the brace with a backslash, like so: C<\N\{>
 
@@ -2626,10 +2654,39 @@ local() if you want to localize a package variable.
 
 =item \\N in a character class must be a named character: \\N{...}
 
-The new (5.12) meaning of C<\N> to match non-newlines is not valid in a
-bracketed character class, for the same reason that C<.> in a character class
-loses its specialness: it matches almost everything, which is probably not what
-you want.
+(F) The new (5.12) meaning of C<\N> as C<[^\n]> is not valid in a bracketed
+character class, for the same reason that C<.> in a character class loses its
+specialness: it matches almost everything, which is probably not what you want.
+
+=item \\N{NAME} must be resolved by the lexer
+
+(F) When compiling a regex pattern, an unresolved named character or sequence
+was encountered.  This can happen in any of several ways that bypass the lexer,
+such as using single-quotish context, or an extra backslash in double quotish:
+
+    $re = '\N{SPACE}'; # Wrong!
+    $re = "\\N{SPACE}";        # Wrong!
+    /$re/;
+
+Instead, use double-quotes with a single backslash:
+
+    $re = "\N{SPACE}"; # ok
+    /$re/;
+
+The lexer can be bypassed as well by creating the pattern from smaller
+components:
+
+    $re = '\N';
+    /${re}{SPACE}/;    # Wrong!
+
+It's not a good idea to split a construct in the middle like this, and it
+doesn't work here.  Instead use the solution above.
+
+Finally, the message also can happen under the C</x> regex modifier when the
+C<\N> is separated by spaces from the C<{>, in which case, remove the spaces.
+
+    /\N {SPACE}/x;     # Wrong!
+    /\N{SPACE}/x;      # ok
 
 =item Name "%s::%s" used only once: possible typo
 
@@ -2646,7 +2703,8 @@ will not trigger this warning.
 =item Invalid hexadecimal number in \\N{U+...}
 
 (F) The character constant represented by C<...> is not a valid hexadecimal
-number.
+number.  Either it is empty, or you tried to use a character other than 0 - 9
+or A - F, a - f in a hexadecimal number.
 
 =item Negative '/' count in unpack
 
@@ -3390,13 +3448,6 @@ so it was not possible to set up some or all fixed-width byte-order
 conversion functions.  This is only a problem when you're using the
 '<' or '>' modifiers in (un)pack templates.  See L<perlfunc/pack>.
 
-=item Perl_pmflag() is deprecated, and will be removed from the XS API
-
-(D deprecated) XS code called the C function C<Perl_pmflag>. This was part of
-Perl's listed public API for extending or embedding the perl interpreter. It has
-now been removed from the public API, and will be removed in a future release,
-hence XS code should be re-written not to use it.
-
 =item Perl %s required--this is only version %s, stopped
 
 (F) The module in question uses features of a version of Perl more
@@ -4844,6 +4895,14 @@ modifier is not presently meaningful in substitutions.
 use the /g modifier.  Currently, /c is meaningful only when /g is
 used.  (This may change in the future.)
 
+=item Use of := for an empty attribute list is deprecated
+
+(D deprecated) The construction C<my $x := 42> currently
+parses correctly in perl, being equivalent to C<my $x : = 42>
+(applying an empty attribute list to C<$x>). This useless
+construct is now deprecated, so C<:=> can be reclaimed as a new
+operator in the future.
+
 =item Use of freed value in iteration
 
 (F) Perhaps you modified the iterated array within the loop?
@@ -5058,8 +5117,8 @@ executed, so its $a is not available for capture.
 
 =item Variable "%s" is not imported%s
 
-(F) While "use strict" in effect, you referred to a global variable that
-you apparently thought was imported from another module, because
+(W misc) With "use strict" in effect, you referred to a global variable
+that you apparently thought was imported from another module, because
 something else of the same name (usually a subroutine) is exported by
 that module.  It usually means you put the wrong funny character on the
 front of your variable.