This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Eliminate (X|F) convention from perldiag.
[perl5.git] / pod / perldiag.pod
index 8f2ad29..ab5b8db 100644 (file)
@@ -104,7 +104,7 @@ really meant to multiply a glob by the result of calling a function.
 (W ambiguous) You wrote something like C<@{foo}>, which might be
 asking for the variable C<@foo>, or it might be calling a function
 named foo, and dereferencing it as an array reference.  If you wanted
-the varable, you can just write C<@foo>.  If you wanted to call the
+the variable, you can just write C<@foo>.  If you wanted to call the
 function, write C<@{foo()}> ... or you could just not have a variable
 and a function with the same name, and save yourself a lot of trouble.
 
@@ -238,6 +238,11 @@ spots.  This is now heavily deprecated.
 
 (P) A general assertion failed.  The file in question must be examined.
 
+=item Assigning non-zero to $[ is no longer possible
+
+(F) The special variable C<$[>, deprecated in older perls, is now a fixed
+zero value, because the feature that it used to control has been removed.
+
 =item Assignment to both a list and a scalar
 
 (F) If you assign to a conditional operator, the 2nd and 3rd arguments
@@ -445,7 +450,6 @@ wasn't a symbol table entry.
 (P) An internal request asked to add a dirhandle entry to something
 that wasn't a symbol table entry.
 
-
 =item Bad symbol for filehandle
 
 (P) An internal request asked to add a filehandle entry to something
@@ -1085,9 +1089,9 @@ to reopen it to accept binary data.  Alas, it failed.
 
 =item Can't resolve method "%s" overloading "%s" in package "%s"
 
-(F|P) Error resolving overloading specified by a method name (as opposed
-to a subroutine reference): no such method callable via the package. If
-the method name is C<???>, this is an internal error.
+(F)(P) Error resolving overloading specified by a method name (as
+opposed to a subroutine reference): no such method callable via the
+package.  If the method name is C<???>, this is an internal error.
 
 =item Can't return %s from lvalue subroutine
 
@@ -1241,7 +1245,7 @@ Perhaps you need to copy the value to a temporary, and repeat that.
 
 =item Character following "\c" must be ASCII
 
-(F|W deprecated, syntax) In C<\cI<X>>, I<X> must be an ASCII character.
+(F)(W deprecated, syntax) In C<\cI<X>>, I<X> must be an ASCII character.
 It is planned to make this fatal in all instances in Perl 5.16.  In the
 cases where it isn't fatal, the character this evaluates to is
 derived by exclusive or'ing the code point of this character with 0x40.
@@ -1363,7 +1367,7 @@ template code following the slash. See L<perlfunc/pack>.
 
 =item Code point 0x%X is not Unicode, may not be portable
 
-=item Code point 0x%X is not Unicode, no properties match it; all inverse properties do
+=item Code point 0x%X is not Unicode, all \p{} matches fail; all \P{} matches succeed
 
 (W utf8, non_unicode) You had a code point above the Unicode maximum of U+10FFFF.
 
@@ -1385,6 +1389,16 @@ will not match, because the code point is not in Unicode.  But
 
 will match.
 
+This may be counterintuitive at times, as both these fail:
+
+ chr(0x110000) =~ \p{ASCII_Hex_Digit=True}      # Fails.
+ chr(0x110000) =~ \p{ASCII_Hex_Digit=False}     # Also fails!
+
+and both these succeed:
+
+ chr(0x110000) =~ \P{ASCII_Hex_Digit=True}      # Succeeds.
+ chr(0x110000) =~ \P{ASCII_Hex_Digit=False}     # Also succeeds!
+
 =item %s: Command not found
 
 (A) You've accidentally run your script through B<csh> instead of Perl.
@@ -1451,7 +1465,6 @@ the character name specified in the C<\N{...}> escape.  Perhaps you
 forgot to load the corresponding C<charnames> pragma?
 See L<charnames>.
 
-
 =item Constant is not %s reference
 
 (F) A constant value (perhaps declared using the C<use constant> pragma)
@@ -1477,6 +1490,16 @@ workarounds.
 (F) The method which overloads "=" is buggy. See
 L<overload/Copy Constructor>.
 
+=item &CORE::%s cannot be called directly
+
+(F) You tried to call a subroutine in the C<CORE::> namespace
+with C<&foo> syntax or through a reference.  Most subroutines
+in this package cannot yet be called that way, but must be
+called as barewords.  Something like this will work:
+
+    BEGIN { *shove = \&CORE::push; }
+    shove @array, 1,2,3; # pushes on to @array
+
 =item CORE::%s is not a keyword
 
 (F) The CORE:: namespace is reserved for Perl keywords.
@@ -1519,9 +1542,26 @@ array is empty, just use C<if (@array) { # not empty }> for example.
 
 =item defined(%hash) is deprecated
 
-(D deprecated) defined() is not usually useful on hashes because it
-checks for an undefined I<scalar> value.  If you want to see if the hash
-is empty, just use C<if (%hash) { # not empty }> for example.
+(D deprecated) C<defined()> is not usually right on hashes and has been
+discouraged since 5.004.
+
+Although C<defined %hash> is false on a plain not-yet-used hash, it
+becomes true in several non-obvious circumstances, including iterators,
+weak references, stash names, even remaining true after C<undef %hash>.
+These things make C<defined %hash> fairly useless in practice.
+
+If a check for non-empty is what you wanted then just put it in boolean
+context (see L<perldata/Scalar values>):
+
+    if (%hash) {
+       # not empty
+    }
+
+If you had C<defined %Foo::Bar::QUUX> to check whether such a package
+variable exists then that's never really been reliable, and isn't
+a good way to enquire about the features of a package, or whether
+it's loaded, etc.
+
 
 =item (?(DEFINE)....) does not allow branches in regex; marked by <-- HERE in m/%s/
 
@@ -1949,14 +1989,14 @@ earlier in the line, and you really meant a "less than".
 
 (W overflow) You called C<gmtime> with a number that was larger than
 it can reliably handle and C<gmtime> probably returned the wrong
-date. This warning is also triggered with nan (the special
+date. This warning is also triggered with NaN (the special
 not-a-number value).
 
 =item gmtime(%f) too small
 
 (W overflow) You called C<gmtime> with a number that was smaller than
 it can reliably handle and C<gmtime> probably returned the wrong
-date. This warning is also triggered with nan (the special
+date. This warning is also triggered with NaN (the special
 not-a-number value).
 
 =item Got an error from DosAllocMem
@@ -2044,6 +2084,11 @@ been used, and the correct charname handler is in scope.
 binary number.  Interpretation of the binary number stopped before the
 offending digit.
 
+=item Illegal character after '_' in prototype for %s : %s
+
+(W illegalproto) An illegal character was found in a prototype declaration.
+Legal characters in prototypes are $, @, %, *, ;, [, ], &, \, and +.
+
 =item Illegal character \%o (carriage return)
 
 (F) Perl normally treats carriage returns in the program text as it
@@ -2186,7 +2231,6 @@ expression that contains a call to a user-defined character property
 function, i.e. C<\p{IsFoo}> or C<\p{InFoo}>.
 See L<perlunicode/User-Defined Character Properties> and L<perlsec>.
 
-
 =item Integer overflow in format string for %s
 
 (F) The indexes and widths specified in the format string of C<printf()>
@@ -2447,14 +2491,14 @@ L<perlfunc/listen>.
 
 (W overflow) You called C<localtime> with a number that was larger
 than it can reliably handle and C<localtime> probably returned the
-wrong date. This warning is also triggered with nan (the special
+wrong date. This warning is also triggered with NaN (the special
 not-a-number value).
 
 =item localtime(%f) too small
 
 (W overflow) You called C<localtime> with a number that was smaller
 than it can reliably handle and C<localtime> probably returned the
-wrong date. This warning is also triggered with nan (the special
+wrong date. This warning is also triggered with NaN (the special
 not-a-number value).
 
 =item Lookbehind longer than %d not implemented in regex m/%s/
@@ -2477,19 +2521,18 @@ You may wish to switch to using L<Math::BigInt> explicitly.
 by that?  lstat() makes sense only on filenames.  (Perl did a fstat()
 instead on the filehandle.)
 
-=item lvalue attribute ignored after the subroutine has been defined
+=item lvalue attribute cannot be removed after the subroutine has been defined
 
-(W misc) Making a subroutine an lvalue subroutine after it has been defined
-by declaring the subroutine with an lvalue attribute is not
-possible. To make the subroutine an lvalue subroutine add the
-lvalue attribute to the definition, or put the declaration before
-the definition.
+(W misc) The lvalue attribute on a Perl subroutine cannot be turned off
+once the subroutine is defined.
 
-=item Lvalue subs returning %s not implemented yet
+=item lvalue attribute ignored after the subroutine has been defined
 
-(F) Due to limitations in the current implementation, array and hash
-values cannot be returned in subroutines used in lvalue context.  See
-L<perlsub/"Lvalue subroutines">.
+(W misc) Making a Perl subroutine an lvalue subroutine after it has been
+defined, whether by declaring the subroutine with an lvalue attribute
+or by using L<attributes.pm|attributes>, is not possible.  To make the subroutine an
+lvalue subroutine, add the lvalue attribute to the definition, or put
+the declaration before the definition.
 
 =item Malformed integer in [] in pack
 
@@ -3169,7 +3212,7 @@ which is odd, because hashes come in key/value pairs.
 
 =item Offset outside string
 
-(F|W layer) You tried to do a read/write/send/recv/seek operation
+(F)(W layer) You tried to do a read/write/send/recv/seek operation
 with an offset pointing outside the buffer.  This is difficult to
 imagine.  The sole exceptions to this are that zero padding will
 take place when going past the end of the string when either
@@ -3284,7 +3327,7 @@ possibility to shut down by trapping this error is granted.
 
 =item Out of memory during request for %s
 
-(X|F) The malloc() function returned 0, indicating there was
+(X)(F) The malloc() function returned 0, indicating there was
 insufficient remaining memory (or virtual memory) to satisfy the
 request.
 
@@ -3380,13 +3423,6 @@ there are in the savestack.
 (P) Failed an internal consistency check while trying to reset a weak
 reference.
 
-=item panic: Devel::DProf inconsistent subroutine return
-
-(P) Devel::DProf called a subroutine that exited using goto(LABEL),
-last(LABEL) or next(LABEL). Leaving that way a subroutine called from
-an XSUB will lead very probably to a crash of the interpreter. This is
-a bug that will hopefully one day get fixed.
-
 =item panic: die %s
 
 (P) We popped the context stack to an eval context, and then discovered
@@ -3423,13 +3459,6 @@ repeatedly, but each time something re-created entries in the glob. Most
 likely the glob contains an object with a reference back to the glob and a
 destructor that adds a new object to the glob.
 
-=item panic: hfreeentries failed to free hash
-
-(P) The internal routine used to clear a hash's entries tried repeatedly,
-but each time something added more entries to the hash. Most likely the hash
-contains an object with a reference back to the hash and a destructor that
-adds a new object to the hash.
-
 =item panic: INTERPCASEMOD
 
 (P) The lexer got into a bad state at a case modifier.
@@ -3543,6 +3572,12 @@ scalar's string buffer.
 (P) The sv_insert() routine was told to remove more string than there
 was string.
 
+=item panic: strxfrm() gets absurd - a => %u, ab => %u
+
+(P) The interpreter's sanity check of the C function strxfrm() failed.
+In your current locale the returned transformation of the string "ab" is
+shorter than that of the string "a", which makes no sense.
+
 =item panic: top_env
 
 (P) The compiler attempted to do a goto, or something weird like that.
@@ -4430,8 +4465,7 @@ before this, because Perl is good at understanding random input.
 Occasionally the line number may be misleading, and once in a blue moon
 the only way to figure out what's triggering the error is to call
 C<perl -c> repeatedly, chopping away half the program each time to see
-if the error went away.  Sort of the cybernetic version of S<20
-questions>.
+if the error went away.  Sort of the cybernetic version of S<20 questions>.
 
 =item syntax error at line %d: `%s' unexpected
 
@@ -4485,21 +4519,6 @@ a dirhandle.  Check your control flow.
 (W unopened) You tried to use the tell() function on a filehandle that
 was either never opened or has since been closed.
 
-=item That use of $[ is unsupported
-
-(F) Assignment to C<$[> is now strictly circumscribed, and interpreted
-as a compiler directive.  You may say only one of
-
-    $[ = 0;
-    $[ = 1;
-    ...
-    local $[ = 0;
-    local $[ = 1;
-    ...
-
-This is to prevent the problem of one module changing the array base out
-from under another module inadvertently.  See L<perlvar/$[>.
-
 =item The crypt() function is unimplemented due to excessive paranoia
 
 (F) Configure couldn't find the crypt() function on your machine,
@@ -4642,6 +4661,13 @@ disallowed. See L<Safe>.
 (F) Your machine doesn't implement a file truncation mechanism that
 Configure knows about.
 
+=item Type of arg %d to &CORE::%s must be %s
+
+(F) The subroutine in question in the CORE package requires its argument
+to be a hard reference to data of the specified type.  Overloading is
+ignored, so a reference to an object that is not the specified type, but
+nonetheless has overloading to handle it, will still not be accepted.
+
 =item Type of arg %d to %s must be %s (not %s)
 
 (F) This function requires the argument in that position to be of a
@@ -4981,6 +5007,12 @@ See L<POSIX/FUNCTIONS> for more information.
 (F) You called a Win32 function with incorrect arguments.
 See L<Win32> for more information.
 
+=item Useless assignment to a temporary
+
+(W misc) You assigned to an lvalue subroutine, but what
+the subroutine returned was a temporary scalar about to
+be discarded, so the assignment had no effect.
+
 =item Useless (?-%s) - don't use /%s modifier in regex; marked by <-- HERE in m/%s/
 
 (W regexp) You have used an internal modifier such as (?-o) that has no
@@ -5087,11 +5119,6 @@ you can write it as C<push(@tied_array,())> to avoid this warning.
 (F) The "use" keyword is recognized and executed at compile time, and
 returns no useful value.  See L<perlmod>.
 
-=item Use of assignment to $[ is deprecated
-
-(D deprecated) The C<$[> variable (index of the first element in an array)
-is deprecated. See L<perlvar/"$[">.
-
 =item Use of bare << to mean <<"" is deprecated
 
 (D deprecated) You are now encouraged to use the explicitly quoted
@@ -5304,15 +5331,6 @@ currently reserved for future use, as the exact behaviour has not
 been decided. (Simply returning the boolean opposite of the
 modified string is usually not particularly useful.)
 
-=item User-defined case-mapping '%s' is deprecated
-
-(W deprecated) You defined a function, such as C<ToLower> that overrides
-the standard case mapping, such as C<lc()> gives.  This feature is being
-deprecated due to its many issues, as documented in
-L<perlunicode/User-Defined Case Mappings (for serious hackers only)>.
-It is planned to remove this feature in Perl 5.16.  A CPAN module
-providing improved functionality is being prepared.
-
 =item UTF-16 surrogate U+%X
 
 (W utf8, surrogate) You had a UTF-16 surrogate in a context where they are
@@ -5532,6 +5550,6 @@ Something Very Wrong.
 
 =head1 SEE ALSO
 
-L<warnings>, L<perllexwarn>.
+L<warnings>, L<perllexwarn>, L<diagnostics>.
 
 =cut