Add a new warning, "Newline in left-justified string for printf/sprintf"
[p5sagit/p5-mst-13.2.git] / pod / perldiag.pod
index bc16459..4d95016 100644 (file)
@@ -805,16 +805,16 @@ the file, say, by doing C<make install>.
 functioning as a class, but that package doesn't define that particular
 method, nor does any of its base classes.  See L<perlobj>.
 
-=item Can't locate PerlIO%s
-
-(F) You tried to use in open() a PerlIO layer that does not exist,
-e.g. open(FH, ">:nosuchlayer", "somefile").
-
 =item Can't locate package %s for @%s::ISA
 
 (W syntax) The @ISA array contained the name of another package that
 doesn't seem to exist.
 
+=item Can't locate PerlIO%s
+
+(F) You tried to use in open() a PerlIO layer that does not exist,
+e.g. open(FH, ">:nosuchlayer", "somefile").
+
 =item Can't make list assignment to \%ENV on this system
 
 (F) List assignment to %ENV is not supported on some systems, notably
@@ -1953,18 +1953,18 @@ an undefined value for the length. See L<perlfunc/pack>.
 to check the return value of your socket() call?  See
 L<perlfunc/listen>.
 
-=item lstat() on filehandle %s
-
-(W io) You tried to do an lstat on a filehandle.  What did you mean
-by that?  lstat() makes sense only on filenames.  (Perl did a fstat()
-instead on the filehandle.)
-
 =item Lookbehind longer than %d not implemented in regex; marked by <-- HERE in m/%s/
 
 (F) There is currently a limit on the length of string which lookbehind can
 handle. This restriction may be eased in a future release. The <-- HERE
 shows in the regular expression about where the problem was discovered.
 
+=item lstat() on filehandle %s
+
+(W io) You tried to do an lstat on a filehandle.  What did you mean
+by that?  lstat() makes sense only on filenames.  (Perl did a fstat()
+instead on the filehandle.)
+
 =item Lvalue subs returning %s not implemented yet
 
 (F) Due to limitations in the current implementation, array and hash
@@ -2222,6 +2222,15 @@ C<??> appear to be nested quantifiers, but aren't.  See L<perlre>.
 (S internal) The symbol in question was declared but somehow went out of
 scope before it could possibly have been used.
 
+=item Newline in left-justified string for %s
+
+(W printf) There is a newline in a string to be left justified by 
+C<printf> or C<sprintf>.
+
+The padding spaces will appear after the newline, which is probably not
+what you wanted.  Usually you should remove the newline from the string 
+and put formatting characters in the C<sprintf> format.
+
 =item No %s allowed while running setuid
 
 (F) Certain operations are deemed to be too insecure for a setuid or
@@ -2781,15 +2790,15 @@ was string.
 
 (P) The compiler attempted to do a goto, or something weird like that.
 
-=item panic: yylex
-
-(P) The lexer got into a bad state while processing a case modifier.
-
 =item panic: utf16_to_utf8: odd bytelen
 
 (P) Something tried to call utf16_to_utf8 with an odd (as opposed
 to even) byte length.
 
+=item panic: yylex
+
+(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
@@ -2996,8 +3005,8 @@ with a numeric comparison operator, like this :
 
 This expression is actually equivalent to C<$x & ($y == 0)>, due to the
 higher precedence of C<==>. This is probably not what you want. (If you
-really meant to write this, disable the warning, or, better, write
-C<$x & ($y == 0 ? 1 : 0)>).
+really meant to write this, disable the warning, or, better, put the
+parentheses explicitly and write C<$x & ($y == 0)>).
 
 =item Possible unintended interpolation of %s in string
 
@@ -3526,6 +3535,10 @@ about where the problem was discovered. See L<perlre>.
 (F) While under the C<use filetest> pragma, we cannot switch the real
 and effective uids or gids.
 
+=item %s syntax
+
+(F) The final summary message when a C<perl -c> succeeds.
+
 =item syntax error
 
 (F) Probably means you had a syntax error.  Common reasons include:
@@ -3560,10 +3573,6 @@ yourself.
 a perl4 interpreter, especially if the next 2 tokens are "use strict"
 or "my $var" or "our $var".
 
-=item %s syntax
-
-(F) The final summary message when a C<perl -c> succeeds.
-
 =item sysread() on closed filehandle %s
 
 (W closed) You tried to read from a closed filehandle.
@@ -3844,10 +3853,6 @@ what you are doing you can turn off this warning by C<no warnings 'utf8';>.
 (F) There are no byte-swapping functions for a machine with this byte
 order.
 
-=item Unknown "re" subpragma '%s' (known ones are: %s)
-
-You tried to use an unknown subpragma of the "re" pragma.
-
 =item Unknown open() mode '%s'
 
 (F) The second argument of 3-argument open() is not among the list
@@ -3861,6 +3866,10 @@ iterating over it, and someone else stuck a message in the stream of
 data Perl expected.  Someone's very confused, or perhaps trying to
 subvert Perl's population of %ENV for nefarious purposes.
 
+=item Unknown "re" subpragma '%s' (known ones are: %s)
+
+You tried to use an unknown subpragma of the "re" pragma.
+
 =item Unknown switch condition (?(%.2s in regex; marked by <-- HERE in m/%s/
 
 (F) The condition part of a (?(condition)if-clause|else-clause) construct
@@ -3932,6 +3941,11 @@ script, a binary program, or a directory as a Perl program.
 recognized by Perl inside character classes.  The character was
 understood literally.
 
+=item Unrecognized escape \\%c passed through
+
+(W misc) You used a backslash-character combination which is not
+recognized by Perl.
+
 =item Unrecognized escape \\%c passed through in regex; marked by <-- HERE in m/%s/
 
 (W regexp) You used a backslash-character combination which is not
@@ -3940,11 +3954,6 @@ a C<'>-delimited regular expression. The character was understood
 literally. The <-- HERE shows in the regular expression about where the
 escape was discovered.
 
-=item Unrecognized escape \\%c passed through
-
-(W misc) You used a backslash-character combination which is not
-recognized by Perl.
-
 =item Unrecognized signal name "%s"
 
 (F) You specified a signal name to the kill() function that was not
@@ -4022,6 +4031,16 @@ earlier in the line, and you really meant a "less than".
 (W untie) A copy of the object returned from C<tie> (or C<tied>) was
 still valid when C<untie> was called.
 
+=item Usage: POSIX::%s(%s)
+
+(F) You called a POSIX function with incorrect arguments.
+See L<POSIX/FUNCTIONS> for more information.
+
+=item Usage: Win32::%s(%s)
+
+(F) You called a Win32 function with incorrect arguments.
+See L<Win32> for more information.
+
 =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
@@ -4050,6 +4069,12 @@ must be written as
 The <-- HERE shows in the regular expression about
 where the problem was discovered. See L<perlre>.
 
+=item Useless localization of %s
+
+(W syntax) The localization of lvalues such as C<local($x=10)> is
+legal, but in fact the local() currently has no effect. This may change at
+some point in the future, but in the meantime such code is discouraged.
+
 =item Useless use of %s in void context
 
 (W void) You did something without a side effect in a context that does
@@ -4142,6 +4167,18 @@ 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 freed value in iteration (perhaps you modified the iterated array within the loop?)
+
+(F) This is typically caused by code like the following:
+
+    @a = (3,4);
+    @a = () for (1,2,@a);
+
+You are not supposed to modify arrays while they are being iterated over.
+For speed and efficiency reasons, Perl internally does not do full
+reference-counting of iterated items, hence deleting such an item in the
+middle of an iteration causes Perl to see a freed value.
+
 =item Use of *glob{FILEHANDLE} is deprecated
 
 (D deprecated) You are now encouraged to use the shorter *glob{IO} form
@@ -4206,18 +4243,6 @@ defined B<awk> feature.  Use an explicit printf() or sprintf() instead.
 generally because there's a better way to do it, and also because the
 old way has bad side effects.
 
-=item Use of freed value in iteration (perhaps you modified the iterated array within the loop?)
-
-(F) This is typically caused by code like the following:
-
-    @a = (3,4);
-    @a = () for (1,2,@a);
-
-You are not supposed to modify arrays while they are being iterated over.
-For speed and efficiency reasons, Perl internally does not do full
-reference-counting of iterated items, hence deleting such an item in the
-middle of an iteration causes Perl to see a freed value.
-
 =item Use of -l on filehandle %s
 
 (W io) A filehandle represents an opened file, and when you opened the file
@@ -4334,26 +4359,35 @@ instance.  This is almost always a typographical error.  Note that the
 earlier variable will still exist until the end of the scope or until
 all closure referents to it are destroyed.
 
-=item Variable "%s" may be unavailable
+=item Variable "%s" is not available
 
-(W closure) An inner (nested) I<anonymous> subroutine is inside a
-I<named> subroutine, and outside that is another subroutine; and the
-anonymous (innermost) subroutine is referencing a lexical variable
-defined in the outermost subroutine.  For example:
+(W closure) During compilation, an inner named subroutine or eval is
+attempting to capture an outer lexical that is not currently available.
+This can be happen for one of two reasons. First, the outer lexical may be
+declared in an outer anonymous subroutine that has not yet been created.
+(Remember that named subs are created at compile time, while anonymous
+subs are created at run-time. For example,
 
-   sub outermost { my $a; sub middle { sub { $a } } }
+    sub { my $a; sub f { $a } }
 
-If the anonymous subroutine is called or referenced (directly or
-indirectly) from the outermost subroutine, it will share the variable as
-you would expect.  But if the anonymous subroutine is called or
-referenced when the outermost subroutine is not active, it will see the
-value of the shared variable as it was before and during the *first*
-call to the outermost subroutine, which is probably not what you want.
+At the time that f is created, it can't capture the current value of $a,
+since the anonymous subroutine hasn't been created yet. Conversely,
+the following won't give a warning since the anonymous subroutine has by
+now been created and is live:
 
-In these circumstances, it is usually best to make the middle subroutine
-anonymous, using the C<sub {}> syntax.  Perl has specific support for
-shared variables in nested anonymous subroutines; a named subroutine in
-between interferes with this feature.
+    sub { my $a; eval 'sub f { $a }' }->();
+
+The second situation is caused by an eval accessing a variable that has
+gone out of scope, for example,
+
+    sub f {
+       my $a;
+       sub { eval '$a' }
+    }
+    f()->();
+
+Here, when the '$a' in the eval is being compiled, f() is not currently being
+executed, so its $a is not available for capture.
 
 =item Variable syntax
 
@@ -4364,22 +4398,18 @@ Perl yourself.
 =item Variable "%s" will not stay shared
 
 (W closure) An inner (nested) I<named> subroutine is referencing a
-lexical variable defined in an outer subroutine.
+lexical variable defined in an outer named subroutine.
 
-When the inner subroutine is called, it will probably see the value of
+When the inner subroutine is called, it will see the value of
 the outer subroutine's variable as it was before and during the *first*
 call to the outer subroutine; in this case, after the first call to the
 outer subroutine is complete, the inner and outer subroutines will no
 longer share a common value for the variable.  In other words, the
 variable will no longer be shared.
 
-Furthermore, if the outer subroutine is anonymous and references a
-lexical variable outside itself, then the outer and inner subroutines
-will I<never> share the given variable.
-
 This problem can usually be solved by making the inner subroutine
 anonymous, using the C<sub {}> syntax.  When inner anonymous subs that
-reference variables in outer subroutines are called or referenced, they
+reference variables in outer subroutines are created, they
 are automatically rebound to the current values of such variables.
 
 =item Version number must be a constant number