This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
disallow nested declarations [perl #125587] [perl #121058]
[perl5.git] / pod / perldiag.pod
index 3ef3ff5..2effeeb 100644 (file)
@@ -560,7 +560,7 @@ copiable.
 encountered an invalid data type.
 
 =item Both or neither range ends should be Unicode in regex; marked by
-<-- HERE in m/%s/
+S<<-- HERE> in m/%s/
 
 (W regexp) (only under C<S<use re 'strict'>> or within C<(?[...])>)
 
@@ -662,6 +662,14 @@ keep a reference count on its arguments and cannot be made to
 do so.  Such arrays are not even supposed to be accessible to
 Perl code, but are only used internally.
 
+=item Cannot yet reorder sv_catpvfn() arguments from va_list
+
+(F) Some XS code tried to use C<sv_catpvfn()> or a related function with a
+format string that specifies explicit indexes for some of the elements, and
+using a C-style variable-argument list (a C<va_list>). This is not currently
+supported. XS authors wanting to do this must instead construct a C array of
+C<SV*> scalars containing the arguments.
+
 =item Can only compress unsigned integers in pack
 
 (F) An argument to pack("w",...) was not an integer.  The BER compressed
@@ -1209,6 +1217,11 @@ missing.  You need to figure out where your CRTL misplaced its environ
 or define F<PERL_ENV_TABLES> (see L<perlvms>) so that environ is not
 searched.
 
+=item Can't redeclare "%s" in "%s"
+
+(F) A "my", "our" or "state" declaration was found within another declaration,
+such as C<my ($x, my($y), $z)> or C<our (my $x)>.
+
 =item Can't "redo" outside a loop block
 
 (F) A "redo" statement was executed to restart the current block, but
@@ -1559,15 +1572,18 @@ 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/
+=item chdir() on unopened filehandle %s
+
+(W unopened) You tried chdir() on a filehandle that was never opened.
 
-(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 no longer supported in regex; marked by S<<-- HERE> in m/%s/
+
+(F) The \C character class used to allow a match of single byte within a
+multi-byte utf-8 character, but was removed in v5.24 as it broke
+encapsulation and its implementation was extremely 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"
 
@@ -1801,7 +1817,7 @@ S<<-- HERE> in m/%s/
 most likely cause of this error is that you left out a parenthesis inside
 of the C<....> part.
 
-The <-- HERE shows whereabouts in the regular expression the problem was
+The S<<-- HERE> shows whereabouts in the regular expression the problem was
 discovered.
 
 =item %s defines neither package nor VERSION--version check failed
@@ -1956,14 +1972,6 @@ already been freed.
 (W unpack) You have applied the same modifier more than once after a
 type in a pack template.  See L<perlfunc/pack>.
 
-=item each on reference is experimental
-
-(S experimental::autoderef) C<each> with a scalar argument is experimental
-and may change or be removed in a future Perl version.  If you want to
-take the risk of using this feature, simply disable this warning:
-
-    no warnings "experimental::autoderef";
-
 =item elseif should be elsif
 
 (S syntax) There is no keyword "elseif" in Perl because Larry thinks
@@ -2024,7 +2032,7 @@ S<<-- HERE> in m/%s/
 (F) You used a pattern that nested too many EVAL calls without consuming
 any text.  Restructure the pattern so that text is consumed.
 
-The <-- HERE shows whereabouts in the regular expression the problem was
+The S<<-- HERE> shows whereabouts in the regular expression the problem was
 discovered.
 
 =item Excessively long <> operator
@@ -2120,6 +2128,13 @@ L<perlrecharclass/Extended Bracketed Character Classes>.
     use feature "signatures";
     sub foo ($left, $right) { ... }
 
+=item Experimental %s on scalar is now forbidden
+
+(F) An experimental feature added in Perl 5.14 allowed C<each>, C<keys>,
+C<push>, C<pop>, C<shift>, C<splice>, C<unshift>, and C<values> to be called
+with a scalar argument. This experiment is considered unsuccessful, and has
+been removed. The C<postderef> feature may meet your needs better.
+
 =item Experimental "%s" subs not enabled
 
 (F) To use lexical subs, you must first enable them:
@@ -2392,7 +2407,7 @@ than the floating point supports.
 (W overflow) The hexadecimal floating point has a smaller exponent
 than the floating point supports.
 
-=item Hexadecimal float: internal error
+=item Hexadecimal float: internal error (%s)
 
 (F) Something went horribly bad in hexadecimal float handling.
 
@@ -2609,6 +2624,27 @@ provides a list context to its subscript, which can do weird things
 if you're expecting only one subscript.  When called in list context,
 it also returns the key in addition to the value.
 
+=item %s() is deprecated on :utf8 handles
+
+(W deprecated) The sysread(), recv(), syswrite() and send() operators
+are deprecated on handles that have the C<:utf8> layer, either
+explicitly, or implicitly, eg., with the C<:encoding(UTF-16LE)> layer.
+
+Both sysread() and recv() currently use only the C<:utf8> flag for the
+stream, ignoring the actual layers.  Since sysread() and recv() do no
+UTF-8 validation they can end up creating invalidly encoded scalars.
+
+Similarly, syswrite() and send() use only the C<:utf8> flag, otherwise
+ignoring any layers.  If the flag is set, both write the value UTF-8
+encoded, even if the layer is some different encoding, such as the
+example above.
+
+Ideally, all of these operators would completely ignore the C<:utf8>
+state, working only with bytes, but this would result in silently
+breaking existing code.  To avoid this a future version of perl will
+throw an exception when any of sysread(), recv(), syswrite() or send()
+are called on handle with the C<:utf8> layer.
+
 =item Insecure dependency in %s
 
 (F) You tried to do something that the tainting mechanism didn't like.
@@ -2802,7 +2838,7 @@ character (U+FFFD).
 with the B<-D> option with no flags to see the list of acceptable values.
 See also L<perlrun/-Dletters>.
 
-=item Invalid quantifier in {,} in regex; marked by <-- HERE in m/%s/
+=item Invalid quantifier in {,} in regex; marked by S<<-- HERE> in m/%s/
 
 (F) The pattern looks like a {min,max} quantifier, but the min or max
 could not be parsed as a valid number - either it has leading zeroes,
@@ -2901,13 +2937,13 @@ with 'useperlio'.
 (F) Your machine doesn't implement the sockatmark() functionality,
 neither as a system call nor an ioctl call (SIOCATMARK).
 
-=item '%s' is an unknown bound type in regex; marked by <-- HERE in m/%s/
+=item '%s' is an unknown bound type in regex; marked by S<<-- HERE> in m/%s/
 
 (F) You used C<\b{...}> or C<\B{...}> and the C<...> is not known to
 Perl.  The current valid ones are given in
 L<perlrebackslash/\b{}, \b, \B{}, \B>.
 
-=item "%s" is more clearly written simply as "%s" in regex; marked by <-- HERE in m/%s/
+=item "%s" is more clearly written simply as "%s" in regex; marked by S<<-- HERE> in m/%s/
 
 (W regexp) (only under C<S<use re 'strict'>> or within C<(?[...])>)
 
@@ -2958,14 +2994,6 @@ line.  See L<perlrun> for more details.
 
 (P) The regular expression parser is confused.
 
-=item keys on reference is experimental
-
-(S experimental::autoderef) C<keys> with a scalar argument is experimental
-and may change or be removed in a future Perl version.  If you want to
-take the risk of using this feature, simply disable this warning:
-
-    no warnings "experimental::autoderef";
-
 =item Label not found for "last %s"
 
 (F) You named a loop to break out of, but you're not currently in a loop
@@ -3043,8 +3071,8 @@ likely fix this error.
 =item Locale '%s' may not work well.%s
 
 (W locale) You are using the named locale, which is a non-UTF-8 one, and
-which Perl has determined is not fully compatible with Perl.  The second
-C<%s> gives a reason.
+which perl has determined is not fully compatible with what it can
+handle.  The second C<%s> gives a reason.
 
 By far the most common reason is that the locale has characters in it
 that are represented by more than one byte.  The only such locales that
@@ -3612,8 +3640,7 @@ 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 S<<-- HERE> in m/%s/
+=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/
 
 (F) Named Unicode character escapes (C<\N{...}>) may return a
 multi-character sequence.  Even though a character class is
@@ -4592,15 +4619,7 @@ fine from VMS' perspective, it's probably not what you intended.
 
 (F) The unpack format P must have an explicit size, not "*".
 
-=item pop on reference is experimental
-
-(S experimental::autoderef) C<pop> with a scalar argument is experimental
-and may change or be removed in a future Perl version.  If you want to
-take the risk of using this feature, simply disable this warning:
-
-    no warnings "experimental::autoderef";
-
-=item POSIX class [:%s:] unknown in regex; marked by S<< <-- HERE in m/%s/ >>
+=item POSIX class [:%s:] unknown in regex; marked by S<<-- HERE> in m/%s/
 
 (F) The class in the character class [: :] syntax is unknown.  The S<<-- HERE>
 shows whereabouts in the regular expression the problem was discovered.
@@ -4750,21 +4769,6 @@ but there was no array C<@foo> in scope at the time.  If you wanted a
 literal @foo, then write it as \@foo; otherwise find out what happened
 to the array you apparently lost track of.
 
-=item Postfix dereference is experimental
-
-(S experimental::postderef) This warning is emitted if you use
-the experimental postfix dereference syntax.  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::postderef";
-    use feature "postderef", "postderef_qq";
-    $ref->$*;
-    $aref->@*;
-    $aref->@[@indices];
-    ... etc ...
-
 =item Precedence problem: open %s should be open(%s)
 
 (S precedence) The old irregular construct
@@ -4834,22 +4838,13 @@ the sub name and via the prototype attribute.  The prototype in
 parentheses is useless, since it will be replaced by the prototype
 from the attribute before it's ever used.
 
-=item push on reference is experimental
-
-(S experimental::autoderef) C<push> with a scalar argument is experimental
-and may change or be removed in a future Perl version.  If you want to
-take the risk of using this feature, simply disable this warning:
-
-    no warnings "experimental::autoderef";
-
-=item Quantifier follows nothing in regex; marked by S<< <-- HERE in m/%s/ >>
+=item Quantifier follows nothing in regex; marked by S<<-- HERE> in m/%s/
 
 (F) You started a regular expression with a quantifier.  Backslash it if
 you meant it literally.  The S<<-- HERE> shows whereabouts in the regular
 expression the problem was discovered.  See L<perlre>.
 
-=item Quantifier in {,} bigger than %d in regex; marked by S<<-- HERE> in
-m/%s/
+=item Quantifier in {,} bigger than %d in regex; marked by S<<-- HERE> in m/%s/
 
 (F) There is currently a limit to the size of the min and max values of
 the {min,max} construct.  The S<<-- HERE> shows whereabouts in the regular
@@ -4879,7 +4874,7 @@ One possible workaround is to force Perl to use magical string increment
 by prepending "0" to your numbers.
 
 =item Ranges of ASCII printables should be some subset of "0-9", "A-Z", or
-"a-z" in regex; marked by <-- HERE in m/%s/
+"a-z" in regex; marked by S<<-- HERE> in m/%s/
 
 (W regexp) (only under C<S<use re 'strict'>> or within C<(?[...])>)
 
@@ -4908,7 +4903,7 @@ character, and not some escape sequence (like C<"\x41">), and the ranges
 must be all digits, or all uppercase letters, or all lowercase letters.
 
 =item Ranges of digits should be from the same group in regex; marked by
-<-- HERE in m/%s/
+S<<-- HERE> in m/%s/
 
 (W regexp) (only under C<S<use re 'strict'>> or within C<(?[...])>)
 
@@ -5011,7 +5006,7 @@ not at least seven sets of capturing parentheses in the expression.  If
 you wanted to have the character with ordinal 7 inserted into the regular
 expression, prepend zeroes to make it three digits long: C<\007>
 
-The <-- HERE shows whereabouts in the regular expression the problem was
+The S<<-- HERE> shows whereabouts in the regular expression the problem was
 discovered.
 
 =item Reference to nonexistent named group in regex; marked by S<<-- HERE>
@@ -5022,7 +5017,7 @@ expression, but there is no corresponding named capturing parentheses
 such as C<(?'NAME'...)> or C<< (?<NAME>...) >>.  Check if the name has been
 spelled correctly both in the backreference and the declaration.
 
-The <-- HERE shows whereabouts in the regular expression the problem was
+The S<<-- HERE> shows whereabouts in the regular expression the problem was
 discovered.
 
 =item Reference to nonexistent or unclosed group in regex; marked by
@@ -5032,7 +5027,7 @@ S<<-- HERE> in m/%s/
 are not at least seven sets of closed capturing parentheses in the
 expression before where the C<\g{-7}> was located.
 
-The <-- HERE shows whereabouts in the regular expression the problem was
+The S<<-- HERE> shows whereabouts in the regular expression the problem was
 discovered.
 
 =item regexp memory corruption
@@ -5367,14 +5362,6 @@ a positive integer, where the integer was the address of the reference.
 As of Perl 5.20.0 this is a fatal error, to allow future versions of Perl
 to use non-integer refs for more interesting purposes.
 
-=item shift on reference is experimental
-
-(S experimental::autoderef) C<shift> with a scalar argument is experimental
-and may change or be removed in a future Perl version.  If you want to
-take the risk of using this feature, simply disable this warning:
-
-    no warnings "experimental::autoderef";
-
 =item shm%s not implemented
 
 (F) You don't have System V shared memory IPC on your system.
@@ -5440,11 +5427,6 @@ overhauled.
 (F) An ancient error message that almost nobody ever runs into anymore.
 But before sort was a keyword, people sometimes used it as a filehandle.
 
-=item Sort subroutine didn't return single value
-
-(F) A sort comparison subroutine written in XS must return exactly one
-item.  See L<perlfunc/sort>.
-
 =item Source filters apply only to byte streams
 
 (F) You tried to activate a source filter (usually by loading a
@@ -5460,15 +5442,6 @@ end of the array, rather than past it.  If this isn't what you want,
 try explicitly pre-extending the array by assigning $#array = $offset.
 See L<perlfunc/splice>.
 
-=item splice on reference is experimental
-
-(S experimental::autoderef) C<splice> with a scalar argument
-is experimental and may change or be removed in a future
-Perl version.  If you want to take the risk of using this
-feature, simply disable this warning:
-
-    no warnings "experimental::autoderef";
-
 =item Split loop
 
 (P) The split was looping infinitely.  (Obviously, a split shouldn't
@@ -5651,7 +5624,7 @@ is not known.  The condition must be one of the following:
  (R&NAME)           true if directly inside named capture
  (DEFINE)           always false; for defining named subpatterns
 
-The <-- HERE shows whereabouts in the regular expression the problem was
+The S<<-- HERE> shows whereabouts in the regular expression the problem was
 discovered.  See L<perlre>.
 
 =item Switch (?(condition)... not terminated in regex; marked by
@@ -5986,11 +5959,6 @@ certain type.  Arrays must be @NAME or C<@{EXPR}>.  Hashes must be
 %NAME or C<%{EXPR}>.  No implicit dereferencing is allowed--use the
 {EXPR} forms as an explicit dereference.  See L<perlref>.
 
-=item Type of argument to %s must be unblessed hashref or arrayref
-
-(F) You called C<keys>, C<values> or C<each> with a scalar argument that
-was not a reference to an unblessed hash or array.
-
 =item umask not implemented
 
 (F) Your machine doesn't implement the umask function and you tried to
@@ -6064,7 +6032,7 @@ C<undef *foo>.
 Check the #! line, or manually feed your script into Perl yourself.
 
 =item Unescaped left brace in regex is deprecated, passed through in regex;
-marked by <-- HERE in m/%s/
+marked by S<<-- 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
@@ -6140,7 +6108,7 @@ There should be an operator before the C<"(">, as there's
 no indication as to how the digits are to be combined
 with the characters in the Lao and Thai scripts.
 
-=item Unicode non-character U+%X is illegal for open interchange
+=item Unicode non-character U+%X is not recommended 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
@@ -6237,7 +6205,7 @@ is not known.  The condition must be one of the following:
  (R&NAME)           true if directly inside named capture
  (DEFINE)           always false; for defining named subpatterns
 
-The <-- HERE shows whereabouts in the regular expression the problem was
+The S<<-- HERE> shows whereabouts in the regular expression the problem was
 discovered.  See L<perlre>.
 
 =item Unknown Unicode option letter '%c'
@@ -6366,15 +6334,6 @@ on your system.
 think you didn't do that, check the #! line to see if it's supplying the
 bad switch on your behalf.)
 
-=item unshift on reference is experimental
-
-(S experimental::autoderef) C<unshift> with a scalar argument
-is experimental and may change or be removed in a future
-Perl version.  If you want to take the risk of using this
-feature, simply disable this warning:
-
-    no warnings "experimental::autoderef";
-
 =item Unsuccessful %s on filename containing newline
 
 (W newline) A file operation was attempted on a filename, and that
@@ -6516,7 +6475,7 @@ must be written as
 
     if ($string =~ /$pattern/) { ... }
 
-The <-- HERE shows whereabouts in the regular expression the problem was
+The S<<-- HERE> shows whereabouts in the regular expression the problem was
 discovered.  See L<perlre>.
 
 =item Useless localization of %s
@@ -6537,7 +6496,7 @@ must be written as
 
     if ($string =~ /$pattern/o) { ... }
 
-The <-- HERE shows whereabouts in the regular expression the problem was
+The S<<-- HERE> shows whereabouts in the regular expression the problem was
 discovered.  See L<perlre>.
 
 =item Useless use of attribute "const"
@@ -6660,16 +6619,6 @@ one.  This doesn't make sense.  Perl will continue, assuming a Unicode
 happens to be ISO-8859-1 (Latin1) where this message is spurious and can
 be ignored.
 
-=item Use of chdir('') or chdir(undef) as chdir() deprecated
-
-(D deprecated) chdir() with no arguments is documented to change to
-$ENV{HOME} or $ENV{LOGDIR}.  chdir(undef) and chdir('') share this
-behavior, but that has been deprecated.  In future versions they
-will simply fail.
-
-Be careful to check that what you pass to chdir() is defined and not
-blank, else you might find yourself in your home directory.
-
 =item Use of /c modifier is meaningless in s///
 
 (W regexp) You used the /c modifier in a substitution.  The /c
@@ -6881,7 +6830,7 @@ 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 /u for '%s' instead of /%s in regex; marked by <-- HERE in m/%s/
+=item Using /u for '%s' instead of /%s in regex; marked by S<<-- HERE> in m/%s/
 
 (W regexp) You used a Unicode boundary (C<\b{...}> or C<\B{...}>) in a
 portion of a regular expression where the character set modifiers C</a>
@@ -6924,15 +6873,6 @@ C<defined> operator.
 longer than 1024 characters.  The return value has been truncated to
 1024 characters.
 
-=item values on reference is experimental
-
-(S experimental::autoderef) C<values> with a scalar argument
-is experimental and may change or be removed in a future
-Perl version.  If you want to take the risk of using this
-feature, simply disable this warning:
-
-    no warnings "experimental::autoderef";
-
 =item Variable "%s" is not available
 
 (W closure) During compilation, an inner named subroutine or eval is
@@ -7107,7 +7047,7 @@ filehandle with an encoding, see L<open> and L<perlfunc/binmode>.
 
 (W locale) While in a single-byte locale (I<i.e.>, a non-UTF-8
 one), a multi-byte character was encountered.   Perl considers this
-character to be the specified Unicode code point.  Combining non-UTF8
+character to be the specified Unicode code point.  Combining non-UTF-8
 locales and Unicode is dangerous.  Almost certainly some characters
 will have two different representations.  For example, in the ISO 8859-7
 (Greek) locale, the code point 0xC3 represents a Capital Gamma.  But so
@@ -7117,6 +7057,11 @@ You likely need to figure out how this multi-byte character got mixed up
 with your single-byte locale (or perhaps you thought you had a UTF-8
 locale, but Perl disagrees).
 
+=item %s() with negative argument
+
+(S misc) Certain operations make no sense with negative arguments.
+Warning is given and the operation is not done.
+
 =item Within []-length '%c' not allowed
 
 (F) The count in the (un)pack template may be replaced by C<[TEMPLATE]>