This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
document the upgrade of Perldoc
[perl5.git] / pod / perldelta.pod
1 =encoding utf8
2
3 =for comment
4 This has been completed up to 9ac8a16, except for:
5 8629c11317 smueller Escape double-quotes in generated #line directives
6 8dc67a69b  shlomif  perl -d: display lines inside subroutines.
7 3dfd1b5cd2 leont    Export PerlIOBase_open
8
9 =head1 NAME
10
11 [ this is a template for a new perldelta file. Any text flagged as
12 XXX needs to be processed before release. ]
13
14 perldelta - what is new for perl v5.15.7
15
16 =head1 DESCRIPTION
17
18 This document describes differences between the 5.15.6 release and
19 the 5.15.7 release.
20
21 If you are upgrading from an earlier release such as 5.15.5, first read
22 L<perl5156delta>, which describes differences between 5.15.5 and
23 5.15.6.
24
25 =head1 Notice
26
27 XXX Any important notices here
28
29 =head1 Core Enhancements
30
31 XXX New core language features go here. Summarise user-visible core language
32 enhancements. Particularly prominent performance optimisations could go
33 here, but most should go in the L</Performance Enhancements> section.
34
35 [ List each enhancement as a =head2 entry ]
36
37 =head2 C<use charnames> no longer needed for C<\N{I<name>}>
38
39 The C<charnames> module is now automatically loaded when needed as if
40 the C<:full> and C<:short> options had been specified.  See
41 L<charnames>.
42
43 =head1 Security
44
45 XXX Any security-related notices go here.  In particular, any security
46 vulnerabilities closed should be noted here rather than in the
47 L</Selected Bug Fixes> section.
48
49 [ List each security issue as a =head2 entry ]
50
51 =head1 Incompatible Changes
52
53 XXX For a release on a stable branch, this section aspires to be:
54
55     There are no changes intentionally incompatible with 5.XXX.XXX
56     If any exist, they are bugs, and we request that you submit a
57     report.  See L</Reporting Bugs> below.
58
59 [ List each incompatible change as a =head2 entry ]
60
61 =head1 Deprecations
62
63 XXX Any deprecated features, syntax, modules etc. should be listed here.
64 In particular, deprecated modules should be listed here even if they are
65 listed as an updated module in the L</Modules and Pragmata> section.
66
67 [ List each deprecation as a =head2 entry ]
68
69 =head2 Deprecated Modules
70
71 =over
72
73 =item L<Version::Requirements>
74
75 Version::Requirements is now DEPRECATED, use CPAN::Meta::Requirements,
76 which is a drop-in replacement. It will be deleted from perl.git blead
77 in v5.17.0.
78
79 =back
80
81 =head1 Performance Enhancements
82
83 XXX Changes which enhance performance without changing behaviour go here. There
84 may well be none in a stable release.
85
86 [ List each enhancement as a =item entry ]
87
88 =over 4
89
90 =item *
91
92 Version declarations with the C<use> keyword (e.g., C<use 5.012>) are now
93 faster, as they enable features without loading F<feature.pm>.
94
95 =back
96
97 =head1 Modules and Pragmata
98
99 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
100 go here.  If Module::CoreList is updated, generate an initial draft of the
101 following sections using F<Porting/corelist-perldelta.pl>, which prints stub
102 entries to STDOUT.  Results can be pasted in place of the '=head2' entries
103 below.  A paragraph summary for important changes should then be added by hand.
104 In an ideal world, dual-life modules would have a F<Changes> file that could be
105 cribbed.
106
107 [ Within each section, list entries as a =item entry ]
108
109 =head2 New Modules and Pragmata
110
111 =over 4
112
113 =item *
114
115 XXX
116
117 =back
118
119 =head2 Updated Modules and Pragmata
120
121 =over 4
122
123 =item *
124
125 L<B::Deparse> has been upgraded from version 1.10 to version 1.11.
126
127 It now deparses C<open('random string')> correctly.  It used to omit the
128 quotation marks, which did not work if the string were not a valid
129 identifier [perl #91416].
130
131 A similar bug also affected hash and array elements such as
132 C<< 'random string'->[0] >>, which would deparse as C<$random string[0]>.
133 This has been fixed.
134
135 Those same syntaxes used to drop the package name from variables beginning
136 with a punctuation mark, as in C<< "foo::]"->{$key} >>.  This, too, has
137 been fixed.
138
139 B::Deparse no longer hangs when deparsing a program with stash
140 circularities, such as C<BEGIN { *Acme::Acme:: = *Acme:: }> [perl #91384].
141
142 C</$s[1]/> used to be deparsed as C<$s[1]> if @s were a lexical variable
143 [perl #81424].  Similarly, C</$#s/> would be deparsed as C<$#s> for both
144 lexical and package variables.  These has been fixed.
145
146 The C</applaud> regular expression flags are no longer omitted.
147
148 Feature hints are now deparsed with C<use feature> rather than C<%^H>
149 assignments.
150
151 A regression in 1.10 that caused C<ambient_pragmas> to disabled strict mode
152 in obscure cases has been fixed.
153
154 Strict mode is now fully deparsed, including subs and vars [perl #24027].
155
156 The global variables C<$(>, C<$|> and C<$)> are now deparsed with braces
157 (i.e., C<${(}>) in regular expressions [perl #86060].
158
159 =item *
160
161 L<CGI> has been upgraded from version 3.58 to version 3.59.
162
163 We no longer read from STDIN when the Content-Length is not set, preventing
164 requests with no Content-Length from freezing in some cases. This is consistent
165 with the CGI RFC 3875, and is also consistent with CGI::Simple. However, the old
166 behavior may have been expected by some command-line uses of CGI.pm.
167
168 =item *
169
170 L<CPAN::Meta> has been upgraded from version 2.112621 to version 2.113640.
171
172 Version::Requirements has now been merged as CPAN::Meta::Requirements.
173
174 =item *
175
176 L<CPANPLUS> has been upgraded from version 0.9113 to version 0.9116.
177
178 =item *
179
180 L<POSIX> has been upgraded from version 1.28 to version 1.29.
181 C<POSIX::sleep> is now a direct call into the underlying OS C<sleep>
182 function, instead of being a Perl wrapper on C<CORE::sleep>. C<POSIX::dup2>
183 now returns the correct value on Win32 (I<i.e.> the file descriptor).
184 C<POSIX::SigSet> C<sigsuspend> and C<sigpending> and C<POSIX::pause> now
185 dispatch safe signals immediately before returning to their caller.
186
187 =item *
188
189 L<Data::Dumper> has been upgraded from version 2.135_01 to version
190 2.135_03.
191
192 It can now dump vstrings [perl #101162].
193
194 The nameless typeglob (C<*{""}>) is now dumped properly.
195
196 =item *
197
198 L<diagnostics> has been upgraded from version 1.26 to version 1.27.
199
200 See the entry for splain in the L</Utility Changes> section, for the
201 changes.  The diagnostics module and the splain utility are actually one
202 and the same.
203
204 =item *
205
206 L<Module::Pluggable> has been upgraded from version 3.9 to version 4.0.
207
208 =item *
209
210 L<POSIX> has been upgraded from version 1.27 to version 1.28.
211
212 C<sigsuspend> and C<pause> now run signals handle before returning, as the
213 whole point of these two functions is to wait until a signal has
214 arrived, and then return I<after> it has been triggered.  Delayed, or
215 "safe", signals were preventing that from happening, possibly resulting in
216 race conditions [perl #107216].
217
218 =item *
219
220 L<Pod::Perldoc> has been upgraded from version 3.15_01 to version 3.15_15.
221
222 =item *
223
224 L<Term::UI> has been upgraded from version 0.26 to version 0.30.
225
226 =item *
227
228 L<Tie::File> has been upgraded from version 0.96 to version 0.98.
229
230 =item *
231
232 L<Unicode::UCD> has been upgraded from version 0.37 to version 0.38.
233 This changes the output of C<prop_invmap()> for the Name_Alias property
234 to reflect the changes that are planned for Unicode 6.1, so that there
235 won't be a format change when upgrading to 6.1.  Briefly, a second
236 component of each alias is added that gives the type of alias it is.
237 Examples are at L<Unicode::UCD/prop_invmap()>.
238
239 =item *
240
241 L<Version::Requirements> has been upgraded from version 0.101020 to version 0.101021.
242
243 Version::Requirements is now DEPRECATED, use CPAN::Meta::Requirements,
244 which is a drop-in replacement.
245
246 =back
247
248 =head2 Removed Modules and Pragmata
249
250 =over 4
251
252 =item *
253
254 XXX
255
256 =back
257
258 =head1 Documentation
259
260 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
261 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
262
263 =head2 New Documentation
264
265 XXX Changes which create B<new> files in F<pod/> go here.
266
267 =head3 L<XXX>
268
269 XXX Description of the purpose of the new file here
270
271 =head2 Changes to Existing Documentation
272
273 XXX Changes which significantly change existing files in F<pod/> go here.
274 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
275 section.
276
277 =head3 L<XXX>
278
279 =over 4
280
281 =item *
282
283 XXX Description of the change here
284
285 =back
286
287 =head1 Diagnostics
288
289 The following additions or changes have been made to diagnostic output,
290 including warnings and fatal error messages.  For the complete list of
291 diagnostic messages, see L<perldiag>.
292
293 XXX New or changed warnings emitted by the core's C<C> code go here. Also
294 include any changes in L<perldiag> that reconcile it to the C<C> code.
295
296 [ Within each section, list entries as a =item entry that links to perldiag,
297   e.g.
298
299   =item *
300
301   L<Invalid version object|perldiag/"Invalid version object">
302 ]
303
304 =head2 New Diagnostics
305
306 XXX Newly added diagnostic messages go here
307
308 =head3 New Errors
309
310 =over 4
311
312 =item *
313
314 L<Cannot set tied @DB::args|perldiag/"Cannot set tied @DB::args">
315
316 This error occurs when C<caller> tries to set C<@DB::args> but finds it
317 tied.  Before this error was added, it used to crash instead.
318
319 =item *
320
321 L<Cannot tie unreifiable array|perldiag/"Cannot tie unreifiable array">
322
323 This error is part of a safety check that the C<tie> operator does before
324 tying a special array like C<@_>.  You should never see this message.
325
326 =back
327
328 =head3 New Warnings
329
330 =over 4
331
332 =item *
333
334 XXX L<message|perldiag/"message">
335
336 =back
337
338 =head2 Changes to Existing Diagnostics
339
340 XXX Changes (i.e. rewording) of diagnostic messages go here
341
342 =over 4
343
344 =item *
345
346 XXX Describe change here
347
348 =back
349
350 =head1 Utility Changes
351
352 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
353 here. Most of these are built within the directories F<utils> and F<x2p>.
354
355 [ List utility changes as a =head3 entry for each utility and =item
356 entries for each change
357 Use L<XXX> with program names to get proper documentation linking. ]
358
359 =head3 L<splain>
360
361 =over 4
362
363 =item *
364
365 splain no longer emits backtraces with the first line number repeated.
366 This:
367
368     Uncaught exception from user code:
369             Cannot fwiddle the fwuddle at -e line 1.
370      at -e line 1
371             main::baz() called at -e line 1
372             main::bar() called at -e line 1
373             main::foo() called at -e line 1
374
375 has become this:
376
377     Uncaught exception from user code:
378             Cannot fwiddle the fwuddle at -e line 1.
379             main::baz() called at -e line 1
380             main::bar() called at -e line 1
381             main::foo() called at -e line 1
382
383 =item *
384
385 Some error message consist of multiple lines that are listed as separate
386 entries in L<perldiag>.  splain has been taught to find the separate
387 entries in these cases, instead of simply failing to find the message.
388
389 =back
390
391 =head1 Configuration and Compilation
392
393 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
394 go here.  Any other changes to the Perl build process should be listed here.
395 However, any platform-specific changes should be listed in the
396 L</Platform Support> section, instead.
397
398 [ List changes as a =item entry ].
399
400 =over 4
401
402 =item *
403
404 The Pod files for the perl FAQ, L<perlxs>, L<perlxstut> and L<perldoc>
405 are once again correctly installed in the same directory as the other core
406 Pods.
407
408 =for 5.16.0 This isn't a regression from 5.14.x, so don't mention this.
409
410 =back
411
412 =head1 Testing
413
414 XXX Any significant changes to the testing of a freshly built perl should be
415 listed here.  Changes which create B<new> files in F<t/> go here as do any
416 large changes to the testing harness (e.g. when parallel testing was added).
417 Changes to existing files in F<t/> aren't worth summarising, although the bugs
418 that they represent may be covered elsewhere.
419
420 [ List each test improvement as a =item entry ]
421
422 =over 4
423
424 =item *
425
426 F<t/porting/utils.t> now tests that various utility scripts compile cleanly.
427 During development, this avoids the embarrassment of inadvertently pushing a
428 commit which breaks code which isn't otherwise tested by the regression test
429 suite. For example, F<installperl> and F<installman>, needed by
430 C<make install>, are tested here.
431
432 =back
433
434 =head1 Platform Support
435
436 XXX Any changes to platform support should be listed in the sections below.
437
438 [ Within the sections, list each platform as a =item entry with specific
439 changes as paragraphs below it. ]
440
441 =head2 New Platforms
442
443 XXX List any platforms that this version of perl compiles on, that previous
444 versions did not. These will either be enabled by new files in the F<hints/>
445 directories, or new subdirectories and F<README> files at the top level of the
446 source tree.
447
448 =over 4
449
450 =item XXX-some-platform
451
452 XXX
453
454 =back
455
456 =head2 Discontinued Platforms
457
458 XXX List any platforms that this version of perl no longer compiles on.
459
460 =over 4
461
462 =item XXX-some-platform
463
464 XXX
465
466 =back
467
468 =head2 Platform-Specific Notes
469
470 XXX List any changes for specific platforms. This could include configuration
471 and compilation changes or changes in portability/compatibility.  However,
472 changes within modules for platforms should generally be listed in the
473 L</Modules and Pragmata> section.
474
475 =over 4
476
477 =item XXX-some-platform
478
479 XXX
480
481 =back
482
483 =head1 Internal Changes
484
485 XXX Changes which affect the interface available to C<XS> code go here.
486 Other significant internal changes for future core maintainers should
487 be noted as well.
488
489 [ List each change as a =item entry ]
490
491 =over 4
492
493 =item *
494
495 There are now feature bundle hints in C<PL_hints> (C<$^H>) that version
496 declarations use, to avoid having to load F<feature.pm>.  One setting of
497 the hint bits indicates a "custom" feature bundle, which means that the
498 entries in C<%^H> still apply.  F<feature.pm> uses that.
499
500 The C<HINT_FEATURE_MASK> macro is defined in F<perl.h> along with other
501 hints.  Other macros for setting and testing features and bundles are in
502 the new F<feature.h>.  C<FEATURE_IS_ENABLED> (which has moved to
503 F<feature.h>) is no longer used throughout the codebase, but more specific
504 macros, e.g., C<FEATURE_SAY_IS_ENABLED>, that are defined in F<feature.h>.
505
506 =item *
507
508 F<lib/feature.pm> is now a generated file, created by the new
509 F<regen/feature.pl> script, which also generates F<feature.h>.
510
511 =item *
512
513 Tied arrays are now always C<AvREAL>.  If C<@_> or C<DB::args> is tied, it
514 is reified first, to make sure this is always the case.
515
516 =back
517
518 =head1 Selected Bug Fixes
519
520 XXX Important bug fixes in the core language are summarised here.
521 Bug fixes in files in F<ext/> and F<lib/> are best summarised in
522 L</Modules and Pragmata>.
523
524 [ List each fix as a =item entry ]
525
526 =over 4
527
528 =item * "b . COND" in the debugger has been fixed
529
530 Breaking on the current line with C<b . COND> was broken by previous work and
531 has now been fixed.
532
533 =item * Tying C<%^H>
534
535 Tying C<%^H> no longer causes perl to crash or ignore
536 the contents of C<%^H> when entering a compilation
537 scope [perl #106282].
538
539 =item * C<~> on vstrings
540
541 The bitwise complement operator (and possibly other operators, too) when
542 passed a vstring would leave vstring magic attached to the return value,
543 even though the string had changed.  This meant that
544 C<< version->new(~v1.2.3) >> would create a version looking like "v1.2.3"
545 even though the string passed to C<< version->new >> was actually
546 "\376\375\374".  This also caused L<B::Deparse> to deparse C<~v1.2.3>
547 incorrectly, without the C<~> [perl #29070].
548
549 =item * Vstrings blowing away magic
550
551 Assigning a vstring to a magic (e.g., tied, C<$!>) variable and then
552 assigning something else used to blow away all the magic.  This meant that
553 tied variables would come undone, C<$!> would stop getting updated on
554 failed system calls, C<$|> would stop setting autoflush, and other
555 mischief would take place.  This has been fixed.
556
557 =item * C<newHVhv> and tied hashes
558
559 The C<newHVhv> XS function now works on tied hashes, instead of crashing or
560 returning an empty hash.
561
562 =item * Hashes will null elements
563
564 It is possible from XS code to create hashes with elements that have no
565 values.  Perl itself sometimes creates such hashes, but they are rarely
566 visible to Perl code.  The hash element and slice operators used to crash
567 when handling these in lvalue context.  These have been fixed.  They now
568 produce a "Modification of non-creatable hash value attempted" error
569 message.
570
571 =item * No warning for C<open(foo::bar)>
572
573 When one writes C<open foo || die>, which used to work in Perl 4, a
574 "Precedence problem" warning is produced.  This warning used erroneously to
575 apply to fully-qualified bareword handle names as well.  This has been
576 corrected.
577
578 =item * C<select> and package aliasing
579
580 After package aliasing (C<*foo:: = *bar::>), C<select> with 0 or 1 argument
581 would sometimes return a name that could not be used to refer to the
582 filehandle, or sometimes it would return C<undef> even when a filehandle
583 was selected.  Now it returns a typeglob reference in such cases.
584
585 =item * C<PerlIO::get_layers> and tied variables
586
587 C<PerlIO::get_layers> no longer ignores FETCH on tied variables as it used
588 to most of the time [perl #97956].
589
590 =item * C<PerlIO::get_layers> and numbers
591
592 C<PerlIO::get_layers> no longer ignores some arguments that it thinks are
593 numeric, while treating others as filehandle names.  It is now consistent
594 for flat scalars (i.e., not references).
595
596 =item * Lvalue subs and strict mode
597
598 Lvalue sub calls that are not determined to be such at compile time
599 (C<&$name> or &{"name"}) are no longer exempt from strict refs if they
600 occur in the last statement of an lvalue subroutine [perl #102486].
601
602 =item * Non-lvalue sub calls in potentially lvalue context
603
604 Sub calls whose subs are not visible at compile time, if
605 they occurred in the last statement of an lvalue subroutine,
606 would reject non-lvalue subroutines and die with "Can't modify non-lvalue
607 subroutine call" [perl #102486].
608
609 Non-lvalue sub calls whose subs I<are> visible at compile time exhibited
610 the opposite bug.  If the call occurred in the last statement of an lvalue
611 subroutine, there would be no error when the lvalue sub was called in
612 lvalue context.  Perl would blindly assign to the temporary value returned
613 by the non-lvalue subroutine.
614
615 =item * AUTOLOADing lvalue subs
616
617 C<AUTOLOAD> routines used to take precedence over the actual sub being
618 called (i.e., when autoloading wasn't needed), for sub calls in lvalue or
619 potential lvalue context, if the subroutine was not visible at compile
620 time.
621
622 =item * C<caller> and tied C<@DB::args>
623
624 C<caller> sets C<@DB::args> to the subroutine arguments when called from
625 the DB package.  It used to crash when doing so if C<@DB::args> happened to
626 be tied.  Now it croaks instead.
627
628 =item * Tying C<@_>
629
630 Under debugging builds, this code:
631
632   sub TIEARRAY{bless[]}
633   sub {
634     tie @_, "";
635     \@_;
636   }->(1);
637
638 use to produce an "av_reify called on tied array" warning.  It doesn't any
639 more.
640
641 =item * Unrecognised switches on C<#!> line
642
643 If a switch, such as B<-x>, that cannot occur on the C<#!> line is used
644 there, perl dies with "Can’t emulate...".
645
646 It used to produce the same message for switches that perl did not
647 recognise at all, whether on the command line or the C<#!> line.
648
649 Now it produces the "Unrecognized switch" error message [perl #104288].
650
651 =item * C<system> and SIGCHLD
652
653 C<system> now temporarily blocks the SIGCHLD signal handler, to prevent the
654 signal handler from stealing the exit status [perl #105700].
655
656 =item * Deleting methods via C<delete>
657
658 Deletion of methods via C<delete $Class::{method}> syntax used to update
659 method caches if called in void context, but not scalar or list context.
660 Now it always updates those caches.
661
662 =item * Hash element deletion and destructors
663
664 When hash elements are deleted in void context, the internal hash entry is
665 now freed before the value is freed, to prevent destructors call by that
666 latter freeing from seeing the hash in an inconsistent state.  It was
667 possible to cause double-frees if the destructor freed the hash itself
668 [perl #100340].
669
670 =item * C<(s)printf>'s %n formatting code
671
672 The %n formatting code, which causes the number of characters to be
673 assigned to the next argument to C<printf> or C<sprintf> now actually
674 assigns the number of characters, instead of the number of bytes.
675
676 It also works now with special lvalue functions like C<substr> and with
677 nonexistent hash and array elements [perl #103492].
678
679 =item * Typeglobs and threads
680
681 Typeglobs returned from threads are no longer cloned if the parent thread
682 already has a glob with the same name.  This means that returned
683 subroutines will now assign to the right package variables [perl #107366].
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.6..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