This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta for =>
[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.19.2
9
10 =head1 DESCRIPTION
11
12 This document describes differences between the 5.19.1 release and the 5.19.2
13 release.
14
15 If you are upgrading from an earlier release such as 5.19.0, first read
16 L<perl5191delta>, which describes differences between 5.19.0 and 5.19.1.
17
18 =head1 Notice
19
20 XXX Any important notices here
21
22 =head1 Core Enhancements
23
24 XXX New core language features go here.  Summarize user-visible core language
25 enhancements.  Particularly prominent performance optimisations could go
26 here, but most should go in the L</Performance Enhancements> section.
27
28 =head2 More consistent prototype parsing
29
30 Multiple semicolons in subroutine prototypes have long been tolerated and
31 treated as a single semicolon.  There was one case where this did not
32 happen.  A subroutine whose prototype begins with "*" or ";*" can affect
33 whether a bareword is considered a method name or sub call.  This now
34 applies also to ";;;*".
35
36 Whitespace has long been allowed inside subroutine prototypes, so
37 C<sub( $ $ )> is equivalent to C<sub($$)>.  But it was stripped when the
38 subroutine was parse.  Hence, whitespace was I<not> allowed in prototypes
39 set by C<Scalar::Util::set_prototype>.  Now it is permitted, and the parser
40 no longer strips whitespace.  This means C<prototype &mysub> returns the
41 original prototype, whitespace and all.
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
65 =head2 Module removals
66
67 XXX Remove this section if inapplicable.
68
69 The following modules will be removed from the core distribution in a
70 future release, and will at that time need to be installed from CPAN.
71 Distributions on CPAN which require these modules will need to list them as
72 prerequisites.
73
74 The core versions of these modules will now issue C<"deprecated">-category
75 warnings to alert you to this fact.  To silence these deprecation warnings,
76 install the modules in question from CPAN.
77
78 Note that these are (with rare exceptions) fine modules that you are encouraged
79 to continue to use.  Their disinclusion from core primarily hinges on their
80 necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
81 not usually on concerns over their design.
82
83 =over
84
85 XXX Note that deprecated modules should be listed here even if they are listed
86 as an updated module in the L</Modules and Pragmata> section.
87
88 =back
89
90 [ List each other deprecation as a =head2 entry ]
91
92 =head1 Performance Enhancements
93
94 XXX Changes which enhance performance without changing behaviour go here.
95 There may well be none in a stable release.
96
97 [ List each enhancement as a =item entry ]
98
99 =over 4
100
101 =item *
102
103 XXX
104
105 =back
106
107 =head1 Modules and Pragmata
108
109 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
110 go here.  If Module::CoreList is updated, generate an initial draft of the
111 following sections using F<Porting/corelist-perldelta.pl>, which prints stub
112 entries to STDOUT.  Results can be pasted in place of the '=head2' entries
113 below.  A paragraph summary for important changes should then be added by hand.
114 In an ideal world, dual-life modules would have a F<Changes> file that could be
115 cribbed.
116
117 [ Within each section, list entries as a =item entry ]
118
119 =head2 New Modules and Pragmata
120
121 =over 4
122
123 =item *
124
125 XXX
126
127 =back
128
129 =head2 Updated Modules and Pragmata
130
131 =over 4
132
133 =item *
134
135 L<ExtUtils::Embed> has been upgraded from version 1.30 to 1.31
136
137 The generated C<C> code now incorporates bug fixes present in
138 F<miniperlmain.c>, and has whitespace changes. It now uses
139 C<#include "..."> for header files instead of C<< #include <...> >>.
140 This should not make any difference, unless programs embedding C<libperl>
141 happen to have local and incompatible files named F<EXTERN.h>, F<XSUB.h> or
142 F<perl.h>, as these will now be picked up instead of the installed Perl
143 headers.
144
145 The C<canon()> function now correctly handles packages with multiple C<::>
146 separators when the I<$as> parameter is not I</>. Given that it used to
147 generate strings which would likely be syntax errors or pathnames instead of
148 filenames, we infer that from the complete lack of bug reports no-one was
149 using this functionality. (C<ExtUtils::Miniperl> is now using it.)
150
151 =item *
152
153 L<ExtUtils::Miniperl> has been upgraded and given a version of 1.
154 Previously it did not have a version number.
155
156 C<writemain()> now takes an optional first argument. A reference to a scalar
157 is treated as a filename to be opened and written to. Any other reference is
158 used as the filehandle to write to. Otherwise the existing default remains,
159 to write to C<STDOUT>.
160
161 C<writemain()> has been refactored to use functions from L<ExtUtils::Embed>,
162 reducing code size and duplication. The internal function C<canon()> has been
163 deleted.
164
165 =item *
166
167 L<POSIX> has been upgraded from version 1.33 to 1.34.
168
169 C<POSIX::AUTOLOAD> will no longer infinitely recurse if the shared
170 object fails to load.
171
172 =item *
173
174 L<Storable> has been upgraded from version 2.43 to 2.44.
175
176 Calling C<STORABLE_attach> hooks no longer leaks memory. [perl #118829]
177
178 =back
179
180 =head2 Removed Modules and Pragmata
181
182 =over 4
183
184 =item *
185
186 XXX
187
188 =back
189
190 =head1 Documentation
191
192 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
193 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
194
195 =head2 New Documentation
196
197 XXX Changes which create B<new> files in F<pod/> go here.
198
199 =head3 L<XXX>
200
201 XXX Description of the purpose of the new file here
202
203 =head2 Changes to Existing Documentation
204
205 XXX Changes which significantly change existing files in F<pod/> go here.
206 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
207 section.
208
209 =head3 L<perlexperiment>
210
211 =over 4
212
213 =item *
214
215 Code in regular expressions, regular expression backtracking verbs,
216 and lvalue subroutines are no longer listed as experimental.  (This
217 also affects L<perlre> and L<perlsub>.)
218
219 =back
220
221 =head3 L<perlfunc>
222
223 =over 4
224
225 =item *
226
227 Since Perl v5.10, it has been possible for subroutines in @INC to return
228 a reference to a scalar holding initial source code to prepend to the file.
229 This is now documented.
230
231 =back
232
233 =head1 Diagnostics
234
235 The following additions or changes have been made to diagnostic output,
236 including warnings and fatal error messages.  For the complete list of
237 diagnostic messages, see L<perldiag>.
238
239 XXX New or changed warnings emitted by the core's C<C> code go here.  Also
240 include any changes in L<perldiag> that reconcile it to the C<C> code.
241
242 =head2 New Diagnostics
243
244 XXX Newly added diagnostic messages go under here, separated into New Errors
245 and New Warnings
246
247 =head3 New Errors
248
249 =over 4
250
251 =item *
252
253 XXX L<message|perldiag/"message">
254
255 =back
256
257 =head3 New Warnings
258
259 =over 4
260
261 =item *
262
263 L<Missing ']' in prototype for %s : %s|perldiag/"Missing ']' in prototype
264 for %s : %s">
265
266 (W illegalproto) A grouping was started with C<[> but never closed with
267 C<]>.
268
269 =back
270
271 =head2 Changes to Existing Diagnostics
272
273 XXX Changes (i.e. rewording) of diagnostic messages go here
274
275 =over 4
276
277 =item *
278
279 Under rare circumstances, one could get a "Can't coerce readonly REF to
280 string" instead of the customary "Modification of a read-only value".  This
281 alternate error message has been removed.
282
283 =item *
284
285 "Ambiguous use of * resolved as operator *": This and similar warnings
286 about "%" and "&" used to occur in some circumstances where there was no
287 operator of the type cited, so the warning was completely wrong.  This has
288 been fixed [perl #117535, #76910].
289
290 =item *
291
292 Warnings about malformed subroutine prototypes are now more consistent in
293 how the prototypes are rendered.  Some of these warnings would truncate
294 prototypes containing nulls.  In other cases one warning would suppress
295 another.  The warning about illegal characters in prototypes no longer says
296 "after '_'" if the bad character came before the underscore.
297
298 =item *
299
300 L<Perl folding rules are not up-to-date for 0x%X; please use the perlbug
301 utility to report; in regex; marked by <-- HERE in
302 mE<sol>%sE<sol>|perldiag/"Perl folding rules are not up-to-date for 0x%X;
303 please use the perlbug utility to report; in regex; marked by <-- HERE in
304 m/%s/">
305
306 This message is now only in the regexp category, and not in the deprecated
307 category.  It is still a default (i.e., severe) warning [perl #89648].
308
309 =item *
310
311 The debugger's "n" command now respects lvalue subroutines and steps over
312 them [perl #118839].
313
314 =back
315
316 =head1 Utility Changes
317
318 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
319 Most of these are built within the directories F<utils> and F<x2p>.
320
321 [ List utility changes as a =head3 entry for each utility and =item
322 entries for each change
323 Use L<XXX> with program names to get proper documentation linking. ]
324
325 =head3 L<XXX>
326
327 =over 4
328
329 =item *
330
331 XXX
332
333 =back
334
335 =head1 Configuration and Compilation
336
337 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
338 go here.  Any other changes to the Perl build process should be listed here.
339 However, any platform-specific changes should be listed in the
340 L</Platform Support> section, instead.
341
342 [ List changes as a =item entry ].
343
344 =over 4
345
346 =item *
347
348 F<installperl> and F<installman>'s option handling has been refactored to use
349 L<Getopt::Long>. Both are used by the F<Makefile> C<install> targets, and
350 are not installed, so these changes are only likely to affect custom
351 installation scripts.
352
353 =over 4
354
355 =item *
356
357 single letter options now also have long names
358
359 =item *
360
361 invalid options are now rejected
362
363 =item *
364
365 command line arguments that are not options are now rejected
366
367 =item *
368
369 Each now has a C<--help> option to display the usage message.
370
371 =back
372
373 The behaviour for all valid documented invocations is unchanged.
374
375 =back
376
377 =head1 Testing
378
379 XXX Any significant changes to the testing of a freshly built perl should be
380 listed here.  Changes which create B<new> files in F<t/> go here as do any
381 large changes to the testing harness (e.g. when parallel testing was added).
382 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
383 that they represent may be covered elsewhere.
384
385 [ List each test improvement as a =item entry ]
386
387 =over 4
388
389 =item *
390
391 XXX
392
393 =back
394
395 =head1 Platform Support
396
397 XXX Any changes to platform support should be listed in the sections below.
398
399 [ Within the sections, list each platform as a =item entry with specific
400 changes as paragraphs below it. ]
401
402 =head2 New Platforms
403
404 XXX List any platforms that this version of perl compiles on, that previous
405 versions did not.  These will either be enabled by new files in the F<hints/>
406 directories, or new subdirectories and F<README> files at the top level of the
407 source tree.
408
409 =over 4
410
411 =item XXX-some-platform
412
413 XXX
414
415 =back
416
417 =head2 Discontinued Platforms
418
419 XXX List any platforms that this version of perl no longer compiles on.
420
421 =over 4
422
423 =item XXX-some-platform
424
425 XXX
426
427 =back
428
429 =head2 Platform-Specific Notes
430
431 XXX List any changes for specific platforms.  This could include configuration
432 and compilation changes or changes in portability/compatibility.  However,
433 changes within modules for platforms should generally be listed in the
434 L</Modules and Pragmata> section.
435
436 =over 4
437
438 =item MidnightBSD
439
440 C<objformat> was removed from version 0.4-RELEASE of MidnightBSD and had been
441 deprecated on earlier versions.  This caused the build environment to be
442 erroneously configured for C<a.out> rather than C<elf>.  This has been now
443 been corrected.
444
445 =back
446
447 =head1 Internal Changes
448
449 XXX Changes which affect the interface available to C<XS> code go here.  Other
450 significant internal changes for future core maintainers should be noted as
451 well.
452
453 [ List each change as a =item entry ]
454
455 =over 4
456
457 =item *
458
459 The Makefile shortcut targets for many rarely (or never) used testing and
460 profiling targets have been removed, or merged into the only other Makefile
461 target that uses them.  Specifically, these targets are gone, along with
462 documentation that referenced them or explained how to use them:
463
464     check.third check.utf16 check.utf8 coretest minitest.prep
465     minitest.utf16 perl.config.dashg perl.config.dashpg
466     perl.config.gcov perl.gcov perl.gprof perl.gprof.config
467     perl.pixie perl.pixie.atom perl.pixie.config perl.pixie.irix
468     perl.third perl.third.config perl.valgrind.config purecovperl
469     pureperl quantperl test.deparse test.taintwarn test.third
470     test.torture test.utf16 test.utf8 test_notty.deparse
471     test_notty.third test_notty.valgrind test_prep.third
472     test_prep.valgrind torturetest ucheck ucheck.third ucheck.utf16
473     ucheck.valgrind utest utest.third utest.utf16 utest.valgrind
474
475 It's still possible to run the relevant commands by "hand" - no underlying
476 functionality has been removed.
477
478 =item *
479
480 It is now possible to keep Perl from initializing locale handling.
481 For the most part, Perl doesn't pay attention to locale.  (See
482 L<perllocale>.)  Nonetheless, until now, on startup, it has always
483 initialized locale handling to the system default, just in case the
484 program being executed ends up using locales.  (This is one of the first
485 things a locale-aware program should do, long before Perl knows if it
486 will actually be needed or not.)  This works well except when Perl is
487 embedded in another application which wants a locale that isn't the
488 system default.  Now, if the environment variable
489 C<PERL_SKIP_LOCALE_INIT> is set at the time Perl is started, this
490 initialization step is skipped.  Prior to this, on Windows platforms,
491 the only workaround for this deficiency was to use a hacked-up copy of
492 internal Perl code.  Applications that need to use older Perls can
493 discover if the embedded Perl they are using needs the workaround by
494 testing that the C preprocessor symbol C<HAS_SKIP_LOCALE_INIT> is not
495 defined.  (RT #38193)
496
497 =item *
498
499 C<BmRARE> and C<BmPREVIOUS> have been removed.  They were not used anywhere
500 and are not part of the API.  For XS modules, they are now #defined as 0.
501
502 =item *
503
504 C<sv_force_normal>, which usually croaks on read-only values, used to allow
505 read-only values to be modified at compile time.  This has been changed to
506 croak on read-only values regardless.  This change uncovered several core
507 bugs.
508
509 =back
510
511 =head1 Selected Bug Fixes
512
513 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
514 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
515
516 [ List each fix as a =item entry ]
517
518 =over 4
519
520 =item *
521
522 There have been several fixes related to Perl's handling of locales.  perl
523 #38193 was described above in L</Internal Changes>.
524 Also fixed is #112208 in which the error string in C<$!> displayed as
525 garbage in many UTF-8 locales;
526 #118197, where the radix (decimal point) character had to be an ASCII
527 character (which doesn't work for some non-Western languages);
528 and #115808, in which C<POSIX::setlocale()> on failure returned an
529 C<undef> which didn't warn about not being defined even if those
530 warnings were enabled.
531
532 =item *
533
534 The dtrace sub-entry probe now works with lexical subs, instead of
535 crashing [perl #118305].
536
537 =item *
538
539 Compiling a C<split> operator whose third argument is a named constant
540 evaulating to 0 no longer causes the constant's value to change.
541
542 =item *
543
544 A named constant used as the second argument to C<index> no longer gets
545 coerced to a string if it is a reference, regular expression, dualvar, etc.
546
547 =item *
548
549 A named constant evaluating to the undefined value used as the second
550 argument to C<index> no longer produces "uninitialized" warnings at compile
551 time.  It will still produce them at run time.
552
553 =item *
554
555 When a scalar was returned from a subroutine in @INC, the referenced scalar
556 was magically converted into an IO thingy, possibly resulting in "Bizarre
557 copy" errors if that scalar continued to be used elsewhere.  Now Perl uses
558 an internal copy of the scalar instead.
559
560 =item *
561
562 Undefining an inlinable lexical subroutine (C<my sub foo() { 42 } undef
563 &foo>) would result in a crash if warnings were turned on.
564
565 =item *
566
567 Certain uses of the C<sort> operator are optimised to modify an array in
568 place, such as C<@a = sort @a>.  During the sorting, the array is made
569 read-only.  If a sort block should happen to die, then the array remained
570 read-only even outside the C<sort>.  This has been fixed.
571
572 =item *
573
574 C<$a> and C<$b> inside a sort block are aliased to the actual arguments to
575 C<sort>, so they can be modified through those two variables.  This did not
576 always work, e.g., for lvalue subs and C<$#ary>, and probably many other
577 operators.  It works now.
578
579 =item *
580
581 The arguments to C<sort> are now all in list context.  If the C<sort>
582 itself were called in void or scalar context, then I<some>, but not all, of
583 the arguments used to be in void or scalar context.
584
585 =item *
586
587 Subroutine prototypes with Unicode characters above U+00FF were getting
588 mangled during closure cloning.  This would happen with subroutines closing
589 over lexical variables declared outside, and with lexical subs.
590
591 =item *
592
593 In regular expressions containing multiple code blocks, the values of
594 C<$1>, C<$2>, etc., set by nested regular expression calls would leak from
595 one block to the next.  Now these variables always refer to the outer
596 regular expression at the start of an embedded block [perl #117917].
597
598 =item *
599
600 C<UNIVERSAL::can> now treats its first argument the same way that method
601 calls do: Typeglobs and glob references with non-empty IO slots are treated
602 as handles, and strings are treated as filehandles, rather than packages,
603 if a handle with that name exists [perl #113932].
604
605 =item *
606
607 Method calls on typeglobs (e.g., C<< *ARGV->getline >>) used to stringify
608 the typeglob and then look it up again.  Combined with changes in Perl
609 5.18.0, this allowed C<< *foo->bar >> to call methods on the "foo" package
610 (like C<< foo->bar >>).  In some cases it could cause the method to be
611 called on the wrong handle.  Now a typeglob argument is treated as a
612 handle (just like C<< (\*foo)->bar >>), or, if its IO slot is empty, an
613 error is raised.
614
615 =item *
616
617 Under copy-on-write builds (the default as of 5.19.1) C<${'_<-e'}[0]> no
618 longer gets mangled.  This is the first line of input saved for the
619 debugger's use for one-liners [perl #118627].
620
621 =item *
622
623 Assigning a vstring to a tied variable or to a subroutine argument aliased
624 to a nonexistent hash or array element now works, without flattening the
625 vstring into a regular string.
626
627 =item *
628
629 C<pos>, C<tie>, C<tied> and C<untie> did not work
630 properly on subroutine arguments aliased to nonexistent
631 hash and array elements [perl #77814, #27010].
632
633 =item *
634
635 The C<< => >> fat arrow operator can now quote built-in keywords even if it
636 occurs on the next line, making it consistent with how it treats other
637 barewords.
638
639 =back
640
641 =head1 Known Problems
642
643 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
644 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
645 platform specific bugs also go here.
646
647 [ List each fix as a =item entry ]
648
649 =over 4
650
651 =item *
652
653 XXX
654
655 =back
656
657 =head1 Obituary
658
659 XXX If any significant core contributor has died, we've added a short obituary
660 here.
661
662 =head1 Acknowledgements
663
664 XXX Generate this with:
665
666   perl Porting/acknowledgements.pl v5.19.1..HEAD
667
668 =head1 Reporting Bugs
669
670 If you find what you think is a bug, you might check the articles recently
671 posted to the comp.lang.perl.misc newsgroup and the perl bug database at
672 http://rt.perl.org/perlbug/ .  There may also be information at
673 http://www.perl.org/ , the Perl Home Page.
674
675 If you believe you have an unreported bug, please run the L<perlbug> program
676 included with your release.  Be sure to trim your bug down to a tiny but
677 sufficient test case.  Your bug report, along with the output of C<perl -V>,
678 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
679
680 If the bug you are reporting has security implications, which make it
681 inappropriate to send to a publicly archived mailing list, then please send it
682 to perl5-security-report@perl.org.  This points to a closed subscription
683 unarchived mailing list, which includes all the core committers, who will be
684 able to help assess the impact of issues, figure out a resolution, and help
685 co-ordinate the release of patches to mitigate or fix the problem across all
686 platforms on which Perl is supported.  Please only use this address for
687 security issues in the Perl core, not for modules independently distributed on
688 CPAN.
689
690 =head1 SEE ALSO
691
692 The F<Changes> file for an explanation of how to view exhaustive details on
693 what changed.
694
695 The F<INSTALL> file for how to build Perl.
696
697 The F<README> file for general stuff.
698
699 The F<Artistic> and F<Copying> files for copyright information.
700
701 =cut