This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update UNIVERSAL::VERSION POD to reflect reality.
[perl5.git] / pod / perldelta.pod
1 =encoding utf8
2
3 =for comment
4 This has been completed up to e08f19f5d07, except for
5 e032854 khw     [perl #32080] is_utf8_string() reads too far
6 b0f2e9e nwclark Fix two bugs related to pod files outside of pod/ (important enough?)
7
8 =head1 NAME
9
10 [ this is a template for a new perldelta file. Any text flagged as
11 XXX needs to be processed before release. ]
12
13 perldelta - what is new for perl v5.15.6
14
15 =head1 DESCRIPTION
16
17 This document describes differences between the 5.15.5 release and
18 the 5.15.6 release.
19
20 If you are upgrading from an earlier release such as 5.15.4, first read
21 L<perl5155delta>, which describes differences between 5.15.4 and
22 5.15.5.
23
24 =head1 Notice
25
26 XXX Any important notices here
27
28 =head1 Core Enhancements
29
30 XXX New core language features go here. Summarise user-visible core language
31 enhancements. Particularly prominent performance optimisations could go
32 here, but most should go in the L</Performance Enhancements> section.
33
34 [ List each enhancement as a =head2 entry ]
35
36 =head2 C<__SUB__>
37
38 The new C<__SUB__> token, available under the "current_sub" feature (see
39 L<feature>) or C<use v5.15>, returns a reference to the current subroutine,
40 making it easier to write recursive closures.
41
42 =head2 New option for the debugger's B<t> command
43
44 The B<t> command in the debugger, which toggles tracing mode, now accepts a
45 numerical argument that determines how many levels of subroutine calls to
46 trace.
47
48 =head2 Return value of C<tied>
49
50 The value returned by C<tied> on a tied variable is now the actual scalar
51 that holds the object to which the variable is tied.  This allows ties to
52 be weakened with C<Scalar::Util::weaken(tied $tied_variable)>.
53
54 =head1 Security
55
56 XXX Any security-related notices go here.  In particular, any security
57 vulnerabilities closed should be noted here rather than in the
58 L</Selected Bug Fixes> section.
59
60 [ List each security issue as a =head2 entry ]
61
62 =head1 Incompatible Changes
63
64 XXX For a release on a stable branch, this section aspires to be:
65
66     There are no changes intentionally incompatible with 5.XXX.XXX
67     If any exist, they are bugs and reports are welcome.
68
69 [ List each incompatible change as a =head2 entry ]
70
71 =head2 C<substr> lvalue revamp
72
73 When C<substr> is called in lvalue or potential lvalue context with two or
74 three arguments, a special lvalue scalar is returned that modifies the
75 original string (the first argument) when assigned to.
76
77 Previously, the offsets (the second and third arguments) passed to
78 C<substr> would be converted immediately to match the string, negative
79 offsets being translated to positive and offsets beyond the end of the
80 string being truncated.
81
82 Now, the offsets are recorded without modification in the special lvalue
83 scalar that is returned, and the original string is not even looked at by
84 C<substr> itself, but only when the returned lvalue is read or modified.
85
86 These changes result in several incompatible changes and bug fixes:
87
88 =over
89
90 =item *
91
92 If the original string changes length after the call to C<substr> but
93 before assignment to its return value, negative offsets will remember
94 their position from the end of the string, affecting code like this:
95
96     my $string = "string";
97     my $lvalue = \substr $string, -4, 2;
98     print $lvalue, "\n"; # prints "ri"
99     $string = "bailing twine";
100     print $lvalue, "\n"; # prints "wi"; used to print "il"
101
102 The same thing happens with an omitted third argument.  The returned lvalue
103 will always extend to the end of the string, even if the string becomes
104 longer.
105
106 =item *
107
108 Tied (and otherwise magical) variables are no longer exempt from the
109 "Attempt ot use reference as lvalue in substr" warning.
110
111 =item *
112
113 That warning now occurs when the returned lvalue is assigned to, not when
114 C<substr> itself is called.  This only makes a difference if the return
115 value of C<substr> is referenced and assigned to later.
116
117 =item *
118
119 The order in which "uninitialized" warnings occur for arguments to
120 C<substr> has changed.
121
122 =item *
123
124 Passing a substring of a read-only value or a typeglob to a function (potential lvalue context) no longer causes an immediate "Can't coerce" or "Modification of a read-only value" error.  That error only occurs if and
125 when the value passed is assigned to.
126
127 The same thing happens with the "substr outside of string" error.  If the
128 lvalue is only read, not written to, it is now just a warning, as with
129 rvalue C<substr>.
130
131 =item *
132
133 C<substr> assignments no longer call FETCH twice if the first argument is a
134 tied variable, but just once.
135
136 =back
137
138 It was impossible to fix all the bugs without an incompatible change, and
139 the behaviour of negative offsets was never specified, so the change was
140 deemed acceptable.
141
142 =head2 XS API tweak
143
144 The C<newCONSTSUB_flags> C-level function, added in 5.15.4, now has a
145 C<len> parameter.
146
147 =head1 Deprecations
148
149 XXX Any deprecated features, syntax, modules etc. should be listed here.
150 In particular, deprecated modules should be listed here even if they are
151 listed as an updated module in the L</Modules and Pragmata> section.
152
153 [ List each deprecation as a =head2 entry ]
154
155 =head1 Performance Enhancements
156
157 XXX Changes which enhance performance without changing behaviour go here. There
158 may well be none in a stable release.
159
160 [ List each enhancement as a =item entry ]
161
162 =over 4
163
164 =item *
165
166 Perl 5.12.0 sped up the destruction of objects whose classes define empty
167 C<DESTROY> methods (to prevent autoloading), simply by not calling such
168 empty methods.  This release takes this optimisation a step further, by not
169 calling any C<DESTROY> method that begins with an C<return> statement.
170 This can be useful for destructors that are only used for debugging:
171
172     use constant DEBUG => 1;
173     sub DESTROY { return unless DEBUG; ... }
174
175 Constant-folding will reduce the first statement to C<return;> if DEBUG is
176 set to 0, triggering this optimisation.
177
178 =item *
179
180 Assign to a variable that holds a typeglob or copy-on-write scalar is now
181 much faster.  Previously the typeglob would be stringified or the
182 copy-on-write scalar would be copied before being clobbered.
183
184 =item *
185
186 Assignment to a substring in void context is now more than twice its
187 previous speed.  Instead of creating and returning a special lvalue scalar
188 that is then assigned to, C<substr> modifies the original string itself.
189
190 =back
191
192 =head1 Modules and Pragmata
193
194 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
195 go here.  If Module::CoreList is updated, generate an initial draft of the
196 following sections using F<Porting/corelist-perldelta.pl>, which prints stub
197 entries to STDOUT.  Results can be pasted in place of the '=head2' entries
198 below.  A paragraph summary for important changes should then be added by hand.
199 In an ideal world, dual-life modules would have a F<Changes> file that could be
200 cribbed.
201
202 [ Within each section, list entries as a =item entry ]
203
204 =head2 New Modules and Pragmata
205
206 =over 4
207
208 =item *
209
210 XXX
211
212 =back
213
214 =head2 Updated Modules and Pragmata
215
216 =over 4
217
218 =item *
219
220 L<Archive::Tar> has been upgraded from version 1.80 to version 1.82.
221
222 Adjustments to handle files >8gb (>0777777777777 octal) and a feature to
223 return the MD5SUM of files in the archive.
224
225 =item *
226
227 L<AutoLoader> has been upgraded from version 5.71 to version 5.72.
228
229 =item *
230
231 L<B::Debug> has been upgraded from version 1.16 to version 1.17.
232
233 =item *
234
235 L<B::Deparse> has been upgraded from version 1.09 to 1.10.
236
237 C<sort(foo(bar))> is now deparsed correctly. (C<sort foo(bar)>, how it used
238 to deparse, makes foo the sort routine, rather than a regular function
239 call.)
240
241 =item *
242
243 L<Compress::Raw::Zlib> has been upgraded from version 2.042 to version 2.045.
244
245 =item *
246
247 L<Compress::Raw::Bzip2> has been upgraded from version 2.042 to version 2.045.
248
249 =item *
250
251 L<Data::Dumper> has been upgraded from version 2.134 to 2.135.
252
253 The XS implementation has been updated to account for the Unicode symbol
254 changes in Perl 5.15.4.  It also knows how to output typeglobs with nulls
255 in their names.
256
257 =item *
258
259 L<ExtUtils::ParseXS> has been upgraded from version 3.05 to version 3.07.
260
261 =item *
262
263 L<IO::Compress::Base> has been upgraded from version 2.042 to version 2.045.
264
265 Added zipdetails utility.
266
267 =item *
268
269 L<Locale::Codes> has been upgraded from version 3.18 to version 3.20.
270
271 The code2XXX, XXX2code, all_XXX_codes, and all_XXX_names functions now support retired codes.
272 All codesets may be specified by a constant or by their name now. Previously,
273 they were specified only by a constant.
274 The alias_code function exists for backward compatibility. It has been replaced by rename_country_code.
275 The alias_code function will be removed sometime after September, 2013.
276 All work is now done in the central module (Locale::Codes). Previously, some was still done in the
277 wrapper modules (Locale::Codes::*) but that is gone now.
278 Added Language Family codes (langfam) as defined in ISO 639-5.
279
280 =item *
281
282 L<Module::Loaded> has been uprgaded from version 0.06 to version 0.08.
283
284 =item *
285
286 L<Pod::LaTeX> has been upgraded from version 0.59 to version 0.60.
287
288 Added another LaTeX escape: --- => -{}-{}-
289
290 Pod::LaTeX doesn't handle -- in PODs specially, passing it directly to
291 LaTeX, which then proceeds to replace it with a single -. This patch
292 replaces ----- with -{}-{}-{}-{}-
293
294 =item *
295
296 L<POSIX> has been upgraded from version 1.26 to 1.27.
297
298 It no longer produces a "Constant subroutine TCSANOW redefined" warning on
299 Windows.
300
301 XXX When did it start producing that warning?  Was it post-5.15.5?  Even if
302 it was not, adding a note will help whoever compiles perl5160delta.
303
304 =item *
305
306 L<Unicode::Collate> has been upgraded from version 0.85 to version 0.87.
307
308 Tailored compatibility ideographs as well as unified ideographs for
309 the locales: ja, ko, zh__big5han, zh__gb2312han, zh__pinyin, zh__stroke.
310
311 Now Locale/*.pl files are searched in @INC.
312
313 =item *
314
315 L<UNIVERSAL> has been upgraded from version 1.10 to 1.11.
316
317 Documentation change clarifies return values from UNIVERSAL::VERSION.
318
319 =back
320
321 =head2 Removed Modules and Pragmata
322
323 =over 4
324
325 =item *
326
327 XXX
328
329 =back
330
331 =head1 Documentation
332
333 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
334 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
335
336 =head2 New Documentation
337
338 XXX Changes which create B<new> files in F<pod/> go here.
339
340 =head3 L<XXX>
341
342 XXX Description of the purpose of the new file here
343
344 =head2 Changes to Existing Documentation
345
346 XXX Changes which significantly change existing files in F<pod/> go here.
347 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
348 section.
349
350 =head3 L<XXX>
351
352 =over 4
353
354 =item *
355
356 XXX Description of the change here
357
358 =back
359
360 =head1 Diagnostics
361
362 The following additions or changes have been made to diagnostic output,
363 including warnings and fatal error messages.  For the complete list of
364 diagnostic messages, see L<perldiag>.
365
366 XXX New or changed warnings emitted by the core's C<C> code go here. Also
367 include any changes in L<perldiag> that reconcile it to the C<C> code.
368
369 [ Within each section, list entries as a =item entry that links to perldiag,
370   e.g.
371
372   =item *
373
374   L<Invalid version object|perldiag/"Invalid version object">
375 ]
376
377 =head2 New Diagnostics
378
379 XXX Newly added diagnostic messages go here
380
381 =head3 New Errors
382
383 =over 4
384
385 =item *
386
387 XXX L<message|perldiag/"message">
388
389 =back
390
391 =head3 New Warnings
392
393 =over 4
394
395 =item *
396
397 XXX L<message|perldiag/"message">
398
399 =back
400
401 =head2 Changes to Existing Diagnostics
402
403 XXX Changes (i.e. rewording) of diagnostic messages go here
404
405 =over 4
406
407 =item *
408
409 Redefinition warnings for constant subroutines used to be mandatory, even
410 occurring under C<no warnings>.  Now they respect the L<warnings> pragma.
411
412 =item *
413
414 The "Attempt to free non-existent shared string" has had the spelling of
415 "non-existent" corrected to "nonexistent".  It was already listed with the
416 correct spelling in L<perldiag>.
417
418 =item *
419
420 The 'Use of "foo" without parentheses is ambiguous' warning has been
421 extended to apply also to user-defined subroutines with a (;$) prototype,
422 and not just to built-in functions.
423
424 =back
425
426 =head1 Utility Changes
427
428 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
429 here. Most of these are built within the directories F<utils> and F<x2p>.
430
431 [ List utility changes as a =head3 entry for each utility and =item
432 entries for each change
433 Use L<XXX> with program names to get proper documentation linking. ]
434
435 =head3 L<zipdetails>
436
437 =over 4
438
439 =item *
440
441 L<zipdetails> displays information about the internal record structure of the zip file.
442 It is not concerned with displaying any details of the compressed data stored in the zip file.
443
444 =back
445
446 =head1 Configuration and Compilation
447
448 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
449 go here.  Any other changes to the Perl build process should be listed here.
450 However, any platform-specific changes should be listed in the
451 L</Platform Support> section, instead.
452
453 [ List changes as a =item entry ].
454
455 =over 4
456
457 =item *
458
459 F<pod/roffitall> is now build by F<pod/buildtoc>, instead of being shipped
460 with the distribution. Its list of manpages is now generated (and therefore
461 current). See also RT #103202 for an unresolved related issue.
462
463 =item *
464
465 Perl 5.15.5 had a bug in its installation script, which did not install
466 F<unicore/Name.pm>.  This has been corrected [perl #104226].
467
468 XXX Is that Perl version correct?  Is the file path correct?
469
470 =back
471
472 =head1 Testing
473
474 XXX Any significant changes to the testing of a freshly built perl should be
475 listed here.  Changes which create B<new> files in F<t/> go here as do any
476 large changes to the testing harness (e.g. when parallel testing was added).
477 Changes to existing files in F<t/> aren't worth summarising, although the bugs
478 that they represent may be covered elsewhere.
479
480 [ List each test improvement as a =item entry ]
481
482 =over 4
483
484 =item *
485
486 The F<substr.t> and F<substr_thr.t> scripts for testing C<substr> have been
487 moved under F<t/op/>, where they were originally.  They had been moved
488 under F<t/re/> along with the substitution tests when that directory was
489 created.
490
491 =back
492
493 =head1 Platform Support
494
495 XXX Any changes to platform support should be listed in the sections below.
496
497 [ Within the sections, list each platform as a =item entry with specific
498 changes as paragraphs below it. ]
499
500 =head2 New Platforms
501
502 XXX List any platforms that this version of perl compiles on, that previous
503 versions did not. These will either be enabled by new files in the F<hints/>
504 directories, or new subdirectories and F<README> files at the top level of the
505 source tree.
506
507 =over 4
508
509 =item XXX-some-platform
510
511 XXX
512
513 =back
514
515 =head2 Discontinued Platforms
516
517 XXX List any platforms that this version of perl no longer compiles on.
518
519 =over 4
520
521 =item XXX-some-platform
522
523 XXX
524
525 =back
526
527 =head2 Platform-Specific Notes
528
529 XXX List any changes for specific platforms. This could include configuration
530 and compilation changes or changes in portability/compatibility.  However,
531 changes within modules for platforms should generally be listed in the
532 L</Modules and Pragmata> section.
533
534 =over 4
535
536 =item XXX-some-platform
537
538 XXX
539
540 =back
541
542 =head1 Internal Changes
543
544 XXX Changes which affect the interface available to C<XS> code go here.
545 Other significant internal changes for future core maintainers should
546 be noted as well.
547
548 [ List each change as a =item entry ]
549
550 =over 4
551
552 =item *
553
554 XXX
555
556 =back
557
558 =head1 Selected Bug Fixes
559
560 XXX Important bug fixes in the core language are summarised here.
561 Bug fixes in files in F<ext/> and F<lib/> are best summarised in
562 L</Modules and Pragmata>.
563
564 [ List each fix as a =item entry ]
565
566 =over 4
567
568 =item *
569
570 A constant subroutine assigned to a glob whose name contains a null will no
571 longer cause extra globs to pop into existence when the constant is
572 referenced under its new name.
573
574 =item *
575
576 C<sort> was not treating C<sub {}> and C<sub {()}> as equivalent when such
577 a sub was provided as the comparison routine.  It used to croak on
578 C<sub {()}>.
579
580 =item *
581
582 Subroutines from the C<autouse> namespace are once more exempt from
583 redefinition warnings.  This used to work in 5.005, but was broken in 5.6
584 for most subroutines.  For subs created via XS that redefine subroutines
585 from the C<autouse> package, this stopped working in 5.10.
586
587 =item *
588
589 New XSUBs now produce redefinition warnings if they overwrite existing
590 subs, as they did in 5.8.x.  (The C<autouse> logic was reversed in 5.10-14.
591 Only subroutines from the C<autouse> namespace would warn when clobbered.)
592
593 =item *
594
595 Redefinition warnings triggered by the creation of XSUBs now respect
596 Unicode glob names, instead of using the internal representation.  This was
597 missed in 5.15.4, partly because this warning was so hard to trigger.  (See
598 the previous item.)
599
600 =item *
601
602 C<newCONSTSUB> used to use compile-time warning hints, instead of run-time
603 hints.  The following code should never produce a redefinition warning, but
604 it used to, if C<newCONSTSUB> redefine and existing subroutine:
605
606     use warnings;
607     BEGIN {
608         no warnings;
609         some_XS_function_that_calls_new_CONSTSUB();
610     }
611
612 =item *
613
614 Redefinition warnings for constant subroutines are on by default (what are
615 known as severe warnings in L<perldiag>).  This was only the case when it
616 was a glob assignment or declaration of a Perl subroutine that caused the
617 warning.  If the creation of XSUBs triggered the warning, it was not a
618 default warning.  This has been corrected.
619
620 =item *
621
622 The internal check to see whether a redefinition warning should occur used
623 to emit "uninitialized" warnings in cases like this:
624
625     use warnings "uninitialized";
626     use constant {u=>undef,v=>undef};
627     sub foo(){u} sub foo(){v}
628
629 =item *
630
631 A bug fix in Perl 5.14 introduced a new bug, causing "uninitialized"
632 warnings to report the wrong variable if the operator in question has
633 two operands and one is C<%{...}> or C<@{...}>.  This has been fixed
634 [perl #103766].
635
636 =item *
637
638 C<< version->new("version") >> and C<printf "%vd", "version"> no longer
639 crash [perl #102586].
640
641 =item *
642
643 C<$tied =~ y/a/b/>, C<chop $tied> and C<chomp $tied> now call FETCH just
644 once when $tied holds a reference.
645
646 =item *
647
648 Four-argument C<select> now always calls FETCH on tied arguments.  It used
649 to skip the call if the tied argument happened to hold C<undef> or a
650 typeglob.
651
652 =item *
653
654 Four-argument C<select> no longer produces its "Non-string passed as
655 bitmask" warning on tied or tainted variables that are strings.
656
657 =item *
658
659 C<sysread> now always calls FETCH on the buffer passed to it if it is tied.
660 It used to skip the call if the tied variable happened to hold a typeglob.
661
662 =item *
663
664 C<< $tied .= <> >> now calls FETCH once on C<$tied>.  It used to call it
665 multiple times if the last value assigned to or returned from the tied
666 variable was anything other than a string or typeglob.
667
668 =item *
669
670 The C<evalbytes> keyword added in 5.15.5 was respecting C<use utf8>
671 declarations from the outer scope, when it should have been ignoring them.
672
673 =item *
674
675 C<goto &func> no longers crashes, but produces an error message, when the
676 unwinding of the current subroutine's scope fires a destructor that
677 undefines the subroutine being "goneto" [perl #99850].
678
679 =item *
680
681 Arithmetic assignment (C<$left += $right>) involving overloaded objects that
682 rely on the 'nomethod' override no longer segfault when the left operand is not
683 overloaded.
684
685 =back
686
687 =head1 Known Problems
688
689 XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
690 tests that had to be C<TODO>ed for the release would be noted here, unless
691 they were specific to a particular platform (see below).
692
693 This is a list of some significant unfixed bugs, which are regressions
694 from either 5.XXX.XXX or 5.XXX.XXX.
695
696 [ List each fix as a =item entry ]
697
698 =over 4
699
700 =item *
701
702 XXX
703
704 =back
705
706 =head1 Obituary
707
708 XXX If any significant core contributor has died, we've added a short obituary
709 here.
710
711 =head1 Acknowledgements
712
713 XXX Generate this with:
714
715   perl Porting/acknowledgements.pl v5.15.5..HEAD
716
717 =head1 Reporting Bugs
718
719 If you find what you think is a bug, you might check the articles
720 recently posted to the comp.lang.perl.misc newsgroup and the perl
721 bug database at http://rt.perl.org/perlbug/ .  There may also be
722 information at http://www.perl.org/ , the Perl Home Page.
723
724 If you believe you have an unreported bug, please run the L<perlbug>
725 program included with your release.  Be sure to trim your bug down
726 to a tiny but sufficient test case.  Your bug report, along with the
727 output of C<perl -V>, will be sent off to perlbug@perl.org to be
728 analysed by the Perl porting team.
729
730 If the bug you are reporting has security implications, which make it
731 inappropriate to send to a publicly archived mailing list, then please send
732 it to perl5-security-report@perl.org. This points to a closed subscription
733 unarchived mailing list, which includes
734 all the core committers, who will be able
735 to help assess the impact of issues, figure out a resolution, and help
736 co-ordinate the release of patches to mitigate or fix the problem across all
737 platforms on which Perl is supported. Please only use this address for
738 security issues in the Perl core, not for modules independently
739 distributed on CPAN.
740
741 =head1 SEE ALSO
742
743 The F<Changes> file for an explanation of how to view exhaustive details
744 on what changed.
745
746 The F<INSTALL> file for how to build Perl.
747
748 The F<README> file for general stuff.
749
750 The F<Artistic> and F<Copying> files for copyright information.
751
752 =cut