applied patch, with indentation tweaks
[p5sagit/p5-mst-13.2.git] / pod / perldiag.pod
index 166e046..8dd2f82 100644 (file)
@@ -194,7 +194,7 @@ the return value of your socket() call?  See L<perlfunc/accept>.
 
 =item Applying %s to %s will act on scalar(%s)
 
-(W) The pattern match (//), substitution (s///), and translation (tr///)
+(W) The pattern match (//), substitution (s///), and transliteration (tr///)
 operators work on scalar values.  If you apply one of them to an array
 or a hash, it will convert the array or hash to a scalar value -- the
 length of an array, or the population info of a hash -- and then work on
@@ -361,6 +361,12 @@ Perl yourself.
 subroutine identifier, in curly braces or to the left of the "=>" symbol.
 Perhaps you need to predeclare a subroutine?
 
+=item Bareword "%s" refers to nonexistent package
+
+(W) You used a qualified bareword of the form C<Foo::>, but
+the compiler saw no other uses of that namespace before that point.
+Perhaps you need to predeclare a package?
+
 =item BEGIN failed--compilation aborted
 
 (F) An untrapped exception was raised while executing a BEGIN subroutine.
@@ -638,6 +644,11 @@ call for another.  It can't manufacture one out of whole cloth.  In general
 you should be calling it out of only an AUTOLOAD routine anyway.  See
 L<perlfunc/goto>.
 
+=item Can't goto subroutine from an eval-string
+
+(F) The "goto subroutine" call can't be used to jump out of an eval "string".
+(You can use it to jump out of an eval {BLOCK}, but you probably don't want to.)
+
 =item Can't localize through a reference
 
 (F) You said something like C<local $$ref>, which Perl can't currently
@@ -682,11 +693,6 @@ to exist.
 
 (F) List assignment to %ENV is not supported on some systems, notably VMS.
 
-=item Can't mktemp()
-
-(F) The mktemp() routine failed for some reason while trying to process
-a B<-e> switch.  Maybe your /tmp partition is full, or clobbered.
-
 =item Can't modify %s in %s
 
 (F) You aren't allowed to assign to the item indicated, or otherwise try to
@@ -817,6 +823,12 @@ message indicates that such a conversion was attempted.
 of upgradability.  Upgrading to undef indicates an error in the
 code calling sv_upgrade.
 
+=item Can't use %%! because Errno.pm is not available
+
+(F) The first time the %! hash is used, perl automatically loads the
+Errno.pm module. The Errno module is expected to tie the %! hash to
+provide symbolic names for C<$!> errno values.
+
 =item Can't use "my %s" in sort comparison
 
 (F) The global variables $a and $b are reserved for sort comparisons.
@@ -872,21 +884,16 @@ weren't.
 subscript.  But to the left of the brackets was an expression that
 didn't look like an array reference, or anything else subscriptable.
 
-=item Can't write to temp file for B<-e>: %s
-
-(F) The write routine failed for some reason while trying to process
-a B<-e> switch.  Maybe your /tmp partition is full, or clobbered.
-
 =item Can't x= to read-only value
 
 (F) You tried to repeat a constant value (often the undefined value) with
 an assignment operator, which implies modifying the value itself.
 Perhaps you need to copy the value to a temporary, and repeat that.
 
-=item Cannot open temporary file
+=item Cannot find an opnumber for "%s"
 
-(F) The create routine failed for some reason while trying to process
-a B<-e> switch.  Maybe your /tmp partition is full, or clobbered.
+(F) A string of a form C<CORE::word> was given to prototype(), but
+there is no builtin with the name C<word>.
 
 =item Cannot resolve method `%s' overloading `%s' in package `%s'
 
@@ -894,6 +901,30 @@ a B<-e> switch.  Maybe your /tmp partition is full, or clobbered.
 opposed to a subroutine reference): no such method callable via the
 package. If method name is C<???>, this is an internal error.
 
+=item Character class syntax [. .] is reserved for future extensions
+
+(W) Within regular expression character classes ([]) the syntax beginning
+with "[." and ending with ".]" is reserved for future extensions.
+If you need to represent those character sequences inside a regular
+expression character class, just quote the square brackets with the
+backslash: "\[." and ".\]".
+
+=item Character class syntax [: :] is reserved for future extensions
+
+(W) Within regular expression character classes ([]) the syntax beginning
+with "[:" and ending with ":]" is reserved for future extensions.
+If you need to represent those character sequences inside a regular
+expression character class, just quote the square brackets with the
+backslash: "\[:" and ":\]".
+
+=item Character class syntax [= =] is reserved for future extensions
+
+(W) Within regular expression character classes ([]) the syntax
+beginning with "[=" and ending with "=]" is reserved for future extensions.
+If you need to represent those character sequences inside a regular
+expression character class, just quote the square brackets with the
+backslash: "\[=" and "=\]".
+
 =item chmod: mode argument is missing initial 0
 
 (W) A novice will sometimes say
@@ -1052,6 +1083,13 @@ a goto, or a loop control statement.
 (W) You are exiting a substitution by unconventional means, such as
 a return, a goto, or a loop control statement.
 
+=item Explicit blessing to '' (assuming package main)
+
+(W) You are blessing a reference to a zero length string.  This has
+the effect of blessing the reference into the package main.  This is
+usually not what you want.  Consider providing a default target
+package, e.g. bless($ref, $p or 'MyPackage');
+
 =item Fatal VMS error at %s, line %d
 
 (P) An error peculiar to VMS.  Something untoward happened in a VMS system
@@ -1230,6 +1268,12 @@ don't take to this kindly.
 (W) You may have tried to use an 8 or 9 in a octal number.  Interpretation
 of the octal number stopped before the 8 or 9.
 
+=item Illegal hex digit ignored
+
+(W) You may have tried to use a character other than 0 - 9 or A - F in a
+hexadecimal number.  Interpretation of the hexadecimal number stopped
+before the illegal character.
+
 =item Illegal switch in PERL5OPT: %s
 
 (X) The PERL5OPT environment variable may only be used to set the
@@ -1669,10 +1713,10 @@ about 250 characters.  You've exceeded that length.  Future versions of
 Perl are likely to eliminate this arbitrary limitation.  In the meantime,
 try using scientific notation (e.g. "1e6" instead of "1_000_000").
 
-=item Odd number of elements in hash list
+=item Odd number of elements in hash assignment
 
-(S) You specified an odd number of elements to a hash list, which is odd,
-because hash lists come in key/value pairs.
+(S) You specified an odd number of elements to initialize a hash, which
+is odd, because hashes come in key/value pairs.
 
 =item Offset outside string
 
@@ -1877,7 +1921,7 @@ was string.
 
 (P) The lexer got into a bad state while processing a case modifier.
 
-=item Pareneses missing around "%s" list
+=item Parentheses missing around "%s" list
 
 (W) You said something like
 
@@ -1915,8 +1959,7 @@ the BSD version, which takes a pid.
 (W) qw() lists contain items separated by whitespace; as with literal
 strings, comment characters are not ignored, but are instead treated
 as literal data.  (You may have used different delimiters than the
-exclamation marks parentheses shown here; braces are also frequently
-used.)
+parentheses shown here; braces are also frequently used.)
 
 You probably wrote something like this:
 
@@ -2021,6 +2064,18 @@ which is why it's currently left out of your copy.
 (F) More than 100 levels of inheritance were used.  Probably indicates
 an unintended loop in your inheritance hierarchy.
 
+=item Reference found where even-sized list expected
+
+(W) You gave a single reference where Perl was expecting a list with
+an even number of elements (for assignment to a hash). This
+usually means that you used the anon hash constructor when you meant 
+to use parens. In any case, a hash requires key/value B<pairs>.
+
+    %hash = { one => 1, two => 2, };   # WRONG
+    %hash = [ qw/ an anon array / ];   # WRONG
+    %hash = ( one => 1, two => 2, );   # right
+    %hash = qw( one 1 two 2 );                 # also fine
+
 =item Reference miscount in sv_replace()
 
 (W) The internal sv_replace() function was handed a new SV with a
@@ -2129,6 +2184,7 @@ or possibly some other missing operator, such as a comma.
 Check your logic flow.
 
 =item Sequence (? incomplete
+
 (F) A regular expression ended with an incomplete extension (?.
 See L<perlre>.
 
@@ -2429,13 +2485,13 @@ Perl yourself.
 (F) The regular expression ends with an unbackslashed backslash.  Backslash
 it.   See L<perlre>.
 
-=item Translation pattern not terminated
+=item Transliteration pattern not terminated
 
 (F) The lexer couldn't find the interior delimiter of a tr/// or tr[][]
 or y/// or y[][] construct.  Missing the leading C<$> from variables
 C<$tr> or C<$y> may cause this error.
 
-=item Translation replacement not terminated
+=item Transliteration replacement not terminated
 
 (F) The lexer couldn't find the final delimiter of a tr/// or tr[][]
 construct.
@@ -2511,6 +2567,11 @@ have been defined yet.  See L<perlfunc/sort>.
 (F) The format indicated doesn't seem to exist.  Perhaps it's really in
 another package?  See L<perlform>.
 
+=item Undefined value assigned to typeglob
+
+(W) An undefined value was assigned to a typeglob, a la C<*foo = undef>.
+This does nothing.  It's possible that you really mean C<undef *foo>.
+
 =item unexec of %s into %s failed!
 
 (F) The unexec() routine failed for some reason.  See your local FSF
@@ -2582,7 +2643,7 @@ the name you call Perl by to C<perl_>, C<perl__>, and so on.
 
 =item Unsupported function %s
 
-(F) This machines doesn't implement the indicated function, apparently.
+(F) This machine doesn't implement the indicated function, apparently.
 At least, Configure doesn't think so.
 
 =item Unsupported socket function "%s" called
@@ -2642,7 +2703,7 @@ a split() explicitly to an array (or list).
 (D) As an (ahem) accidental feature, C<AUTOLOAD> subroutines are looked
 up as methods (using the C<@ISA> hierarchy) even when the subroutines to
 be autoloaded were called as plain functions (e.g. C<Foo::bar()>), not
-as methods (e.g. C<Foo->bar()> or C<$obj->bar()>).
+as methods (e.g. C<Foo-E<gt>bar()> or C<$obj-E<gt>bar()>).
 
 This bug will be rectified in Perl 5.005, which will use method lookup
 only for methods' C<AUTOLOAD>s.  However, there is a significant base
@@ -2657,7 +2718,7 @@ C<BaseClass>, execute C<*AUTOLOAD = \&BaseClass::AUTOLOAD> during startup.
 
 In code that currently says C<use AutoLoader; @ISA = qw(AutoLoader);> you
 should remove AutoLoader from @ISA and change C<use AutoLoader;> to
-C<C<use AutoLoader 'AUTOLOAD';>.
+C<use AutoLoader 'AUTOLOAD';>.
 
 =item Use of %s is deprecated
 
@@ -2773,6 +2834,27 @@ variables.
 of Perl.  Check the #! line, or manually feed your script into
 Perl yourself.
 
+=item perl: warning: Setting locale failed.
+
+(S) The whole warning message will look something like:
+
+       perl: warning: Setting locale failed.
+       perl: warning: Please check that your locale settings:
+               LC_ALL = "En_US",
+               LANG = (unset)
+           are supported and installed on your system.
+       perl: warning: Falling back to the standard locale ("C").
+
+Exactly what were the failed locale settings varies.  In the above the
+settings were that the LC_ALL was "En_US" and the LANG had no value.
+This error means that Perl detected that you and/or your system
+administrator have set up the so-called variable system but Perl could
+not use those settings.  This was not dead serious, fortunately: there
+is a "default locale" called "C" that Perl can and will use, the
+script will be run.  Before you really fix the problem, however, you
+will get the same error message each time you run Perl.  How to really
+fix the problem can be found in L<perllocale> section B<LOCALE PROBLEMS>.
+
 =item Warning: something's wrong
 
 (W) You passed warn() an empty string (the equivalent of C<warn "">) or