90861de58155e16dc0116107359467c7c542a41d
[perl.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.30
18
19 =head3 C<< File::Glob::glob() >> will disappear
20
21 C<< File::Glob >> has a function called C<< glob >>, which just calls
22 C<< bsd_glob >>. However, its prototype is different from the prototype
23 of C<< CORE::glob >>, and hence, C<< File::Glob::glob >> should not
24 be used.
25
26 C<< File::Glob::glob() >> was deprecated in Perl 5.8. A deprecation
27 message was issued from Perl 5.26 onwards, and the function will
28 disappear in Perl 5.30.
29
30 Code using C<< File::Glob::glob() >> should call
31 C<< File::Glob::bsd_glob() >> instead.
32
33
34 =head3 Unescaped left braces in regular expressions
35
36 The simple rule to remember, if you want to match a literal C<{>
37 character (U+007B C<LEFT CURLY BRACKET>) in a regular expression
38 pattern, is to escape each literal instance of it in some way.
39 Generally easiest is to precede it with a backslash, like C<\{>
40 or enclose it in square brackets (C<[{]>).  If the pattern
41 delimiters are also braces, any matching right brace (C<}>) should
42 also be escaped to avoid confusing the parser, for example,
43
44  qr{abc\{def\}ghi}
45
46 Forcing literal C<{> characters to be escaped will enable the Perl
47 language to be extended in various ways in future releases.  To avoid
48 needlessly breaking existing code, the restriction is is not enforced in
49 contexts where there are unlikely to ever be extensions that could
50 conflict with the use there of C<{> as a literal.
51
52 Literal uses of C<{> were deprecated in Perl 5.20, and some uses of it
53 started to give deprecation warnings since. These cases were made fatal
54 in Perl 5.26. Due to an oversight, not all cases of a use of a literal
55 C<{> got a deprecation warning. These cases started warning in Perl 5.26,
56 and they will be fatal by Perl 5.30.
57
58
59 =head2 Perl 5.28
60
61 =head3 Attribute "%s" is deprecated, and will disappear in 5.28
62
63 The attributes C<< :locked >> (on code references) and C<< :unique >>
64 (on array, hash and scalar references) have had no effect since 
65 Perl 5.005 and Perl 5.8.8 respectively. Their use has been deprecated
66 since.
67
68 These attributes will no longer be recognized in Perl 5.28, and will
69 then result in a syntax error. Since the attributes do not do anything,
70 removing them from your code fixes the deprecation warning; and removing
71 them will not influence the behaviour of your code.
72
73
74 =head3 Bare here-document terminators
75
76 Perl has allowed you to use a bare here-document terminator to have the
77 here-document end at the first empty line. This practise was deprecated
78 in Perl 5.000, and this will be a fatal error in Perl 5.28.
79
80 You are encouraged to use the explictly quoted form if you wish to
81 use an empty line as the terminator of the here-document:
82
83   print <<"";
84     Print this line.
85
86   # Previous blank line ends the here-document.
87
88
89 =head3 Setting $/ to a reference to a non-positive integer
90
91 You assigned a reference to a scalar to C<$/> where the
92 referenced item is not a positive integer.  In older perls this B<appeared>
93 to work the same as setting it to C<undef> but was in fact internally
94 different, less efficient and with very bad luck could have resulted in
95 your file being split by a stringified form of the reference.
96
97 In Perl 5.20.0 this was changed so that it would be B<exactly> the same as
98 setting C<$/> to undef, with the exception that this warning would be
99 thrown.
100
101 In Perl 5.28, this will throw a fatal error.
102
103 You are recommended to change your code to set C<$/> to C<undef> explicitly
104 if you wish to slurp the file.
105
106
107 =head3 Limit on the value of Unicode code points.
108
109 Unicode only allows code points up to 0x10FFFF, but Perl allows much
110 larger ones. However, using code points exceeding the maximum value
111 of an integer (C<IV_MAX>) may break the perl interpreter in some constructs,
112 including causing it to hang in a few cases.  The known problem areas
113 are in C<tr///>, regular expression pattern matching using quantifiers,
114 as quote delimiters in C<qI<X>...I<X>> (where I<X> is the C<chr()> of a large
115 code point), and as the upper limits in loops.
116
117 The use of out of range code points was deprecated in Perl 5.24, and
118 it will be a fatal error in Perl 5.28.
119
120 If your code is to run on various platforms, keep in mind that the upper
121 limit depends on the platform.  It is much larger on 64-bit word sizes
122 than 32-bit ones.
123
124
125 =head3 Use of comma-less variable list in formats.
126
127 It's allowed to use a list of variables in a format, without
128 separating them with commas. This usage has been deprecated
129 for a long time, and it will be a fatal error in Perl 5.28.
130
131
132
133 =head3 Use of C<\N{}>
134
135 Use of C<\N{}> with nothing between the braces was deprecated in
136 Perl 5.24, and will throw a fatal error in Perl 5.28.
137
138 Since such a construct is equivalent to using an empty string,
139 you are recommended to remove such C<\N{}> constructs.
140
141
142 =head3 Using the same symbol to open a filehandle and a dirhandle
143
144 It used to be legal to use C<open()> to associate both a
145 filehandle and a dirhandle to the same symbol (glob or scalar).
146 This idiom is likely to be confusing, and it was deprecated in
147 Perl 5.10.
148
149 Using the same symbol to C<open()> a filehandle and a dirhandle
150 will be a fatal error in Perl 5.28.
151
152 You should be using two different symbols instead.
153
154
155
156 =head3 Use of "goto" to jump into a construct.
157
158 Use of C<goto> to jump from an outer scope into an inner scope was
159 deprecated in Perl 5.12, and it will be a fatal error in Perl 5.28.
160
161 This means, you should not write constructs like:
162
163    $x = 1;
164    while ($x) {
165        $foo = 1;
166      LABEL:
167        $bar = 1;
168    }
169    goto LABEL;
170
171 This will jump into the block belonging to C<while>. Not only has 
172 been this a cause of subtle bugs in the past, it's generally
173 considered to lead to hard to understand programs.
174
175 This means, soon it's not possible anymore to write
176 L<Duff's device|https://www.lysator.liu.se/c/duffs-device.html> in pure Perl.
177 But you never wanted to do this anyway.
178
179
180 =head3 ${^ENCODING} is no longer supported.
181
182 The special variable C<${^ENCODING}> was used to implement
183 the C<encoding> pragma. Setting this variable to anything other
184 than C<undef> was deprecated in Perl 5.22. Full deprecation
185 of the variable happened in Perl 5.25.3.
186
187 Setting this variable will become a fatal error in Perl 5.28.
188
189
190
191 =head3 Use of inherited AUTOLOAD for non-method %s() is deprecated
192
193 As an (ahem) accidental feature, C<AUTOLOAD> subroutines are looked
194 up as methods (using the C<@ISA> hierarchy) even when the subroutines
195 to be autoloaded were called as plain functions (e.g. C<Foo::bar()>),
196 not as methods (e.g. C<< Foo->bar() >> or C<< $obj->bar() >>).
197
198 This bug will be rectified in future by using method lookup only for
199 methods' C<AUTOLOAD>s.
200
201 The simple rule is:  Inheritance will not work when autoloading
202 non-methods.  The simple fix for old code is:  In any module that used
203 to depend on inheriting C<AUTOLOAD> for non-methods from a base class
204 named C<BaseClass>, execute C<*AUTOLOAD = \&BaseClass::AUTOLOAD> during
205 startup.
206
207 In code that currently says C<use AutoLoader; @ISA = qw(AutoLoader);>
208 you should remove AutoLoader from @ISA and change C<use AutoLoader;> to
209 C<use AutoLoader 'AUTOLOAD';>.
210
211 This feature was deprecated in Perl 5.004, and will be fatal in Perl 5.28.
212
213
214 =head2 Perl 5.26
215
216 =head3 C<< --libpods >> in C<< Pod::Html >>
217
218 Since Perl 5.18, the option C<< --libpods >> has been deprecated, and
219 using this option did not do anything other than producing a warning.
220
221 The C<< --libpods >> option is no longer recognized in Perl 5.26.
222
223
224 =head3 The utilities C<< c2ph >> and C<< pstruct >>
225
226 These old, perl3-era utilities have been deprecated in favour of
227 C<< h2xs >> for a long time. In Perl 5.26, they have been removed.
228
229
230 =head3 Trapping C<< $SIG {__DIE__} >> other than during program exit.
231
232 The C<$SIG{__DIE__}> hook is called even inside an C<eval()>. It was
233 never intended to happen this way, but an implementation glitch made
234 this possible. This used to be deprecated, as it allowed strange action
235 at a distance like rewriting a pending exception in C<$@>. Plans to
236 rectify this have been scrapped, as users found that rewriting a
237 pending exception is actually a useful feature, and not a bug.
238
239 Perl never issued a deprecation warning for this; the deprecation
240 was by documentation policy only. But this deprecation has been 
241 lifted in Perl 5.26.
242
243
244 =head2 Perl 5.24
245
246 =head3 Use of C<< *glob{FILEHANDLE} >>
247
248 The use of C<< *glob{FILEHANDLE} >> was deprecated in Perl 5.8.
249 The intention was to use C<< *glob{IO} >> instead, for which 
250 C<< *glob{FILEHANDLE} >> is an alias.
251
252 However, this feature was undeprecated in Perl 5.24.
253
254 =head3 Calling POSIX::%s() is deprecated
255
256 The following functions in the C<POSIX> module are no longer available:
257 C<isalnum>, C<isalpha>, C<iscntrl>, C<isdigit>, C<isgraph>, C<islower>,  
258 C<isprint>, C<ispunct>, C<isspace>, C<isupper>, and C<isxdigit>.  The 
259 functions are buggy and don't work on UTF-8 encoded strings.  See their
260 entries in L<POSIX> for more information.
261
262 The functions were deprecated in Perl 5.20, and removed in Perl 5.24.
263
264
265 =head2 Perl 5.16
266
267 =head3 Use of %s on a handle without * is deprecated
268
269 It used to be possible to use C<tie>, C<tied> or C<untie> on a scalar
270 while the scalar holds a typeglob. This caused its filehandle to be
271 tied. It left no way to tie the scalar itself when it held a typeglob,
272 and no way to untie a scalar that had had a typeglob assigned to it.
273
274 This was deprecated in Perl 5.14, and the bug was fixed in Perl 5.16.
275
276 So now C<tie $scalar> will always tie the scalar, not the handle it holds.
277 To tie the handle, use C<tie *$scalar> (with an explicit asterisk).  The same
278 applies to C<tied *$scalar> and C<untie *$scalar>.
279
280
281 =head2 Perl 5.10
282
283 =head3 $* is no longer supported
284
285 C<$*> was once a magic variable. C<$*> enabled or disabled
286 multi-line matching within a string. Deprecated since Perl 5.000,
287 its special meaning was removed in Perl 5.10. Aftwards, an
288 deprecation message was issued when using this variable; this message
289 was discontinued in Perl 5.26.
290
291 Instead of using C<$*> you should use the C</m> (and maybe C</s>) regexp
292 modifiers.  You can enable C</m> for a lexical scope (even a whole file)
293 with C<use re '/m'>.  (In older versions: when C<$*> was set to a true value
294 then all regular expressions behaved as if they were written using C</m>.)
295
296 Although you can use C<$*> as a normal variable, you are discouraged 
297 from doing so.
298
299 =head3 $# is no longer supported
300
301 C<$#> was once a magic variable. C<$#> could be used to format
302 printed numbers. Deprecated since Perl 5.000,
303 its special meaning was removed in Perl 5.10. Aftwards, an
304 deprecation message was issued when using this variable; this message
305 was discontinued in Perl 5.26.
306
307 Instead of using C<$#>, you should be using C<(s)printf> to format
308 your numbers.
309
310 Although you can use C<$#> as a normal variable, you are discouraged 
311 from doing so.
312
313
314 =head1 SEE ALSO
315
316 L<warnings>, L<diagnostics>.
317
318 =cut