This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Separate the extraction of hex values.
[perl5.git] / pod / perldiag.pod
index 86ba73b..ddcc0b9 100644 (file)
@@ -186,21 +186,12 @@ point and did not attempt to push this layer.  If your program
 didn't explicitly request the failing operation, it may be the
 result of the value of the environment variable PERLIO.
 
-=item charnames alias definitions may not contain a sequence of multiple spaces
-
-(F) You defined a character name which had multiple space
-characters in a row.  Change them to single spaces.  Usually these
-names are defined in the C<:alias> import argument to C<use charnames>, but
-they could be defined by a translator installed into C<$^H{charnames}>.
-See L<charnames/CUSTOM ALIASES>.
-
-=item charnames alias definitions may not contain trailing white-space
+=item Argument "%s" treated as 0 in increment (++)
 
-(F) You defined a character name which ended in a space
-character.  Remove the trailing space(s).  Usually these names are
-defined in the C<:alias> import argument to C<use charnames>, but they
-could be defined by a translator installed into C<$^H{charnames}>.
-See L<charnames/CUSTOM ALIASES>.
+(W numeric) The indicated string was fed as an argument to the C<++>
+operator which expects either a number or a string matching
+C</^[a-zA-Z]*[0-9]*\z/>.  See L<perlop/Auto-increment and
+Auto-decrement> for details.
 
 =item assertion botched: %s
 
@@ -221,6 +212,11 @@ the special variable C<$[>, which is deprecated, is now a fixed zero value.
 must either both be scalars or both be lists.  Otherwise Perl won't
 know which context to supply to the right side.
 
+=item <> at require-statement should be quotes
+
+(F) You wrote C<< require <file> >> when you should have written
+C<require 'file'>.
+
 =item Attempt to access disallowed key '%s' in a restricted hash
 
 (F) The failing code has attempted to get or set a key which is not in
@@ -1178,14 +1174,16 @@ other than "=" after the module name.
 =item Can't use a hash as a reference
 
 (F) You tried to use a hash as a reference, as in
-C<< %foo->{"bar"} >> or C<< %$ref->{"hello"} >>.  Versions of perl <= 5.6.1
-used to allow this syntax, but shouldn't have.
+C<< %foo->{"bar"} >> or C<< %$ref->{"hello"} >>.  Versions of perl
+<= 5.22.0 used to allow this syntax, but shouldn't
+have.  This was deprecated in perl 5.6.1.
 
 =item Can't use an array as a reference
 
 (F) You tried to use an array as a reference, as in
-C<< @foo->[23] >> or C<< @$ref->[99] >>.  Versions of perl <= 5.6.1 used to
-allow this syntax, but shouldn't have.
+C<< @foo->[23] >> or C<< @$ref->[99] >>.  Versions of perl <= 5.22.0
+used to allow this syntax, but shouldn't have.  This
+was deprecated in perl 5.6.1.
 
 =item Can't use anonymous symbol table for method lookup
 
@@ -1408,6 +1406,32 @@ uses the character values modulus 256 instead, as if you had provided:
 
    unpack("s", "\x{f3}b")
 
+=item charnames alias definitions may not contain a sequence of multiple spaces
+
+(F) You defined a character name which had multiple space characters
+in a row.  Change them to single spaces.  Usually these names are
+defined in the C<:alias> import argument to C<use charnames>, but they
+could be defined by a translator installed into C<$^H{charnames}>.  See
+L<charnames/CUSTOM ALIASES>.
+
+=item charnames alias definitions may not contain trailing white-space
+
+(F) You defined a character name which ended in a space
+character.  Remove the trailing space(s).  Usually these names are
+defined in the C<:alias> import argument to C<use charnames>, but they
+could be defined by a translator installed into C<$^H{charnames}>.
+See L<charnames/CUSTOM ALIASES>.
+
+=item \C is deprecated in regex; marked by <-- HERE in m/%s/
+
+(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
+bytes, you probably want to convert your string to one where each
+underlying byte is stored as a character, with utf8::encode().
+
 =item "\c%c" is more clearly written simply as "%s"
 
 (W syntax) The C<\cI<X>> construct is intended to be a way to specify
@@ -1454,8 +1478,8 @@ but not higher.  Code points above 0xFFFF_FFFF require larger than a
 =item %s: Command not found
 
 (A) You've accidentally run your script through B<csh> or another shell
-instead of Perl.  Check the #! line, or manually feed your script
-into Perl yourself.  The #! line at the top of your file could look like
+instead of Perl.  Check the #! line, or manually feed your script into
+Perl yourself.  The #! line at the top of your file could look like
 
   #!/usr/bin/perl -w
 
@@ -2155,6 +2179,39 @@ 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 Hexadecimal float: exponent overflow
+
+(W overflow) The hexadecimal floating point has larger exponent
+than the floating point supports.
+
+=item Hexadecimal float: exponent underflow
+
+(W overflow) The hexadecimal floating point has smaller exponent
+than the floating point supports.
+
+=item Hexadecimal float: internal error
+
+(F) Something went horribly bad in hexadecimal float handling.
+
+=item Hexadecimal float: mantissa overflow
+
+(W overflow) The hexadecimal floating point literal had more bits in
+the mantissa (the part between the 0x and the exponent, also known as
+the fraction or the significand) than the floating point supports.
+
+=item Hexadecimal float: precision loss
+
+(W overflow) The hexadecimal floating point had internally more
+digits than could be output.  This can be caused by unsupported
+long double formats, or by 64-bit integers not being available
+(needed to retrieve the digits under some configurations).
+
+=item Hexadecimal float: unsupported long double format
+
+(F) You have configured Perl to use long doubles but
+the internals of the long double format are unknown,
+therefore the hexadecimal float output is impossible.
+
 =item Hexadecimal number > 0xffffffff non-portable
 
 (W portable) The hexadecimal number you specified is larger than 2**32-1
@@ -2381,14 +2438,6 @@ expression that contains a call to a user-defined character property
 function, i.e. C<\p{IsFoo}> or C<\p{InFoo}>.
 See L<perlunicode/User-Defined Character Properties> and L<perlsec>.
 
-=item In '(?...)', the '(' and '?' must be adjacent in regex;
-marked by S<<-- HERE> in m/%s/
-
-(F) The two-character sequence C<"(?"> in
-this context in a regular expression pattern should be an
-indivisible token, with nothing intervening between the C<"(">
-and the C<"?">, but you separated them.
-
 =item Integer overflow in format string for %s
 
 (F) The indexes and widths specified in the format string of C<printf()>
@@ -2463,6 +2512,14 @@ followed by parentheses turns into a function, with all the list
 operators arguments found inside the parentheses.  See
 L<perlop/Terms and List Operators (Leftward)>.
 
+=item In '(?...)', the '(' and '?' must be adjacent in regex;
+marked by S<<-- HERE> in m/%s/
+
+(F) The two-character sequence C<"(?"> in this context in a regular
+expression pattern should be an indivisible token, with nothing
+intervening between the C<"("> and the C<"?">, but you separated them
+with whitespace.
+
 =item Invalid %s attribute: %s
 
 (F) The indicated attribute for a subroutine or variable was not recognized
@@ -3050,6 +3107,12 @@ can vary from one line to the next.
 (S syntax) This is an educated guess made in conjunction with the message
 "%s found where operator expected".  Often the missing operator is a comma.
 
+=item Missing or undefined argument to require
+
+(F) You tried to call require with no argument or with an undefined
+value as an argument.  Require expects either a package name or a
+file-specification as an argument.  See L<perlfunc/require>.
+
 =item Missing right brace on \%c{} in regex; marked by S<<-- HERE> in m/%s/
 
 (F) Missing right brace in C<\x{...}>, C<\p{...}>, C<\P{...}>, or C<\N{...}>.
@@ -3203,10 +3266,10 @@ names.  If you had a good reason for having a unique name, then
 just mention it again somehow to suppress the message.  The C<our>
 declaration is also provided for this purpose.
 
-NOTE: This warning detects package symbols that have been used only
-once. This means lexical variables will never trigger this warning.
-It also means that all of the package variables $c, @c, %c, as well
-as *c, &c, sub c{}, c(), and c (the filehandle or
+NOTE: This warning detects package symbols that have been used
+only once.  This means lexical variables will never trigger this
+warning.  It also means that all of the package variables $c, @c,
+%c, as well as *c, &c, sub c{}, c(), and c (the filehandle or
 format) are considered the same; if a program uses $c only once
 but also uses any of the others it will not trigger this warning.
 Symbols beginning with an underscore and symbols using special
@@ -3593,11 +3656,6 @@ to UTC.  If it's not, define the logical name
 F<SYS$TIMEZONE_DIFFERENTIAL> to translate to the number of seconds which
 need to be added to UTC to get local time.
 
-=item Null filename used
-
-(F) You can't require the null filename, especially because on many
-machines that means the current directory!  See L<perlfunc/require>.
-
 =item NULL OP IN RUN
 
 (S debugging) Some internal routine called run() with a null opcode
@@ -4149,6 +4207,14 @@ 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.
 
+=item PerlIO layer ':win32' is experimental
+
+(S experimental::win32_perlio) The C<:win32> PerlIO layer is
+experimental.  If you want to take the risk of using this layer,
+simply disable this warning:
+
+    no warnings "experimental::win32_perlio";
+
 =item Perl_my_%s() not available
 
 (F) Your platform has very uncommon byte-order and integer size,
@@ -4231,14 +4297,6 @@ are as follows.
 Both numeric and string values are accepted, but note that string values are
 case sensitive.  The default for this setting is "RANDOM" or 1.
 
-=item PerlIO layer ':win32' is experimental
-
-(S experimental::win32_perlio) The C<:win32> PerlIO layer is
-experimental.  If you want to take the risk of using this layer,
-simply disable this warning:
-
-    no warnings "experimental::win32_perlio";
-
 =item pid %x not a child
 
 (W exec) A warning peculiar to VMS.  Waitpid() was asked to wait for a
@@ -4609,6 +4667,13 @@ loading PerlIO::scalar explicitly first.
 believes it found an infinite loop in the C<@ISA> hierarchy.  This is a
 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
+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>.
+
 =item refcnt_dec: fd %d%s
 
 =item refcnt: fd %d%s
@@ -5011,11 +5076,6 @@ take the risk of using this feature, simply disable this warning:
 interpreted as the != (numeric not equal) and ~ (1's complement)
 operators: probably not what you intended.
 
-=item <> at require-statement should be quotes
-
-(F) You wrote C<< require <file> >> when you should have written
-C<require 'file'>.
-
 =item /%s/ should probably be written as "%s"
 
 (W syntax) You have used a pattern where Perl expected to find a string,
@@ -5655,11 +5715,11 @@ 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 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, for
-example,
+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,
+for example,
 
     qr{abc\{def\}ghi}
 
@@ -5731,16 +5791,16 @@ with the characters in the Lao and Thai scripts.
 =item Unicode non-character U+%X is illegal for open interchange
 
 (S nonchar) Certain codepoints, such as U+FFFE and U+FFFF, are
-defined by the Unicode standard to be non-characters.  Those are
-legal codepoints, but are reserved for internal use; so, applications
-shouldn't attempt to exchange them.  An application may not be
-expecting any of these characters at all, and receiving them
-may lead to bugs.  If you know what you are doing
-you can turn off this warning by C<no warnings 'nonchar';>.
-
-This is not really a "serious" error, but it is supposed to be raised
-by default even if warnings are not enabled, and currently the only
-way to do that in Perl is to mark it as serious.
+defined by the Unicode standard to be non-characters.  Those
+are legal codepoints, but are reserved for internal use; so,
+applications shouldn't attempt to exchange them.  An application
+may not be expecting any of these characters at all, and receiving
+them may lead to bugs.  If you know what you are doing you can
+turn off this warning by C<no warnings 'nonchar';>.
+
+This is not really a "severe" error, but it is supposed to be
+raised by default even if warnings are not enabled, and currently
+the only way to do that in Perl is to mark it as serious.
 
 =item Unicode surrogate U+%X is illegal in UTF-8