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