This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
utf8.c: Fix comment
[perl5.git] / pod / perldiag.pod
index 159b9ac..db21861 100644 (file)
@@ -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
@@ -1959,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
@@ -2123,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:
@@ -2395,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.
 
@@ -2612,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.
@@ -2961,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
@@ -3507,6 +3532,13 @@ They're written like C<$foo[1][2][3]>, as in C.
 follow some unpack specification producing a numeric value.
 See L<perlfunc/pack>.
 
+=item %s must not be a named sequence in transliteration operator
+
+(F) Transliteration (C<tr///> and C<y///>) transliterates individual
+characters.  But a named sequence by definition is more than an
+individual charater, and hence doing this operation on it doesn't make
+sense.
+
 =item "my sub" not yet implemented
 
 (F) Lexically scoped subroutines are not yet implemented.  Don't try
@@ -4594,14 +4626,6 @@ 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/
 
 (F) The class in the character class [: :] syntax is unknown.  The S<<-- HERE>
@@ -4821,14 +4845,6 @@ 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/
 
 (F) You started a regular expression with a quantifier.  Backslash it if
@@ -5353,14 +5369,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.
@@ -5441,15 +5449,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
@@ -5967,11 +5966,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
@@ -6347,15 +6341,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
@@ -6523,7 +6508,7 @@ discovered.  See L<perlre>.
 
 =item Useless use of attribute "const"
 
-(W misc) The "const" attribute has no effect except
+(W misc) The C<const> attribute has no effect except
 on anonymous closure prototypes.  You applied it to
 a subroutine via L<attributes.pm|attributes>.  This is only useful
 inside an attribute handler for an anonymous subroutine.
@@ -6632,14 +6617,13 @@ is deprecated.  See L<perlvar/"$[">.
 form if you wish to use an empty line as the terminator of the
 here-document.
 
-=item Use of \b{} for non-UTF-8 locale is wrong.  Assuming a UTF-8 locale
+=item Use of %s for non-UTF-8 locale is wrong.  Assuming a UTF-8 locale
 
 (W locale)  You are matching a regular expression using locale rules,
-and a Unicode boundary is being matched, but the locale is not a Unicode
-one.  This doesn't make sense.  Perl will continue, assuming a Unicode
-(UTF-8) locale, but the results could well be wrong except if the locale
-happens to be ISO-8859-1 (Latin1) where this message is spurious and can
-be ignored.
+and the specified construct was encountered.  This construct is only
+valid for UTF-8 locales, which the current locale isn't.  This doesn't
+make sense.  Perl will continue, assuming a Unicode (UTF-8) locale, but
+the results are likely to be wrong.
 
 =item Use of /c modifier is meaningless in s///
 
@@ -6758,12 +6742,6 @@ for historical reasons.
 it already went past any symlink you are presumably trying to look for.
 The operation returned C<undef>.  Use a filename instead.
 
-=item Use of my $_ is experimental
-
-(S experimental::lexical_topic) Lexical $_ is an experimental feature and
-its behavior may change or even be removed in any future release of perl.
-See the explanation under L<perlvar/$_>.
-
 =item Use of %s on a handle without * is deprecated
 
 (D deprecated) You used C<tie>, C<tied> or C<untie> on a scalar but that scalar
@@ -6895,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