This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Sync regcomp warn with reality.
[perl5.git] / pod / perldelta.pod
1 =head1 NAME
2
3 perldelta - what's new for perl5.006 (as of 5.005_56)
4
5 =head1 DESCRIPTION
6
7 This document describes differences between the 5.005 release and this one.
8
9 =head1 Incompatible Changes
10
11 =head2 Perl Source Incompatibilities
12
13 None known at this time.
14
15 =head2 C Source Incompatibilities
16
17 =over 4
18
19 =item C<PERL_POLLUTE>
20
21 Release 5.005 grandfathered old global symbol names by providing preprocessor
22 macros for extension source compatibility.  As of release 5.006, these
23 preprocessor definitions are not available by default.  You need to explicitly
24 compile perl with C<-DPERL_POLLUTE> to get these definitions.  For
25 extensions still using the old symbols, this option can be
26 specified via MakeMaker:
27
28     perl Makefile.PL POLLUTE=1
29
30 =item C<PERL_POLLUTE_MALLOC>
31
32 Enabling Perl's malloc in release 5.005 and earlier caused
33 the namespace of system versions of the malloc family of functions to
34 be usurped by the Perl versions, since by default they used the
35 same names.
36
37 Besides causing problems on platforms that do not allow these functions to
38 be cleanly replaced, this also meant that the system versions could not
39 be called in programs that used Perl's malloc.  Previous versions of Perl
40 have allowed this behaviour to be suppressed with the HIDEMYMALLOC and
41 EMBEDMYMALLOC preprocessor definitions.
42
43 As of release 5.006, Perl's malloc family of functions have default names
44 distinct from the system versions.  You need to explicitly compile perl with
45 C<-DPERL_POLLUTE_MALLOC> to get the older behaviour.  HIDEMYMALLOC
46 and EMBEDMYMALLOC have no effect, since the behaviour they enabled is now
47 the default.
48
49 Note that these functions do B<not> constitute Perl's memory allocation API.
50 See L<perlguts/"Memory Allocation"> for further information about that.
51
52 =item C<PL_na> and C<dTHR> Issues
53
54 The C<PL_na> global is now thread local, so a C<dTHR> declaration is needed
55 in the scope in which the global appears.  XSUBs should handle this automatically,
56 but if you have used C<PL_na> in support functions, you either need to
57 change the C<PL_na> to a local variable (which is recommended), or put in
58 a C<dTHR>.
59
60 =back
61
62 =head2 Compatible C Source API Changes
63
64 =over
65
66 =item C<PATCHLEVEL> is now C<PERL_VERSION>
67
68 The cpp macros C<PERL_REVISION>, C<PERL_VERSION>, and C<PERL_SUBVERSION>
69 are now available by default from perl.h, and reflect the base revision,
70 patchlevel, and subversion respectively.  C<PERL_REVISION> had no
71 prior equivalent, while C<PERL_VERSION> and C<PERL_SUBVERSION> were
72 previously available as C<PATCHLEVEL> and C<SUBVERSION>.
73
74 The new names cause less pollution of the B<cpp> namespace and reflect what
75 the numbers have come to stand for in common practice.  For compatibility,
76 the old names are still supported when F<patchlevel.h> is explicitly
77 included (as required before), so there is no source incompatibility
78 from the change.
79
80 =back
81
82 =head2 Binary Incompatibilities
83
84 This release is not binary compatible with the 5.005 release or its
85 maintenance versions.
86
87 =head1 Core Changes
88
89 =head2 Unicode and UTF-8 support
90
91 Perl can optionally use UTF-8 as its internal representation for character
92 strings.  The C<use utf8> pragma enables this support in the current lexical
93 scope.  See L<utf8> for more information.
94
95 =head2 Lexically scoped warning categories
96
97 You can now control the granularity of warnings emitted by perl at a finer
98 level using the C<use warning> pragma.  See L<warning> and L<perllexwarn>
99 for details.
100
101 =head2 Binary numbers supported
102
103 Binary numbers are now supported as literals, in s?printf formats, and
104 C<oct()>:
105
106     $answer = 0b101010;
107     printf "The answer is: %b\n", oct("0b101010");
108
109 =head2 syswrite() ease-of-use
110
111 The length argument of C<syswrite()> is now optional.
112
113 =head2 64-bit support
114
115 Better 64-bit support -- but full support still a distant goal.  One
116 must Configure with -Duse64bits to get Configure to probe for the
117 extent of 64-bit support.  Depending on the platform (hints file) more
118 or less 64-awareness becomes available.  As of 5.005_54 at least
119 somewhat 64-bit aware platforms are HP-UX 11 or better, Solaris 2.6 or
120 better, IRIX 6.2 or better.  Naturally 64-bit platforms like Digital
121 Unix and UNICOS also have 64-bit support.
122
123 =head2 Better syntax checks on parenthesized unary operators
124
125 TODO
126
127 =head2 POSIX character class syntax [: :] supported
128
129 For example to match alphabetic characters use /[[:alpha:]]/.
130 See L<perlre> for details.
131
132 Expressions such as:
133
134     print defined(&foo,&bar,&baz);
135     print uc("foo","bar","baz");
136     undef($foo,&bar);
137
138 used to be accidentally allowed in earlier versions, and produced
139 unpredictable behaviour.  Some produced ancillary warnings
140 when used in this way; others silently did the wrong thing.
141
142 The parenthesized forms of most unary operators that expect a single
143 argument now ensure that they are not called with more than one
144 argument, making the cases shown above syntax errors.  The usual
145 behaviour of:
146
147     print defined &foo, &bar, &baz;
148     print uc "foo", "bar", "baz";
149     undef $foo, &bar;
150
151 remains unchanged.  See L<perlop>.
152
153 =head2 Improved C<qw//> operator
154
155 The C<qw//> operator is now evaluated at compile time into a true list
156 instead of being replaced with a run time call to C<split()>.  This
157 removes the confusing misbehaviour of C<qw//> in scalar context, which
158 had inherited that behaviour from split().
159
160 Thus:
161
162     $foo = ($bar) = qw(a b c); print "$foo|$bar\n";
163
164 now correctly prints "3|a", instead of "2|a".
165
166 =head2 pack() format 'Z' supported
167
168 The new format type 'Z' is useful for packing and unpacking null-terminated
169 strings.  See L<perlfunc/"pack">.
170
171 =head2 pack() format modifier '!' supported
172
173 The new format type modifier '!' is useful for packing and unpacking
174 native shorts, ints, and longs.  See L<perlfunc/"pack">.
175
176 =head2 $^X variables may now have names longer than one character
177
178 Formerly, $^X was synonymous with ${"\cX"}, but $^XY was a syntax
179 error.  Now variable names that begin with a control character may be
180 arbitrarily long.  However, for compatibility reasons, these variables
181 I<must> be written with explicit braces, as C<${^XY}> for example.
182 C<${^XYZ}> is synonymous with ${"\cXYZ"}.  Variable names with more
183 than one control character, such as C<${^XY^Z}>, are illegal.
184
185 The old syntax has not changed.  As before, `^X' may be either a
186 literal control-X character or the two-character sequence `caret' plus
187 `X'.  When braces are omitted, the variable name stops after the
188 control character.  Thus C<"$^XYZ"> continues to be synonymous with
189 C<$^X . "YZ"> as before.
190
191 As before, lexical variables may not have names beginning with control
192 characters.  As before, variables whose names begin with a control
193 character are always forced to be in package `main'.  All such variables
194 are reserved for future extensions, except those that begin with
195 C<^_>, which may be used by user programs and is guaranteed not to
196 acquire special meaning in any future version of Perl.
197
198 =head1 Significant bug fixes
199
200 =head2 E<lt>HANDLEE<gt> on empty files
201
202 With C<$/> set to C<undef>, slurping an empty file returns a string of
203 zero length (instead of C<undef>, as it used to) the first time the
204 HANDLE is read.  Further reads yield C<undef>.
205
206 This means that the following will append "foo" to an empty file (it used
207 to do nothing):
208
209     perl -0777 -pi -e 's/^/foo/' empty_file
210
211 The behaviour of:
212
213     perl -pi -e 's/^/foo/' empty_file
214
215 is unchanged (it continues to leave the file empty).
216
217 =head2 C<eval '...'> improvements
218
219 Line numbers (as reflected by caller() and most diagnostics) within
220 C<eval '...'> were often incorrect when here documents were involved.
221 This has been corrected.
222
223 Lexical lookups for variables appearing in C<eval '...'> within
224 functions that were themselves called within an C<eval '...'> were
225 searching the wrong place for lexicals.  The lexical search now
226 correctly ends at the subroutine's block boundary.
227
228 Parsing of here documents used to be flawed when they appeared as
229 the replacement expression in C<eval 's/.../.../e'>.  This has
230 been fixed.
231
232 =head2 Automatic flushing of output buffers
233
234 fork(), exec(), system(), qx//, and pipe open()s now flush buffers
235 of all files opened for output when the operation
236 was attempted.  This mostly eliminates confusing 
237 buffering mishaps suffered by users unaware of how Perl internally
238 handles I/O.
239
240 =head2 Better diagnostics on meaningless filehandle operations
241
242 Constructs such as C<open(E<lt>FHE<gt>)> and C<close(E<lt>FHE<gt>)>
243 are compile time errors.  Attempting to read from filehandles that
244 were opened only for writing will now produce warnings (just as
245 writing to read-only filehandles does).
246
247 =head1 Supported Platforms
248
249 =over 4
250
251 =item *
252
253 VM/ESA is now supported.
254
255 =item *
256
257 Siemens BS2000 is now supported under the POSIX Shell.
258
259 =item *
260
261 The Mach CThreads (NEXTSTEP, OPENSTEP) are now supported by the Thread
262 extension.
263
264 =item *
265
266 GNU/Hurd is now supported.
267
268 =item *
269
270 Rhapsody is now supported.
271
272 =item *
273
274 EPOC is is now supported (on Psion 5).
275
276 =back
277
278 =head1 New tests
279
280 =over 4
281
282 =item   op/io_const
283
284 IO constants (SEEK_*, _IO*).
285
286 =item   op/io_dir
287
288 Directory-related IO methods (new, read, close, rewind, tied delete).
289
290 =item   op/io_multihomed
291
292 INET sockets with multi-homed hosts.
293
294 =item   op/io_poll
295
296 IO poll().
297
298 =item   op/io_unix
299
300 UNIX sockets.
301
302 =item   op/filetest
303
304 File test operators.
305
306 =item   op/lex_assign
307
308 Verify operations that access pad objects (lexicals and temporaries).
309
310 =back
311
312 =head1 Modules and Pragmata
313
314 =head2 Modules
315
316 =over 4
317
318 =item Dumpvalue
319
320 Added Dumpvalue module provides screen dumps of Perl data.
321
322 =item Benchmark
323
324 You can now run tests for I<n> seconds instead of guessing the right
325 number of tests to run: e.g. timethese(-5, ...) will run each 
326 code for at least 5 CPU seconds.  Zero as the "number of repetitions"
327 means "for at least 3 CPU seconds".  The output format has also
328 changed.  For example:
329
330 use Benchmark;$x=3;timethese(-5,{a=>sub{$x*$x},b=>sub{$x**2}})
331
332 will now output something like this:
333
334 Benchmark: running a, b, each for at least 5 CPU seconds...
335          a:  5 wallclock secs ( 5.77 usr +  0.00 sys =  5.77 CPU) @ 200551.91/s (n=1156516)
336          b:  4 wallclock secs ( 5.00 usr +  0.02 sys =  5.02 CPU) @ 159605.18/s (n=800686)
337
338 New features: "each for at least N CPU seconds...", "wallclock secs",
339 and the "@ operations/CPU second (n=operations)".
340
341 =item Devel::Peek
342
343 The Devel::Peek module provides access to the internal representation
344 of Perl variables and data.  It is a data debugging tool for the XS programmer.
345
346 =item Fcntl
347
348 More Fcntl constants added: F_SETLK64, F_SETLKW64, O_LARGEFILE for
349 large (more than 4G) file access (64-bit support is not yet
350 working, though, so no need to get overly excited), Free/Net/OpenBSD
351 locking behaviour flags F_FLOCK, F_POSIX, Linux F_SHLCK, and
352 O_ACCMODE: the mask of O_RDONLY, O_WRONLY, and O_RDWR.
353
354 =item File::Spec
355
356 New methods have been added to the File::Spec module: devnull() returns
357 the name of the null device (/dev/null on Unix) and tmpdir() the name of
358 the temp directory (normally /tmp on Unix).  There are now also methods
359 to convert between absolute and relative filenames: abs2rel() and
360 rel2abs().  For compatibility with operating systems that specify volume
361 names in file paths, the splitpath(), splitdir(), and catdir() methods
362 have been added.
363
364 =item File::Spec::Functions
365
366 The new File::Spec::Functions modules provides a function interface
367 to the File::Spec module.  Allows shorthand
368
369     $fullname = catfile($dir1, $dir2, $file);
370
371 instead of
372
373     $fullname = File::Spec->catfile($dir1, $dir2, $file);
374
375 =item Math::BigInt
376
377 The logical operations C<E<lt>E<lt>>, C<E<gt>E<gt>>, C<&>, C<|>,
378 and C<~> are now supported on bigints.
379
380 =item Math::Complex
381
382 The accessor methods Re, Im, arg, abs, rho, and theta can now also
383 act as mutators (accessor $z->Re(), mutator $z->Re(3)).
384
385 =item Math::Trig
386
387 A little bit of radial trigonometry (cylindrical and spherical),
388 radial coordinate conversions, and the great circle distance were added.
389
390 =item SDBM_File
391
392 An EXISTS method has been added to this module (and sdbm_exists() has
393 been added to the underlying sdbm library), so one can now call exists
394 on an SDBM_File tied hash and get the correct result, rather than a
395 runtime error.
396
397 =item Time::Local
398
399 The timelocal() and timegm() functions used to silently return bogus
400 results when the date exceeded the machine's integer range.  They
401 now consistently croak() if the date falls in an unsupported range.
402
403 =item Win32
404
405 The error return value in list context has been changed for all functions
406 that return a list of values.  Previously these functions returned a list
407 with a single element C<undef> if an error occurred.  Now these functions
408 return the empty list in these situations.  This applies to the following
409 functions:
410
411     Win32::FsType
412     Win32::GetOSVersion
413
414 The remaining functions are unchanged and continue to return C<undef> on
415 error even in list context.
416
417 The Win32::SetLastError(ERROR) function has been added as a complement
418 to the Win32::GetLastError() function.
419
420 The new Win32::GetFullPathName(FILENAME) returns the full absolute
421 pathname for FILENAME in scalar context.  In list context it returns
422 a two-element list containing the fully qualified directory name and
423 the filename.
424
425 =item DBM Filters
426
427 A new feature called "DBM Filters" has been added to all the
428 DBM modules--DB_File, GDBM_File, NDBM_File, ODBM_File, and SDBM_File.
429 DBM Filters add four new methods to each DBM module:
430
431     filter_store_key
432     filter_store_value
433     filter_fetch_key
434     filter_fetch_value
435
436 These can be used to filter key-value pairs before the pairs are
437 written to the database or just after they are read from the database.
438 See L<perldbmfilter> for further information.
439
440 =back
441
442 =head2 Pragmata
443
444 C<use utf8> to enable UTF-8 and Unicode support.
445
446 C<use caller 'encoding'> allows modules to inherit pragmatic attributes
447 from the caller's context.  C<encoding> is currently the only supported
448 attribute.
449
450 Lexical warnings pragma, C<use warning;>, to control optional warnings.
451
452 C<use filetest> to control the behaviour of filetests (C<-r> C<-w> ...).
453 Currently only one subpragma implemented, "use filetest 'access';",
454 that enables the use of access(2) or equivalent to check
455 permissions instead of using stat(2) as usual.  This matters
456 in filesystems where there are ACLs (access control lists): the
457 stat(2) might lie, but access(2) knows better.
458
459 =head1 Utility Changes
460
461 Todo.
462
463 =head1 Documentation Changes
464
465 =over 4
466
467 =item perlopentut.pod
468
469 A tutorial on using open() effectively.
470
471 =item perlreftut.pod
472
473 A tutorial that introduces the essentials of references.
474
475 =item perltootc.pod
476
477 A tutorial on managing class data for object modules.
478
479 =back
480
481 =head1 New Diagnostics
482
483 =item /%s/: Unrecognized escape \\%c passed through
484
485 (W) You used a backslash-character combination which is not recognized
486 by Perl.  This combination appears in an interpolated variable or a
487 C<'>-delimited regular expression.
488
489 =item Filehandle %s opened only for output
490
491 (W) You tried to read from a filehandle opened only for writing.  If you
492 intended it to be a read-write filehandle, you needed to open it with
493 "+E<lt>" or "+E<gt>" or "+E<gt>E<gt>" instead of with "E<lt>" or nothing.  If
494 you intended only to read from the file, use "E<lt>".  See
495 L<perlfunc/open>.
496
497 =item Missing command in piped open
498
499 (W) You used the C<open(FH, "| command")> or C<open(FH, "command |")>
500 construction, but the command was missing or blank.
501
502 =item Unrecognized escape \\%c passed through
503
504 (W) You used a backslash-character combination which is not recognized
505 by Perl.
506
507 =item defined(@array) is deprecated
508
509 (D) defined() is not usually useful on arrays because it checks for an
510 undefined I<scalar> value.  If you want to see if the array is empty,
511 just use C<if (@array) { # not empty }> for example.  
512
513 =item defined(%hash) is deprecated
514
515 (D) defined() is not usually useful on hashes because it checks for an
516 undefined I<scalar> value.  If you want to see if the hash is empty,
517 just use C<if (%hash) { # not empty }> for example.  
518
519 =head1 Obsolete Diagnostics
520
521 Todo.
522
523 =head1 Configuration Changes
524
525 =head2 installusrbinperl
526
527 You can use "Configure -Uinstallusrbinperl" which causes installperl
528 to skip installing perl also as /usr/bin/perl.  This is useful if you
529 prefer not to modify /usr/bin for some reason or another but harmful
530 because many scripts assume to find Perl in /usr/bin/perl.
531
532 =head2 SOCKS support
533
534 You can use "Configure -Dusesocks" which causes Perl to probe
535 for the SOCKS proxy protocol library, http://www.socks.nec.com/
536
537 =head1 BUGS
538
539 If you find what you think is a bug, you might check the headers of
540 articles recently posted to the comp.lang.perl.misc newsgroup.
541 There may also be information at http://www.perl.com/perl/, the Perl
542 Home Page.
543
544 If you believe you have an unreported bug, please run the B<perlbug>
545 program included with your release.  Make sure to trim your bug down
546 to a tiny but sufficient test case.  Your bug report, along with the
547 output of C<perl -V>, will be sent off to perlbug@perl.com to be
548 analysed by the Perl porting team.
549
550 =head1 SEE ALSO
551
552 The F<Changes> file for exhaustive details on what changed.
553
554 The F<INSTALL> file for how to build Perl.
555
556 The F<README> file for general stuff.
557
558 The F<Artistic> and F<Copying> files for copyright information.
559
560 =head1 HISTORY
561
562 Written by Gurusamy Sarathy <F<gsar@umich.edu>>, with many contributions
563 from The Perl Porters.
564
565 Send omissions or corrections to <F<perlbug@perl.com>>.
566
567 =cut