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