This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta for b3cf482, 4fa715f
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
7065301c
RS
5[ this is a template for a new perldelta file. Any text flagged as XXX needs
6to be processed before release. ]
7
8perldelta - what is new for perl v5.21.1
c68523cb 9
238894db 10=head1 DESCRIPTION
c68523cb 11
7065301c 12This document describes differences between the 5.21.0 release and the 5.21.1
238894db 13release.
c68523cb 14
7065301c
RS
15If you are upgrading from an earlier release such as 5.20.0, first read
16L<perl5210delta>, which describes differences between 5.20.0 and 5.21.0.
17
18=head1 Notice
19
20XXX Any important notices here
21
22=head1 Core Enhancements
23
24XXX New core language features go here. Summarize user-visible core language
25enhancements. Particularly prominent performance optimisations could go
26here, but most should go in the L</Performance Enhancements> section.
27
28[ List each enhancement as a =head2 entry ]
29
8373491a
KW
30=head2 C<qr/foo/x> now ignores any Unicode pattern white space
31
32The C</x> regular expression modifier allows the pattern to contain
33white space and comments, both of which are ignored, for improved
34readability. Until now, not all the white space characters that Unicode
35designates for this purpose were handled. The additional ones now
36recognized are
37U+0085 NEXT LINE,
38U+200E LEFT-TO-RIGHT MARK,
39U+200F RIGHT-TO-LEFT MARK,
40U+2028 LINE SEPARATOR,
41and
42U+2029 PARAGRAPH SEPARATOR.
43
d6ded950
KW
44=head2 S<C<use locale>> can restrict which locale categories are affected
45
46It is now possible to pass a parameter to S<C<use locale>> to specify
47a subset of locale categories to be locale-aware, with the remaining
48ones unaffected. See L<perllocale/The "use locale" pragma> for details.
49
7065301c
RS
50=head1 Security
51
52XXX Any security-related notices go here. In particular, any security
53vulnerabilities closed should be noted here rather than in the
54L</Selected Bug Fixes> section.
55
56[ List each security issue as a =head2 entry ]
57
58=head1 Incompatible Changes
59
60XXX For a release on a stable branch, this section aspires to be:
61
62 There are no changes intentionally incompatible with 5.XXX.XXX
63 If any exist, they are bugs, and we request that you submit a
64 report. See L</Reporting Bugs> below.
65
7357bd17
KW
66=head2 In double-quotish C<\cI<X>>, I<X> must now be a printable ASCII character
67
68In prior releases, failure to do this raised a deprecation warning.
7065301c 69
cd209d9d
KW
70=head2 Splitting the tokens C<(?> and C<(*> in regular expressions is
71now a fatal compilation error.
72
73These had been deprecated since v5.18.
74
8373491a
KW
75=head2 5 additional characters are treated as white space under C</x> in
76regex patterns (unless escaped)
77
78The use of these characters with C</x> outside bracketed character
79classes and when not preceeded by a backslash has raised a deprecation
80warning since v5.18. Now they will be ignored. See L</qrE<sol>fooE<sol>x>
81for the list of the five characters.
82
83=head2 Comment lines within S<C<(?[ ])>> now are ended only by a C<\n>
84
85S<C<(?[ ])>> is an experimental feature, introduced in v5.18. It operates
86as if C</x> is always enabled. But there was a difference, comment
87lines (following a C<#> character) were terminated by anything matching
88C<\R> which includes all vertical whitespace, such as form feeds. For
89consistency, this is now changed to match what terminates comment lines
90outside S<C<(?[ ])>>, namely a C<\n> (even if escaped), which is the
91same as what terminates a heredoc string and formats.
92
b5adc3e5
DIM
93=head2 Omitting % and @ on hash and array names is no longer permitted
94
95Really old Perl let you omit the @ on array names and the % on hash
96names in some spots. This has issued a deprecation warning since Perl
975.0, and is no longer permitted.
98
2c6ee1a7
KW
99=head2 C<"$!"> text is now in English outside C<"use locale"> scope
100
101Previously, the text, unlike almost everything else, always came out
102based on the current underlying locale of the program. (Also affected
103on some systems is C<"$^E>".) For programs that are unprepared to
104handle locale, this can cause garbage text to be displayed. It's better
105to display text that is translatable via some tool than garbage text
106which is much harder to figure out.
107
5320b60d
KW
108=head2 C<"$!"> text will be returned in UTF-8 when appropriate
109
110The stringification of C<$!> and C<$^E> will have the UTF-8 flag set
111when the text is actually non-ASCII UTF-8. This will enable programs
112that are set up to be locale-aware to properly output messages in the
113user's native language. Code that needs to continue the 5.20 and
114earlier behavior can do the stringification within the scopes of both
115'use bytes' and 'use locale ":messages". No other Perl operations will
116be affected by locale; only C<$!> and C<$^E> stringification. The
117'bytes' pragma causes the UTF-8 flag to not be set, just as in previous
118Perl releases. This resolves [perl #112208].
119
7065301c
RS
120=head1 Deprecations
121
122XXX Any deprecated features, syntax, modules etc. should be listed here.
123
df758df2
KW
124=head2 Using a NO-BREAK space in a character alias for C<\N{...}> is now
125deprecated
126
127This non-graphic character is essentially indistinguishable from a
128regular space, and so should not be allowed. See
129L<charnames/CUSTOM ALIASES>.
130
7065301c
RS
131=head2 Module removals
132
133XXX Remove this section if inapplicable.
134
135The following modules will be removed from the core distribution in a
136future release, and will at that time need to be installed from CPAN.
137Distributions on CPAN which require these modules will need to list them as
138prerequisites.
139
140The core versions of these modules will now issue C<"deprecated">-category
141warnings to alert you to this fact. To silence these deprecation warnings,
142install the modules in question from CPAN.
143
144Note that these are (with rare exceptions) fine modules that you are encouraged
145to continue to use. Their disinclusion from core primarily hinges on their
146necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
147not usually on concerns over their design.
148
149=over
150
151=item XXX
152
153XXX Note that deprecated modules should be listed here even if they are listed
154as an updated module in the L</Modules and Pragmata> section.
155
156=back
157
158[ List each other deprecation as a =head2 entry ]
159
160=head1 Performance Enhancements
161
162XXX Changes which enhance performance without changing behaviour go here.
163There may well be none in a stable release.
164
165[ List each enhancement as a =item entry ]
166
167=over 4
168
169=item *
170
8a16341a
MH
171Many internal functions have been refactored to improve performance and reduce
172their memory footprints.
d133a3dd
MH
173
174L<[perl #121436]|https://rt.perl.org/Ticket/Display.html?id=121436>
8a16341a
MH
175L<[perl #121906]|https://rt.perl.org/Ticket/Display.html?id=121906>
176L<[perl #121969]|https://rt.perl.org/Ticket/Display.html?id=121969>
7065301c 177
6bb82be0
MH
178=item *
179
180C<-T> and C<-B> filetests will return sooner when an empty file is detected.
181
182L<perl #121489|https://rt.perl.org/Ticket/Display.html?id=121489>
183
7065301c
RS
184=back
185
7ef8b31d 186=head1 Modules and Pragmata
f6f3144e 187
7065301c
RS
188XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
189go here. If Module::CoreList is updated, generate an initial draft of the
190following sections using F<Porting/corelist-perldelta.pl>. A paragraph summary
191for important changes should then be added by hand. In an ideal world,
192dual-life modules would have a F<Changes> file that could be cribbed.
193
194[ Within each section, list entries as a =item entry ]
195
196=head2 New Modules and Pragmata
24a38d90
RS
197
198=over 4
199
200=item *
201
7065301c
RS
202XXX
203
204=back
205
206=head2 Updated Modules and Pragmata
207
208=over 4
24a38d90
RS
209
210=item *
211
56cdf413
TC
212L<Carp> has been upgraded from version 1.3301 to 1.34.
213
214Carp::Heavy now ignores version mismatches with Carp if Carp is newer
215than 1.12, since Carp::Heavy's guts were merged into Carp at that
216point.
217L<[perl #121574]|https://rt.perl.org/Ticket/Display.html?id=121574>
218
219=item *
220
28e02325
SH
221L<Encode> has been upgraded from version 2.60_01 to 2.62.
222
223B<piconv> now has better error handling when the encoding name is nonexistent,
224and a build breakage when upgrading L<Encode> in perl-5.8.2 and earlier has
225been fixed.
226
227=item *
228
5abafd4c
SH
229The libnet collection of modules has been upgraded from version 1.25 to 1.27.
230
231There are only whitespace changes to the installed files.
232
233=item *
234
7a945bf5
SH
235The Locale-Codes collection of modules has been upgraded from vesion 3.30 to 3.31.
236
237Fixed a bug in the scripts used to extract data from spreadsheets that
238prevented the SHP currency code from being found.
239L<[cpan #94229]|https://rt.cpan.org/Ticket/Display.html?id=94229>
240
241=item *
242
4ed8f5ed
TC
243L<Math::BigInt> has been upgraded from version 1.9993 to 1.9994.
244
245Synchronize POD changes from the CPAN release.
246
ee15bb65
TC
247C<< Math::BigFloat->blog(x) >> would sometimes return blog(2*x) when
248the accuracy was greater than 70 digits.
249
250The result of C<< Math::BigFloat->bdiv() >> in list context now
251satisfies C<< x = quotient * divisor + remainder >>.
252
4ed8f5ed
TC
253=item *
254
234105dd
TC
255L<Math::BigRat> has been upgraded from version 0.2606 to 0.2607.
256
257Synchronize POD changes from the CPAN release.
258
259=item *
260
f97d984b 261L<Module::Metadata> has been upgraded from version 1.000022 to 1.000024.
b9beed70
SH
262
263Support installations on older perls with an L<ExtUtils::MakeMaker> earlier
264than 6.63_03
265
266=item *
267
c13fd1a2
TC
268L<perl5db.pl> has been upgraded from version 1.44 to 1.45.
269
3ca75eca
YO
270=item *
271
272A mismatch between the documentation and the code in utf8::downgrade()
273was fixed in favour of the documentation. The optional second argument
274is now correctly treated as a perl boolean (true/false semantics) and
275not as an integer.
276
277=item *
278
c13fd1a2 279fork() in the debugger under C<tmux> will now create a new window for
891822fa
TC
280the forked process. L<[perl
281#121333]|https://rt.perl.org/Ticket/Display.html?id=121333>
282
283The debugger now saves the current working directory on startup and
284restores it when you restart your program with C<R> or <rerun>. L<[perl
285#121509]|https://rt.perl.org/Ticket/Display.html?id=121509>
24a38d90 286
f8187d97
SH
287L<Unicode::Collate> has been upgraded from version 1.04 to 1.07.
288
289Version 0.67's improved discontiguous contractions is invalidated by default
290and is supported as a parameter 'long_contraction'.
291
95f3e8d2
SH
292=item *
293
294L<Unicode::Normalize> has been upgraded from version 1.17 to 1.18.
295
296The XSUB implementation has been removed in favour of pure Perl.
297
3eaa3d14
YO
298=item *
299
300L<Hash::Util> has been upgraded from version 0.16 to 0.17.
301
302Minor bug fixes and documentation fixes to Hash::Util::hash_stats()
303
304
238894db 305=back
24a38d90 306
92fa985e 307=head2 Removed Modules and Pragmata
24a38d90 308
238894db 309=over 4
24a38d90
RS
310
311=item *
312
7065301c
RS
313XXX
314
315=back
316
317=head1 Documentation
318
319XXX Changes to files in F<pod/> go here. Consider grouping entries by
320file and be sure to link to the appropriate page, e.g. L<perlfunc>.
321
322=head2 New Documentation
323
324XXX Changes which create B<new> files in F<pod/> go here.
325
326=head3 L<XXX>
327
328XXX Description of the purpose of the new file here
329
330=head2 Changes to Existing Documentation
331
332XXX Changes which significantly change existing files in F<pod/> go here.
333However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
334section.
335
9c0f2733 336=head3 L<perlfunc>
7065301c
RS
337
338=over 4
339
340=item *
341
9c0f2733
MH
342C<-l> now notes that it will return false if symlinks aren't supported by the
343file system.
344
345L<[perl #121523]|https://rt.perl.org/Ticket/Display.html?id=121523>
7065301c
RS
346
347=back
348
349=head1 Diagnostics
350
351The following additions or changes have been made to diagnostic output,
352including warnings and fatal error messages. For the complete list of
353diagnostic messages, see L<perldiag>.
354
355XXX New or changed warnings emitted by the core's C<C> code go here. Also
356include any changes in L<perldiag> that reconcile it to the C<C> code.
357
358=head2 New Diagnostics
359
360XXX Newly added diagnostic messages go under here, separated into New Errors
361and New Warnings
362
363=head3 New Errors
364
365=over 4
24a38d90
RS
366
367=item *
368
7065301c
RS
369XXX L<message|perldiag/"message">
370
371=back
372
373=head3 New Warnings
374
375=over 4
24a38d90
RS
376
377=item *
378
097675bf
TC
379L<PerlIO layer ':win32' is experimental|perldiag/"PerlIO layer ':win32' is experimental">:
380
381(S experimental::win32_perlio) The C<:win32> PerlIO layer is
382experimental. If you want to take the risk of using this layer,
383simply disable this warning:
384
385 no warnings "experimental::win32_perlio";
24a38d90 386
238894db 387=back
24a38d90 388
7065301c 389=head2 Changes to Existing Diagnostics
24a38d90 390
7065301c 391XXX Changes (i.e. rewording) of diagnostic messages go here
24a38d90 392
7065301c
RS
393=over 4
394
395=item *
396
723edb96
TC
397L<Unsuccessful %s on filename containing newline|perldiag/"Unsuccessful %s on filename containing newline">
398
399This warning is now only produced when the newline is at the end of
400the filename.
7065301c
RS
401
402=back
403
404=head1 Utility Changes
405
406XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
407Most of these are built within the directories F<utils> and F<x2p>.
408
409[ List utility changes as a =head2 entry for each utility and =item
410entries for each change
411Use L<XXX> with program names to get proper documentation linking. ]
412
413=head2 L<XXX>
414
415=over 4
416
417=item *
24a38d90 418
7065301c
RS
419XXX
420
421=back
422
423=head1 Configuration and Compilation
424
425XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
426go here. Any other changes to the Perl build process should be listed here.
427However, any platform-specific changes should be listed in the
428L</Platform Support> section, instead.
429
430[ List changes as a =item entry ].
431
432=over 4
433
434=item *
435
436XXX
437
438=back
439
440=head1 Testing
441
442XXX Any significant changes to the testing of a freshly built perl should be
443listed here. Changes which create B<new> files in F<t/> go here as do any
444large changes to the testing harness (e.g. when parallel testing was added).
445Changes to existing files in F<t/> aren't worth summarizing, although the bugs
446that they represent may be covered elsewhere.
447
448[ List each test improvement as a =item entry ]
449
450=over 4
451
452=item *
453
454XXX
455
456=back
457
458=head1 Platform Support
459
460XXX Any changes to platform support should be listed in the sections below.
461
462[ Within the sections, list each platform as a =item entry with specific
463changes as paragraphs below it. ]
464
465=head2 New Platforms
466
467XXX List any platforms that this version of perl compiles on, that previous
468versions did not. These will either be enabled by new files in the F<hints/>
469directories, or new subdirectories and F<README> files at the top level of the
470source tree.
471
472=over 4
473
474=item XXX-some-platform
475
476XXX
477
478=back
479
480=head2 Discontinued Platforms
481
482XXX List any platforms that this version of perl no longer compiles on.
483
484=over 4
485
486=item XXX-some-platform
487
488XXX
489
490=back
491
492=head2 Platform-Specific Notes
493
494XXX List any changes for specific platforms. This could include configuration
495and compilation changes or changes in portability/compatibility. However,
496changes within modules for platforms should generally be listed in the
497L</Modules and Pragmata> section.
498
499=over 4
500
501=item XXX-some-platform
502
503XXX
504
505=back
506
507=head1 Internal Changes
508
509XXX Changes which affect the interface available to C<XS> code go here. Other
510significant internal changes for future core maintainers should be noted as
511well.
512
7065301c
RS
513=over 4
514
515=item *
516
8dab3ba5 517The deprecated variable C<PL_sv_objcount> has been removed.
7065301c 518
4c28b29c
KW
519=item *
520
521Perl now tries to keep the locale category C<LC_NUMERIC> set to "C"
522except around operations that need it to be set to the program's
523underlying locale. This protects the many XS modules that cannot cope
524with the decimal radix character not being a dot. Prior to this
525release, Perl initialized this category to "C", but a call to
526C<POSIX::setlocale()> would change it. Now such a call will change the
527underlying locale of the C<LC_NUMERIC> category for the program, but the
528locale exposed to XS code will remain "C". There is an API under
529development for those relatively few modules that need to use the
530underlying locale. This API will be nailed down during the course of
531developing v5.21. Send email to L<mailto:perl5-porters@perl.org> for
532guidance.
533
7065301c
RS
534=back
535
536=head1 Selected Bug Fixes
537
538XXX Important bug fixes in the core language are summarized here. Bug fixes in
539files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
540
541[ List each fix as a =item entry ]
542
543=over 4
544
545=item *
546
30536d4a
TC
547index() and rindex() no longer crash when used on strings over 2GB in
548size.
549L<[perl #121562]|https://rt.perl.org/Ticket/Display.html?id=121562>.
7065301c 550
0c2c57a8
DD
551=item *
552
553A small previously intentional memory leak in PERL_SYS_INIT/PERL_SYS_INIT3 on
554Win32 builds was fixed. This might affect embedders who repeatedly create and
555destroy perl engines within the same process.
556
a835cd47
KW
557=item *
558
559C<POSIX::localeconv()> now returns the data for the program's underlying
560locale even when called from outside the scope of S<C<use locale>>.
561
03ceeedf
KW
562=item *
563
564C<POSIX::localeconv()> now works properly on platforms which don't have
565C<LC_NUMERIC> and/or C<LC_MONETARY>, or for which Perl has been compiled
566to disregard either or both of these locale categories. In such
567circumstances, there are now no entries for the corresponding values in
568the hash returned by C<localeconv()>.
569
c1284011
KW
570=item *
571
572C<POSIX::localeconv()> now marks appropriately the values it returns as
573UTF-8 or not. Previously they were always returned as a bytes, even if
574they were supposed to be encoded as UTF-8.
575
375f5f06
KW
576=item *
577
578On Microsoft Windows, within the scope of C<S<use locale>>, the following
579POSIX character classes gave results for many locales that did not
580conform to the POSIX standard:
581C<[[:alnum:]]>,
582C<[[:alpha:]]>,
583C<[[:blank:]]>,
584C<[[:digit:]]>,
585C<[[:graph:]]>,
586C<[[:lower:]]>,
587C<[[:print:]]>,
588C<[[:punct:]]>,
589C<[[:upper:]]>,
590C<[[:word:]]>,
591and
592C<[[:xdigit:]]>.
593These are because the underlying Microsoft implementation does not
594follow the standard. Perl now takes special precautions to correct for
595this.
596
7065301c
RS
597=back
598
599=head1 Known Problems
600
601XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
602tests that had to be C<TODO>ed for the release would be noted here. Unfixed
603platform specific bugs also go here.
604
605[ List each fix as a =item entry ]
606
607=over 4
608
609=item *
610
611XXX
612
613=back
614
615=head1 Errata From Previous Releases
616
617=over 4
618
619=item *
620
621XXX Add anything here that we forgot to add, or were mistaken about, in
622the perldelta of a previous release.
623
624=back
625
626=head1 Obituary
627
628XXX If any significant core contributor has died, we've added a short obituary
629here.
630
631=head1 Acknowledgements
24a38d90 632
7065301c 633XXX Generate this with:
52e02e68 634
7065301c 635 perl Porting/acknowledgements.pl v5.21.1..HEAD
f5b73711 636
44691e6f
AB
637=head1 Reporting Bugs
638
e08634c5
SH
639If you find what you think is a bug, you might check the articles recently
640posted to the comp.lang.perl.misc newsgroup and the perl bug database at
238894db 641https://rt.perl.org/ . There may also be information at
7ef8b31d 642http://www.perl.org/ , the Perl Home Page.
44691e6f 643
e08634c5
SH
644If you believe you have an unreported bug, please run the L<perlbug> program
645included with your release. Be sure to trim your bug down to a tiny but
646sufficient test case. Your bug report, along with the output of C<perl -V>,
647will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f
AB
648
649If the bug you are reporting has security implications, which make it
e08634c5
SH
650inappropriate to send to a publicly archived mailing list, then please send it
651to perl5-security-report@perl.org. This points to a closed subscription
652unarchived mailing list, which includes all the core committers, who will be
653able to help assess the impact of issues, figure out a resolution, and help
f9001595 654co-ordinate the release of patches to mitigate or fix the problem across all
e08634c5
SH
655platforms on which Perl is supported. Please only use this address for
656security issues in the Perl core, not for modules independently distributed on
657CPAN.
44691e6f
AB
658
659=head1 SEE ALSO
660
e08634c5
SH
661The F<Changes> file for an explanation of how to view exhaustive details on
662what changed.
44691e6f
AB
663
664The F<INSTALL> file for how to build Perl.
665
666The F<README> file for general stuff.
667
668The F<Artistic> and F<Copying> files for copyright information.
669
670=cut