perl5133delta.pod: editorial changes and cleanup
[perl.git] / pod / perl5132delta.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 perl5132delta - what is new for perl v5.13.2
6
7 =head1 DESCRIPTION
8
9 This document describes differences between the 5.13.2 release and
10 the 5.13.1 release.
11
12 If you are upgrading from an earlier release such as 5.10, first read
13 L<perl5120delta>, which describes differences between 5.10 and
14 5.12.
15
16 =head1 Incompatible Changes
17
18 =head2 localised tied scalars are tied again.
19
20 The change in behaviour in 5.13.1 of localising tied scalar values has
21 been reverted to the existing 5.12.0 and earlier behaviour (the change for
22 arrays and hashes remains).
23
24 =head2 Naming fixes in Policy_sh.SH may invalidate Policy.sh
25
26 Several long-standing typos and naming confusions in Policy_sh.SH have
27 been fixed, standardizing on the variable names used in config.sh.
28
29 This will change the behavior of Policy.sh if you happen to have been
30 accidentally relying on the Policy.sh incorrect behavior. We'd appreciate
31 feedback from anyone using Policy.sh to be sure nothing is broken by
32 this change (c1bd23).
33
34 =head2 Stashes are now always defined
35
36 C<defined %Foo::> now always returns true, even when no symbols have yet been
37 defined in that package.
38
39 This is a side effect of removing a special case kludge in the tokeniser,
40 added for 5.10.0, to hide side effects of changes to the internal storage of
41 hashes that to drastically reduce their memory usage overhead.
42
43 Calling defined on a stash has been deprecated since 5.6.0, warned on
44 lexicals since 5.6.0, and has warned for stashes (and other package
45 variables) since 5.12.0. C<defined %hash> has always exposed an
46 implementation detail - emptying a hash by deleting all entries from it does
47 not make C<defined %hash> false, hence C<defined %hash> is not valid code to
48 determine whether an arbitrary hash is empty. Instead, use the behaviour
49 that an empty <%hash> always returns false in a scalar context.
50
51 =head1 Core Enhancements
52
53 =head2 Non-destructive substitution
54
55 The substitution operator now supports a C</r> option that
56 copies the input variable, carries out the substitution on
57 the copy and returns the result.  The original remains unmodified.
58
59   my $old = 'cat';
60   my $new = $old =~ s/cat/dog/r;
61   # $old is 'cat' and $new is 'dog'
62
63 This is particularly useful with C<map>.  See L<perlop> for more examples
64 (4f4d75, 000c65).
65
66 =head2 package block syntax
67
68 A package declaration can now contain a code block, in which case the
69 declaration is in scope only inside that block.  So C<package Foo { ... }>
70 is precisely equivalent to C<{ package Foo; ... }>.  It also works with
71 a version number in the declaration, as in C<package Foo 1.2 { ... }>.
72 See L<perlfunc> (434da3..36f77d, 702646).
73
74 =head2 CLONE_PARAMS structure added to ease correct thread creation
75
76 Modules that create threads should now create C<CLONE_PARAMS> structures
77 by calling the new function C<Perl_clone_params_new()>, and free them with
78 C<Perl_clone_params_del()>. This will ensure compatibility with any future
79 changes to the internals of the C<CLONE_PARAMS> structure layout, and that
80 it is correctly allocated and initialised.
81
82 =head2 perl -h no longer recommends -w
83
84 perl -h used to mark the -w option as recommended; since this option is
85 far less useful than it used to be due to lexical 'use warnings' and since
86 perl -h is primary a list and brief explanation of the command line switches,
87 the recommendation has now been removed (60eaec).
88
89 =head1 Modules and Pragmata
90
91 =head2 Updated Modules
92
93 =head3 Locale-Codes 3.13
94
95 Locale::Country, Locale::Language and Locale::Currency were updated from
96 3.12 to 3.13 of the Locale-Codes distribution to include locale code changes
97 (e1137b).
98
99 =head3 Thread-Semaphore 2.11
100
101 Added new methods -E<gt>down_nb() and -E<gt>down_force() at the suggestion
102 of Rick Garlick.
103
104 Refactored methods to skip argument validation when no argument is supplied.
105
106 (04febe, f06daa)
107
108 =head3 CPAN.pm 1.94_57
109
110 =over 4
111
112 =item * release 1.94_57
113
114 =item * bugfix: treat modules correctly that are deprecated in perl 5.12.
115
116 =item * bugfix: RT #57482 and #57788 revealed that configure_requires
117 implicitly assumed build_requires instead of normal requires. (Reported
118 by Andrew Whatson and Father Chrysostomos respectively)
119
120 =item * testfix: solaris should run the tests without expect because (some?)
121 solaris have a broken expect 
122
123 =item * testfix: run tests with cache_metadata off to prevent spill over
124 effects from previous test runs
125
126 =back
127
128 (742adb)
129
130 =head3 Hash::Util warning fix
131
132 Hash::Util now enables "no warnings 'uninitialized'" to suppress spurious
133 warnings from undefined hash values (RT #74280).
134
135 =head3 B::Deparse now handles 'no VERSION'
136
137 The 'no 5.13.2' or similar form is now correctly handled by B::Deparse.
138
139 =head3 IO::Socket doc additions
140
141 getsockopt and setsockopt are now documented.
142
143 =head3 B::Concise updated for OPpDEREF
144
145 B::Concise marks rv2sv, rv2av and rv2hv ops with the new OPpDEREF flag
146 as "DREFed".
147
148 =head3 File::Copy doc clarification
149
150 An extra stanza was added explaining behaviours when the copy destination
151 already exists and is a directory.
152
153 =head3 Multiple POD spelling fixes.
154
155 Fixes were made to VMS::DCLsym, mro, Search::Dist, B::t::OptreeCheck
156 and UNIVERSAL.
157
158 =head1 Changes to Existing Documentation
159
160 =head2 Replace wrong tr/// table in perlebcdic.pod
161
162 perlebcdic.pod contains a helpful table to use in tr/// to convert
163 between EBCDIC and Latin1/ASCII.  Unfortunately, the table was the
164 inverse of the one it describes, though the code that used the table
165 worked correctly for the specific example given.
166
167 The table has been changed to its inverse, and the sample code changed
168 to correspond, as this is easier for the person trying to follow the
169 instructions since deriving the old table is somewhat more complicated.
170
171 The table has also been changed to hex from octal, as that is more the norm
172 these days, and the recipes in the pod altered to print out leading
173 zeros to make all the values the same length, as the table that they can
174 generate has them (5f26d5).
175
176 =head2 Document tricks for user-defined casing
177
178 perlunicode.pod now contains an explanation of how to override, mangle
179 and otherwise tweak the way perl handles upper, lower and other case
180 conversions on unicode data, and how to provide scoped changes to alter
181 one's own code's behaviour without stomping on anybody else (71648f).
182
183 =head2 Document $# and $* as removed and clarify $#array usage
184
185 $# and $* were both disabled as of perl5 version 10; this release adds
186 documentation to that effect, a description of the results of continuing
187 to try and use them, and a note explaining that $# can also function as a
188 sigil in the $#array form (7f315d2).
189
190 =head2 INSTALL explicitly states the requirement for C89
191
192 This was already true but it's now Officially Stated For The Record (51eec7).
193
194 =head2 No longer advertise Math::TrulyRandom
195
196 This module hasn't been updated since 1996 so we can't recommend it any more
197 (83918a).
198
199 =head2 perlfaq synchronised to upstream
200
201 The FAQ has been updated to commit
202 37550b8f812e591bcd0dd869d61677dac5bda92c from the perlfaq repository
203 at git@github.com:briandfoy/perlfaq.git
204
205 =head1 Performance Enhancements
206
207 Only allocate entries for @_ on demand - this not only saves memory per
208 subroutine defined but should hopefully improve COW behaviour (77bac2).
209
210 =head2 Multiple small improvements to threads
211
212 The internal structures of threading now make fewer API calls and fewer
213 allocations, resulting in noticeably smaller object code. Additionally,
214 many thread context checks have been deferred so that they're only done
215 when required (although this is only possible for non-debugging builds).
216
217 =head2 Size optimisations to SV and HV structures
218
219 xhv_fill has been eliminated from struct xpvhv, saving 1 IV per hash and
220 on some systems will cause struct xpvhv to become cache aligned. To avoid
221 this memory saving causing a slowdown elsewhere, boolean use of HvFILL
222 now calls HvTOTALKEYS instead (which is equivalent) - so while the fill
223 data when actually required is now calculated on demand, the cases when
224 this needs to be done should be few and far between (f4431c .. fcd245).
225
226 The order of structure elements in SV bodies has changed. Effectively,
227 the NV slot has swapped location with STASH and MAGIC. As all access to
228 SV members is via macros, this should be completely transparent. This
229 change allows the space saving for PVHVs documented above, and may reduce
230 the memory allocation needed for PVIVs on some architectures.
231
232 =head2 Optimisation of regexp engine string comparison work
233
234 The foldEQ_utf8 API function for case-insensitive comparison of strings (which
235 is used heavily by the regexp engine) was substantially refactored and
236 optimised - and its documentation much improved as a free bonus gift
237 (8b3587, e6226b).
238
239 =head2 Memory consumption improvements to Exporter
240
241 The @EXPORT_FAIL AV is no longer created unless required, hence neither is
242 the typeglob backing it - this saves about 200 bytes per Exporter using
243 package that doesn't use this functionality.
244
245 =head1 Installation and Configuration Improvements
246
247 =head2 Compilation improvements
248
249 Fix CCINCDIR and CCLIBDIR for mingw64 cross compiler to correctly be under
250 $(CCHOME)\mingw\include and \lib rather than immediately below $(CCHOME).
251
252 This means the 'incpath', 'libpth', 'ldflags', 'lddlflags' and
253 'ldflags_nolargefiles' values in Config.pm and Config_heavy.pl are now
254 set correctly (23ae7f).
255
256 =head1 Selected Bug Fixes
257
258 =over 4
259
260 =item * Timely cleanup of SVs that are cloned into a new thread but then
261 discovered to be orphaned (i.e. their owners are -not- cloned) (e42956)
262
263 =item * Don't accidentally clone lexicals in scope within active stack frames in
264 the parent when creating a child thread (RT #73086) (05d04d).
265
266 =item * Avoid loading feature.pm when 'no 5.13.2;' or similar is
267 encountered (faee19).
268
269 =item * Trap invalid use of SvIVX on SVt_REGEXP when assertions are on
270 (e77da3)
271
272 =item * Don't stamp on $DB::single, $DB::trace and $DB::signal if they
273 already have values when $^P is assigned to (RT #72422) (4c0f30).
274
275 =item * chop now correctly handles perl's extended UTF-8 (RT #73246) (65ab92)
276
277 =item * Defer signal handling when shared SV locks are held to avoid
278 deadlocks (RT #74868) (65c742).
279
280 =item * glob() no longer crashes when %File::Glob:: is empty and
281 CORE::GLOBAL::glob isn't present (4984aa).
282
283 =item * perlbug now always permits the sender address to be changed
284 before sending - if you were having trouble sending bug reports before
285 now, this should fix it, we hope (e6eb90).
286
287 =item * Overloading now works properly in conjunction with tied
288 variables. What formerly happened was that most ops checked their
289 arguments for overloading I<before> checking for magic, so for example
290 an overloaded object returned by a tied array access would usually be
291 treated as not overloaded (RT #57012) (6f1401, ed3b9b, 6a5f8c .. 24328f).
292
293 =item * Independently, a bug was fixed that prevented $tied-E<gt>() from
294 always calling FETCH correctly (RT #8438) (7c7501)
295
296 =back
297
298 =head1 Changed Internals
299
300 =over 4
301
302 =item * The implementation of sv_dup_inc() has changed from a macro to a function.
303
304 =item *
305
306 The C<find_rundefsvoffset> function has been deprecated. It appeared that
307 its design was insufficient to reliably get the lexical C<$_> at run-time.
308
309 Use the new C<find_rundefsv> function or the C<UNDERBAR> macro instead.
310 They directly return the right SV representing C<$_>, whether it's lexical
311 or dynamic (789bd8 .. 03d5bc).
312
313 =item *
314
315 The following new functions or macros have been added to the public API:
316 C<SvNV_nomg>,  C<sv_2nv_flags>, C<find_rundefsv>.
317
318 =item *
319
320 The C<UNDERBAR> macro now calls C<find_rundefsv>. C<dUNDERBAR> is now a
321 noop but should still be used to ensure past and future compatibility.
322
323 =item *
324
325 The ibcmp_* functions have been renamed and are now called foldEQ,
326 foldEQ_locale and foldEQ_utf8 (e6226b).
327
328 =back
329
330 =head1 Deprecations
331
332 The following items are now deprecated.
333
334 =over 4
335
336 =item *
337
338 Omitting a space between a regex pattern or pattern modifiers and the following
339 word is deprecated.  For example, C<< m/foo/sand $bar >> will still be parsed
340 as C<< m/foo/s and $bar >> but will issue a warning.
341
342 =back
343
344 =head1 Platform Specific Notes
345
346 =head2 Recent OpenBSDs now use perl's malloc
347
348 OpenBSD E<gt> 3.7 has a new malloc implementation which is mmap based
349 and as such can release memory back to the OS; however for perl using
350 this malloc causes a substantial slowdown so we now default to using
351 perl's malloc instead (RT #75742) (9b58b5).
352
353 =head1 Acknowledgements
354
355 Perl 5.13.2 represents thirty days of development since Perl 5.13.1 (and
356 two days of waiting around while the release manager remembered where he
357 left his brain) and contains 3685 lines of changes across 194 files from
358 30 authors and committers.
359
360 Thank you to the following for contributing to this release:
361
362 Abigail, Andreas J. Koenig, Chas. Owens, Chris 'BinGOs' Williams,
363 Craig A. Berry, David Caldwell, David Golden, David Mitchell,
364 Father Chrysostomos, George Greer, H.Merijn Brand, Jerry D. Hedden,
365 Karl Williamson, Maik Hentsche, Matt S Trout, Nicholas Clark, Rafael
366 Garcia-Suarez, Ricardo Signes, Salvador Fandino, Salvador Ortiz Garcia,
367 Shlomi Fish, Sinan Unur, Sisyphus, Slaven Rezic, Sullivan Beck, Tony Cook,
368 Vincent Pit, Zefram, brian d foy, Ævar Arnfjörð Bjarmason
369
370 Your humble release manager would like to specifically call out
371 Karl Williamson for making the tests a better place to be, and Shlomi
372 Fish for a passel of tiny incremental docfixes of the sort that don't get
373 made often enough.
374
375 =head1 Reporting Bugs
376
377 If you find what you think is a bug, you might check the articles
378 recently posted to the comp.lang.perl.misc newsgroup and the perl
379 bug database at http://rt.perl.org/perlbug/ .  There may also be
380 information at http://www.perl.org/ , the Perl Home Page.
381
382 If you believe you have an unreported bug, please run the B<perlbug>
383 program included with your release.  Be sure to trim your bug down
384 to a tiny but sufficient test case.  Your bug report, along with the
385 output of C<perl -V>, will be sent off to perlbug@perl.org to be
386 analysed by the Perl porting team.
387
388 If the bug you are reporting has security implications, which make it
389 inappropriate to send to a publicly archived mailing list, then please send
390 it to perl5-security-report@perl.org. This points to a closed subscription
391 unarchived mailing list, which includes all the core committers, who be able
392 to help assess the impact of issues, figure out a resolution, and help
393 co-ordinate the release of patches to mitigate or fix the problem across all
394 platforms on which Perl is supported. Please only use this address for
395 security issues in the Perl core, not for modules independently
396 distributed on CPAN.
397
398 =head1 SEE ALSO
399
400 The F<Changes> file for an explanation of how to view exhaustive details
401 on what changed.
402
403 The F<INSTALL> file for how to build Perl.
404
405 The F<README> file for general stuff.
406
407 The F<Artistic> and F<Copying> files for copyright information.
408
409 =cut