This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldiag: Fix typo
[perl5.git] / pod / perldiag.pod
index 80b6002..a163937 100644 (file)
@@ -201,6 +201,23 @@ Auto-decrement> for details.
 
 (X) A general assertion failed.  The file in question must be examined.
 
+=item Assigned value is not a reference
+
+(F) You tried to assign something that was not a reference to an lvalue
+reference (e.g., C<\$x = $y>).  If you meant to make $x an alias to $y, use
+C<\$x = \$y>.
+
+=item Assigned value is not %s reference
+
+(F) You tried to assign a reference to an lvalue reference, but the two
+references were not of the same type.  You cannot alias a scalar to an
+array, or an array to a hash; the two types must match.
+
+    \$x = \@y;  # error
+    \@x = \%y;  # error
+     $y = [];
+    \$x = $y;   # error; did you mean \$y?
+
 =item Assigning non-zero to $[ is no longer possible
 
 (F) When the "array_base" feature is disabled (e.g., under C<use v5.16;>)
@@ -546,11 +563,20 @@ the warning.  See L<perlsub>.
 (D deprecated) You called a function whose use is deprecated.  See
 the function's name in L<POSIX> for details.
 
+=item Cannot chr %f
+
+(F) You passed an invalid number (like an infinity or not-a-number) to C<chr>.
+
+=item Cannot compress %f in pack
+
+(F) You tried compressing an infinity or not-a-number as an unsigned
+integer with BER, which makes no sense.
+
 =item Cannot compress integer in pack
 
-(F) An argument to pack("w",...) was too large to compress.  The BER
-compressed integer format can only be used with positive integers, and you
-attempted to compress Infinity or a very large number (> 1e308).
+(F) An argument to pack("w",...) was too large to compress.
+The BER compressed integer format can only be used with positive
+integers, and you attempted to compress a very large number (> 1e308).
 See L<perlfunc/pack>.
 
 =item Cannot compress negative numbers in pack
@@ -575,6 +601,16 @@ be directly assigned to.
 (S io) You tried to apply an encoding that did not exist to a filehandle,
 either with open() or binmode().
 
+=item Cannot pack %f with '%c'
+
+(F) You tried converting an infinity or not-a-number to an integer,
+which makes no sense.
+
+=item Cannot printf %f with '%c'
+
+(F) You tried printing an infinity or not-a-number as a character (%c),
+which makes no sense.  Maybe you meant '%s', or just stringifying it?
+
 =item Cannot set tied @DB::args
 
 (F) C<caller> tried to set C<@DB::args>, but found it tied.  Tying C<@DB::args>
@@ -957,6 +993,13 @@ unable to locate this library.  See L<DynaLoader>.
 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 object method "%s" via package "%s" (perhaps you forgot
+to load "%s"?)
+
+(F) You called a method on a class that did not exist, and the method
+could not be found in UNIVERSAL.  This often means that a method
+requires a package that has not been loaded.
+
 =item Can't locate package %s for @%s::ISA
 
 (W syntax) The @ISA array contained the name of another package that
@@ -1328,18 +1371,6 @@ Note that ASCII characters that don't map to control characters are
 discouraged, and will generate the warning (when enabled)
 L</""\c%c" is more clearly written simply as "%s"">.
 
-=item Character in 'C' format overflow in pack
-
-(W pack) You tried converting an infinity or not-a-number to an
-unsigned character, which makes no sense.  Perl behaved as if you
-tried to pack 0xFF.
-
-=item Character in 'c' format overflow in pack
-
-(W pack) You tried converting an infinity or not-a-number to a
-signed character, which makes no sense.  Perl behaved as if you
-tried to pack 0xFF.
-
 =item Character in 'C' format wrapped in pack
 
 (W pack) You said
@@ -1438,9 +1469,9 @@ See L<charnames/CUSTOM ALIASES>.
 
 (D deprecated, regexp) The \C character class is deprecated, and will
 become a compile-time error in a future release of perl (tentatively
-v5.24). This construct allows you to match a single byte of what makes up
-a multi-byte single UTF8 character, and breaks encapsulation. It is
-currently also very buggy. If you really need to process the individual
+v5.24).  This construct allows you to match a single byte of what makes
+up a multi-byte single UTF8 character, and breaks encapsulation.  It is
+currently also very buggy.  If you really need to process the individual
 bytes, you probably want to convert your string to one where each
 underlying byte is stored as a character, with utf8::encode().
 
@@ -1930,6 +1961,14 @@ interpolated.  If you see this error message, then you probably
 have some other C<(?...)> construct inside your character class.  See
 L<perlrecharclass/Extended Bracketed Character Classes>.
 
+=item Experimental lvalue references not enabled
+
+(F) To use lvalue references, you must first enable them:
+
+    no warnings "experimental::lvalue_refs";
+    use feature "lvalue_refs";
+    \$x = \$y;
+
 =item Experimental subroutine signatures not enabled
 
 (F) To use subroutine signatures, you must first enable them:
@@ -2104,7 +2143,8 @@ is experimental, so its behavior may change or even be removed
 in any future release of perl.  See the explanation under
 L<perlsyn/Experimental Details on given and when>.
 
-=item Global symbol "%s" requires explicit package name
+=item Global symbol "%s" requires explicit package name (did you forget to
+declare "my %s"?)
 
 (F) You've said "use strict" or "use strict vars", which indicates 
 that all variables must either be lexically scoped (using "my" or "state"), 
@@ -2192,6 +2232,13 @@ created on an emergency basis to prevent a core dump.
 (F) The parser has given up trying to parse the program after 10 errors.
 Further error messages would likely be uninformative.
 
+=item Having more than one /%c regexp modifier is deprecated
+
+(D deprecated, regexp) You used the indicated regular expression pattern
+modifier at least twice in a string of modifiers.  It is deprecated to
+do this with this particular modifier, to allow future extensions to the
+Perl language.
+
 =item Hexadecimal float: exponent overflow
 
 (W overflow) The hexadecimal floating point has a larger exponent
@@ -2241,7 +2288,7 @@ of Perl are likely to eliminate these arbitrary limitations.
 =item Ignoring zero length \N{} in character class in regex; marked by
 S<<-- HERE> in m/%s/
 
-(W regexp) Named Unicode character escapes C<(\N{...})> may return a
+(W regexp) Named Unicode character escapes (C<\N{...}>) may return a
 zero-length sequence.  When such an escape is used in a character class
 its behaviour is not well defined.  Check that the correct escape has
 been used, and the correct charname handler is in scope.
@@ -2606,12 +2653,6 @@ a module that is a MRO plugin.  See L<mro> and L<perlmroapi>.
 not valid character numbers, so it returns the Unicode replacement
 character (U+FFFD).
 
-=item Invalid number (%f) in chr
-
-(W utf8) You passed an invalid number (like an infinity or
-not-a-number) to C<chr>.  Those are not valid character numbers,
-so it return the Unicode replacement character (U+FFFD).
-
 =item invalid option -D%c, use -D'' to see choices
 
 (S debugging) Perl was called with invalid debugger flags.  Call perl
@@ -2885,6 +2926,19 @@ foo :lvalue;> declaration before the definition.
 
 See also L<attributes.pm|attributes>.
 
+=item Lvalue references are experimental
+
+(S experimental::lvalue_refs) This warning is emitted if you use
+a reference constructor on the left-hand side of an assignment to
+alias one variable to another.  Simply suppress the warning if you
+want to use the feature, but know that in doing so you are taking
+the risk of using an experimental feature which may change or be
+removed in a future Perl version:
+
+    no warnings "experimental::lvalue_refs";
+    use feature "lvalue_refs";
+    \$x = \$y;
+
 =item Magical list constants are not supported
 
 (F) You assigned a magical array to a stash element, and then tried
@@ -3264,6 +3318,11 @@ See L<perlfunc/pack>.
 (F) Lexically scoped subroutines are not yet implemented.  Don't try
 that yet.
 
+=item "my" subroutine %s can't be in a package
+
+(F) Lexically scoped subroutines aren't in a package, so it doesn't make
+sense to try to declare one with a package qualifier on the front.
+
 =item "my %s" used in sort comparison
 
 (W syntax) The package variables $a and $b are used for sort comparisons.
@@ -3365,20 +3424,20 @@ probably not what you want.
 =item \N{} in inverted character class or as a range end-point is restricted to one character in regex; marked
 by S<<-- HERE> in m/%s/
 
-(F) Named Unicode character escapes C<(\N{...})> may return a
-multi-character sequence.  Even though a character class is supposed to
-match just one character of input, perl will match the whole thing
-correctly, except when the class is inverted (C<[^...]>, or the escape
-is the beginning or final end point of a range.  The mathematically
-logical behavior for what matches when inverting is very different than
-what people expect, so we have decided to forbid it.
-Similarly unclear is what should be generated when the C<\N{...}> is
-used as one of the end points of the range, such as in
+(F) Named Unicode character escapes (C<\N{...}>) may return a
+multi-character sequence.  Even though a character class is
+supposed to match just one character of input, perl will match the
+whole thing correctly, except when the class is inverted (C<[^...]>),
+or the escape is the beginning or final end point of a range.  The
+mathematically logical behavior for what matches when inverting
+is very different from what people expect, so we have decided to
+forbid it.  Similarly unclear is what should be generated when the
+C<\N{...}> is used as one of the end points of the range, such as in
 
  [\x{41}-\N{ARABIC SEQUENCE YEH WITH HAMZA ABOVE WITH AE}]
 
-What is meant here is unclear, as the C<\N{...}> escape is a sequence of
-code points, so this is made an error.
+What is meant here is unclear, as the C<\N{...}> escape is a sequence
+of code points, so this is made an error.
 
 =item \N{NAME} must be resolved by the lexer in regex; marked by
 S<<-- HERE> in m/%s/
@@ -4079,7 +4138,8 @@ and freeing temporaries and lexicals from.
 
 =item panic: pad_free po
 
-(P) An invalid scratch pad offset was detected internally.
+(P) A zero scratch pad offset was detected internally.  An attempt was
+made to free a target that had not been allocated to begin with.
 
 =item panic: pad_reset curpad, %p!=%p
 
@@ -4088,7 +4148,9 @@ and freeing temporaries and lexicals from.
 
 =item panic: pad_sv po
 
-(P) An invalid scratch pad offset was detected internally.
+(P) A zero scratch pad offset was detected internally.  Most likely
+an operator needed a target but that target had not been allocated
+for whatever reason.
 
 =item panic: pad_swipe curpad, %p!=%p
 
@@ -4220,12 +4282,6 @@ the nesting limit is exceeded.
 command-line switch.  (This output goes to STDOUT unless you've
 redirected it with select().)
 
-=item (perhaps you forgot to load "%s"?)
-
-(F) This is an educated guess made in conjunction with the message
-"Can't locate object method \"%s\" via package \"%s\"".  It often means
-that a method requires a package that has not been loaded.
-
 =item Perl folding rules are not up-to-date for 0x%X; please use the perlbug
 utility to report; in regex; marked by S<<-- HERE> in m/%s/
 
@@ -4697,7 +4753,7 @@ crude check that bails out after 100 levels of C<@ISA> depth.
 =item Redundant argument in %s
 
 (W redundant) You called a function with more arguments than other
-arguments you supplied indicated would be needed. Currently only
+arguments you supplied indicated would be needed.  Currently only
 emitted when a printf-type format required fewer arguments than were
 supplied, but might be used in the future for e.g. L<perlfunc/pack>.
 
@@ -5201,6 +5257,11 @@ unless there was a failure.  You probably wanted to use system()
 instead, which does return.  To suppress this warning, put the exec() in
 a block by itself.
 
+=item "state" subroutine %s can't be in a package
+
+(F) Lexically scoped subroutines aren't in a package, so it doesn't make
+sense to try to declare one with a package qualifier on the front.
+
 =item "state %s" used in sort comparison
 
 (W syntax) The package variables $a and $b are used for sort comparisons.
@@ -5348,6 +5409,13 @@ is not known.  The condition must be one of the following:
 The <-- HERE shows whereabouts in the regular expression the problem was
 discovered.  See L<perlre>.
 
+=item Switch (?(condition)... not terminated in regex; marked by
+S<<-- HERE> in m/%s/
+
+(F) You omitted to close a (?(condition)...) block somewhere
+in the pattern.  Add a closing parenthesis in the appropriate
+position.  See L<perlre>.
+
 =item switching effective %s is not implemented
 
 (F) While under the C<use filetest> pragma, we cannot switch the real
@@ -5742,7 +5810,7 @@ Check the #! line, or manually feed your script into Perl yourself.
 marked by <-- HERE in m/%s/
 
 (D deprecated, regexp) You used a literal C<"{"> character in a regular
-expression pattern. You should change to use C<"\{"> instead, because a
+expression pattern.  You should change to use C<"\{"> instead, because a
 future version of Perl (tentatively v5.26) will consider this to be a
 syntax error.  If the pattern delimiters are also braces, any matching
 right brace (C<"}">) should also be escaped to avoid confusing the parser,
@@ -6515,14 +6583,14 @@ You need to add either braces or blanks to disambiguate.
 =item Using just the first character returned by \N{} in character class in 
 regex; marked by S<<-- HERE> in m/%s/
 
-(W regexp) Named Unicode character escapes C<(\N{...})> may return a
-multi-character sequence.  Even though a character class is supposed to
-match just one character of input, perl will match the whole thing
-correctly, except when the class is inverted (C<[^...]>, or the escape
-is the beginning or final end point of a range.  For these, what should
-happen isn't clear at all.  In these circumstances, Perl discards all
-but the first character of the returned sequence, which is not likely
-what you want.
+(W regexp) Named Unicode character escapes C<(\N{...})> may return
+a multi-character sequence.  Even though a character class is
+supposed to match just one character of input, perl will match
+the whole thing correctly, except when the class is inverted
+(C<[^...]>), or the escape is the beginning or final end point of
+a range.  For these, what should happen isn't clear at all.  In
+these circumstances, Perl discards all but the first character
+of the returned sequence, which is not likely what you want.
 
 =item Using !~ with %s doesn't make sense
 
@@ -6786,7 +6854,7 @@ Something Very Wrong.
 
 =item Zero length \N{} in regex; marked by S<<-- HERE> in m/%s/
 
-(F) Named Unicode character escapes C<(\N{...})> may return a zero-length
+(F) Named Unicode character escapes (C<\N{...}>) may return a zero-length
 sequence.  Such an escape was used in an extended character class, i.e.
 C<(?[...])>, which is not permitted.  Check that the correct escape has
 been used, and the correct charnames handler is in scope.  The S<<-- HERE>