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