This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
(toke|regcomp).c: Use common fcn to handle \0 problems
[perl5.git] / pod / perldiag.pod
index 4b618cf..cef5716 100644 (file)
@@ -864,12 +864,6 @@ a file in /dev, a FIFO or an uneditable directory.  The file was ignored.
 (S inplace) The creation of the new file failed for the indicated
 reason.
 
-=item Can't do inplace edit without backup
-
-(F) You're on a system such as MS-DOS that gets confused if you try
-reading from a deleted (but still opened) file.  You have to say
-C<-i.bak>, or some such.
-
 =item Can't do inplace edit: %s would not be unique
 
 (S inplace) Your filesystem does not support filenames longer than 14
@@ -1505,7 +1499,7 @@ it's loaded, etc.
 
 (P) The parser got confused when trying to parse a C<foreach> loop.
 
-=item Can't use global %s in "%s"
+=item Can't use global %s in %s
 
 (F) You tried to declare a magical variable as a lexical variable.  This
 is not allowed, because the magic can be tied to only one location
@@ -1737,22 +1731,23 @@ another template code following the slash.  See L<perlfunc/pack>.
 
 =item Code point 0x%X is not Unicode, and not portable
 
-(S non_unicode) You had a code point that has never been in any
+(S non_unicode portable) You had a code point that has never been in any
 standard, so it is likely that languages other than Perl will NOT
-understand it.  At one time, it was legal in some standards to have code
-points up to 0x7FFF_FFFF, but not higher, and this code point is higher.
+understand it.  This code point also will not fit in a 32-bit word on
+ASCII platforms and therefore is non-portable between systems.
+
+At one time, it was legal in some standards to have code points up to
+0x7FFF_FFFF, but not higher, and this code point is higher.
 
 Acceptance of these code points is a Perl extension, and you should
 expect that nothing other than Perl can handle them; Perl itself on
 EBCDIC platforms before v5.24 does not handle them.
 
-Code points above 0xFFFF_FFFF require larger than a 32 bit word.
-
 Perl also makes no guarantees that the representation of these code
 points won't change at some point in the future, say when machines
 become available that have larger than a 64-bit word.  At that time,
-files written by an older Perl would require conversion before being
-readable by a newer Perl.
+files containing any of these, written by an older Perl might require
+conversion before being readable by a newer Perl.
 
 =item Code point 0x%X is not Unicode, may not be portable
 
@@ -1839,10 +1834,9 @@ The message indicates the type of reference that was expected.  This
 usually indicates a syntax error in dereferencing the constant value.
 See L<perlsub/"Constant Functions"> and L<constant>.
 
-=item Constants from lexical variables potentially modified elsewhere are
-deprecated. This will not be allowed in Perl 5.32
+=item Constants from lexical variables potentially modified elsewhere are no longer permitted
 
-(D deprecated) You wrote something like
+(F) You wrote something like
 
     my $var;
     $sub = sub () { $var };
@@ -1859,7 +1853,7 @@ breaks the behavior of closures, in which the subroutine captures
 the variable itself, rather than its value, so future changes to the
 variable are reflected in the subroutine's return value.
 
-This usage is deprecated, and will no longer be allowed in Perl 5.32,
+This usage was deprecated, and as of Perl 5.32 is no longer allowed,
 making it possible to change the behavior in the future.
 
 If you intended for the subroutine to be eligible for inlining, then
@@ -1930,7 +1924,7 @@ called as barewords.  Something like this will work:
 
 (P) This is either an error in Perl, or, if you're using
 one, your L<custom regular expression engine|perlreapi>.  If not the
-latter, report the problem through the L<perlbug> utility.
+latter, report the problem to L<https://github.com/Perl/perl5/issues>.
 
 =item corrupted regexp pointers
 
@@ -2159,11 +2153,20 @@ unlikely to be what you want.
 
 =item Empty \%c in regex; marked by S<<-- HERE> in m/%s/
 
+=item Empty \%c{}
+
 =item Empty \%c{} in regex; marked by S<<-- HERE> in m/%s/
 
-(F) C<\p> and C<\P> are used to introduce a named Unicode property, as
-described in L<perlunicode> and L<perlre>.  You used C<\p> or C<\P> in
-a regular expression without specifying the property name.
+(F) You used something like C<\b{}>, C<\B{}>, C<\o{}>, C<\p>, C<\P>, or
+C<\x> without specifying anything for it to operate on.
+
+Unfortunately, for backwards compatibility reasons, an empty C<\x> is
+legal outside S<C<use re 'strict'>> and expands to a NUL character.
+
+=item Empty (?) without any modifiers in regex; marked by <-- HERE in m/%s/
+
+(W regexp) (only under C<S<use re 'strict'>>)
+C<(?)> does nothing, so perhaps this is a typo.
 
 =item ${^ENCODING} is no longer supported
 
@@ -2665,15 +2668,19 @@ zero-length sequence.  When such an escape is used in a character
 class its behavior is not well defined.  Check that the correct
 escape has been used, and the correct charname handler is in scope.
 
-=item Illegal binary digit '%c'
+=item Illegal %s digit '%c' ignored
 
-(F) You used a digit other than 0 or 1 in a binary number.
+(W digit) Here C<%s> is one of "binary", "octal", or "hex".
+You may have tried to use a digit other than one that is legal for the
+given type, such as only 0 and 1 for binary.  For octals, this is raised
+only if the illegal character is an '8' or '9'.  For hex, 'A' - 'F' and
+'a' - 'f' are legal.
+Interpretation of the number stopped just before the offending digit or
+character.
 
-=item Illegal binary digit %s ignored
+=item Illegal binary digit '%c'
 
-(W digit) You may have tried to use a digit other than 0 or 1 in a
-binary number.  Interpretation of the binary number stopped before the
-offending digit.
+(F) You used a digit other than 0 or 1 in a binary number.
 
 =item Illegal character after '_' in prototype for %s : %s
 
@@ -2729,12 +2736,6 @@ you must always specify a block of code.  See L<perlsub>.
 your logic, or you need to put a conditional in to guard against
 meaningless input.
 
-=item Illegal hexadecimal digit %s ignored
-
-(W digit) You may have tried to use a character other than 0 - 9 or
-A - F, a - f in a hexadecimal number.  Interpretation of the hexadecimal
-number stopped before the illegal character.
-
 =item Illegal modulus zero
 
 (F) You tried to divide a number by 0 to get the remainder.  Most
@@ -2749,11 +2750,6 @@ two from 1 to 32 (or 64, if your platform supports that).
 
 (F) You used an 8 or 9 in an octal number.
 
-=item Illegal octal digit %s ignored
-
-(W digit) You may have tried to use an 8 or 9 in an octal number.
-Interpretation of the octal number stopped before the 8 or 9.
-
 =item Illegal operator following parameter in a subroutine signature
 
 (F) A parameter in a subroutine signature, was followed by something
@@ -3260,6 +3256,12 @@ an anonymous subroutine, or a reference to a subroutine.
 (W overload) You tried to overload a constant type the overload package is
 unaware of.
 
+=item isa is experimental
+
+(S experimental::isa) This warning is emitted if you use the (C<isa>)
+operator. This operator is currently experimental and its behaviour may
+change in future releases of Perl.
+
 =item -i used with no filenames on the command line, reading from STDIN
 
 (S inplace) The C<-i> option was passed on the command line, indicating
@@ -3274,6 +3276,11 @@ line.  See L<perlrun> for more details.
 
 (P) The regular expression parser is confused.
 
+=item \K not permitted in lookahead/lookbehind in regex; marked by <-- HERE in m/%s/
+
+(F) Your regular expression used C<\K> in a lookhead or lookbehind
+assertion, which isn't permitted.
+
 =item Label not found for "last %s"
 
 (F) You named a loop to break out of, but you're not currently in a loop
@@ -4004,16 +4011,25 @@ bracketed character class, for the same reason that C<.> in a character
 class loses its specialness: it matches almost everything, which is
 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 <-- HERE in m/%s/
+=item \N{} here is restricted to one character in regex; marked by <-- 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
+whole thing correctly, except under certain conditions.  These currently
+are
+
+=over 4
+
+=item When the class is inverted (C<[^...]>)
+
+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
+forbid it.
+
+=item The escape is the beginning or final end point of a range
+
+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}]
@@ -4021,6 +4037,13 @@ C<\N{...}> is used as one of the end points of the range, such as in
 What is meant here is unclear, as the C<\N{...}> escape is a sequence
 of code points, so this is made an error.
 
+=item In a regex set
+
+The syntax S<C<(?[   ])>> in a regular expression yields a list of
+single code points, none can be a sequence.
+
+=back
+
 =item No %s allowed while running setuid
 
 (F) Certain operations are deemed to be too insecure for a setuid or
@@ -4081,6 +4104,11 @@ for some reason the current debugger (e.g. F<perl5db.pl> or a C<Devel::>
 module) didn't define a C<DB::sub> routine to be called at the beginning
 of each ordinary subroutine call.
 
+=item No digits found for %s literal
+
+(F) No hexadecimal digits were found following C<0x> or no binary digits
+were found following C<0b>.
+
 =item No directory specified for -I
 
 (F) The B<-I> command-line switch requires a directory name as part of the
@@ -4124,6 +4152,15 @@ a hex one was expected, like
  (?[ [ \xDG ] ])
  (?[ [ \x{DEKA} ] ])
 
+=item Non-hex character '%c' terminates \x early.  Resolved as "%s"
+
+(W digit) In parsing a hexadecimal numeric constant, a character was
+unexpectedly encountered that isn't hexadecimal.  The resulting value
+is as indicated.
+
+Note that, within braces, every character starting with the first
+non-hexadecimal up to the ending brace is ignored.
+
 =item Non-octal character in regex; marked by S<<-- HERE> in m/%s/
 
 (F) In a regular expression, there was a non-octal character where
@@ -4131,12 +4168,22 @@ an octal one was expected, like
 
  (?[ [ \o{1278} ] ])
 
-=item Non-octal character '%c'.  Resolved as "%s"
+=item Non-octal character '%c' terminates \o early.  Resolved as "%s"
 
 (W digit) In parsing an octal numeric constant, a character was
 unexpectedly encountered that isn't octal.  The resulting value
 is as indicated.
 
+When not using C<\o{...}>, you wrote something like C<\08>, or C<\179>
+in a double-quotish string.  The resolution is as indicated, with all
+but the last digit treated as a single character, specified in octal.
+The last digit is the next character in the string.  To tell Perl that
+this is indeed what you want, you can use the C<\o{ }> syntax, or use
+exactly three digits to specify the octal for the character.
+
+Note that, within braces, every character starting with the first
+non-octal up to the ending brace is ignored.
+
 =item "no" not allowed in expression
 
 (F) The "no" keyword is recognized and executed at compile time, and
@@ -4290,13 +4337,6 @@ supplied.  See L<perlform>.
 of Perl.  Check the #! line, or manually feed your script into Perl
 yourself.
 
-=item (?[...]) not valid in locale in regex; marked by S<<-- HERE> in m/%s/
-
-(F) C<(?[...])> cannot be used within the scope of a C<S<use locale>> or with
-an C</l> regular expression modifier, as that would require deferring
-to run-time the calculation of what it should evaluate to, and it is
-regex compile-time only.
-
 =item no UTC offset information; assuming local time is UTC
 
 (S) A warning peculiar to VMS.  Perl was unable to find the local
@@ -4342,6 +4382,12 @@ the meantime, try using scientific notation (e.g. "1e6" instead of
 a number.  This happens, for example with C<\o{}>, with no number between
 the braces.
 
+=item Numeric format result too large
+
+(F) The length of the result of a numeric format supplied to sprintf()
+or printf() would have been too large for the underlying C function to
+report.  This limit is typically 2GB.
+
 =item Octal number > 037777777777 non-portable
 
 (W portable) The octal number you specified is larger than 2**32-1
@@ -4833,7 +4879,7 @@ utility to report; in regex; marked by S<<-- HERE> in m/%s/
 (S regexp) You used a regular expression with case-insensitive matching,
 and there is a bug in Perl in which the built-in regular expression
 folding rules are not accurate.  This may lead to incorrect results.
-Please report this as a bug using the L<perlbug> utility.
+Please report this as a bug to L<https://github.com/Perl/perl5/issues>.
 
 =item PerlIO layer ':win32' is experimental
 
@@ -5414,6 +5460,8 @@ Supply these or check that you are using the right construct.
 
 =item '%s' resolved to '\o{%s}%d'
 
+As of Perl 5.32, this message is no longer generated.  Instead, see
+L</Non-octal character '%c' terminates \o early.  Resolved as "%s">.
 (W misc, regexp)  You wrote something like C<\08>, or C<\179> in a
 double-quotish string.  All but the last digit is treated as a single
 character, specified in octal.  The last digit is the next character in
@@ -5637,7 +5685,7 @@ variables (like PATH) from the user it isn't running under, and isn't
 in a location where the CGI server can't find it, basically, more or
 less.  Please see the following for more information:
 
-       http://www.perl.org/CGI_MetaFAQ.html
+       https://www.perl.org/CGI_MetaFAQ.html
        http://www.htmlhelp.org/faq/cgifaq.html
        http://www.w3.org/Security/Faq/
 
@@ -5946,11 +5994,6 @@ assignment or as a subroutine argument for example).
 (P) Perl tried to force the upgrade of an SV to a type which was actually
 inferior to its current type.
 
-=item SWASHNEW didn't return an HV ref
-
-(P) Something went wrong internally when Perl was trying to look up
-Unicode characters.
-
 =item Switch (?(condition)... contains too many branches in regex; marked by 
 S<<-- HERE> in m/%s/
 
@@ -6077,12 +6120,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 The alpha_assertions feature is experimental
-
-(S experimental::alpha_assertions) This feature is experimental
-and its behavior may change in any future release of perl.  See
-L<perlre/Extended Patterns>.
-
 =item The crypt() function is unimplemented due to excessive paranoia.
 
 (F) Configure couldn't find the crypt() function on your machine,
@@ -6121,12 +6158,6 @@ warning:
 
     no warnings "experimental::regex_sets";
 
-=item The script_run feature is experimental
-
-(S experimental::script_run) This feature is experimental
-and its behavior may in any future release of perl.  See
-L<perlre/Script Runs>.
-
 =item The signatures feature is experimental
 
 (S experimental::signatures) This warning is emitted if you unwrap a
@@ -7326,15 +7357,14 @@ C<~>) on a string containing a code point over 0xFF.  The string bitwise
 operators treat their operands as strings of bytes, and values beyond
 0xFF are nonsensical in this context.
 
-This became fatal in Perl 5.28.
+Certain instances became fatal in Perl 5.28; others in perl 5.32.
 
-=item Use of strings with code points over 0xFF as arguments to C<vec>
-is deprecated. This will be a fatal error in Perl 5.32
+=item Use of strings with code points over 0xFF as arguments to vec is forbidden
 
-(D deprecated) You tried to use L<C<vec>|perlfunc/vec EXPR,OFFSET,BITS>
+(F) You tried to use L<C<vec>|perlfunc/vec EXPR,OFFSET,BITS>
 on a string containing a code point over 0xFF, which is nonsensical here.
 
-Such usage will be a fatal error in Perl 5.32.
+This became fatal in Perl 5.32.
 
 =item Use of tainted arguments in %s is deprecated
 
@@ -7715,6 +7745,18 @@ can be determined from the template alone.  This is not possible if
 it contains any of the codes @, /, U, u, w or a *-length.  Redesign
 the template.
 
+=item While trying to resolve method call %s->%s() can not locate package "%s" yet it is mentioned in @%s::ISA (perhaps you forgot to load "%s"?)
+
+(W syntax) It is possible that the C<@ISA> contains a misspelled or never loaded
+package name, which can result in perl choosing an unexpected parent
+class's method to resolve the method call. If this is deliberate you
+can do something like
+
+  @Missing::Package::ISA = ();
+
+to silence the warnings, otherwise you should correct the package name, or
+ensure that the package is loaded prior to the method call.
+
 =item %s() with negative argument
 
 (S misc) Certain operations make no sense with negative arguments.