This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta - Fill in one more item and add currently remaining possible TODOs
[perl5.git] / pod / perldelta.pod
1 =encoding utf8
2
3 =for comment
4 To do:
5 df8c7dee Fix segfault in filehandle duplication
6 b66f3475 Fix PerlIO_get_cnt and friends
7 9cefd268 [perl #118747] Allow in-place s///g when !!PL_sawampersand
8 e94bb470 install useful Regexp::CARP_TRACE from Carp
9 88e3936f Fix processing of PERL_ENV_TABLES
10 9d32676e [perl #117265] fix various problems with safesyscalls
11 9c7618be regcomp.c: Use Perl_form() instead of buggy sprintf
12 c04e4151 op.c:leave_scope: use mg_free before sv_force_normal [#119295]
13 650b1534 Make B::OP::slabbed, folded, etc. actually work
14 531d75b0 [perl #89502]: Add support for Atari FreeMiNT platform
15 acb34050 [perl #119501] \(1+2) always referencing the same sv
16
17 =head1 NAME
18
19 [ this is a template for a new perldelta file.  Any text flagged as XXX needs
20 to be processed before release. ]
21
22 perldelta - what is new for perl v5.19.4
23
24 =head1 DESCRIPTION
25
26 This document describes differences between the 5.19.3 release and the 5.19.4
27 release.
28
29 If you are upgrading from an earlier release such as 5.19.2, first read
30 L<perl5193delta>, which describes differences between 5.19.2 and 5.19.3.
31
32 =head1 Notice
33
34 XXX Any important notices here
35
36 =head1 Core Enhancements
37
38 XXX New core language features go here.  Summarize user-visible core language
39 enhancements.  Particularly prominent performance optimisations could go
40 here, but most should go in the L</Performance Enhancements> section.
41
42 [ List each enhancement as a =head2 entry ]
43
44 =head2 C<rand> now uses a consistent random number generator
45
46 Previously perl would use a platform specific random number generator, varying
47 between the libc rand(), random() or drand48().
48
49 This meant that the quality of perl's random numbers would vary from platform
50 to platform, from the 15 bits of rand() on Windows to 48-bits on POSIX
51 platforms such as Linux with drand48().
52
53 Perl now uses its own internal drand48() implementation on all platforms.  This
54 does not make perl's C<rand> cryptographically secure.  [perl #115928]
55
56 =head2 Better 64-bit support
57
58 On 64-bit platforms, the internal array functions now use 64-bit offsets,
59 allowing Perl arrays to hold more than 2**31 elements, if you have the memory
60 available.
61
62 The regular expression engine now supports strings longer than 2**31
63 characters.  [perl #112790, #116907]
64
65 =head2 New slice syntax
66
67 The new C<%hash{...}> and C<@array[...]> syntax returns a list of key/value (or
68 index/value) pairs.
69
70 =head2 EBCDIC support
71
72 Core Perl now mostly works on EBCDIC platforms.   This is not true of
73 many modules, including some which are shipped with this release.  If
74 you have resources to help continue this process, including test
75 machines, send email to L<mailto:perl-mvs@perl.org>.
76
77 As a result of this, certain C<XS> functions are now deprecated; see
78 L</Internal Changes>.
79
80 =head1 Security
81
82 XXX Any security-related notices go here.  In particular, any security
83 vulnerabilities closed should be noted here rather than in the
84 L</Selected Bug Fixes> section.
85
86 [ List each security issue as a =head2 entry ]
87
88 =head1 Incompatible Changes
89
90 =head2 Locale decimal point character no longer leaks outside of
91 S<C<use locale>> scope (with the exception of $!)
92
93 This is actually a bug fix, but some code has come to rely on the bug being
94 present, so this change is listed here.  The current locale that the program is
95 running under is not supposed to be visible to Perl code except within the
96 scope of a S<C<use locale>>.  However, until now under certain circumstances,
97 the character used for a decimal point (often a comma) leaked outside the
98 scope.
99
100 This continues the work released in Perl 5.19.1.  It turns out that that did
101 not catch all the leaks, including C<printf> and C<sprintf> not respecting
102 S<C<use locale>>.  If your code is affected by this change, simply add a
103 S<C<use locale>>.
104
105 Now, the only known place where S<C<use locale>> is not respected is in the
106 stringification of L<$!|perlvar/$!>.
107
108 =head2 Assignments of Windows sockets error codes to $! now prefer F<errno.h> values over WSAGetLastError() values
109
110 In previous versions of Perl, Windows sockets error codes as returned by
111 WSAGetLastError() were assigned to $!, and some constants such as ECONNABORTED,
112 not in F<errno.h> in VC++ (or the various Windows ports of gcc) were defined to
113 corresponding WSAE* values to allow $! to be tested against the E* constants
114 exported by L<Errno> and L<POSIX>.
115
116 This worked well until VC++ 2010 and later, which introduced new E* constants
117 with values E<gt> 100 into F<errno.h>, including some being (re)defined by perl
118 to WSAE* values.  That caused problems when linking XS code against other
119 libraries which used the original definitions of F<errno.h> constants.
120
121 To avoid this incompatibility, perl now maps WSAE* error codes to E* values
122 where possible, and assigns those values to $!.  The E* constants exported by
123 L<Errno> and L<POSIX> are updated to match so that testing $! against them,
124 wherever previously possible, will continue to work as expected, and all E*
125 constants found in F<errno.h> are now exported from those modules with their
126 original F<errno.h> values
127
128 In order to avoid breakage in existing Perl code which assigns WSAE* values to
129 $!, perl now intercepts the assignment and performs the same mapping to E*
130 values as it uses internally when assigning to $! itself.
131
132 However, one backwards-incompatibility remains: existing Perl code which
133 compares $! against the numeric values of the WSAE* error codes that were
134 previously assigned to $! will now be broken in those cases where a
135 corresponding E* value has been assigned instead.  This is only an issue for
136 those E* values E<lt> 100, which were always exported from L<Errno> and
137 L<POSIX> with their original F<errno.h> values, and therefore could not be used
138 for WSAE* error code tests (e.g. WSAEINVAL is 10022, but the corresponding
139 EINVAL is 22).  (E* values E<gt> 100, if present, were redefined to WSAE*
140 values anyway, so compatibility can be achieved by using the E* constants,
141 which will work both before and after this change, albeit using different
142 numeric values under the hood.)
143
144 =head1 Deprecations
145
146 XXX Any deprecated features, syntax, modules etc. should be listed here.
147
148 =head2 Module removals
149
150 XXX Remove this section if inapplicable.
151
152 The following modules will be removed from the core distribution in a
153 future release, and will at that time need to be installed from CPAN.
154 Distributions on CPAN which require these modules will need to list them as
155 prerequisites.
156
157 The core versions of these modules will now issue C<"deprecated">-category
158 warnings to alert you to this fact.  To silence these deprecation warnings,
159 install the modules in question from CPAN.
160
161 Note that these are (with rare exceptions) fine modules that you are encouraged
162 to continue to use.  Their disinclusion from core primarily hinges on their
163 necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
164 not usually on concerns over their design.
165
166 =over
167
168 XXX Note that deprecated modules should be listed here even if they are listed
169 as an updated module in the L</Modules and Pragmata> section.
170
171 =back
172
173 [ List each other deprecation as a =head2 entry ]
174
175 =head1 Performance Enhancements
176
177 =over 4
178
179 =item *
180
181 The trie performance enhancement for regular expressions has now been extended
182 to those compiled under C</iaa>.
183
184 =back
185
186 =head1 Modules and Pragmata
187
188 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
189 go here.  If Module::CoreList is updated, generate an initial draft of the
190 following sections using F<Porting/corelist-perldelta.pl>, which prints stub
191 entries to STDOUT.  Results can be pasted in place of the '=head2' entries
192 below.  A paragraph summary for important changes should then be added by hand.
193 In an ideal world, dual-life modules would have a F<Changes> file that could be
194 cribbed.
195
196 [ Within each section, list entries as a =item entry ]
197
198 =head2 New Modules and Pragmata
199
200 =over 4
201
202 =item *
203
204 XXX
205
206 =back
207
208 =head2 Updated Modules and Pragmata
209
210 =over 4
211
212 =item *
213
214 L<autodie> has been upgraded from version 2.20 to 2.21.
215
216 Numerous improvements have been made, many speed-related.  See the F<Changes>
217 file in the CPAN distribution for full details.
218
219 =item *
220
221 L<B> has been upgraded from version 1.45 to 1.46.
222
223 The fix for [perl #118525] introduced a regression in the behaviour of
224 C<B::CV::GV>, changing the return value from a C<B::SPECIAL> object on a
225 C<NULL> C<CvGV> to C<undef>.  C<B::CV::GV> again returns a C<B::SPECIAL> object
226 in this case.  [perl #119351]
227
228 =item *
229
230 L<B::Concise> has been upgraded from version 0.98 to 0.99.
231
232 The handling of the C<glob> operator, broken since Perl 5.17.6, has been fixed
233 and handling of the new kvaslice and kvhslice operators have been added.
234
235 =item *
236
237 L<B::Deparse> has been upgraded from version 1.22 to 1.23.
238
239 The new kvaslice and kvhslice operators have been added.
240
241 =item *
242
243 L<Carp> has been upgraded from version 1.31 to 1.32.
244
245 =over 4
246
247 =item *
248
249 In stack traces, subroutine arguments that are strings are now quoted in a
250 consistent manner, regardless of what characters they contain and how they're
251 internally represented.
252
253 =item *
254
255 C<Carp> now takes care not to clobber the status variables $! and $^E.
256
257 =item *
258
259 C<Carp> now won't vivify the C<overload::StrVal> glob or subroutine or the
260 C<overload> stash.
261
262 =item *
263
264 C<Carp> now avoids some unwanted Unicode warnings on older Perls.  This doesn't
265 affect behaviour with current Perls.
266
267 =item *
268
269 C<Carp::Heavy> detects version mismatch with C<Carp>, to give a good error
270 message if a current (stub) C<Carp::Heavy> gets loaded by an old C<Carp> that
271 expects C<Carp::Heavy> to provide subroutines.
272
273 =back
274
275 =item *
276
277 L<charnames> has been upgraded from version 1.38 to 1.39.
278
279 This module now works on EBCDIC platforms.
280
281 =item *
282
283 L<CPAN> has been upgraded from version 2.00 to 2.03-TRIAL.
284
285 Numerous updates and bug fixes are incorporated.  See the F<Changes> file for
286 full details.
287
288 =item *
289
290 L<CPAN::Meta> has been upgraded from version 2.132140 to 2.132510.
291
292 No changes have been made to the installed code other than the version bump to
293 keep in sync with the latest CPAN release.
294
295 =item *
296
297 L<CPAN::Meta::Requirements> has been upgraded from version 2.122 to 2.123.
298
299 No changes have been made to the installed code other than the version bump to
300 keep in sync with the latest CPAN release.
301
302 =item *
303
304 L<Data::Dumper> has been upgraded from version 2.148 to 2.149.
305
306 This upgrade is part of a larger change to make the array interface 64-bit safe
307 by using SSize_t instead of I32 for array indices.
308
309 In addition, an EBCDIC fix has been applied.
310
311 =item *
312
313 L<Devel::Peek> has been upgraded from version 1.13 to 1.14.
314
315 This upgrade is part of a larger change to preserve referential identity when
316 passing C<undef> to a subroutine by using NULL rather than &PL_sv_undef for
317 nonexistent array elements.
318
319 In addition, C<Dump> with no args was broken in Perl 5.19.3, but has now been
320 fixed.
321
322 =item *
323
324 L<DynaLoader> has been upgraded from version 1.19 to 1.20.
325
326 The documentation now makes it clear, as has always been the case, that
327 C<dl_unload_file> is only called automatically to unload all loaded shared
328 objects if the perl interpreter was built with the C macro
329 DL_UNLOAD_ALL_AT_EXIT defined.  Support for GNU DLD has also been removed.
330
331 =item *
332
333 L<Encode> has been upgraded from version 2.52 to 2.55.
334
335 An erroneous early return in C<decode_utf8> has been removed, and a bug in
336 C<_utf8_on> under COW has been fixed.  Encode also now uses L<parent> rather
337 than L<base> throughout.
338
339 =item *
340
341 L<Errno> has been upgraded from version 1.19 to 1.20.
342
343 The list of E* constants exported on Windows has been updated to reflect the
344 changes made in the assignment of sockets error codes to $! (see
345 L</Incompatible Changes>).
346
347 =item *
348
349 L<Exporter> has been upgraded from version 5.69 to 5.70.
350
351 A number of typos have been corrected in the documentation.
352
353 =item *
354
355 L<ExtUtils::CBuilder> has been upgraded from version 0.280205 to 0.280212.
356
357 No changes have been made to the installed code other than the version bump to
358 keep in sync with the latest CPAN release.
359
360 =item *
361
362 L<ExtUtils::Command> has been upgraded from version 1.17 to 1.18.
363
364 No changes have been made to the installed code other than the version bump to
365 keep in sync with the latest CPAN release.
366
367 =item *
368
369 L<ExtUtils::MakeMaker> has been upgraded from version 6.72 to 6.76.
370
371 Numerous updates and bug fixes are incorporated.  See the F<Changes> file for
372 full details.
373
374 =item *
375
376 L<ExtUtils::ParseXS> has been upgraded from version 3.21 to 3.23.
377
378 Unquoted "here-doc" markers for typemaps can now be optionally followed by a
379 semicolon, just like quoted markers.  [perl #119761]
380
381 =item *
382
383 L<File::Find> has been upgraded from version 1.24 to 1.25.
384
385 Better diagnostics are now provided in the case of a failed C<chdir>.
386
387 =item *
388
389 L<File::Glob> has been upgraded from version 1.20 to 1.21.
390
391 C<glob> now warns in the context of C<use warnings "syscalls";> if the supplied
392 pattern has an internal NUL (C<"\0">) character.
393
394 =item *
395
396 L<FileCache> has been upgraded from version 1.08 to 1.09.
397
398 This upgrade is part of a larger change to use L<parent> rather than L<base>.
399
400 =item *
401
402 L<Hash::Util::FieldHash> has been upgraded from version 1.12 to 1.13.
403
404 This upgrade is part of a larger change to use L<parent> rather than L<base>.
405
406 =item *
407
408 L<HTTP::Tiny> has been upgraded from version 0.034 to 0.035.
409
410 Encoded data from C<post_form> now preserves term order if data is provided as
411 an array reference.  (They are still sorted for consistency if provided as a
412 hash reference.)
413
414 =item *
415
416 L<I18N::LangTags> has been upgraded from version 0.39 to 0.40.
417
418 Bosnian has now joined Croatian and Serbian in the lists of mutually
419 intelligible Slavic languages.  [perl #72594]
420
421 =item *
422
423 L<IO> has been upgraded from version 1.28 to 1.29.
424
425 A minor internals-only change has been made to the XS code.
426
427 =item *
428
429 L<IPC::Open3> has been upgraded from version 1.15 to 1.16.
430
431 This upgrade is part of a larger change to preserve referential identity when
432 passing C<undef> to a subroutine by using NULL rather than &PL_sv_undef for
433 nonexistent array elements.
434
435 =item *
436
437 L<Locale::Codes> has been upgraded from version 3.26 to 3.27.
438
439 New codes have been added and the (deprecated) set of FIPS-10 country codes has
440 been removed.
441
442 =item *
443
444 L<Math::BigInt> has been upgraded from version 1.9992 to 1.9993.
445
446 Cleaned up the L<Math::BigInt> and L<Math::BigFloat> documentation to be more
447 consistent with other Perl documentation.  [perl #86686]
448
449 Added a C<bint> method for rounding towards zero.  [perl #85296]
450
451 =item *
452
453 L<Math::BigInt::FastCalc> has been upgraded from version 0.30 to 0.31.
454
455 This upgrade is part of a larger change to make the array interface 64-bit safe
456 by using SSize_t instead of I32 for array indices.
457
458 =item *
459
460 L<Module::CoreList> has been upgraded from version 2.97 to 2.98.
461
462 The list of Perl versions covered has been updated.
463
464 =item *
465
466 L<Module::Load::Conditional> has been upgraded from version 0.54 to 0.58.
467
468 C<requires> has been made more robust.  [cpan #83728]
469
470 =item *
471
472 L<Module::Metadata> has been upgraded from version 1.000014 to 1.000018.
473
474 The module's DESCRIPTION has been re-worded regarding safety/security to
475 satisfy CVE-2013-1437.  Also, versions are now detainted if needed.  [cpan
476 #88576]
477
478 =item *
479
480 L<mro> has been upgraded from version 1.13 to 1.14.
481
482 This upgrade is part of a larger change to make the array interface 64-bit safe
483 by using SSize_t instead of I32 for array indices.
484
485 =item *
486
487 L<Opcode> has been upgraded from version 1.25 to 1.26.
488
489 The new kvaslice and kvhslice operators have been added.
490
491 =item *
492
493 L<parent> has been upgraded from version 0.226 to 0.227.
494
495 No changes have been made to the installed code other than the version bump to
496 keep in sync with the latest CPAN release.
497
498 =item *
499
500 L<Parse::CPAN::Meta> has been upgraded from version 1.4405 to 1.4407.
501
502 No changes have been made to the installed code other than the version bump to
503 keep in sync with the latest CPAN release.
504
505 =item *
506
507 L<Perl::OSType> has been upgraded from version 1.003 to 1.005.
508
509 The Unix OSType 'bitrig' has been added.
510
511 =item *
512
513 L<perlfaq> has been upgraded from version 5.0150043 to 5.0150044.
514
515 The use of C<gensym> in a number of examples has been removed, the use of C<&>
516 in subroutine calls is now clarified and several new questions have been
517 answered.
518
519 =item *
520
521 L<Pod::Html> has been upgraded from version 1.20 to 1.21.
522
523 This upgrade is part of a larger change to use L<parent> rather than L<base>.
524
525 =item *
526
527 L<POSIX> has been upgraded from version 1.34 to 1.35.
528
529 The list of E* constants exported on Windows has been updated to reflect the
530 changes made in the assignment of sockets error codes to $! (see
531 L</Incompatible Changes>).
532
533 =item *
534
535 L<re> has been upgraded from version 0.25 to 0.26.
536
537 This upgrade is part of a larger change to support 64-bit string lengths in the
538 regular expression engine.
539
540 =item *
541
542 L<Scalar::Util> has been upgraded from version 1.31 to 1.32.
543
544 The documentation of C<blessed> has been improved to mention the fact that
545 package "0" is defined but false.
546
547 =item *
548
549 L<Socket> has been upgraded from version 2.011 to 2.012.
550
551 Syntax errors when building on the WinCE platform have been fixed.  [cpan
552 #87389]
553
554 =item *
555
556 L<Storable> has been upgraded from version 2.46 to 2.47.
557
558 This upgrade is part of a larger change to preserve referential identity when
559 passing C<undef> to a subroutine by using NULL rather than &PL_sv_undef for
560 nonexistent array elements.
561
562 =item *
563
564 L<Term::ReadLine> has been upgraded from version 1.10 to 1.14.
565
566 Term::ReadLine::EditLine support has been added.
567
568 =item *
569
570 L<Time::Piece> has been upgraded from version 1.22 to 1.23.
571
572 Day of year parsing (like "%y%j") has been fixed.
573
574 =item *
575
576 L<Unicode::Collate> has been upgraded from version 0.98 to 0.99.
577
578 By default, out-of-range values are replaced with C<U+FFFD> (REPLACEMENT
579 CHARACTER) when C<UCA_Version> E<gt>= 22, or ignored when C<UCA_Version> E<lt>=
580 20.  When C<UCA_Version> E<gt>= 22, the weights of out-of-range values can be
581 overridden.
582
583 =item *
584
585 L<Unicode::UCD> has been upgraded from version 0.53 to 0.54.
586
587 This module now works on EBCDIC platforms.
588
589 =item *
590
591 L<version> has been upgraded from version 0.9903 to 0.9904.
592
593 No changes have been made to the installed code other than the version bump to
594 keep in sync with the latest CPAN release.
595
596 =item *
597
598 L<warnings> has been upgraded from version 1.18 to 1.19.
599
600 The C<syscalls> warnings category has been added to check for embedded NUL
601 (C<"\0">) characters in pathnames and string arguments to other system calls.
602
603 =item *
604
605 L<XS::Typemap> has been upgraded from version 0.10 to 0.11.
606
607 This upgrade is part of the change to remove the uninitialized warnings
608 exemption for uninitialized values returned by XSUBs (see the L</Selected Bug
609 Fixes> section).
610
611 =back
612
613 =head2 Removed Modules and Pragmata
614
615 =over 4
616
617 =item *
618
619 XXX
620
621 =back
622
623 =head1 Documentation
624
625 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
626 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
627
628 =head2 New Documentation
629
630 =head3 L<perlrepository>
631
632 This document was removed (actually, renamed L<perlgit> and given a major
633 overhaul) in Perl 5.13.10, causing Perl documentation websites to show the now
634 out of date version in Perl 5.12 as the latest version.  It has now been
635 restored in stub form, directing readers to current information.
636
637 =head2 Changes to Existing Documentation
638
639 =head3 L<perldata>
640
641 =over 4
642
643 =item *
644
645 New sections have been added to document the new index/value array slice and
646 key/value hash slice syntax.
647
648 =back
649
650 =head3 L<perldebguts>
651
652 =over 4
653
654 =item *
655
656 The C<&DB::goto> and C<&DB::lsub> debugger subroutines are now documented.
657 [perl #77680]
658
659 =back
660
661 =head3 L<perlguts>
662
663 =over 4
664
665 =item *
666
667 Numerous minor changes have been made to reflect changes made to the perl
668 internals in this release.
669
670 =back
671
672 =head3 L<perlhack>
673
674 =over 4
675
676 =item *
677
678 The L<SUPER QUICK PATCH GUIDE|perlhack/SUPER QUICK PATCH GUIDE> section has
679 been updated.
680
681 =back
682
683 =head3 L<perlsub>
684
685 =over 4
686
687 =item *
688
689 A list of subroutine names used by the perl implementation is now included.
690 [perl #77680]
691
692 =back
693
694 =head1 Diagnostics
695
696 The following additions or changes have been made to diagnostic output,
697 including warnings and fatal error messages.  For the complete list of
698 diagnostic messages, see L<perldiag>.
699
700 XXX New or changed warnings emitted by the core's C<C> code go here.  Also
701 include any changes in L<perldiag> that reconcile it to the C<C> code.
702
703 =head2 New Diagnostics
704
705 XXX Newly added diagnostic messages go under here, separated into New Errors
706 and New Warnings
707
708 =head3 New Errors
709
710 =over 4
711
712 =item *
713
714 L<delete argument is indexE<sol>value array slice, use array slice|perldiag/"delete argument is index/value array slice, use array slice">
715
716 (F) You used index/value array slice syntax (C<%array[...]>) as the argument to
717 C<delete>.  You probably meant C<@array[...]> with an @ symbol instead.
718
719 =item *
720
721 L<delete argument is keyE<sol>value hash slice, use hash slice|perldiag/"delete argument is key/value hash slice, use hash slice">
722
723 (F) You used key/value hash slice syntax (C<%hash{...}>) as the argument to
724 C<delete>.  You probably meant C<@hash{...}> with an @ symbol instead.
725
726 =back
727
728 =head3 New Warnings
729
730 =over 4
731
732 =item *
733
734 L<Invalid \0 character in %s for %s: %s\0%s|perldiag/"Invalid \0 character in %s for %s: %s\0%s">
735
736 (W syscalls) Embedded \0 characters in pathnames or other system call arguments
737 produce a warning as of 5.20.  The parts after the \0 were formerly ignored by
738 system calls.
739
740 =item *
741
742 L<Possible precedence issue with control flow operator|perldiag/"Possible precedence issue with control flow operator">
743
744 (W syntax) There is a possible problem with the mixing of a control flow
745 operator (e.g. C<return>) and a low-precedence operator like C<or>.  Consider:
746
747     sub { return $a or $b; }
748
749 This is parsed as:
750
751     sub { (return $a) or $b; }
752
753 Which is effectively just:
754
755     sub { return $a; }
756
757 Either use parentheses or the high-precedence variant of the operator.
758
759 Note this may be also triggered for constructs like:
760
761     sub { 1 if die; }
762
763 =item *
764
765 L<Scalar value %%s[%s] better written as $%s[%s]|perldiag/"Scalar value %%s[%s] better written as $%s[%s]">
766
767 (W syntax) In scalar context, you've used an array index/value slice (indicated
768 by %) to select a single element of an array.  Generally it's better to ask for
769 a scalar value (indicated by $).  The difference is that C<$foo[&bar]> always
770 behaves like a scalar, both in the value it returns and when evaluating its
771 argument, while C<%foo[&bar]> provides a list context to its subscript, which
772 can do weird things if you're expecting only one subscript.  When called in
773 list context, it also returns the index (what C<&bar> returns) in addition to
774 the value.
775
776 =item *
777
778 L<Scalar value %%s{%s} better written as $%s{%s}|perldiag/"Scalar value %%s{%s} better written as $%s{%s}">
779
780 (W syntax) In scalar context, you've used a hash key/value slice (indicated by
781 %) to select a single element of a hash.  Generally it's better to ask for a
782 scalar value (indicated by $).  The difference is that C<$foo{&bar}> always
783 behaves like a scalar, both in the value it returns and when evaluating its
784 argument, while C<@foo{&bar}> and provides a list context to its subscript,
785 which can do weird things if you're expecting only one subscript.  When called
786 in list context, it also returns the key in addition to the value.
787
788 =back
789
790 =head2 Changes to Existing Diagnostics
791
792 XXX Changes (i.e. rewording) of diagnostic messages go here
793
794 =over 4
795
796 =item *
797
798 Warnings and errors from the regexp engine are now UTF-8 clean
799
800 =item *
801
802 The "Unknown switch condition" error message has some slight changes.  This
803 error triggers when there is an unknown condition in a C<(?(foo))> conditional.
804 The error message used to read:
805
806     Unknown switch condition (?(%s in regex;
807
808 But what %s could be was mostly up to luck.  For C<(?(foobar))>, you might have
809 seen "fo" or "f".  For Unicode characters, you would generally get a corrupted
810 string.  The message has been changed to read:
811
812     Unknown switch condition (?(...)) in regex;
813
814 Additionally, the C<'E<lt>-- HERE'> marker in the error will now point to the
815 correct spot in the regex.
816
817 =item *
818
819 The "%s "\x%X" does not map to Unicode" warning is now correctly listed as a
820 severe warning rather than as a fatal error.
821
822 =back
823
824 =head1 Utility Changes
825
826 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
827 Most of these are built within the directories F<utils> and F<x2p>.
828
829 [ List utility changes as a =head3 entry for each utility and =item
830 entries for each change
831 Use L<XXX> with program names to get proper documentation linking. ]
832
833 =head3 L<find2perl>
834
835 =over 4
836
837 =item *
838
839 L<find2perl> now handles C<?> wildcards correctly.  [perl #113054]
840
841 =back
842
843 =head1 Configuration and Compilation
844
845 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
846 go here.  Any other changes to the Perl build process should be listed here.
847 However, any platform-specific changes should be listed in the
848 L</Platform Support> section, instead.
849
850 [ List changes as a =item entry ].
851
852 =over 4
853
854 =item *
855
856 The F<Makefile.PL> for C<SDBM_File> now generates a better F<Makefile>, which
857 avoids a race condition during parallel makes, which could cause the build to
858 fail.  This is the last known parallel make problem (on *nix platforms), and
859 therefore we believe that a parallel make should now always be error free.
860
861 =for comment
862
863 Strictly only for a build where build files such as F<Makefile.SH> have not
864 been updated by C<git> in an already configured and built tree.
865
866 =back
867
868 =head1 Testing
869
870 XXX Any significant changes to the testing of a freshly built perl should be
871 listed here.  Changes which create B<new> files in F<t/> go here as do any
872 large changes to the testing harness (e.g. when parallel testing was added).
873 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
874 that they represent may be covered elsewhere.
875
876 [ List each test improvement as a =item entry ]
877
878 =over 4
879
880 =item *
881
882 The test script F<t/bigmem/regexp.t> has been added to test that regular
883 expression matches on very large strings now succeed as expected.
884
885 =item *
886
887 A bug that was fixed in Perl 5.15.4 is now tested by the new test script
888 F<t/io/eintr_print.t>.  [perl #119097]
889
890 =item *
891
892 The new test scripts F<t/op/kvaslice.t> and F<t/op/kvhslice.t> test the new
893 index/value array slice and key/value hash slice syntax respectively.
894
895 =item *
896
897 Various cases of C<die>, C<last>, C<goto> and C<exit> triggering C<DESTROY> are
898 now tested by the new test script F<t/op/rt119311.t>.
899
900 =item *
901
902 The new test script F<t/op/waitpid.t> tests the fix for [perl #85228] (see
903 L</Selected Bug Fixes>).
904
905 =item *
906
907 The latest copyright years in the top-level F<README> file and the B<perl -v>
908 output are now tested as matching each other by the new test script
909 F<t/porting/copyright.t>
910
911 =item *
912
913 The new test script F<t/win32/signal.t> tests that $! and $^E are now preserved
914 across signal handlers by the Win32 signal emulation code.
915
916 =item *
917
918 The test script F<t/x2p/find2perl.t> has been added to test the F<find2perl>
919 program on platforms where it is practical to do so.
920
921 =back
922
923 =head1 Platform Support
924
925 XXX Any changes to platform support should be listed in the sections below.
926
927 [ Within the sections, list each platform as a =item entry with specific
928 changes as paragraphs below it. ]
929
930 =head2 New Platforms
931
932 XXX List any platforms that this version of perl compiles on, that previous
933 versions did not.  These will either be enabled by new files in the F<hints/>
934 directories, or new subdirectories and F<README> files at the top level of the
935 source tree.
936
937 =over 4
938
939 =item Bitrig
940
941 Compile support has been added for Bitrig, a fork of OpenBSD.
942
943 =back
944
945 =head2 Discontinued Platforms
946
947 Configure hints and conditional code for several very old platforms has been
948 removed.  We have not received reports for these in many years, typically not
949 since Perl 5.6.0.
950
951 =over 4
952
953 =item AT&T 3b1
954
955 Configure support for the 3b1, also known as the AT&T Unix PC (and the similar
956 AT&T 7300), has been removed.
957
958 =back
959
960 =head2 Platform-Specific Notes
961
962 XXX List any changes for specific platforms.  This could include configuration
963 and compilation changes or changes in portability/compatibility.  However,
964 changes within modules for platforms should generally be listed in the
965 L</Modules and Pragmata> section.
966
967 =over 4
968
969 =item Win32
970
971 C<rename> and C<link> on Win32 now set C<$!> to ENOSPC and EDQUOT when appropriate. [perl #119857]
972
973 =item WinCE
974
975 Perl now builds again on WinCE, following locale-related breakage (WinCE has
976 non-existent locale support) introduced around 5.19.1.  [perl #119443]
977
978 The building of XS modules has largely been restored.  Several still cannot
979 (yet) be built but it is now possible to build Perl on WinCE with only a couple
980 of further patches (to L<Socket> and L<ExtUtils::MakeMaker>), hopefully to be
981 incorporated soon.
982
983 =item GNU/Hurd
984
985 The BSD compatibility library C<libbsd> is no longer required for builds.
986
987 =back
988
989 =head1 Internal Changes
990
991 XXX Changes which affect the interface available to C<XS> code go here.  Other
992 significant internal changes for future core maintainers should be noted as
993 well.
994
995 [ List each change as a =item entry ]
996
997 =over 4
998
999 =item *
1000
1001 The internal representation has changed for the match variables $1, $2 etc.,
1002 $`, $&, $', ${^PREMATCH}, ${^MATCH} and ${^POSTMATCH}.  It uses slightly less
1003 memory, avoids string comparisons and numeric conversions during lookup, and
1004 uses 23 fewer lines of C.  This change should not affect any external code.
1005
1006 =item *
1007
1008 Arrays now use NULL internally to represent unused slots, instead of
1009 &PL_sv_undef.  &PL_sv_undef is no longer treated as a special value, so
1010 av_store(av, 0, &PL_sv_undef) will cause element 0 of that array to hold a
1011 read-only undefined scalar.  C<$array[0] = anything> will croak and
1012 C<\$array[0]> will compare equal to C<\undef>.
1013
1014 =item *
1015
1016 The SV returned by HeSVKEY_force() now correctly reflects the UTF8ness
1017 of the underlying hash key when that key is not stored as a SV.  [perl
1018 #79074]
1019
1020 =item *
1021
1022 Certain rarely used functions and macros available to C<XS> code are
1023 now, or are planned to be deprecated.  These are:
1024 C<utf8n_to_uvuni> (use C<utf8_to_uvchr_buf> instead),
1025 C<utf8_to_uni_buf> (use C<utf8_to_uvchr_buf> instead),
1026 C<valid_utf8_to_uvuni> (use C<utf8_to_uvchr_buf> instead),
1027 C<uvuni_to_utf8> (use C<uvchr_to_utf8> instead),
1028 C<NATIVE_TO_NEED> (this did not work properly anyway),
1029 and C<ASCII_TO_NEED>  (this did not work properly anyway).
1030
1031 Starting in this release, almost never does application code need to
1032 distinguish between the platform's character set and Latin1, on which the
1033 lowest 256 characters of Unicode are based.
1034
1035 =back
1036
1037 =head1 Selected Bug Fixes
1038
1039 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
1040 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
1041
1042 [ List each fix as a =item entry ]
1043
1044 =over 4
1045
1046 =item *
1047
1048 The value of $^E is now saved across signal handlers on Windows.  [perl #85104]
1049
1050 =item *
1051
1052 A lexical filehandle (as in C<open my $fh...>) is usually given a name based on
1053 the current package and the name of the variable, e.g. "main::$fh".  Under
1054 recursion, the filehandle was losing the "$fh" part of the name.  This has been
1055 fixed.
1056
1057 =item *
1058
1059 Perl 5.19.3 accidentally extended the previous bug to all closures, even when
1060 not called recursively, i.e. lexical handles in closure would always be called
1061 "main::" or "MyPackage::" etc.  This has been fixed.
1062
1063 =item *
1064
1065 Uninitialized values returned by XSUBs are no longer exempt from uninitialized
1066 warnings.  [perl #118693]
1067
1068 =item *
1069
1070 C<elsif ("")> no longer erroneously produces a warning about void context.
1071 [perl #118753]
1072
1073 =item *
1074
1075 Passing C<undef> to a subroutine now causes @_ to contain the same read-only
1076 undefined scalar that C<undef> returns.  Furthermore, C<exists $_[0]> will now
1077 return true if C<undef> was the first argument.  [perl #7508, #109726]
1078
1079 =item *
1080
1081 Passing a nonexistent array element to a subroutine does not usually autovivify
1082 it unless the subroutine modifies its argument.  This did not work correctly
1083 with negative indices and with nonexistent elements within the array.  The
1084 element would be vivified immediately.  The delayed vivification has been
1085 extended to work with those.  [perl #118691]
1086
1087 =item *
1088
1089 Assigning references or globs to the scalar returned by $#foo after the @foo
1090 array has been freed no longer causes assertion failures on debugging builds
1091 and memory leaks on regular builds.
1092
1093 =item *
1094
1095 Perl 5.19.2 threw line numbers off after some cases of line breaks following
1096 keywords, such as
1097
1098    1 unless
1099    1;
1100
1101 This has been fixed.  [perl #118931]
1102
1103 =item *
1104
1105 On 64-bit platforms, large ranges like 1..1000000000000 no longer crash, but
1106 eat up all your memory instead.  [perl #119161]
1107
1108 =item *
1109
1110 C<__DATA__> now puts the C<DATA> handle in the right package, even if the
1111 current package has been renamed through glob assignment.
1112
1113 =item *
1114
1115 The string position set by C<pos> could shift if the string changed
1116 representation internally to or from utf8.  This could happen, e.g., with
1117 references to objects with string overloading.
1118
1119 =item *
1120
1121 Taking references to the return values of two C<pos> calls with the same
1122 argument, and then assigning a reference to one and C<undef> to the other,
1123 could result in assertion failures or memory leaks.
1124
1125 =item *
1126
1127 Elements of @- and @+ now update correctly when they refer to nonexistent
1128 captures.  Previously, a referenced element (C<$ref = \$-[1]>) could refer to
1129 the wrong match after subsequent matches.
1130
1131 =item *
1132
1133 When C<die>, C<last>, C<next>, C<redo>, C<goto> and C<exit> unwind the scope,
1134 it is possible for C<DESTROY> recursively to call a subroutine or format that
1135 is currently being exited.  It that case, sometimes the lexical variables
1136 inside the sub would start out having values from the outer call, instead of
1137 being undefined as they should.  This has been fixed.  [perl #119311]
1138
1139 =item *
1140
1141 ${^MPEN} is no longer treated as a synonym for ${^MATCH}.
1142
1143 =item *
1144
1145 Perl now tries a little harder to return the correct line number in
1146 C<(caller)[2]>.  [perl #115768]
1147
1148 =item *
1149
1150 Line numbers inside multiline quote-like operators are now reported correctly.
1151 [perl #3643]
1152
1153 =item *
1154
1155 C<#line> directives inside code embedded in quote-like operators are now
1156 respected.
1157
1158 =item *
1159
1160 Line numbers are now correct inside the second here-doc when two here-doc
1161 markers occur on the same line.
1162
1163 =item *
1164
1165 Starting with Perl 5.12, line numbers were off by one if the B<-d> switch was
1166 used on the #! line.  Now they are correct.
1167
1168 =item *
1169
1170 Perl 5.19.2 inadvertently stopped some lines of code from being available to
1171 the debugger if C<=E<gt>> occurred at the beginning of a line and the previous
1172 line ended with a keyword.  This is now fixed.
1173
1174 =item *
1175
1176 Perl 5.19.2 allowed the PERL5DB environment variable to contain multiple lines
1177 of code, but those lines were not made available to the debugger.  Now they are
1178 all stuffed into line number 0, accessible via C<$dbline[0]> in the debugger.
1179
1180 =item *
1181
1182 An optimisation in Perl 5.18 made incorrect assumptions causing a bad
1183 interaction with the L<Devel::CallParser> CPAN module.  If the module was
1184 loaded then lexical variables declared in separate statements following a
1185 C<my(...)> list might fail to be cleared on scope exit.
1186
1187 =item *
1188
1189 C<&xsub> and C<goto &xsub> calls now allow the called subroutine to autovivify
1190 elements of @_.
1191
1192 =item *
1193
1194 C<&xsub> and C<goto &xsub> no longer crash if *_ has been undefined and has no
1195 ARRAY entry (i.e. @_ does not exist).
1196
1197 =item *
1198
1199 C<&xsub> and C<goto &xsub> now work with tied @_.
1200
1201 =item *
1202
1203 Overlong identifiers no longer cause a buffer overflow (and a crash).  They
1204 started doing so in Perl 5.18.
1205
1206 =item *
1207
1208 The warning "Scalar value @hash{foo} better written as $hash{foo}" now produces
1209 far fewer false positives.  In particular, C<@hash{+function_returning_a_list}>
1210 and C<@hash{ qw "foo bar baz" }> no longer warn.  The same applies to array
1211 slices.  [perl #28380, #114024]
1212
1213 =item *
1214
1215 C< $! = EINVAL; waitpid(0, WNOHANG); > no longer goes into an internal infinite
1216 loop.  [perl #85228]
1217
1218 =back
1219
1220 =head1 Known Problems
1221
1222 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
1223 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
1224 platform specific bugs also go here.
1225
1226 [ List each fix as a =item entry ]
1227
1228 =over 4
1229
1230 =item *
1231
1232 XXX
1233
1234 =back
1235
1236 =head1 Obituary
1237
1238 XXX If any significant core contributor has died, we've added a short obituary
1239 here.
1240
1241 =head1 Acknowledgements
1242
1243 XXX Generate this with:
1244
1245   perl Porting/acknowledgements.pl v5.19.3..HEAD
1246
1247 =head1 Reporting Bugs
1248
1249 If you find what you think is a bug, you might check the articles recently
1250 posted to the comp.lang.perl.misc newsgroup and the perl bug database at
1251 http://rt.perl.org/perlbug/ .  There may also be information at
1252 http://www.perl.org/ , the Perl Home Page.
1253
1254 If you believe you have an unreported bug, please run the L<perlbug> program
1255 included with your release.  Be sure to trim your bug down to a tiny but
1256 sufficient test case.  Your bug report, along with the output of C<perl -V>,
1257 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
1258
1259 If the bug you are reporting has security implications, which make it
1260 inappropriate to send to a publicly archived mailing list, then please send it
1261 to perl5-security-report@perl.org.  This points to a closed subscription
1262 unarchived mailing list, which includes all the core committers, who will be
1263 able to help assess the impact of issues, figure out a resolution, and help
1264 co-ordinate the release of patches to mitigate or fix the problem across all
1265 platforms on which Perl is supported.  Please only use this address for
1266 security issues in the Perl core, not for modules independently distributed on
1267 CPAN.
1268
1269 =head1 SEE ALSO
1270
1271 The F<Changes> file for an explanation of how to view exhaustive details on
1272 what changed.
1273
1274 The F<INSTALL> file for how to build Perl.
1275
1276 The F<README> file for general stuff.
1277
1278 The F<Artistic> and F<Copying> files for copyright information.
1279
1280 =cut