perlfaq update from From Tom Christiansen and Nathan Torkington
[p5sagit/p5-mst-13.2.git] / pod / perldiag.pod
index 221cc35..5fdeb70 100644 (file)
@@ -207,6 +207,22 @@ L<perlfunc/grep> and L<perlfunc/map> for alternatives.
 you thought.  Normally it's pretty easy to disambiguate it by supplying
 a missing quote, operator, parenthesis pair or declaration.
 
+=item Ambiguous call resolved as CORE::%s(), qualify as such or use &
+
+(W) A subroutine you have declared has the same name as a Perl keyword,
+and you have used the name without qualification for calling one or the
+other.  Perl decided to call the builtin because the subroutine is
+not imported.
+
+To force interpretation as a subroutine call, either put an ampersand
+before the subroutine name, or qualify the name with its package.
+Alternatively, you can import the subroutine (or pretend that it's
+imported with the C<use subs> pragma).
+
+To silently interpret it as the Perl operator, use the C<CORE::> prefix
+on the operator (e.g. C<CORE::log($x)>) or by declaring the subroutine
+to be an object method (see L<attrs>).
+
 =item Args must match #! line
 
 (F) The setuid emulator requires that the arguments Perl was invoked
@@ -318,13 +334,9 @@ system malloc().
 
 =item Bad index while coercing array into hash
 
-(F) A field name of a typed variable was looked up in the %FIELDS
-hash, but the index found was not legal, i.e. less than 1.
-
-=item Bad index while coercing array into hash
-
-(F) The index looked up in the hash found as 0'th element of the array
-is not legal.  Index values must be at 1 or greater.
+(F) The index looked up in the hash found as the 0'th element of a
+pseudo-hash is not legal.  Index values must be at 1 or greater.
+See L<perlref>.
 
 =item Bad name after %s::
 
@@ -465,7 +477,17 @@ an object reference until it has been blessed.  See L<perlobj>.
 
 (F) You used the syntax of a method call, but the slot filled by the
 object reference or package name contains an expression that returns
-neither an object reference nor a package name.  (Perhaps it's null?)
+a defined value which is neither an object reference nor a package name.
+Something like this will reproduce the error:
+
+    $BADREF = 42;
+    process $BADREF 1,2,3;
+    $BADREF->process(1,2,3);
+
+=item Can't call method "%s" on an undefined value
+
+(F) You used the syntax of a method call, but the slot filled by the
+object reference or package name contains an undefined value.
 Something like this will reproduce the error:
 
     $BADREF = undef;
@@ -675,6 +697,13 @@ lexical variable using "my".  This is not allowed.  If you want to
 localize a package variable of the same name, qualify it with the
 package name.
 
+=item Can't localize pseudo-hash element
+
+(F) You said something like C<local $ar-E<gt>{'key'}>, where $ar is
+a reference to a pseudo-hash.  That hasn't been implemented yet, but
+you can get a similar effect by localizing the corresponding array
+element directly -- C<local $ar-E<gt>[$ar-E<gt>[0]{'key'}]>.
+
 =item Can't locate auto/%s.al in @INC
 
 (F) A function (or method) was called in a package which allows autoload,
@@ -956,6 +985,18 @@ to 01411.  Octal constants are introduced with a leading 0 in Perl, as in C.
 Perl uses this generic message when none of the errors that it encountered
 were severe enough to halt compilation immediately.
 
+=item Complex regular subexpression recursion limit (%d) exceeded
+
+(W) The regular expression engine uses recursion in complex situations
+where back-tracking is required.  Recursion depth is limited to 32766,
+or perhaps less in architectures where the stack cannot grow
+arbitrarily.  ("Simple" and "medium" situations are handled without
+recursion and are not subject to a limit.)  Try shortening the string
+under examination; looping in Perl code (e.g. with C<while>) rather
+than in the regular expression engine; or rewriting the regular
+expression so that it is simpler or backtracks less.  (See L<perlbook>
+for information on I<Mastering Regular Expressions>.)
+
 =item connect() on closed fd
 
 (W) You tried to do a connect on a closed socket.  Did you forget to check
@@ -1078,8 +1119,8 @@ in effect.  See L<perlre/(?{ code })>.
 =item %s: Eval-group not allowed at run time
 
 (F) Perl tried to compile a regular expression containing the C<(?{ ... })>
-zero-width assertion at run time, at it would when the pattern contains
-interpolated values.  Since this is a risk to security, it is not allowed.
+zero-width assertion at run time, as it would when the pattern contains
+interpolated values.  Since that is a security risk, it is not allowed.
 If you insist, you may still do this by explicitly building the pattern
 from an interpolated string at run time and using that in an eval().
 See L<perlre/(?{ code })>.
@@ -1489,13 +1530,13 @@ catches that.  But an easy way to do the same thing is:
 
 Another way is to assign to a substr() that's off the end of the string.
 
-=item Modification of noncreatable array value attempted, subscript %d
+=item Modification of non-creatable array value attempted, subscript %d
 
 (F) You tried to make an array value spring into existence, and the
 subscript was probably negative, even counting from end of the array
 backwards.
 
-=item Modification of noncreatable hash value attempted, subscript "%s"
+=item Modification of non-creatable hash value attempted, subscript "%s"
 
 (F) You tried to make a hash value spring into existence, and it couldn't
 be created for some peculiar reason.
@@ -2379,21 +2420,6 @@ may break this.
        eval "sub name { ... }";
     }
 
-=item Subroutine %s hidden by keyword; use ampersand
-
-(W) You are trying to call a subroutine that has the same name as a
-keyword.  However, because the subroutine is not imported and
-you're not using an ampersand, Perl won't call the subroutine.
-
-To force a subroutine call, either put an ampersand before the
-subroutine name, or qualify the name with its package.  Alternatively,
-you can import the subroutine (or pretend that it's imported with the
-C<use subs> pragma).
-
-If the Perl operator is what you want, then eliminate this warning by
-using the CORE:: prefix on the operator (e.g. CORE::log($x)) or by
-declaring the subroutine to be an object method (see L<attrs>).
-
 =item Substitution loop
 
 (P) The substitution was looping infinitely.  (Obviously, a
@@ -2590,8 +2616,13 @@ certain type.  Arrays must be @NAME or C<@{EXPR}>.  Hashes must be
 
 =item umask: argument is missing initial 0
 
-(W) A umask of 222 is incorrect.  It should be 0222, because octal literals
-always start with 0 in Perl, as in C.
+(W) A umask of 222 is incorrect.  It should be 0222, because octal
+literals always start with 0 in Perl, as in C.
+
+=item umask not implemented
+
+(F) Your machine doesn't implement the umask function and you tried
+to use it to restrict permissions for yourself (EXPR & 0700).
 
 =item Unable to create sub named "%s"
 
@@ -2821,6 +2852,10 @@ bad side effects.
 interpreted as a "" or a 0, but maybe it was a mistake.  To suppress this
 warning assign an initial value to your variables.
 
+=item Useless use of "re" pragma
+
+(W) You did C<use re;> without any arguments.   That isn't very useful.
+
 =item Useless use of %s in void context
 
 (W) You did something without a side effect in a context that does nothing