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