This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta for lexsub warnings
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
e14ac59b
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.17.7
e128ab2c 9
4eabcf70 10=head1 DESCRIPTION
6db9054f 11
e14ac59b 12This document describes differences between the 5.17.6 release and the 5.17.7
e08634c5 13release.
6db9054f 14
e14ac59b
RS
15If you are upgrading from an earlier release such as 5.17.5, first read
16L<perl5176delta>, which describes differences between 5.17.5 and 5.17.6.
17
18=head1 Notice
19
20XXX Any important notices here
5faa50e9 21
5d8c8c8a 22=head1 Core Enhancements
4db91b87 23
e14ac59b
RS
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.
bde9e88d 27
e14ac59b 28[ List each enhancement as a =head2 entry ]
bde9e88d 29
e14ac59b 30=head1 Security
86148eee 31
e14ac59b
RS
32XXX Any security-related notices go here. In particular, any security
33vulnerabilities closed should be noted here rather than in the
34L</Selected Bug Fixes> section.
86148eee 35
e14ac59b 36[ List each security issue as a =head2 entry ]
9c5f5e7a 37
e14ac59b 38=head1 Incompatible Changes
90249f0a 39
3ef6ec90
TC
40=head2 readline() with C<$/ = \N> now reads N characters, not N bytes
41
42Previously, when reading from a stream with I/O layers such as
43C<encoding>, the readline() function, otherwise known as the C<< <> >>
44operator, would read I<N> bytes from the top-most layer. [perl #79960]
45
46Now, I<N> characters are read instead.
47
48There is no change in behaviour when reading from streams with no
49extra layers, since bytes map exactly to characters.
50
9a0708b2 51=head2 Lexical subroutine warnings have moved
90249f0a 52
9a0708b2
FC
53The warning about the use of an experimental feature emitted when lexical
54subroutines (added in 5.17.4) are used now happens when the subroutine
55itself is declared, not when the "lexical_subs" feature is activated via
56C<use feature>.
4d7cd482 57
9a0708b2
FC
58This stops C<use feature ':all'> from warning, but causes
59C<my sub foo; my sub bar> to warn twice.
4d7cd482 60
e14ac59b 61=head1 Deprecations
4d7cd482 62
e14ac59b
RS
63XXX Any deprecated features, syntax, modules etc. should be listed here. In
64particular, deprecated modules should be listed here even if they are listed as
65an updated module in the L</Modules and Pragmata> section.
4d7cd482 66
e14ac59b 67[ List each deprecation as a =head2 entry ]
86148eee 68
61b19385
KW
69=head2 Various XS-callable functions are now deprecated
70
71The following functions will be removed from a future version of Perl,
72and should not be used. With participating C compilers (e.g., gcc),
73compiling any file that uses any of these will generate a warning.
74These were not intended for public use; there are equivalent, faster,
75macros for most of them. See L<perlapi/Character classes>:
76C<is_uni_ascii>,
77C<is_uni_ascii_lc>,
78C<is_uni_blank>,
79C<is_uni_blank_lc>,
80C<is_uni_cntrl>,
81C<is_uni_cntrl_lc>,
82C<is_uni_idfirst_lc>,
83C<is_uni_space>,
84C<is_uni_space_lc>,
85C<is_uni_xdigit>,
86C<is_uni_xdigit_lc>,
87C<is_utf8_ascii>,
88C<is_utf8_blank>,
89C<is_utf8_cntrl>,
90C<is_utf8_idcont>,
91C<is_utf8_idfirst>,
92C<is_utf8_perl_space>,
93C<is_utf8_perl_word>,
94C<is_utf8_posix_digit>,
95C<is_utf8_space>,
96C<is_utf8_xdigit>.
97C<is_utf8_xidcont>,
98C<is_utf8_xidfirst>,
99C<to_uni_lower_lc>,
100C<to_uni_title_lc>,
101and
102C<to_uni_upper_lc>.
103
e14ac59b 104=head1 Performance Enhancements
86148eee 105
e14ac59b
RS
106XXX Changes which enhance performance without changing behaviour go here.
107There may well be none in a stable release.
86148eee 108
e14ac59b 109[ List each enhancement as a =item entry ]
1611045a 110
e14ac59b 111=over 4
7a7a10c7 112
e14ac59b 113=item *
7a7a10c7 114
e14ac59b 115XXX
7a7a10c7 116
e14ac59b 117=back
7a7a10c7 118
e14ac59b 119=head1 Modules and Pragmata
7a7a10c7 120
e14ac59b
RS
121XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
122go here. If Module::CoreList is updated, generate an initial draft of the
123following sections using F<Porting/corelist-perldelta.pl>, which prints stub
124entries to STDOUT. Results can be pasted in place of the '=head2' entries
125below. A paragraph summary for important changes should then be added by hand.
126In an ideal world, dual-life modules would have a F<Changes> file that could be
127cribbed.
7a7a10c7 128
e14ac59b 129[ Within each section, list entries as a =item entry ]
7a7a10c7 130
e14ac59b 131=head2 New Modules and Pragmata
45f11e9c 132
916c45d9 133=over 4
338a1057
SH
134
135=item *
136
e14ac59b 137XXX
0ace302a 138
e14ac59b 139=back
32209f41 140
e14ac59b 141=head2 Updated Modules and Pragmata
c387386a 142
e14ac59b 143=over 4
32209f41 144
e14ac59b 145=item *
5faa50e9 146
476161f6
NC
147L<GDBM_File> has been upgraded from version 1.14 to 1.15. The undocumented
148optional fifth parameter to C<TIEHASH> has been removed. This was intended
149to provide control of the callback used by C<gdbm*> functions in case of
150fatal errors (such as filesystem problems), but did not work (and could
151never have worked). No code on CPAN even attempted to use it. The callback
152is now always the previous default, C<croak>. Problems on some platforms with
153how the C<C> C<croak> function is called have also been resolved.
5faa50e9 154
e14ac59b
RS
155=back
156
157=head2 Removed Modules and Pragmata
4cc02608 158
916c45d9 159=over 4
e7b92d54
SH
160
161=item *
162
e14ac59b 163XXX
11e375e0 164
e14ac59b 165=back
11e375e0 166
e14ac59b 167=head1 Documentation
11e375e0 168
e14ac59b
RS
169XXX Changes to files in F<pod/> go here. Consider grouping entries by
170file and be sure to link to the appropriate page, e.g. L<perlfunc>.
7b379596 171
e14ac59b 172=head2 New Documentation
5c26a176 173
e14ac59b 174XXX Changes which create B<new> files in F<pod/> go here.
5c26a176 175
e14ac59b 176=head3 L<XXX>
cb077ed2 177
e14ac59b 178XXX Description of the purpose of the new file here
11e375e0 179
e14ac59b 180=head2 Changes to Existing Documentation
11e375e0 181
e14ac59b
RS
182XXX Changes which significantly change existing files in F<pod/> go here.
183However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
184section.
185
243effed 186=head3 L<perlapi/Character classes>
11e375e0 187
e14ac59b 188=over 4
e498bd59
RS
189
190=item *
191
243effed
KW
192There are quite a few macros callable from XS modules that classify
193characters into things like alphabetic, punctuation, etc. More of these
194are now documented, including ones which work on characters whose code
195points are outside the Latin-1 range.
cb077ed2 196
5d8c8c8a 197=back
5f877a7f 198
e14ac59b
RS
199=head1 Diagnostics
200
201The following additions or changes have been made to diagnostic output,
202including warnings and fatal error messages. For the complete list of
203diagnostic messages, see L<perldiag>.
1ea91bbe 204
e14ac59b
RS
205XXX New or changed warnings emitted by the core's C<C> code go here. Also
206include any changes in L<perldiag> that reconcile it to the C<C> code.
207
208=head2 New Diagnostics
209
210XXX Newly added diagnostic messages go under here, separated into New Errors
211and New Warnings
212
213=head3 New Errors
5faa50e9 214
5d8c8c8a 215=over 4
1ea91bbe
FR
216
217=item *
218
e14ac59b 219XXX L<message|perldiag/"message">
5faa50e9 220
916c45d9 221=back
9c5f5e7a 222
e14ac59b 223=head3 New Warnings
4db91b87 224
5d8c8c8a 225=over 4
4db91b87 226
e14ac59b 227=item *
4db91b87 228
e14ac59b 229XXX L<message|perldiag/"message">
4db91b87 230
5d8c8c8a 231=back
5faa50e9 232
e14ac59b
RS
233=head2 Changes to Existing Diagnostics
234
235XXX Changes (i.e. rewording) of diagnostic messages go here
5faa50e9 236
5d8c8c8a 237=over 4
5faa50e9 238
e14ac59b 239=item *
ddb1bef5 240
e14ac59b 241XXX Describe change here
ddb1bef5 242
e14ac59b 243=back
5faa50e9 244
e14ac59b 245=head1 Utility Changes
5faa50e9 246
e14ac59b
RS
247XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
248Most of these are built within the directories F<utils> and F<x2p>.
5faa50e9 249
e14ac59b
RS
250[ List utility changes as a =head3 entry for each utility and =item
251entries for each change
252Use L<XXX> with program names to get proper documentation linking. ]
253
254=head3 L<XXX>
5faa50e9 255
5d8c8c8a 256=over 4
5faa50e9
FR
257
258=item *
259
e14ac59b 260XXX
cb077ed2 261
e14ac59b
RS
262=back
263
264=head1 Configuration and Compilation
265
266XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
267go here. Any other changes to the Perl build process should be listed here.
268However, any platform-specific changes should be listed in the
269L</Platform Support> section, instead.
cb077ed2 270
e14ac59b
RS
271[ List changes as a =item entry ].
272
273=over 4
90814a4e 274
5ce83ae9
DM
275=item *
276
e14ac59b 277XXX
5ce83ae9 278
5d8c8c8a 279=back
31c15ce5 280
e14ac59b
RS
281=head1 Testing
282
283XXX Any significant changes to the testing of a freshly built perl should be
284listed here. Changes which create B<new> files in F<t/> go here as do any
285large changes to the testing harness (e.g. when parallel testing was added).
286Changes to existing files in F<t/> aren't worth summarizing, although the bugs
287that they represent may be covered elsewhere.
288
289[ List each test improvement as a =item entry ]
4db91b87 290
5d8c8c8a 291=over 4
4db91b87
FC
292
293=item *
294
e14ac59b 295XXX
11e375e0 296
e14ac59b 297=back
11e375e0 298
e14ac59b 299=head1 Platform Support
11e375e0 300
e14ac59b 301XXX Any changes to platform support should be listed in the sections below.
11e375e0 302
e14ac59b
RS
303[ Within the sections, list each platform as a =item entry with specific
304changes as paragraphs below it. ]
11e375e0 305
e14ac59b 306=head2 New Platforms
11e375e0 307
e14ac59b
RS
308XXX List any platforms that this version of perl compiles on, that previous
309versions did not. These will either be enabled by new files in the F<hints/>
310directories, or new subdirectories and F<README> files at the top level of the
311source tree.
11e375e0 312
e14ac59b 313=over 4
11e375e0 314
e14ac59b 315=item XXX-some-platform
11e375e0 316
e14ac59b 317XXX
11e375e0 318
e14ac59b 319=back
11e375e0 320
e14ac59b 321=head2 Discontinued Platforms
11e375e0 322
e14ac59b 323=over 4
11e375e0 324
b6c36746 325=item BeOS
11e375e0 326
b6c36746 327Support for BeOS has been removed.
11e375e0 328
e14ac59b 329=back
11e375e0 330
e14ac59b 331=head2 Platform-Specific Notes
11e375e0 332
e14ac59b
RS
333XXX List any changes for specific platforms. This could include configuration
334and compilation changes or changes in portability/compatibility. However,
335changes within modules for platforms should generally be listed in the
336L</Modules and Pragmata> section.
11e375e0 337
e14ac59b 338=over 4
11e375e0 339
e14ac59b 340=item XXX-some-platform
11e375e0 341
e14ac59b 342XXX
11e375e0 343
e14ac59b 344=back
11e375e0 345
e14ac59b 346=head1 Internal Changes
11e375e0 347
e14ac59b
RS
348XXX Changes which affect the interface available to C<XS> code go here. Other
349significant internal changes for future core maintainers should be noted as
350well.
11e375e0 351
e14ac59b 352[ List each change as a =item entry ]
11e375e0 353
e14ac59b 354=over 4
11e375e0
FC
355
356=item *
357
463ea229
DM
358SvUPGRADE() is no longer an expression. Originally this macro (and its
359underlying function, sv_upgrade()) were documented as boolean, although
360in reality they always croaked on error and never returned false. In 2005
361the documentation was updated to specify a void return value, but
362SvUPGRADE() was left always returning 1 for backwards compatibility. This
363has now been removed, and SvUPGRADE() is now a statement with no return
364value.
365
366So this is now a syntax error:
367
368 if (!SvUPGRADE(sv)) { croak(...); }
369
370If you have code like that, simply replace it with
371
372 SvUPGRADE(sv);
e14ac59b 373
8b877d20
DM
374or to to avoid compiler warnings with older perls, possibly
375
376 (void)SvUPGRADE(sv);
377
e14ac59b
RS
378=back
379
380=head1 Selected Bug Fixes
381
382XXX Important bug fixes in the core language are summarized here. Bug fixes in
383files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
384
385[ List each fix as a =item entry ]
386
387=over 4
11e375e0
FC
388
389=item *
390
8b998a90
FC
391C<sort {undef} ...> under fatal warnings no longer crashes. It started
392crashing in Perl 5.16.
e14ac59b 393
fdea6f98
FC
394=item *
395
396Stashes blessed into each other
397(C<bless \%Foo::, 'Bar'; bless \%Bar::, 'Foo'>) no longer result in double
398frees. This bug started happening in Perl 5.16.
399
7cf3104f
FC
400=item *
401
402Numerous memory leaks have been fixed, mostly involving fatal warnings and
403syntax errors.
404
e14ac59b
RS
405=back
406
407=head1 Known Problems
408
409XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
410tests that had to be C<TODO>ed for the release would be noted here. Unfixed
411platform specific bugs also go here.
412
413[ List each fix as a =item entry ]
414
415=over 4
2d9cd31f 416
c9ac5216
FC
417=item *
418
e14ac59b 419XXX
c9ac5216 420
5d8c8c8a 421=back
4db91b87 422
e14ac59b
RS
423=head1 Obituary
424
425XXX If any significant core contributor has died, we've added a short obituary
426here.
427
916c45d9 428=head1 Acknowledgements
05bee12a 429
e14ac59b
RS
430XXX Generate this with:
431
432 perl Porting/acknowledgements.pl v5.17.6..HEAD
29cf780c 433
44691e6f
AB
434=head1 Reporting Bugs
435
e08634c5
SH
436If you find what you think is a bug, you might check the articles recently
437posted to the comp.lang.perl.misc newsgroup and the perl bug database at
438http://rt.perl.org/perlbug/ . There may also be information at
439http://www.perl.org/ , the Perl Home Page.
44691e6f 440
e08634c5
SH
441If you believe you have an unreported bug, please run the L<perlbug> program
442included with your release. Be sure to trim your bug down to a tiny but
443sufficient test case. Your bug report, along with the output of C<perl -V>,
444will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f
AB
445
446If the bug you are reporting has security implications, which make it
e08634c5
SH
447inappropriate to send to a publicly archived mailing list, then please send it
448to perl5-security-report@perl.org. This points to a closed subscription
449unarchived mailing list, which includes all the core committers, who will be
450able to help assess the impact of issues, figure out a resolution, and help
f9001595 451co-ordinate the release of patches to mitigate or fix the problem across all
e08634c5
SH
452platforms on which Perl is supported. Please only use this address for
453security issues in the Perl core, not for modules independently distributed on
454CPAN.
44691e6f
AB
455
456=head1 SEE ALSO
457
e08634c5
SH
458The F<Changes> file for an explanation of how to view exhaustive details on
459what changed.
44691e6f
AB
460
461The F<INSTALL> file for how to build Perl.
462
463The F<README> file for general stuff.
464
465The F<Artistic> and F<Copying> files for copyright information.
466
467=cut