This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldiag.pod: Correctly alphabetize an entry
[perl5.git] / pod / perldiag.pod
index db21861..02f9237 100644 (file)
@@ -868,13 +868,6 @@ found in the PATH did not have correct permissions.
 (F) A string of a form C<CORE::word> was given to prototype(), but there
 is no builtin with the name C<word>.
 
-=item Can't find %s character property "%s"
-
-(F) You used C<\p{}> or C<\P{}> but the character property by that name
-could not be found.  Maybe you misspelled the name of the property?
-See L<perluniprops/Properties accessible through \p{} and \P{}>
-for a complete list of available official properties.
-
 =item Can't find label %s
 
 (F) You said to goto a label that isn't mentioned anywhere that it's
@@ -907,13 +900,19 @@ L<perlop> for the full details on here-documents.
 
 =item Can't find Unicode property definition "%s"
 
-(F) You may have tried to use C<\p> which means a Unicode
-property (for example C<\p{Lu}> matches all uppercase
-letters).  If you did mean to use a Unicode property, see
+=item Can't find Unicode property definition "%s" in regex; marked by <-- HERE in m/%s/
+
+(F) The named property which you specified via C<\p> or C<\P> is not one
+known to Perl.  Perhaps you misspelled the name?  See
 L<perluniprops/Properties accessible through \p{} and \P{}>
-for a complete list of available properties.  If you didn't
-mean to use a Unicode property, escape the C<\p>, either by
-C<\\p> (just the C<\p>) or by C<\Q\p> (the rest of the string, or
+for a complete list of available official
+properties.  If it is a
+L<user-defined property|perlunicode/User-Defined Character Properties>
+it must have been defined by the time the regular expression is
+matched.
+
+If you didn't mean to use a Unicode property, escape the C<\p>, either
+by C<\\p> (just the C<\p>) or by C<\Q\p> (the rest of the string, or
 until C<\E>).
 
 =item Can't fork: %s
@@ -1108,7 +1107,7 @@ to change it, such as with an auto-increment.
 (P) The internal routine that does assignment to a substr() was handed
 a NULL.
 
-=item Can't modify non-lvalue subroutine call
+=item Can't modify non-lvalue subroutine call of &%s
 
 (F) Subroutines meant to be used in lvalue context should be declared as
 such.  See L<perlsub/"Lvalue subroutines">.
@@ -1478,6 +1477,13 @@ 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 following \%c must be '{' or a single-character Unicode property name in regex; marked by <-- HERE in m/%s/
+
+(F) (In the above the C<%c> is replaced by either C<p> or C<P>.)  You
+specified something that isn't a legal Unicode property name.  Most
+Unicode properties are specified by C<\p{...}>.  But if the name is a
+single character one, the braces may be omitted.
+
 =item Character in 'C' format wrapped in pack
 
 (W pack) You said
@@ -1617,17 +1623,41 @@ This subroutine cannot be called.
 (F) You had a (sub-)template that ends with a '/'.  There must be
 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
+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.
+
+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.
+
 =item Code point 0x%X is not Unicode, may not be portable
 
 (S non_unicode) You had a code point above the Unicode maximum
 of U+10FFFF.
 
-Perl allows strings to contain a superset of Unicode code points, up
-to the limit of what is storable in an unsigned integer on your system,
-but these may not be accepted by other languages/systems.  At one time,
-it was legal in some standards to have code points up to 0x7FFF_FFFF,
-but not higher.  Code points above 0xFFFF_FFFF require larger than a
-32 bit word.
+Perl allows strings to contain a superset of Unicode code points, but
+these may not be accepted by other languages/systems.  Further, even if
+these languages/systems accept these large code points, they may have
+chosen a different representation for them than the UTF-8-like one that
+Perl has, which would mean files are not exchangeable between them and
+Perl.
+
+On EBCDIC platforms, code points above 0x3FFF_FFFF have a different
+representation in Perl v5.24 than before, so any file containing these
+that was written before that version will require conversion before
+being readable by a later Perl.
 
 =item %s: Command not found
 
@@ -2543,6 +2573,15 @@ L<C<(?I<PARNO>)>|perlre/(?PARNO) (?-PARNO) (?+PARNO) (?R) (?0)>.
 (X) The PERL5OPT environment variable may only be used to set the
 following switches: B<-[CDIMUdmtw]>.
 
+=item Illegal user-defined property name
+
+(F) You specified a Unicode-like property name in a regular expression
+pattern (using C<\p{}> or C<\P{}>) that Perl knows isn't an official
+Unicode property, and was likely meant to be a user-defined property
+name, but it can't be one of those, as they must begin with either C<In>
+or C<Is>.  Check the spelling.  See also
+L</Can't find Unicode property definition "%s">.
+
 =item Ill-formed CRTL environ value "%s"
 
 (W internal) A warning peculiar to VMS.  Perl tried to read the CRTL's
@@ -2582,12 +2621,6 @@ parent '%s'
 C3-consistent, and you have enabled the C3 MRO for this class.  See the C3
 documentation in L<mro> for more information.
 
-=item In EBCDIC the v-string components cannot exceed 2147483647
-
-(F) An error peculiar to EBCDIC.  Internally, v-strings are stored as
-Unicode code points, and encoded in EBCDIC as UTF-EBCDIC.  The UTF-EBCDIC
-encoding is limited to code points no larger than 2147483647 (0x7FFFFFFF).
-
 =item Infinite recursion in regex
 
 (F) You used a pattern that references itself without consuming any input
@@ -2624,6 +2657,11 @@ 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 Invalid number '%s' for -C option.
+
+(F) You supplied a number to the -C option that either has extra leading
+zeroes or overflows perl's unsigned integer representation.
+
 =item %s() is deprecated on :utf8 handles
 
 (W deprecated) The sysread(), recv(), syswrite() and send() operators
@@ -2980,6 +3018,20 @@ 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 It is deprecated to use code point 0x%s; the permissible max is 0x%s
+
+(D deprecated) You used a code point that will not be allowed in a
+future perl version, because it is too large.  Unicode only allows code
+points up to 0x10FFFF, but Perl allows much larger ones.  However, the
+largest possible ones break the perl interpreter in some constructs,
+including causing it to hang in a few cases.  The known problem areas
+are in C<tr///>, regular expression pattern matching using quantifiers,
+and as the upper limits in loops.
+
+If your code is to run on various platforms, keep in mind that the upper
+limit depends on the platform.  It is much larger on 64-bit word sizes
+than 32-bit ones.
+
 =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
@@ -4813,16 +4865,6 @@ port.  One can easily disable this by appropriate sighandlers, see
 L<perlipc/"Signals">.  See also "Process terminated by SIGTERM/SIGINT"
 in L<perlos2>.
 
-=item Property '%s' is unknown in regex; marked by S<<-- HERE> in m/%s/
-
-(F) The named property which you specified via C<\p> or C<\P> is not one
-known to Perl.  Perhaps you misspelled the name?  See
-L<perluniprops/Properties accessible through \p{} and \P{}>
-for a complete list of available official
-properties.  If it is a L<user-defined property|perlunicode/User-Defined Character Properties>
-it must have been defined by the time the regular expression is
-compiled.
-
 =item Prototype after '%c' for %s : %s
 
 (W illegalproto) A character follows % or @ in a prototype.  This is
@@ -5257,6 +5299,13 @@ missing the final closing quote or angle bracket after the name.  The
 S<<-- HERE> shows whereabouts in the regular expression the problem was
 discovered.
 
+=item Sequence (?... not terminated in regex; marked by S<<-- HERE> in
+m/%s/
+
+(F) There was no matching closing parenthesis for the '('.  The
+S<<-- HERE> shows whereabouts in the regular expression the problem was
+discovered.
+
 =item Sequence \%s... not terminated in regex; marked by S<<-- HERE> in
 m/%s/
 
@@ -6617,14 +6666,6 @@ is deprecated.  See L<perlvar/"$[">.
 form if you wish to use an empty line as the terminator of the
 here-document.
 
-=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 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///
 
 (W regexp) You used the /c modifier in a substitution.  The /c
@@ -6657,6 +6698,14 @@ error, so C<:=> can be reclaimed as a new operator in the future.
 If you need an empty attribute list, for example in a code generator, add
 a space before the C<=>.
 
+=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 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 freed value in iteration
 
 (F) Perhaps you modified the iterated array within the loop?