pod/perldelta.pod

   1 =encoding utf8
   2
   3 =for to-do
   4 23b7025ebc definitely needs to be summarised.
   5
   6 =head1 NAME
   7
   8 [ this is a template for a new perldelta file.  Any text flagged as XXX needs
   9 to be processed before release. ]
  10
  11 perldelta - what is new for perl v5.17.7
  12
  13 =head1 DESCRIPTION
  14
  15 This document describes differences between the 5.17.6 release and the 5.17.7
  16 release.
  17
  18 If you are upgrading from an earlier release such as 5.17.5, first read
  19 L<perl5176delta>, which describes differences between 5.17.5 and 5.17.6.
  20
  21 =head1 Notice
  22
  23 XXX Any important notices here
  24
  25 =head1 Core Enhancements
  26
  27 =head2 $&, $` and $' are no longer slow
  28
  29 These three infamous variables have been redeemed and no longer slow down
  30 your program when used.  Hence, the /p regular expression flag now does
  31 nothing.
  32
  33 =head1 Security
  34
  35 XXX Any security-related notices go here.  In particular, any security
  36 vulnerabilities closed should be noted here rather than in the
  37 L</Selected Bug Fixes> section.
  38
  39 [ List each security issue as a =head2 entry ]
  40
  41 =head1 Incompatible Changes
  42
  43 =head2 readline() with C<$/ = \N> now reads N characters, not N bytes
  44
  45 Previously, when reading from a stream with I/O layers such as
  46 C<encoding>, the readline() function, otherwise known as the C<< <> >>
  47 operator, would read I<N> bytes from the top-most layer. [perl #79960]
  48
  49 Now, I<N> characters are read instead.
  50
  51 There is no change in behaviour when reading from streams with no
  52 extra layers, since bytes map exactly to characters.
  53
  54 =head2 Lexical subroutine warnings have moved
  55
  56 The warning about the use of an experimental feature emitted when lexical
  57 subroutines (added in 5.17.4) are used now happens when the subroutine
  58 itself is declared, not when the "lexical_subs" feature is activated via
  59 C<use feature>.
  60
  61 This stops C<use feature ':all'> from warning, but causes
  62 C<my sub foo; my sub bar> to warn twice.
  63
  64 =head2 Overridden C<glob> is now passed one argument
  65
  66 C<glob> overrides used to be passed a magical undocumented second argument
  67 that identified the caller.  Nothing on CPAN was using this, and it got in
  68 the way of a bug fix, so it was removed.  If you really need to identify
  69 the caller, see L<Devel::Callsite> on CPAN.
  70
  71 =head1 Deprecations
  72
  73 XXX Any deprecated features, syntax, modules etc. should be listed here.  In
  74 particular, deprecated modules should be listed here even if they are listed as
  75 an updated module in the L</Modules and Pragmata> section.
  76
  77 [ List each deprecation as a =head2 entry ]
  78
  79 =head2 Lexical $_ is now deprecated
  80
  81 Since it was introduced in Perl 5.10, it has caused much confusion with no
  82 obvious solution:
  83
  84 =over
  85
  86 =item *
  87
  88 Various modules (e.g., List::Util) expect callback routines to use the
  89 global $_.  C<use List::Util 'first'; my $_; first { $_ == 1 } @list> does
  90 not work as one would expect.
  91
  92 =item *
  93
  94 A C<my $_> declaration earlier in the same file can cause confusing closure
  95 warnings.
  96
  97 =item *
  98
  99 The "_" subroutine prototype character allows called subroutines to access
 100 your lexical $_, so it is not really private after all.
 101
 102 =item *
 103
 104 Nevertheless, subroutines with a "(@)" prototype and methods cannot access
 105 the caller's lexical $_, unless they are written in XS.
 106
 107 =item *
 108
 109 But even XS routines cannot access a lexical $_ declared, not in the
 110 calling subroutine, but in an outer scope, iff that subroutine happened not
 111 to mention $_ or use any operators that default to $_.
 112
 113 =back
 114
 115 =head2 Various XS-callable functions are now deprecated
 116
 117 The following functions will be removed from a future version of Perl,
 118 and should not be used.  With participating C compilers (e.g., gcc),
 119 compiling any file that uses any of these will generate a warning.
 120 These were not intended for public use; there are equivalent, faster,
 121 macros for most of them.  See L<perlapi/Character classes>:
 122 C<is_uni_ascii>,
 123 C<is_uni_ascii_lc>,
 124 C<is_uni_blank>,
 125 C<is_uni_blank_lc>,
 126 C<is_uni_cntrl>,
 127 C<is_uni_cntrl_lc>,
 128 C<is_uni_idfirst_lc>,
 129 C<is_uni_space>,
 130 C<is_uni_space_lc>,
 131 C<is_uni_xdigit>,
 132 C<is_uni_xdigit_lc>,
 133 C<is_utf8_ascii>,
 134 C<is_utf8_blank>,
 135 C<is_utf8_cntrl>,
 136 C<is_utf8_idcont>,
 137 C<is_utf8_idfirst>,
 138 C<is_utf8_perl_space>,
 139 C<is_utf8_perl_word>,
 140 C<is_utf8_posix_digit>,
 141 C<is_utf8_space>,
 142 C<is_utf8_xdigit>.
 143 C<is_utf8_xidcont>,
 144 C<is_utf8_xidfirst>,
 145 C<to_uni_lower_lc>,
 146 C<to_uni_title_lc>,
 147 and
 148 C<to_uni_upper_lc>.
 149
 150 =head1 Performance Enhancements
 151
 152 XXX Changes which enhance performance without changing behaviour go here.
 153 There may well be none in a stable release.
 154
 155 [ List each enhancement as a =item entry ]
 156
 157 =over 4
 158
 159 =item *
 160
 161 Perl has a new copy-on-write mechanism that avoids the need to copy the
 162 internal string buffer when assigning from one scalar to another.  This
 163 makes copying large strings appear much faster.  Modifying one of the two
 164 (or more) strings after an assignment will force a copy internally.  This
 165 makes it unnecessary to pass strings by reference for efficiency.
 166
 167 =back
 168
 169 =head1 Modules and Pragmata
 170
 171 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
 172 go here.  If Module::CoreList is updated, generate an initial draft of the
 173 following sections using F<Porting/corelist-perldelta.pl>, which prints stub
 174 entries to STDOUT.  Results can be pasted in place of the '=head2' entries
 175 below.  A paragraph summary for important changes should then be added by hand.
 176 In an ideal world, dual-life modules would have a F<Changes> file that could be
 177 cribbed.
 178
 179 [ Within each section, list entries as a =item entry ]
 180
 181 =head2 New Modules and Pragmata
 182
 183 =over 4
 184
 185 =item *
 186
 187 XXX
 188
 189 =back
 190
 191 =head2 Updated Modules and Pragmata
 192
 193 =over 4
 194
 195 =item *
 196
 197 L<File::DosGlob> has been upgraded from version 1.08 to 1.09.  The internal
 198 cache of file names that it keeps for each caller is now freed when that
 199 caller is freed.  This means
 200 C<< use File::DosGlob 'glob'; eval 'scalar <*>' >> no longer leaks memory.
 201
 202 =item *
 203
 204 L<File::Glob> has been upgraded from version 1.18 to 1.19.  File::Glob has
 205 had exactly the same fix as File::DosGlob.  Since it is what Perl's own
 206 C<glob> operator itself uses (except on VMS), this means
 207 C<< eval 'scalar <*>' >> no longer leaks.
 208
 209 =item *
 210
 211 L<GDBM_File> has been upgraded from version 1.14 to 1.15. The undocumented
 212 optional fifth parameter to C<TIEHASH> has been removed. This was intended
 213 to provide control of the callback used by C<gdbm*> functions in case of
 214 fatal errors (such as filesystem problems), but did not work (and could
 215 never have worked). No code on CPAN even attempted to use it. The callback
 216 is now always the previous default, C<croak>. Problems on some platforms with
 217 how the C<C> C<croak> function is called have also been resolved.
 218
 219 =back
 220
 221 =head2 Removed Modules and Pragmata
 222
 223 =over 4
 224
 225 =item *
 226
 227 XXX
 228
 229 =back
 230
 231 =head1 Documentation
 232
 233 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
 234 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
 235
 236 =head2 New Documentation
 237
 238 XXX Changes which create B<new> files in F<pod/> go here.
 239
 240 =head3 L<XXX>
 241
 242 XXX Description of the purpose of the new file here
 243
 244 =head2 Changes to Existing Documentation
 245
 246 XXX Changes which significantly change existing files in F<pod/> go here.
 247 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
 248 section.
 249
 250 =head3 L<perlapi/Character classes>
 251
 252 =over 4
 253
 254 =item *
 255
 256 There are quite a few macros callable from XS modules that classify
 257 characters into things like alphabetic, punctuation, etc.  More of these
 258 are now documented, including ones which work on characters whose code
 259 points are outside the Latin-1 range.
 260
 261 =back
 262
 263 =head1 Diagnostics
 264
 265 The following additions or changes have been made to diagnostic output,
 266 including warnings and fatal error messages.  For the complete list of
 267 diagnostic messages, see L<perldiag>.
 268
 269 XXX New or changed warnings emitted by the core's C<C> code go here.  Also
 270 include any changes in L<perldiag> that reconcile it to the C<C> code.
 271
 272 =head2 New Diagnostics
 273
 274 XXX Newly added diagnostic messages go under here, separated into New Errors
 275 and New Warnings
 276
 277 =head3 New Errors
 278
 279 =over 4
 280
 281 =item *
 282
 283 XXX L<message|perldiag/"message">
 284
 285 =back
 286
 287 =head3 New Warnings
 288
 289 =over 4
 290
 291 =item *
 292
 293 XXX L<message|perldiag/"message">
 294
 295 =back
 296
 297 =head2 Changes to Existing Diagnostics
 298
 299 XXX Changes (i.e. rewording) of diagnostic messages go here
 300
 301 =over 4
 302
 303 =item *
 304
 305 L<Constant(%s): Call to &{$^H{%s}} did not return a defined value|perldiag/Constant(%s): Call to &{$^H{%s}} did not return a defined value>
 306
 307 Constant overloading that returns C<undef> results in this error message.
 308 For numeric constants, it used to say "Constant(undef)".  "undef" has been
 309 replaced with the number itself.
 310
 311 =back
 312
 313 =head1 Utility Changes
 314
 315 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
 316 Most of these are built within the directories F<utils> and F<x2p>.
 317
 318 [ List utility changes as a =head3 entry for each utility and =item
 319 entries for each change
 320 Use L<XXX> with program names to get proper documentation linking. ]
 321
 322 =head3 L<XXX>
 323
 324 =over 4
 325
 326 =item *
 327
 328 XXX
 329
 330 =back
 331
 332 =head1 Configuration and Compilation
 333
 334 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
 335 go here.  Any other changes to the Perl build process should be listed here.
 336 However, any platform-specific changes should be listed in the
 337 L</Platform Support> section, instead.
 338
 339 [ List changes as a =item entry ].
 340
 341 =over 4
 342
 343 =item *
 344
 345 XXX
 346
 347 =back
 348
 349 =head1 Testing
 350
 351 XXX Any significant changes to the testing of a freshly built perl should be
 352 listed here.  Changes which create B<new> files in F<t/> go here as do any
 353 large changes to the testing harness (e.g. when parallel testing was added).
 354 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
 355 that they represent may be covered elsewhere.
 356
 357 [ List each test improvement as a =item entry ]
 358
 359 =over 4
 360
 361 =item *
 362
 363 XXX
 364
 365 =back
 366
 367 =head1 Platform Support
 368
 369 XXX Any changes to platform support should be listed in the sections below.
 370
 371 [ Within the sections, list each platform as a =item entry with specific
 372 changes as paragraphs below it. ]
 373
 374 =head2 New Platforms
 375
 376 XXX List any platforms that this version of perl compiles on, that previous
 377 versions did not.  These will either be enabled by new files in the F<hints/>
 378 directories, or new subdirectories and F<README> files at the top level of the
 379 source tree.
 380
 381 =over 4
 382
 383 =item XXX-some-platform
 384
 385 XXX
 386
 387 =back
 388
 389 =head2 Discontinued Platforms
 390
 391 =over 4
 392
 393 =item BeOS
 394
 395 Support for BeOS has been removed.
 396
 397 =back
 398
 399 =head2 Platform-Specific Notes
 400
 401 XXX List any changes for specific platforms.  This could include configuration
 402 and compilation changes or changes in portability/compatibility.  However,
 403 changes within modules for platforms should generally be listed in the
 404 L</Modules and Pragmata> section.
 405
 406 =over 4
 407
 408 =item XXX-some-platform
 409
 410 XXX
 411
 412 =back
 413
 414 =head1 Internal Changes
 415
 416 XXX Changes which affect the interface available to C<XS> code go here.  Other
 417 significant internal changes for future core maintainers should be noted as
 418 well.
 419
 420 [ List each change as a =item entry ]
 421
 422 =over 4
 423
 424 =item *
 425
 426 SvUPGRADE() is no longer an expression. Originally this macro (and its
 427 underlying function, sv_upgrade()) were documented as boolean, although
 428 in reality they always croaked on error and never returned false. In 2005
 429 the documentation was updated to specify a void return value, but
 430 SvUPGRADE() was left always returning 1 for backwards compatibility. This
 431 has now been removed, and SvUPGRADE() is now a statement with no return
 432 value.
 433
 434 So this is now a syntax error:
 435
 436     if (!SvUPGRADE(sv)) { croak(...); }
 437
 438 If you have code like that, simply replace it with
 439
 440     SvUPGRADE(sv);
 441
 442 or to to avoid compiler warnings with older perls, possibly
 443
 444     (void)SvUPGRADE(sv);
 445
 446 =item *
 447
 448 Perl has a new copy-on-write mechanism that allows any SvPOK scalar to be
 449 upgraded to a copy-on-write scalar.  A reference count on the string buffer
 450 is stored in the string buffer itself.
 451
 452 This breaks a few XS modules by allowing copy-on-write scalars to go
 453 through code paths that never encountered them before.
 454
 455 This behaviour can still be disabled by running F<Configure> with
 456 B<-Accflags=-DPERL_NO_COW>.  This option will probably be removed in Perl
 457 5.20.
 458
 459 =item *
 460
 461 Copy-on-write no longer uses the SvFAKE and SvREADONLY flags.  Hence,
 462 SvREADONLY indicates a true read-only SV.
 463
 464 Use the SvIsCOW macro (as before) to identify a copy-on-write scalar.
 465
 466 =item *
 467
 468 C<PL_sawampersand> is now a constant.  The switch this variable provided
 469 (to enable/disable the pre-match copy depending on whether C<$&> had been
 470 seen) has been removed and replaced with copy-on-write, eliminating a few
 471 bugs.
 472
 473 The previous behaviour can still be enabled by running F<Configure> with
 474 B<-Accflags=-DPERL_SAWAMPERSAND>.
 475
 476 =item *
 477
 478 PL_glob_index is gone.
 479
 480 =back
 481
 482 =head1 Selected Bug Fixes
 483
 484 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
 485 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
 486
 487 [ List each fix as a =item entry ]
 488
 489 =over 4
 490
 491 =item *
 492
 493 C<sort {undef} ...> under fatal warnings no longer crashes.  It started
 494 crashing in Perl 5.16.
 495
 496 =item *
 497
 498 Stashes blessed into each other
 499 (C<bless \%Foo::, 'Bar'; bless \%Bar::, 'Foo'>) no longer result in double
 500 frees.  This bug started happening in Perl 5.16.
 501
 502 =item *
 503
 504 Numerous memory leaks have been fixed, mostly involving fatal warnings and
 505 syntax errors.
 506
 507 =item *
 508
 509 Lexical constants (C<my sub answer () { 42 }>) no longer cause double
 510 frees.
 511
 512 =item *
 513
 514 Constant subroutine redefinition warns by default, but lexical constants
 515 were accidentally exempt from default warnings.  This has been corrected.
 516
 517 =item *
 518
 519 Some failed regular expression matches such as C<'f' =~ /../g> were not
 520 resetting C<pos>.  Also, "match-once" patterns (C<m?...?g>) failed to reset
 521 it, too, when invoked a second time [perl #23180].
 522
 523 =item *
 524
 525 Accessing C<$&> after a pattern match now works if it had not been seen
 526 before the match.  I.e., this applies to C<${'&'}> (under C<no strict>) and
 527 C<eval '$&'>.  The same applies to C<$'> and C<$`> [perl #4289].
 528
 529 =item *
 530
 531 Several bugs involving C<local *ISA> and C<local *Foo::> causing stale
 532 MRO caches have been fixed.
 533
 534 =item *
 535
 536 Defining a subroutine when its typeglob has been aliased no longer results
 537 in stale method caches.  This bug was introduced in Perl 5.10.
 538
 539 =item *
 540
 541 Localising a typeglob containing a subroutine when the typeglob's package
 542 has been deleted from its parent stash no longer produces an error.  This
 543 bug was introduced in Perl 5.14.
 544
 545 =item *
 546
 547 Under some circumstances, C<local *method=...> would fail to reset method
 548 caches upon scope exit.
 549
 550 =item *
 551
 552 C</[.foo.]/> is no longer an error, but produces a warning (as before) and
 553 is treated as C</[.fo]/> [perl #115818].
 554
 555 =item *
 556
 557 C<goto $tied_var> now calls FETCH before deciding what type of goto
 558 (subroutine or label) this is.
 559
 560 =item *
 561
 562 Renaming packages through glob assignment
 563 (C<*Foo:: = *Bar::; *Bar:: = *Baz::>) in combination with C<m?...?> and
 564 C<reset> no longer makes threaded builds crash.
 565
 566 =item *
 567
 568 An earlier release in the 5.17.x series could crash if user code prevented
 569 _charnames from loading via C<$INC{'_charnames.pm'}++>.
 570
 571 =back
 572
 573 =head1 Known Problems
 574
 575 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
 576 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
 577 platform specific bugs also go here.
 578
 579 [ List each fix as a =item entry ]
 580
 581 =over 4
 582
 583 =item *
 584
 585 XXX
 586
 587 =back
 588
 589 =head1 Obituary
 590
 591 XXX If any significant core contributor has died, we've added a short obituary
 592 here.
 593
 594 =head1 Acknowledgements
 595
 596 XXX Generate this with:
 597
 598   perl Porting/acknowledgements.pl v5.17.6..HEAD
 599
 600 =head1 Reporting Bugs
 601
 602 If you find what you think is a bug, you might check the articles recently
 603 posted to the comp.lang.perl.misc newsgroup and the perl bug database at
 604 http://rt.perl.org/perlbug/ .  There may also be information at
 605 http://www.perl.org/ , the Perl Home Page.
 606
 607 If you believe you have an unreported bug, please run the L<perlbug> program
 608 included with your release.  Be sure to trim your bug down to a tiny but
 609 sufficient test case.  Your bug report, along with the output of C<perl -V>,
 610 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
 611
 612 If the bug you are reporting has security implications, which make it
 613 inappropriate to send to a publicly archived mailing list, then please send it
 614 to perl5-security-report@perl.org.  This points to a closed subscription
 615 unarchived mailing list, which includes all the core committers, who will be
 616 able to help assess the impact of issues, figure out a resolution, and help
 617 co-ordinate the release of patches to mitigate or fix the problem across all
 618 platforms on which Perl is supported.  Please only use this address for
 619 security issues in the Perl core, not for modules independently distributed on
 620 CPAN.
 621
 622 =head1 SEE ALSO
 623
 624 The F<Changes> file for an explanation of how to view exhaustive details on
 625 what changed.
 626
 627 The F<INSTALL> file for how to build Perl.
 628
 629 The F<README> file for general stuff.
 630
 631 The F<Artistic> and F<Copying> files for copyright information.
 632
 633 =cut