This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Remove deprecated character classification/case changing macros
[perl5.git] / pod / perldeprecation.pod
1 =head1 NAME
2
3 perldeprecation - list Perl deprecations
4
5 =head1 DESCRIPTION
6
7 The purpose of this document is to document what has been deprecated
8 in Perl, and by which version the deprecated feature will disappear,
9 or, for already removed features, when it was removed.
10
11 This document will try to discuss what alternatives for the deprecated
12 features are available.
13
14 The deprecated features will be grouped by the version of Perl in
15 which they will be removed.
16
17 =head2 Perl 5.32
18
19 =head3 Constants from lexical variables potentially modified elsewhere
20
21 You wrote something like
22
23     my $var;
24     $sub = sub () { $var };
25
26 but $var is referenced elsewhere and could be modified after the C<sub>
27 expression is evaluated.  Either it is explicitly modified elsewhere
28 (C<$var = 3>) or it is passed to a subroutine or to an operator like
29 C<printf> or C<map>, which may or may not modify the variable.
30
31 Traditionally, Perl has captured the value of the variable at that
32 point and turned the subroutine into a constant eligible for inlining.
33 In those cases where the variable can be modified elsewhere, this
34 breaks the behavior of closures, in which the subroutine captures
35 the variable itself, rather than its value, so future changes to the
36 variable are reflected in the subroutine's return value.
37
38 If you intended for the subroutine to be eligible for inlining, then
39 make sure the variable is not referenced elsewhere, possibly by
40 copying it:
41
42     my $var2 = $var;
43     $sub = sub () { $var2 };
44
45 If you do want this subroutine to be a closure that reflects future
46 changes to the variable that it closes over, add an explicit C<return>:
47
48     my $var;
49     $sub = sub () { return $var };
50
51 This usage has been deprecated, and will no longer be allowed in Perl 5.32.
52
53 =head3 Use of strings with code points over 0xFF as arguments to C<vec>
54
55 C<vec> views its string argument as a sequence of bits.  A string
56 containing a code point over 0xFF is nonsensical.  This usage is
57 deprecated in Perl 5.28, and was removed in Perl 5.32.
58
59 =head3 Use of code points over 0xFF in string bitwise operators
60
61 The string bitwise operators, C<&>, C<|>, C<^>, and C<~>, treat their
62 operands as strings of bytes. As such, values above 0xFF are
63 nonsensical. Some instances of these have been deprecated since Perl
64 5.24, and were made fatal in 5.28, but it turns out that in cases where
65 the wide characters did not affect the end result, no deprecation
66 notice was raised, and so remain legal.  Now, all occurrences either are
67 fatal or raise a deprecation warning, so that the remaining legal
68 occurrences became fatal in 5.32.
69
70 An example of this is
71
72  "" & "\x{100}"
73
74 The wide character is not used in the C<&> operation because the left
75 operand is shorter.  This now throws an exception.
76
77 =head3 hostname() doesn't accept any arguments
78
79 The function C<hostname()> in the L<Sys::Hostname> module has always
80 been documented to be called with no arguments.  Historically it has not
81 enforced this, and has actually accepted and ignored any arguments.  As a
82 result, some users have got the mistaken impression that an argument does
83 something useful.  To avoid these bugs, the function is being made strict.
84 Passing arguments was deprecated in Perl 5.28, and will become fatal in
85 Perl 5.32.
86
87 =head3 Unescaped left braces in regular expressions
88
89 The simple rule to remember, if you want to match a literal C<{>
90 character (U+007B C<LEFT CURLY BRACKET>) in a regular expression
91 pattern, is to escape each literal instance of it in some way.
92 Generally easiest is to precede it with a backslash, like C<\{>
93 or enclose it in square brackets (C<[{]>).  If the pattern
94 delimiters are also braces, any matching right brace (C<}>) should
95 also be escaped to avoid confusing the parser, for example,
96
97  qr{abc\{def\}ghi}
98
99 Forcing literal C<{> characters to be escaped will enable the Perl
100 language to be extended in various ways in future releases.  To avoid
101 needlessly breaking existing code, the restriction is is not enforced in
102 contexts where there are unlikely to ever be extensions that could
103 conflict with the use there of C<{> as a literal.  A non-deprecation
104 warning that the left brace is being taken literally is raised in
105 contexts where there could be confusion about it.
106
107 Literal uses of C<{> were deprecated in Perl 5.20, and some uses of it
108 started to give deprecation warnings since. These cases were made fatal
109 in Perl 5.26. Due to an oversight, not all cases of a use of a literal
110 C<{> got a deprecation warning.  Some cases started warning in Perl 5.26,
111 and were made fatal in Perl 5.30.  Other cases started in Perl 5.28,
112 and will be made fatal in 5.32.
113
114 =head3 In XS code, use of various macros dealing with UTF-8.
115
116 The macros below now require an extra parameter than in versions prior
117 to Perl 5.32.  The final parameter in each one is a pointer into the
118 string supplied by the first parameter beyond which the input will not
119 be read.  This prevents potential reading beyond the end of the buffer.
120 C<isALPHANUMERIC_utf8>,
121 C<isASCII_utf8>,
122 C<isBLANK_utf8>,
123 C<isCNTRL_utf8>,
124 C<isDIGIT_utf8>,
125 C<isIDFIRST_utf8>,
126 C<isPSXSPC_utf8>,
127 C<isSPACE_utf8>,
128 C<isVERTWS_utf8>,
129 C<isWORDCHAR_utf8>,
130 C<isXDIGIT_utf8>,
131 C<isALPHANUMERIC_LC_utf8>,
132 C<isALPHA_LC_utf8>,
133 C<isASCII_LC_utf8>,
134 C<isBLANK_LC_utf8>,
135 C<isCNTRL_LC_utf8>,
136 C<isDIGIT_LC_utf8>,
137 C<isGRAPH_LC_utf8>,
138 C<isIDCONT_LC_utf8>,
139 C<isIDFIRST_LC_utf8>,
140 C<isLOWER_LC_utf8>,
141 C<isPRINT_LC_utf8>,
142 C<isPSXSPC_LC_utf8>,
143 C<isPUNCT_LC_utf8>,
144 C<isSPACE_LC_utf8>,
145 C<isUPPER_LC_utf8>,
146 C<isWORDCHAR_LC_utf8>,
147 C<isXDIGIT_LC_utf8>,
148 C<toFOLD_utf8>,
149 C<toLOWER_utf8>,
150 C<toTITLE_utf8>,
151 and
152 C<toUPPER_utf8>.
153
154 Since Perl 5.26, this functionality with the extra parameter has been
155 available by using a corresponding macro to each one of these, and whose
156 name is formed by appending C<_safe> to the base name.  There is no
157 change to the functionality of those.  For example, C<isDIGIT_utf8_safe>
158 corresponds to C<isDIGIT_utf8>, and both now behave identically.  All
159 are documented in L<perlapi/Character case changing> and
160 L<perlapi/Character classification>.
161
162 This change was originally scheduled for 5.30, but was delayed.
163
164 =head2 Perl 5.30
165
166 =head3 C<< $* >> is no longer supported
167
168 Before Perl 5.10, setting C<< $* >> to a true value globally enabled
169 multi-line matching within a string. This relique from the past lost
170 its special meaning in 5.10. Use of this variable will be a fatal error
171 in Perl 5.30, freeing the variable up for a future special meaning.
172
173 To enable multiline matching one should use the C<< /m >> regexp
174 modifier (possibly in combination with C<< /s >>). This can be set
175 on a per match bases, or can be enabled per lexical scope (including
176 a whole file) with C<< use re '/m' >>.
177
178 =head3 C<< $# >> is no longer supported
179
180 This variable used to have a special meaning -- it could be used
181 to control how numbers were formatted when printed. This seldom
182 used functionality was removed in Perl 5.10. In order to free up
183 the variable for a future special meaning, its use will be a fatal
184 error in Perl 5.30.
185
186 To specify how numbers are formatted when printed, one is advised
187 to use C<< printf >> or C<< sprintf >> instead.
188
189 =head3 Assigning non-zero to C<< $[ >> is fatal
190
191 This variable (and the corresponding C<array_base> feature and
192 L<arybase> module) allowed changing the base for array and string
193 indexing operations.
194
195 Setting this to a non-zero value has been deprecated since Perl 5.12 and
196 throws a fatal error as of Perl 5.30.
197
198 =head3 C<< File::Glob::glob() >> will disappear
199
200 C<< File::Glob >> has a function called C<< glob >>, which just calls
201 C<< bsd_glob >>. However, its prototype is different from the prototype
202 of C<< CORE::glob >>, and hence, C<< File::Glob::glob >> should not
203 be used.
204
205 C<< File::Glob::glob() >> was deprecated in Perl 5.8. A deprecation
206 message was issued from Perl 5.26 onwards, and the function will
207 disappear in Perl 5.30.
208
209 Code using C<< File::Glob::glob() >> should call
210 C<< File::Glob::bsd_glob() >> instead.
211
212 =head3 Unescaped left braces in regular expressions (for 5.30)
213
214 See L</Unescaped left braces in regular expressions> above.
215
216 =head3 Unqualified C<dump()>
217
218 Use of C<dump()> instead of C<CORE::dump()> was deprecated in Perl 5.8,
219 and an unqualified C<dump()> will no longer be available in Perl 5.30.
220
221 See L<perlfunc/dump>.
222
223
224 =head3 Using my() in false conditional.
225
226 There has been a long-standing bug in Perl that causes a lexical variable
227 not to be cleared at scope exit when its declaration includes a false
228 conditional.  Some people have exploited this bug to achieve a kind of
229 static variable.  Since we intend to fix this bug, we don't want people
230 relying on this behavior.
231
232 Instead, it's recommended one uses C<state> variables to achieve the
233 same effect:
234
235     use 5.10.0;
236     sub count {state $counter; return ++ $counter}
237     say count ();    # Prints 1
238     say count ();    # Prints 2
239
240 C<state> variables were introduced in Perl 5.10.
241
242 Alternatively, you can achieve a similar static effect by
243 declaring the variable in a separate block outside the function, eg
244
245     sub f { my $x if 0; return $x++ }
246
247 becomes
248
249     { my $x; sub f { return $x++ } }
250
251 The use of C<my()> in a false conditional has been deprecated in
252 Perl 5.10, and it will become a fatal error in Perl 5.30.
253
254
255 =head3 Reading/writing bytes from/to :utf8 handles.
256
257 The sysread(), recv(), syswrite() and send() operators are
258 deprecated on handles that have the C<:utf8> layer, either explicitly, or
259 implicitly, eg., with the C<:encoding(UTF-16LE)> layer.
260
261 Both sysread() and recv() currently use only the C<:utf8> flag for the stream,
262 ignoring the actual layers.  Since sysread() and recv() do no UTF-8
263 validation they can end up creating invalidly encoded scalars.
264
265 Similarly, syswrite() and send() use only the C<:utf8> flag, otherwise ignoring
266 any layers.  If the flag is set, both write the value UTF-8 encoded, even if
267 the layer is some different encoding, such as the example above.
268
269 Ideally, all of these operators would completely ignore the C<:utf8> state,
270 working only with bytes, but this would result in silently breaking existing
271 code.  To avoid this a future version of perl will throw an exception when
272 any of sysread(), recv(), syswrite() or send() are called on handle with the
273 C<:utf8> layer.
274
275 In Perl 5.30, it will no longer be possible to use sysread(), recv(),
276 syswrite() or send() to read or send bytes from/to :utf8 handles.
277
278
279 =head3 Use of unassigned code point or non-standalone grapheme for a delimiter.
280
281 A grapheme is what appears to a native-speaker of a language to be a
282 character.  In Unicode (and hence Perl) a grapheme may actually be
283 several adjacent characters that together form a complete grapheme.  For
284 example, there can be a base character, like "R" and an accent, like a
285 circumflex "^", that appear to be a single character when displayed,
286 with the circumflex hovering over the "R".
287
288 As of Perl 5.30, use of delimiters which are non-standalone graphemes is
289 fatal, in order to move the language to be able to accept
290 multi-character graphemes as delimiters.
291
292 Also, as of Perl 5.30, delimiters which are unassigned code points
293 but that may someday become assigned are prohibited.  Otherwise, code
294 that works today would fail to compile if the currently unassigned
295 delimiter ends up being something that isn't a stand-alone grapheme.
296 Because Unicode is never going to assign L<non-character code
297 points|perlunicode/Noncharacter code points>, nor L<code points that are
298 above the legal Unicode maximum|perlunicode/Beyond Unicode code
299 points>, those can be delimiters.
300
301 =head2 Perl 5.28
302
303 =head3 Attributes C<< :locked >> and C<< :unique >>
304
305 The attributes C<< :locked >> (on code references) and C<< :unique >>
306 (on array, hash and scalar references) have had no effect since 
307 Perl 5.005 and Perl 5.8.8 respectively. Their use has been deprecated
308 since.
309
310 As of Perl 5.28, these attributes are syntax errors. Since the
311 attributes do not do anything, removing them from your code fixes
312 the syntax error; and removing them will not influence the behaviour
313 of your code.
314
315
316 =head3 Bare here-document terminators
317
318 Perl has allowed you to use a bare here-document terminator to have the
319 here-document end at the first empty line. This practise was deprecated
320 in Perl 5.000; as of Perl 5.28, using a bare here-document terminator
321 throws a fatal error.
322
323 You are encouraged to use the explicitly quoted form if you wish to
324 use an empty line as the terminator of the here-document:
325
326   print <<"";
327     Print this line.
328
329   # Previous blank line ends the here-document.
330
331
332 =head3 Setting $/ to a reference to a non-positive integer
333
334 You assigned a reference to a scalar to C<$/> where the
335 referenced item is not a positive integer.  In older perls this B<appeared>
336 to work the same as setting it to C<undef> but was in fact internally
337 different, less efficient and with very bad luck could have resulted in
338 your file being split by a stringified form of the reference.
339
340 In Perl 5.20.0 this was changed so that it would be B<exactly> the same as
341 setting C<$/> to undef, with the exception that this warning would be
342 thrown.
343
344 As of Perl 5.28, setting C<$/> to a reference of a non-positive
345 integer throws a fatal error.
346
347 You are recommended to change your code to set C<$/> to C<undef> explicitly
348 if you wish to slurp the file.
349
350
351 =head3 Limit on the value of Unicode code points.
352
353 Unicode only allows code points up to 0x10FFFF, but Perl allows
354 much larger ones. Up till Perl 5.28, it was allowed to use code
355 points exceeding the maximum value of an integer (C<IV_MAX>).
356 However, that did break the perl interpreter in some constructs,
357 including causing it to hang in a few cases.  The known problem
358 areas were in C<tr///>, regular expression pattern matching using
359 quantifiers, as quote delimiters in C<qI<X>...I<X>> (where I<X> is
360 the C<chr()> of a large code point), and as the upper limits in
361 loops.
362
363 The use of out of range code points was deprecated in Perl 5.24; as of
364 Perl 5.28 using a code point exceeding C<IV_MAX> throws a fatal error.
365
366 If your code is to run on various platforms, keep in mind that the upper
367 limit depends on the platform. It is much larger on 64-bit word sizes
368 than 32-bit ones. For 32-bit integers, C<IV_MAX> equals C<0x7FFFFFFF>,
369 for 64-bit integers, C<IV_MAX> equals C<0x7FFFFFFFFFFFFFFF>.
370
371
372 =head3 Use of comma-less variable list in formats.
373
374 It was allowed to use a list of variables in a format, without
375 separating them with commas. This usage has been deprecated
376 for a long time, and as of Perl 5.28, this throws a fatal error.
377
378 =head3 Use of C<\N{}>
379
380 Use of C<\N{}> with nothing between the braces was deprecated in
381 Perl 5.24, and throws a fatal error as of Perl 5.28.
382
383 Since such a construct is equivalent to using an empty string,
384 you are recommended to remove such C<\N{}> constructs.
385
386 =head3 Using the same symbol to open a filehandle and a dirhandle
387
388 It used to be legal to use C<open()> to associate both a
389 filehandle and a dirhandle to the same symbol (glob or scalar).
390 This idiom is likely to be confusing, and it was deprecated in
391 Perl 5.10.
392
393 Using the same symbol to C<open()> a filehandle and a dirhandle
394 throws a fatal error as of Perl 5.28.
395
396 You should be using two different symbols instead.
397
398 =head3 ${^ENCODING} is no longer supported.
399
400 The special variable C<${^ENCODING}> was used to implement
401 the C<encoding> pragma. Setting this variable to anything other
402 than C<undef> was deprecated in Perl 5.22. Full deprecation
403 of the variable happened in Perl 5.25.3.
404
405 Setting this variable to anything other than an undefined value
406 throws a fatal error as of Perl 5.28.
407
408
409 =head3 C<< B::OP::terse >>
410
411 This method, which just calls C<< B::Concise::b_terse >>, has been
412 deprecated, and disappeared in Perl 5.28. Please use 
413 C<< B::Concise >> instead.
414
415
416
417 =head3 Use of inherited AUTOLOAD for non-method %s::%s() is no longer allowed
418
419 As an (ahem) accidental feature, C<AUTOLOAD> subroutines were looked
420 up as methods (using the C<@ISA> hierarchy) even when the subroutines
421 to be autoloaded were called as plain functions (e.g. C<Foo::bar()>),
422 not as methods (e.g. C<< Foo->bar() >> or C<< $obj->bar() >>).
423
424 This bug was deprecated in Perl 5.004, has been rectified in Perl 5.28
425 by using method lookup only for methods' C<AUTOLOAD>s.
426
427 The simple rule is:  Inheritance will not work when autoloading
428 non-methods.  The simple fix for old code is:  In any module that used
429 to depend on inheriting C<AUTOLOAD> for non-methods from a base class
430 named C<BaseClass>, execute C<*AUTOLOAD = \&BaseClass::AUTOLOAD> during
431 startup.
432
433 In code that currently says C<use AutoLoader; @ISA = qw(AutoLoader);>
434 you should remove AutoLoader from @ISA and change C<use AutoLoader;> to
435 C<use AutoLoader 'AUTOLOAD';>.
436
437
438 =head3 Use of code points over 0xFF in string bitwise operators
439
440 The string bitwise operators, C<&>, C<|>, C<^>, and C<~>, treat
441 their operands as strings of bytes. As such, values above 0xFF 
442 are nonsensical. Using such code points with these operators
443 was deprecated in Perl 5.24, and is fatal as of Perl 5.28.
444
445 =head3 In XS code, use of C<to_utf8_case()>
446
447 This function has been removed as of Perl 5.28; instead convert to call
448 the appropriate one of:
449 L<C<toFOLD_utf8_safe>|perlapi/toFOLD_utf8_safe>.
450 L<C<toLOWER_utf8_safe>|perlapi/toLOWER_utf8_safe>,
451 L<C<toTITLE_utf8_safe>|perlapi/toTITLE_utf8_safe>,
452 or
453 L<C<toUPPER_utf8_safe>|perlapi/toUPPER_utf8_safe>.
454
455 =head2 Perl 5.26
456
457 =head3 C<< --libpods >> in C<< Pod::Html >>
458
459 Since Perl 5.18, the option C<< --libpods >> has been deprecated, and
460 using this option did not do anything other than producing a warning.
461
462 The C<< --libpods >> option is no longer recognized as of Perl 5.26.
463
464
465 =head3 The utilities C<< c2ph >> and C<< pstruct >>
466
467 These old, perl3-era utilities have been deprecated in favour of
468 C<< h2xs >> for a long time. As of Perl 5.26, they have been removed.
469
470
471 =head3 Trapping C<< $SIG {__DIE__} >> other than during program exit.
472
473 The C<$SIG{__DIE__}> hook is called even inside an C<eval()>. It was
474 never intended to happen this way, but an implementation glitch made
475 this possible. This used to be deprecated, as it allowed strange action
476 at a distance like rewriting a pending exception in C<$@>. Plans to
477 rectify this have been scrapped, as users found that rewriting a
478 pending exception is actually a useful feature, and not a bug.
479
480 Perl never issued a deprecation warning for this; the deprecation
481 was by documentation policy only. But this deprecation has been 
482 lifted as of Perl 5.26.
483
484
485 =head3 Malformed UTF-8 string in "%s"
486
487 This message indicates a bug either in the Perl core or in XS
488 code. Such code was trying to find out if a character, allegedly
489 stored internally encoded as UTF-8, was of a given type, such as
490 being punctuation or a digit.  But the character was not encoded
491 in legal UTF-8.  The C<%s> is replaced by a string that can be used
492 by knowledgeable people to determine what the type being checked
493 against was.
494
495 Passing malformed strings was deprecated in Perl 5.18, and
496 became fatal in Perl 5.26.
497
498
499 =head2 Perl 5.24
500
501 =head3 Use of C<< *glob{FILEHANDLE} >>
502
503 The use of C<< *glob{FILEHANDLE} >> was deprecated in Perl 5.8.
504 The intention was to use C<< *glob{IO} >> instead, for which 
505 C<< *glob{FILEHANDLE} >> is an alias.
506
507 However, this feature was undeprecated in Perl 5.24.
508
509 =head3 Calling POSIX::%s() is deprecated
510
511 The following functions in the C<POSIX> module are no longer available:
512 C<isalnum>, C<isalpha>, C<iscntrl>, C<isdigit>, C<isgraph>, C<islower>,  
513 C<isprint>, C<ispunct>, C<isspace>, C<isupper>, and C<isxdigit>.  The 
514 functions are buggy and don't work on UTF-8 encoded strings.  See their
515 entries in L<POSIX> for more information.
516
517 The functions were deprecated in Perl 5.20, and removed in Perl 5.24.
518
519
520 =head2 Perl 5.16
521
522 =head3 Use of %s on a handle without * is deprecated
523
524 It used to be possible to use C<tie>, C<tied> or C<untie> on a scalar
525 while the scalar holds a typeglob. This caused its filehandle to be
526 tied. It left no way to tie the scalar itself when it held a typeglob,
527 and no way to untie a scalar that had had a typeglob assigned to it.
528
529 This was deprecated in Perl 5.14, and the bug was fixed in Perl 5.16.
530
531 So now C<tie $scalar> will always tie the scalar, not the handle it holds.
532 To tie the handle, use C<tie *$scalar> (with an explicit asterisk).  The same
533 applies to C<tied *$scalar> and C<untie *$scalar>.
534
535
536 =head1 SEE ALSO
537
538 L<warnings>, L<diagnostics>.
539
540 =cut