This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
f4d00ab8d96730f1bcaf79816bd24fadcf41f566
[perl5.git] / pod / perldelta.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 [ this is a template for a new perldelta file.  Any text flagged as XXX needs
6 to be processed before release. ]
7
8 perldelta - what is new for perl v5.17.7
9
10 =head1 DESCRIPTION
11
12 This document describes differences between the 5.17.6 release and the 5.17.7
13 release.
14
15 If you are upgrading from an earlier release such as 5.17.5, first read
16 L<perl5176delta>, which describes differences between 5.17.5 and 5.17.6.
17
18 =head1 Notice
19
20 XXX Any important notices here
21
22 =head1 Core Enhancements
23
24 =head2 $&, $` and $' are no longer slow
25
26 These three infamous variables have been redeemed and no longer slow down
27 your program when used.  Hence, the /p regular expression flag now does
28 nothing.
29
30 =head1 Security
31
32 XXX Any security-related notices go here.  In particular, any security
33 vulnerabilities closed should be noted here rather than in the
34 L</Selected Bug Fixes> section.
35
36 [ List each security issue as a =head2 entry ]
37
38 =head1 Incompatible Changes
39
40 =head2 readline() with C<$/ = \N> now reads N characters, not N bytes
41
42 Previously, when reading from a stream with I/O layers such as
43 C<encoding>, the readline() function, otherwise known as the C<< <> >>
44 operator, would read I<N> bytes from the top-most layer. [perl #79960]
45
46 Now, I<N> characters are read instead.
47
48 There is no change in behaviour when reading from streams with no
49 extra layers, since bytes map exactly to characters.
50
51 =head2 Lexical subroutine warnings have moved
52
53 The warning about the use of an experimental feature emitted when lexical
54 subroutines (added in 5.17.4) are used now happens when the subroutine
55 itself is declared, not when the "lexical_subs" feature is activated via
56 C<use feature>.
57
58 This stops C<use feature ':all'> from warning, but causes
59 C<my sub foo; my sub bar> to warn twice.
60
61 =head1 Deprecations
62
63 XXX Any deprecated features, syntax, modules etc. should be listed here.  In
64 particular, deprecated modules should be listed here even if they are listed as
65 an updated module in the L</Modules and Pragmata> section.
66
67 [ List each deprecation as a =head2 entry ]
68
69 =head2 Lexical $_ is now deprecated
70
71 Since it was introduced in Perl 5.10, it has caused much confusion with no
72 obvious solution:
73
74 =over
75
76 =item *
77
78 Various modules (e.g., List::Util) expect callback routines to use the
79 global $_.  C<use List::Util 'first'; my $_; first { $_ == 1 } @list> does
80 not work as one would expect.
81
82 =item *
83
84 A C<my $_> declaration earlier in the same file can cause confusing closure
85 warnings.
86
87 =item *
88
89 The "_" subroutine prototype character allows called subroutines to access
90 your lexical $_, so it is not really private after all.
91
92 =item *
93
94 Nevertheless, subroutines with a "(@)" prototype and methods cannot access
95 the caller's lexical $_, unless they are written in XS.
96
97 =item *
98
99 But even XS routines cannot access a lexical $_ declared, not in the
100 calling subroutine, but in an outer scope, iff that subroutine happened not
101 to mention $_ or use any operators that default to $_.
102
103 =back
104
105 =head2 Various XS-callable functions are now deprecated
106
107 The following functions will be removed from a future version of Perl,
108 and should not be used.  With participating C compilers (e.g., gcc),
109 compiling any file that uses any of these will generate a warning.
110 These were not intended for public use; there are equivalent, faster,
111 macros for most of them.  See L<perlapi/Character classes>:
112 C<is_uni_ascii>,
113 C<is_uni_ascii_lc>,
114 C<is_uni_blank>,
115 C<is_uni_blank_lc>,
116 C<is_uni_cntrl>,
117 C<is_uni_cntrl_lc>,
118 C<is_uni_idfirst_lc>,
119 C<is_uni_space>,
120 C<is_uni_space_lc>,
121 C<is_uni_xdigit>,
122 C<is_uni_xdigit_lc>,
123 C<is_utf8_ascii>,
124 C<is_utf8_blank>,
125 C<is_utf8_cntrl>,
126 C<is_utf8_idcont>,
127 C<is_utf8_idfirst>,
128 C<is_utf8_perl_space>,
129 C<is_utf8_perl_word>,
130 C<is_utf8_posix_digit>,
131 C<is_utf8_space>,
132 C<is_utf8_xdigit>.
133 C<is_utf8_xidcont>,
134 C<is_utf8_xidfirst>,
135 C<to_uni_lower_lc>,
136 C<to_uni_title_lc>,
137 and
138 C<to_uni_upper_lc>.
139
140 =head1 Performance Enhancements
141
142 XXX Changes which enhance performance without changing behaviour go here.
143 There may well be none in a stable release.
144
145 [ List each enhancement as a =item entry ]
146
147 =over 4
148
149 =item *
150
151 Perl has a new copy-on-write mechanism that avoids the need to copy the
152 internal string buffer when assigning from one scalar to another.  This
153 makes copying large strings appear much faster.  Modifying one of the two
154 (or more) strings after an assignment will force a copy internally.  This
155 makes it unnecessary to pass strings by reference for efficiency.
156
157 =back
158
159 =head1 Modules and Pragmata
160
161 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
162 go here.  If Module::CoreList is updated, generate an initial draft of the
163 following sections using F<Porting/corelist-perldelta.pl>, which prints stub
164 entries to STDOUT.  Results can be pasted in place of the '=head2' entries
165 below.  A paragraph summary for important changes should then be added by hand.
166 In an ideal world, dual-life modules would have a F<Changes> file that could be
167 cribbed.
168
169 [ Within each section, list entries as a =item entry ]
170
171 =head2 New Modules and Pragmata
172
173 =over 4
174
175 =item *
176
177 XXX
178
179 =back
180
181 =head2 Updated Modules and Pragmata
182
183 =over 4
184
185 =item *
186
187 L<GDBM_File> has been upgraded from version 1.14 to 1.15. The undocumented
188 optional fifth parameter to C<TIEHASH> has been removed. This was intended
189 to provide control of the callback used by C<gdbm*> functions in case of
190 fatal errors (such as filesystem problems), but did not work (and could
191 never have worked). No code on CPAN even attempted to use it. The callback
192 is now always the previous default, C<croak>. Problems on some platforms with
193 how the C<C> C<croak> function is called have also been resolved.
194
195 =back
196
197 =head2 Removed Modules and Pragmata
198
199 =over 4
200
201 =item *
202
203 XXX
204
205 =back
206
207 =head1 Documentation
208
209 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
210 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
211
212 =head2 New Documentation
213
214 XXX Changes which create B<new> files in F<pod/> go here.
215
216 =head3 L<XXX>
217
218 XXX Description of the purpose of the new file here
219
220 =head2 Changes to Existing Documentation
221
222 XXX Changes which significantly change existing files in F<pod/> go here.
223 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
224 section.
225
226 =head3 L<perlapi/Character classes>
227
228 =over 4
229
230 =item *
231
232 There are quite a few macros callable from XS modules that classify
233 characters into things like alphabetic, punctuation, etc.  More of these
234 are now documented, including ones which work on characters whose code
235 points are outside the Latin-1 range.
236
237 =back
238
239 =head1 Diagnostics
240
241 The following additions or changes have been made to diagnostic output,
242 including warnings and fatal error messages.  For the complete list of
243 diagnostic messages, see L<perldiag>.
244
245 XXX New or changed warnings emitted by the core's C<C> code go here.  Also
246 include any changes in L<perldiag> that reconcile it to the C<C> code.
247
248 =head2 New Diagnostics
249
250 XXX Newly added diagnostic messages go under here, separated into New Errors
251 and New Warnings
252
253 =head3 New Errors
254
255 =over 4
256
257 =item *
258
259 XXX L<message|perldiag/"message">
260
261 =back
262
263 =head3 New Warnings
264
265 =over 4
266
267 =item *
268
269 XXX L<message|perldiag/"message">
270
271 =back
272
273 =head2 Changes to Existing Diagnostics
274
275 XXX Changes (i.e. rewording) of diagnostic messages go here
276
277 =over 4
278
279 =item *
280
281 XXX Describe change here
282
283 =back
284
285 =head1 Utility Changes
286
287 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
288 Most of these are built within the directories F<utils> and F<x2p>.
289
290 [ List utility changes as a =head3 entry for each utility and =item
291 entries for each change
292 Use L<XXX> with program names to get proper documentation linking. ]
293
294 =head3 L<XXX>
295
296 =over 4
297
298 =item *
299
300 XXX
301
302 =back
303
304 =head1 Configuration and Compilation
305
306 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
307 go here.  Any other changes to the Perl build process should be listed here.
308 However, any platform-specific changes should be listed in the
309 L</Platform Support> section, instead.
310
311 [ List changes as a =item entry ].
312
313 =over 4
314
315 =item *
316
317 XXX
318
319 =back
320
321 =head1 Testing
322
323 XXX Any significant changes to the testing of a freshly built perl should be
324 listed here.  Changes which create B<new> files in F<t/> go here as do any
325 large changes to the testing harness (e.g. when parallel testing was added).
326 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
327 that they represent may be covered elsewhere.
328
329 [ List each test improvement as a =item entry ]
330
331 =over 4
332
333 =item *
334
335 XXX
336
337 =back
338
339 =head1 Platform Support
340
341 XXX Any changes to platform support should be listed in the sections below.
342
343 [ Within the sections, list each platform as a =item entry with specific
344 changes as paragraphs below it. ]
345
346 =head2 New Platforms
347
348 XXX List any platforms that this version of perl compiles on, that previous
349 versions did not.  These will either be enabled by new files in the F<hints/>
350 directories, or new subdirectories and F<README> files at the top level of the
351 source tree.
352
353 =over 4
354
355 =item XXX-some-platform
356
357 XXX
358
359 =back
360
361 =head2 Discontinued Platforms
362
363 =over 4
364
365 =item BeOS
366
367 Support for BeOS has been removed.
368
369 =back
370
371 =head2 Platform-Specific Notes
372
373 XXX List any changes for specific platforms.  This could include configuration
374 and compilation changes or changes in portability/compatibility.  However,
375 changes within modules for platforms should generally be listed in the
376 L</Modules and Pragmata> section.
377
378 =over 4
379
380 =item XXX-some-platform
381
382 XXX
383
384 =back
385
386 =head1 Internal Changes
387
388 XXX Changes which affect the interface available to C<XS> code go here.  Other
389 significant internal changes for future core maintainers should be noted as
390 well.
391
392 [ List each change as a =item entry ]
393
394 =over 4
395
396 =item *
397
398 SvUPGRADE() is no longer an expression. Originally this macro (and its
399 underlying function, sv_upgrade()) were documented as boolean, although
400 in reality they always croaked on error and never returned false. In 2005
401 the documentation was updated to specify a void return value, but
402 SvUPGRADE() was left always returning 1 for backwards compatibility. This
403 has now been removed, and SvUPGRADE() is now a statement with no return
404 value.
405
406 So this is now a syntax error:
407
408     if (!SvUPGRADE(sv)) { croak(...); }
409
410 If you have code like that, simply replace it with
411
412     SvUPGRADE(sv);
413
414 or to to avoid compiler warnings with older perls, possibly
415
416     (void)SvUPGRADE(sv);
417
418 =item *
419
420 Perl has a new copy-on-write mechanism that allows any SvPOK scalar to be
421 upgraded to a copy-on-write scalar.  A reference count on the string buffer
422 is stored in the string buffer itself.
423
424 This breaks a few XS modules by allowing copy-on-write scalars to go
425 through code paths that never encountered them before.
426
427 This behaviour can still be disabled by running F<Configure> with
428 B<-Accflags=-DPERL_NO_COW>.  This option will probably be removed in Perl
429 5.20.
430
431 =item *
432
433 Copy-on-write no longer uses the SvFAKE and SvREADONLY flags.  Hence,
434 SvREADONLY indicates a true read-only SV.
435
436 Use the SvIsCOW macro (as before) to identify a copy-on-write scalar.
437
438 =item *
439
440 C<PL_sawampersand> is now a constant.  The switch this variable provided
441 (to enable/disable the pre-match copy depending on whether C<$&> had been
442 seen) has been removed and replaced with copy-on-write, eliminating a few
443 bugs.
444
445 The previous behaviour can still be enabled by running F<Configure> with
446 B<-Accflags=-DPERL_SAWAMPERSAND>.
447
448 =back
449
450 =head1 Selected Bug Fixes
451
452 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
453 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
454
455 [ List each fix as a =item entry ]
456
457 =over 4
458
459 =item *
460
461 C<sort {undef} ...> under fatal warnings no longer crashes.  It started
462 crashing in Perl 5.16.
463
464 =item *
465
466 Stashes blessed into each other
467 (C<bless \%Foo::, 'Bar'; bless \%Bar::, 'Foo'>) no longer result in double
468 frees.  This bug started happening in Perl 5.16.
469
470 =item *
471
472 Numerous memory leaks have been fixed, mostly involving fatal warnings and
473 syntax errors.
474
475 =item *
476
477 Lexical constants (C<my sub answer () { 42 }>) no longer cause double
478 frees.
479
480 =item *
481
482 Constant subroutine redefinition warns by default, but lexical constants
483 were accidentally exempt from default warnings.  This has been corrected.
484
485 =item *
486
487 Some failed regular expression matches such as C<'f' =~ /../g> were not
488 resetting C<pos>.  Also, "match-once" patterns (C<m?...?g>) failed to reset
489 it, too, when invoked a second time [perl #23180].
490
491 =item *
492
493 Accessing C<$&> after a pattern match now works if it had not been seen
494 before the match.  I.e., this applies to C<${'&'}> (under C<no strict>) and
495 C<eval '$&'>.  The same applies to C<$'> and C<$`> [perl #4289].
496
497 =item *
498
499 Several bugs involving C<local *ISA> and C<local *Foo::> causing stale
500 MRO caches have been fixed.  
501
502 =item *
503
504 Defining a subroutine when its typeglob has been aliased no longer results
505 in stale method caches.  This bug was introduced in Perl 5.10.
506
507 =item *
508
509 Localising a typeglob containing a subroutine when the typeglob's package
510 has been deleted from its parent stash no longer produces an error.  This
511 bug was introduced in Perl 5.14.
512
513 =item *
514
515 Under some circumstances, C<local *method=...> would fail to reset method
516 caches upon scope exit.
517
518 =item *
519
520 C</[.foo.]/> is no longer an error, but produces a warning (as before) and
521 is treated as C</[.fo]/> [perl #115818].
522
523 =item *
524
525 C<goto $tied_var> now calls FETCH before deciding what type of goto
526 (subroutine or label) this is.
527
528 =back
529
530 =head1 Known Problems
531
532 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
533 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
534 platform specific bugs also go here.
535
536 [ List each fix as a =item entry ]
537
538 =over 4
539
540 =item *
541
542 XXX
543
544 =back
545
546 =head1 Obituary
547
548 XXX If any significant core contributor has died, we've added a short obituary
549 here.
550
551 =head1 Acknowledgements
552
553 XXX Generate this with:
554
555   perl Porting/acknowledgements.pl v5.17.6..HEAD
556
557 =head1 Reporting Bugs
558
559 If you find what you think is a bug, you might check the articles recently
560 posted to the comp.lang.perl.misc newsgroup and the perl bug database at
561 http://rt.perl.org/perlbug/ .  There may also be information at
562 http://www.perl.org/ , the Perl Home Page.
563
564 If you believe you have an unreported bug, please run the L<perlbug> program
565 included with your release.  Be sure to trim your bug down to a tiny but
566 sufficient test case.  Your bug report, along with the output of C<perl -V>,
567 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
568
569 If the bug you are reporting has security implications, which make it
570 inappropriate to send to a publicly archived mailing list, then please send it
571 to perl5-security-report@perl.org.  This points to a closed subscription
572 unarchived mailing list, which includes all the core committers, who will be
573 able to help assess the impact of issues, figure out a resolution, and help
574 co-ordinate the release of patches to mitigate or fix the problem across all
575 platforms on which Perl is supported.  Please only use this address for
576 security issues in the Perl core, not for modules independently distributed on
577 CPAN.
578
579 =head1 SEE ALSO
580
581 The F<Changes> file for an explanation of how to view exhaustive details on
582 what changed.
583
584 The F<INSTALL> file for how to build Perl.
585
586 The F<README> file for general stuff.
587
588 The F<Artistic> and F<Copying> files for copyright information.
589
590 =cut