diff options
| author | Perl 5 Porters <perl5-porters@africa.nicoh.com> | 1997-01-25 15:58:00 +1200 |
|---|---|---|
| committer | Chip Salzenberg <chip@atlantic.net> | 1997-01-25 15:58:00 +1200 |
| commit | 774d564bb7dd1ed64ca0d7e534aa67e93f991f02 (patch) | |
| tree | 2e8fac95be59aed598a9217a2911632612d07854 /pod | |
| parent | 9e3a2af888982d0a201149cbcdbf3feb6771acb4 (diff) | |
| parent | bbad36071d5a6d4be3588f0f10c88247439076d8 (diff) | |
| download | perl-774d564bb7dd1ed64ca0d7e534aa67e93f991f02.tar.gz | |
[inseparable changes from patch from perl5.003_22 to perl5.003_23]perl-5.003_23
BUILD PROCESS
Subject: Make configure.gnu a copy of configure; make configure writea
From: Chip Salzenberg <chip@atlantic.net>
Files: MANIFEST configure.gnu
Subject: Regen Configure with metaconfig: +ARCHNAME, -FILE_filbuf
From: Chip Salzenberg <chip@perl.com>
Files: Configure config_H config_h.SH hints/lynxos.sh os2/diff.configure os2/os2ish.h plan9/config.plan9 sv.c utils/perlbug.PL vms/config.vms vms/fndvers.com
Subject: Compile with optimization when testing memory functions
From: Chip Salzenberg <chip@atlantic.net>
Files: Configure
CORE LANGUAGE CHANGES
Subject: Disallow changing $_[0] in __DIE__ handlers
From: Chip Salzenberg <chip@atlantic.net>
Files: pod/perlfunc.pod util.c
Subject: Fix overloading with inheritance and AUTOLOAD
Date: Mon, 20 Jan 1997 17:26:32 -0500 (EST)
From: Ilya Zakharevich <ilya@math.ohio-state.edu>
Files: gv.c lib/diagnostics.pm lib/overload.pm pod/perldebug.pod pod/perldiag.pod pod/perlfunc.pod pod/perlop.pod pod/perlre.pod pod/perltoc.pod pod/perlxs.pod
Msg-ID: <199701202226.RAA05072@monk.mps.ohio-state.edu>
(applied based on p5p patch as commit e7ea3e70155d0bea30720ba41eb6bb6742aac0d1)
Subject: Nested here-docs
Date: Mon, 20 Jan 1997 15:13:42 -0800
From: Larry Wall <larry@wall.org>
Files: toke.c
Msg-ID: <199701202313.PAA11693@wall.org>
(applied based on p5p patch as commit fd2d0953290ddd46f0820dbd6c87245486b7ab28)
Subject: Revert $^X to old behavior (plus HP-UX bug fix)
From: Chip Salzenberg <chip@atlantic.net>
Files: hints/hpux.sh toke.c
Subject: Protect against '0' in 'stmt while <HANDLE>'
From: Chip Salzenberg <chip@atlantic.net>
Files: op.c
Subject: Don't warn when closure uses var at file scope
From: Chip Salzenberg <chip@atlantic.net>
Files: op.c
CORE PORTABILITY
Subject: VMS patches for _22
Date: Mon, 20 Jan 1997 22:50:21 -0500 (EST)
From: Charles Bailey <bailey@HMIVAX.HUMGEN.UPENN.EDU>
Files: ext/POSIX/POSIX.xs lib/ExtUtils/MM_VMS.pm lib/ExtUtils/xsubpp lib/Test/Harness.pm toke.c vms/Makefile vms/descrip.mms vms/genconfig.pl vms/perly_c.vms vms/vmsish.h x2p/a2p.h vms/Makefile vms/config.vms vms/descrip.mms vms/perly_c.vms
private-msgid: <01IEGBJ2TMYS003PCL@hmivax.humgen.upenn.edu>
Subject: Plan9 update
From: Luther Huffman <lutherh@stratcom.com>
Files: plan9/config.plan9 plan9/mkfile
Subject: hints & Configure changes to build perl on DC/OSx
Date: Thu, 16 Jan 1997 16:43:52 -0800
From: Stephen Zander <stephen.zander@interlock.mckesson.com>
Files: Configure MANIFEST hints/dcosx.sh
Msg-ID: <199701170043.QAA25985@wsbip1.mckesson.com>
(applied based on p5p patch as commit 23f8769697279d7912be5943de9fdf93f6aa3013)
DOCUMENTATION
Subject: Additional docs for __DIE__ and __WARN__
From: Gurusamy Sarathy <gsar@engin.umich.edu>
Files: pod/perlfunc.pod pod/perlrun.pod pod/perlvar.pod
Subject: Document #line directive
Date: Fri, 24 Jan 1997 04:08:44 -0500
From: Gurusamy Sarathy <gsar@engin.umich.edu>
Files: pod/perlsyn.pod pod/perltoc.pod
private-msgid: <199701240908.EAA23846@aatma.engin.umich.edu>
Subject: delta for perldelta
Date: Fri, 24 Jan 1997 07:57:43 -0800
From: Tom Christiansen <tchrist@mox.perl.com>
Files: pod/perlnews.pod pod/perltoc.pod
private-msgid: <804.854121463@jinete>
Subject: Updates to perldelta
Date: Mon, 20 Jan 1997 06:48:49 -0500 (EST)
From: Ilya Zakharevich <ilya@math.ohio-state.edu>
Files: pod/perlnews.pod pod/perltoc.pod
private-msgid: <199701211610.LAA06227@monk.mps.ohio-state.edu>
Subject: perlnews.pod diff for the Fcntl
Date: Tue, 21 Jan 1997 18:00:56 +0200 (EET)
From: Jarkko Hietaniemi <jhi@cc.hut.fi>
Files: pod/perlnews.pod
private-msgid: <199701211600.SAA30117@alpha.hut.fi>
Subject: Rename perlnews -> perldelta per Tom's request
From: Chip Salzenberg <chip@atlantic.net>
Files: MANIFEST pod/Makefile pod/buildtoc pod/perl.pod pod/perldelta.pod pod/perltoc.pod pod/roffitall
LIBRARY AND EXTENSIONS
Subject: Refresh IO to 1.15 (plus DESTROY and new_tmpfile fixes)
From: Chip Salzenberg <chip@atlantic.net>
Files: ext/IO/lib/IO/File.pm ext/IO/lib/IO/Handle.pm ext/IO/lib/IO/Pipe.pm ext/IO/lib/IO/Seekable.pm ext/IO/lib/IO/Socket.pm t/lib/io_pipe.t
Subject: Allow IO.xs to remain at 1.15 while $VERSION is 1.1501
From: Chip Salzenberg <chip@atlantic.net>
Files: XSUB.h ext/IO/Makefile.PL ext/IO/lib/IO/Handle.pm
Subject: Add E* and SA_* constants
Date: Wed, 22 Jan 1997 21:36:07 -0500
From: Roderick Schertler <roderick@gate.net>
Files: ext/POSIX/POSIX.pm ext/POSIX/POSIX.pod ext/POSIX/POSIX.xs
private-msgid: <23338.853986967@eeyore.ibcinc.com>
OTHER CORE CHANGES
Subject: Make PERL5LIB and -I work like C<use lib>
Date: Thu, 23 Jan 1997 15:23:27 +0000
From: Tim Bunce <Tim.Bunce@ig.co.uk>
Files: lib/lib.pm perl.c
private-msgid: <9701231523.AA26613@toad.ig.co.uk>
Subject: Fix /\G.a/
From: Chip Salzenberg <chip@atlantic.net>
Files: regcomp.c regcomp.h regexec.c regexp.h toke.c
Subject: Extend stack in pp_undef (!)
From: Chip Salzenberg <chip@atlantic.net>
Files: pp.c
Subject: Allow for sub to be redefined while executing
From: Chip Salzenberg <chip@atlantic.net>
Files: cop.h pp_hot.c t/op/misc.t
Subject: Eliminate redundant flag CVf_FORMAT
From: Chip Salzenberg <chip@atlantic.net>
Files: cv.h op.c perl.c perly.c perly.y proto.h sv.c toke.c
Subject: Generate IVs when possible in abs() and int()
From: Chip Salzenberg <chip@atlantic.net>
Files: pp.c
Subject: Efficiency patchlet for pp_aassign()
Date: Mon, 20 Jan 1997 22:05:39 -0500 (EST)
From: Ilya Zakharevich <ilya@math.ohio-state.edu>
Files: pp_hot.c
Msg-ID: <199701210305.WAA05451@monk.mps.ohio-state.edu>
(applied based on p5p patch as commit 7e42bd57a6867e174bc3bc555c3268b485940a98)
Subject: Remove "suidperl security patch" message
From: Chip Salzenberg <chip@atlantic.net>
Files: perl.c
TESTS
Subject: Fix tests of $^X and $0 to work with QNX
From: Chip Salzenberg <chip@atlantic.net>
Files: t/lib/io_pipe.t t/lib/open2.t t/lib/open3.t t/op/magic.t
Subject: Patch tests for systems without fork()
Date: Thu, 23 Jan 1997 23:51:28 +0100
From: "Norbert Pueschel" <pueschel@imsdd.meb.uni-bonn.de>
Files: t/io/pipe.t t/lib/filehand.t t/lib/io_pipe.t t/lib/io_sock.t t/lib/open2.t t/lib/open3.t t/op/fork.t
private-msgid: <77724697@Armageddon.meb.uni-bonn.de>
Subject: Test patches for OS/2
Date: Thu, 16 Jan 1997 23:48:18 -0500 (EST)
From: Ilya Zakharevich <ilya@math.ohio-state.edu>
Files: os2/OS2/ExtAttr/t/os2_ea.t os2/OS2/PrfDB/t/os2_prfdb.t os2/OS2/REXX/t/rx_cmprt.t os2/OS2/REXX/t/rx_dllld.t os2/OS2/REXX/t/rx_objcall.t os2/OS2/REXX/t/rx_sql.test os2/OS2/REXX/t/rx_tiesql.test os2/OS2/REXX/t/rx_tievar.t os2/OS2/REXX/t/rx_tieydb.t os2/OS2/REXX/t/rx_varset.t os2/OS2/REXX/t/rx_vrexx.t t/README t/cmd/while.t t/comp/colon.t t/comp/multiline.t t/io/argv.t t/lib/anydbm.t t/lib/gdbm.t t/lib/ndbm.t t/lib/odbm.t t/lib/sdbm.t t/op/cmp.t t/op/magic.t
Msg-ID: <199701170448.XAA28948@monk.mps.ohio-state.edu>
(applied based on p5p patch as commit bbad36071d5a6d4be3588f0f10c88247439076d8)
UTILITIES
Subject: Translate \200 to È in pod2html
From: Chip Salzenberg <chip@atlantic.net>
Files: pod/pod2html.PL
Subject: VMS patches: '.com' extension on scripts
Date: Fri, 24 Jan 1997 18:42:29 -0500 (EST)
From: Charles Bailey <bailey@HMIVAX.HUMGEN.UPENN.EDU>
Files: pod/checkpods.PL pod/pod2html.PL pod/pod2latex.PL pod/pod2man.PL pod/pod2text.PL utils/c2ph.PL utils/h2ph.PL utils/h2xs.PL utils/perlbug.PL utils/perldoc.PL utils/pl2pm.PL utils/splain.PL vms/Makefile vms/descrip.mms x2p/find2perl.PL x2p/s2p.PL
private-msgid: <01IELNPDLYJM003E7J@hmivax.humgen.upenn.edu>
Diffstat (limited to 'pod')
| -rw-r--r-- | pod/Makefile | 8 | ||||
| -rw-r--r-- | pod/buildtoc | 6 | ||||
| -rw-r--r-- | pod/checkpods.PL | 1 | ||||
| -rw-r--r-- | pod/perl.pod | 2 | ||||
| -rw-r--r-- | pod/perldebug.pod | 402 | ||||
| -rw-r--r-- | pod/perldelta.pod | 335 | ||||
| -rw-r--r-- | pod/perldiag.pod | 86 | ||||
| -rw-r--r-- | pod/perlembed.pod | 3 | ||||
| -rw-r--r-- | pod/perlfunc.pod | 80 | ||||
| -rw-r--r-- | pod/perlop.pod | 26 | ||||
| -rw-r--r-- | pod/perlre.pod | 6 | ||||
| -rw-r--r-- | pod/perlrun.pod | 10 | ||||
| -rw-r--r-- | pod/perlsyn.pod | 44 | ||||
| -rw-r--r-- | pod/perltoc.pod | 130 | ||||
| -rw-r--r-- | pod/perlvar.pod | 5 | ||||
| -rw-r--r-- | pod/perlxs.pod | 26 | ||||
| -rw-r--r-- | pod/pod2html.PL | 3 | ||||
| -rw-r--r-- | pod/pod2latex.PL | 1 | ||||
| -rw-r--r-- | pod/pod2man.PL | 1 | ||||
| -rw-r--r-- | pod/pod2text.PL | 1 | ||||
| -rwxr-xr-x | pod/roffitall | 2 |
21 files changed, 953 insertions, 225 deletions
diff --git a/pod/Makefile b/pod/Makefile index cd01028069..cf1e7a49d5 100644 --- a/pod/Makefile +++ b/pod/Makefile @@ -5,7 +5,7 @@ PERL = ../miniperl POD = \ perl.pod \ - perlnews.pod \ + perldelta.pod \ perldata.pod \ perlsyn.pod \ perlop.pod \ @@ -42,7 +42,7 @@ POD = \ MAN = \ perl.man \ - perlnews.man \ + perldelta.man \ perldata.man \ perlsyn.man \ perlop.man \ @@ -79,7 +79,7 @@ MAN = \ HTML = \ perl.html \ - perlnews.html \ + perldelta.html \ perldata.html \ perlsyn.html \ perlop.html \ @@ -116,7 +116,7 @@ HTML = \ TEX = \ perl.tex \ - perlnews.tex \ + perldelta.tex \ perldata.tex \ perlsyn.tex \ perlop.tex \ diff --git a/pod/buildtoc b/pod/buildtoc index da458568da..b0e514ee05 100644 --- a/pod/buildtoc +++ b/pod/buildtoc @@ -5,11 +5,11 @@ use Text::Wrap; sub output ($); @pods = qw( - perl perlnews perldata perlsyn perlop perlre perlrun perlfunc + perl perldelta perldata perlsyn perlop perlre perlrun perlfunc perlvar perlsub perlmod perlform perllocale perlref perldsc perllol perltoot perlobj perltie perlbot perlipc perldebug - perldiag perlsec perltrap perlstyle perlpod perlbook - perlembed perlapio perlxs perlxstut perlguts perlcall + perldiag perlsec perltrap perlstyle perlpod perlbook perlembed + perlapio perlxs perlxstut perlguts perlcall ); for (@pods) { s/$/.pod/ } diff --git a/pod/checkpods.PL b/pod/checkpods.PL index c4721a6118..4bec4da609 100644 --- a/pod/checkpods.PL +++ b/pod/checkpods.PL @@ -14,6 +14,7 @@ use File::Basename qw(&basename &dirname); # This is so that make depend always knows where to find PL derivatives. chdir dirname($0); $file = basename($0, '.PL'); +$file .= '.com' if $^O eq 'VMS'; open OUT,">$file" or die "Can't create $file: $!"; diff --git a/pod/perl.pod b/pod/perl.pod index 7ac7094f57..dcab07a37b 100644 --- a/pod/perl.pod +++ b/pod/perl.pod @@ -19,7 +19,7 @@ For ease of access, the Perl manual has been split up into a number of sections: perl Perl overview (this section) - perlnews Perl news about changes from previous version + perldelta Perl changes since previous version perldata Perl data structures perlsyn Perl syntax diff --git a/pod/perldebug.pod b/pod/perldebug.pod index 77502f27d3..0c61b74350 100644 --- a/pod/perldebug.pod +++ b/pod/perldebug.pod @@ -60,12 +60,17 @@ it's run through your pager, as in DB> |h +You may change the pager which is used via C<O pager=...> command. + =item p expr Same as C<print {$DB::OUT} expr> in the current package. In particular, because this is just Perl's own B<print> function, this means that nested data structures and objects are not dumped, unlike with the C<x> command. +The C<DB::OUT> filehandle is opened to F</dev/tty>, regardless of +where STDOUT may be redirected to. + =item x expr Evaluates its expression in list context and dumps out the result @@ -105,10 +110,12 @@ Single step. Executes until it reaches the beginning of another statement, descending into subroutine calls. If an expression is supplied that includes function calls, it too will be single-stepped. -=item n +=item n [expr] Next. Executes over subroutine calls, until it reaches the beginning -of the next statement. +of the next statement. If an expression is supplied that includes +function calls, those functions will be executed with stops before +each statement. =item E<lt>CRE<gt> @@ -129,7 +136,7 @@ List C<incr+1> lines starting at C<min>. =item l min-max -List lines C<min> through C<max>. +List lines C<min> through C<max>. C<l -> is synonymous to C<->. =item l line @@ -154,7 +161,9 @@ print it out. =item f filename -Switch to viewing a different file. +Switch to viewing a different file or eval statement. If C<filename> +is not a full filename as found in values of %INC, it is considered as +a regexp. =item /pattern/ @@ -235,7 +244,13 @@ Set breakpoint at first line of subroutine after it is compiled. =item b load filename -Set breakpoint at the first executed line of the file. +Set breakpoint at the first executed line of the file. Filename should +be a full name as found in values of %INC. + +=item b compile subname + +Sets breakpoint at the first statement executed after the subroutine +is compiled. =item d [line] @@ -273,34 +288,41 @@ be abbreviated. Several options can be listed. =over 12 -=item recallCommand, ShellBang +=item C<recallCommand>, C<ShellBang> The characters used to recall command or spawn shell. By default, these are both set to C<!>. -=item pager +=item C<pager> Program to use for output of pager-piped commands (those beginning with a C<|> character.) By default, C<$ENV{PAGER}> will be used. -=item tkRunning +=item C<tkRunning> Run Tk while prompting (with ReadLine). -=item signalLevel, warnLevel, dieLevel +=item C<signalLevel>, C<warnLevel>, C<dieLevel> + +Level of verbosity. By default the debugger is in a sane verbose mode, +thus it will print backtraces on all the warnings and die-messages +which are going to be printed out, and will print a message when +interesting uncaught signals arrive. -Level of verbosity. +To disable this behaviour, set these values to 0. If C<dieLevel> is 2, +then the messages which will be caught by surrounding C<eval> are also +printed. -=item AutoTrace +=item C<AutoTrace> -Where to print all the breakable points in the executed program -(similar to C<t> command, but can be put into C<PERLDB_OPTS>). +Trace mode (similar to C<t> command, but can be put into +C<PERLDB_OPTS>). -=item LineInfo +=item C<LineInfo> -File or pipe to print line number info to. If it is a -pipe, then a short, "emacs like" message is used. +File or pipe to print line number info to. If it is a pipe (say, +C<|visual_perl_db>), then a short, "emacs like" message is used. =item C<inhibit_exit> @@ -317,7 +339,14 @@ C<frame & 2> is false, messages are printed on entry only. (Printing on exit may be useful if inter(di)spersed with other messages.) If C<frame & 4>, arguments to functions are printed as well as the -context and caller info. +context and caller info. If C<frame & 8>, overloaded C<stringify> and +C<tie>d C<FETCH> are enabled on the printed arguments. The length at +which the argument list is truncated is governed by the next option: + +=item C<maxTraceLen> + +length at which the argument list is truncated when C<frame> option's +bit 4 is set. =back @@ -326,29 +355,38 @@ commands: =over 12 -=item arrayDepth, hashDepth +=item C<arrayDepth>, C<hashDepth> Print only first N elements ('' for all). -=item compactDump, veryCompact +=item C<compactDump>, C<veryCompact> -Change style of array and hash dump. +Change style of array and hash dump. If C<compactDump>, short array +may be printed on one line. -=item globPrint +=item C<globPrint> Whether to print contents of globs. -=item DumpDBFiles +=item C<DumpDBFiles> Dump arrays holding debugged files. -=item DumpPackages +=item C<DumpPackages> Dump symbol tables of packages. -=item quote, HighBit, undefPrint +=item C<quote>, C<HighBit>, C<undefPrint> + +Change style of string dump. Default value of C<quote> is C<auto>, one +can enable either double-quotish dump, or single-quotish by setting it +to C<"> or C<'>. By default, characters with high bit set are printed +I<as is>. + +=item C<UsageOnly> -Change style of string dump. +I<very> rudimentally per-package memory usage dump. Calculates total +size of strings in variables in the package. =back @@ -358,7 +396,7 @@ C<ReadLine>, and C<NonStop> there. Example rc file: - &parse_options("NonStop=1 LineInfo=db.out AutoTrace"); + &parse_options("NonStop=1 LineInfo=db.out AutoTrace"); The script will run without human intervention, putting trace information into the file I<db.out>. (If you interrupt it, you would better reset @@ -370,16 +408,9 @@ C<LineInfo> to something "interactive"!) The TTY to use for debugging I/O. -=item noTTY - -If set, goes in C<NonStop> mode. On interrupt if TTY is not set uses the -value of C<noTTY> or "/tmp/perldbtty$$" to find TTY using -C<Term::Rendezvous>. Current variant is to have the name of TTY in this -file. - =item C<noTTY> -If set, goes in C<NonStop> mode, and would not connect to a TTY. If +If set, goes in C<NonStop> mode, and would not connect to a TTY. If interrupt (or if control goes to debugger via explicit setting of $DB::signal or $DB::single from the Perl script), connects to a TTY specified by the C<TTY> option at startup, or to a TTY found at @@ -387,7 +418,7 @@ runtime using C<Term::Rendezvous> module of your choice. This module should implement a method C<new> which returns an object with two methods: C<IN> and C<OUT>, returning two filehandles to use -for debugging input and output correspondingly. Method C<new> may +for debugging input and output correspondingly. Method C<new> may inspect an argument which is a value of C<$ENV{PERLDB_NOTTY}> at startup, or is C<"/tmp/perldbtty$$"> otherwise. @@ -405,18 +436,18 @@ programmatically by setting $DB::signal or $DB::single. Here's an example of using the C<$ENV{PERLDB_OPTS}> variable: - $ PERLDB_OPTS="N f=2" perl -d myprogram + $ PERLDB_OPTS="N f=2" perl -d myprogram will run the script C<myprogram> without human intervention, printing out the call tree with entry and exit points. Note that C<N f=2> is -equivalent to C<NonStop=1 frame=2>. Note also that at the moment when +equivalent to C<NonStop=1 frame=2>. Note also that at the moment when this documentation was written all the options to the debugger could be uniquely abbreviated by the first letter (with exception of C<Dump*> options). Other examples may include - $ PERLDB_OPTS="N f A L=listing" perl -d myprogram + $ PERLDB_OPTS="N f A L=listing" perl -d myprogram - runs script non-interactively, printing info on each entry into a subroutine and each executed line into the file F<listing>. (If you @@ -424,13 +455,13 @@ interrupt it, you would better reset C<LineInfo> to something "interactive"!) - $ env "PERLDB_OPTS=R=0 TTY=/dev/ttyc" perl -d myprogram + $ env "PERLDB_OPTS=R=0 TTY=/dev/ttyc" perl -d myprogram may be useful for debugging a program which uses C<Term::ReadLine> -itself. Do not forget detach shell from the TTY in the window which +itself. Do not forget detach shell from the TTY in the window which corresponds to F</dev/ttyc>, say, by issuing a command like - $ sleep 1000000 + $ sleep 1000000 See L<"Debugger Internals"> below for more details. @@ -500,7 +531,7 @@ Quit. ("quit" doesn't work for this.) This is the only supported way to exit the debugger, though typing C<exit> twice may do it too. Set an C<O>ption C<inhibit_exit> to 0 if you want to be able to I<step -off> the end the script. You may also need to set C<$finished> to 0 at +off> the end the script. You may also need to set C<$finished> to 0 at some moment if you want to step through global destruction. =item R @@ -527,20 +558,34 @@ output, such as =item = [alias value] -Define a command alias, or list current aliases. +Define a command alias, like + + = quit q + +or list current aliases. =item command Execute command as a Perl statement. A missing semicolon will be supplied. -=item p expr +=item m expr -Same as C<print DB::OUT expr>. The DB::OUT filehandle is opened to -/dev/tty, regardless of where STDOUT may be redirected to. +The expression is evaluated, and the methods which may be applied to +the result are listed. + +=item m package + +The methods which may be applied to objects in the C<package> are listed. =back +=head2 Debugger input/output + +=over 8 + +=item Prompt + The debugger prompt is something like DB<8> @@ -557,9 +602,12 @@ you'd already at a breakpoint and then printed out the result of a function call that itself also has a breakpoint, or you step into an expression via C<s/n/t expression> command. +=item Multi-line commands + If you want to enter a multi-line command, such as a subroutine -definition with several statements, you may escape the newline that would -normally end the debugger command with a backslash. Here's an example: +definition with several statements, or a format, you may escape the +newline that would normally end the debugger command with a backslash. +Here's an example: DB<1> for (1..4) { \ cont: print "ok\n"; \ @@ -572,7 +620,10 @@ normally end the debugger command with a backslash. Here's an example: Note that this business of escaping a newline is specific to interactive commands typed into the debugger. -Here's an example of what a stack back-trace might look like: +=item Stack backtrace + +Here's an example of what a stack back-trace via C<T> command might +look like: $ = main::infested called from file `Ambulation.pm' line 10 @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7 @@ -589,6 +640,160 @@ I<camel_flea> file with four arguments. The last stack frame shows that C<main::pests> was called in a scalar context, also from I<camel_flea>, but from line 4. +Note that if you execute C<T> command from inside an active C<use> +statement, the backtrace will contain both C<L<perlfunc/require>> +frame and an C<L<perlfunc/eval EXPR>>) frame. + +=item Listing + +Listing given via different flavors of C<l> command looks like this: + + DB<<13>> l + 101: @i{@i} = (); + 102:b @isa{@i,$pack} = () + 103 if(exists $i{$prevpack} || exists $isa{$pack}); + 104 } + 105 + 106 next + 107==> if(exists $isa{$pack}); + 108 + 109:a if ($extra-- > 0) { + 110: %isa = ($pack,1); + +Note that the breakable lines are marked with C<:>, lines with +breakpoints are marked by C<b>, with actions by C<a>, and the +next executed line is marked by C<==E<gt>>. + +=item Frame listing + +When C<frame> option is set, debugger would print entered (and +optionally exited) subroutines in different styles. + +What follows is the start of the listing of + + env "PERLDB_OPTS=f=1 N" perl -d -V + +=over 4 + +=item 1 + + entering main::BEGIN + entering Config::BEGIN + Package lib/Exporter.pm. + Package lib/Carp.pm. + Package lib/Config.pm. + entering Config::TIEHASH + entering Exporter::import + entering Exporter::export + entering Config::myconfig + entering Config::FETCH + entering Config::FETCH + entering Config::FETCH + entering Config::FETCH + +=item 2 + + entering main::BEGIN + entering Config::BEGIN + Package lib/Exporter.pm. + Package lib/Carp.pm. + exited Config::BEGIN + Package lib/Config.pm. + entering Config::TIEHASH + exited Config::TIEHASH + entering Exporter::import + entering Exporter::export + exited Exporter::export + exited Exporter::import + exited main::BEGIN + entering Config::myconfig + entering Config::FETCH + exited Config::FETCH + entering Config::FETCH + exited Config::FETCH + entering Config::FETCH + +=item 4 + + in $=main::BEGIN() from /dev/nul:0 + in $=Config::BEGIN() from lib/Config.pm:2 + Package lib/Exporter.pm. + Package lib/Carp.pm. + Package lib/Config.pm. + in $=Config::TIEHASH('Config') from lib/Config.pm:644 + in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0 + in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li + in @=Config::myconfig() from /dev/nul:0 + in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574 + in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574 + in $=Config::FETCH(ref(Config), 'PATCHLEVEL') from lib/Config.pm:574 + in $=Config::FETCH(ref(Config), 'SUBVERSION') from lib/Config.pm:574 + in $=Config::FETCH(ref(Config), 'osname') from lib/Config.pm:574 + in $=Config::FETCH(ref(Config), 'osvers') from lib/Config.pm:574 + +=item 6 + + in $=main::BEGIN() from /dev/nul:0 + in $=Config::BEGIN() from lib/Config.pm:2 + Package lib/Exporter.pm. + Package lib/Carp.pm. + out $=Config::BEGIN() from lib/Config.pm:0 + Package lib/Config.pm. + in $=Config::TIEHASH('Config') from lib/Config.pm:644 + out $=Config::TIEHASH('Config') from lib/Config.pm:644 + in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0 + in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/ + out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/ + out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0 + out $=main::BEGIN() from /dev/nul:0 + in @=Config::myconfig() from /dev/nul:0 + in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574 + out $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574 + in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574 + out $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574 + in $=Config::FETCH(ref(Config), 'PATCHLEVEL') from lib/Config.pm:574 + out $=Config::FETCH(ref(Config), 'PATCHLEVEL') from lib/Config.pm:574 + in $=Config::FETCH(ref(Config), 'SUBVERSION') from lib/Config.pm:574 + +=item 14 + + in $=main::BEGIN() from /dev/nul:0 + in $=Config::BEGIN() from lib/Config.pm:2 + Package lib/Exporter.pm. + Package lib/Carp.pm. + out $=Config::BEGIN() from lib/Config.pm:0 + Package lib/Config.pm. + in $=Config::TIEHASH('Config') from lib/Config.pm:644 + out $=Config::TIEHASH('Config') from lib/Config.pm:644 + in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0 + in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E + out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E + out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0 + out $=main::BEGIN() from /dev/nul:0 + in @=Config::myconfig() from /dev/nul:0 + in $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574 + out $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574 + in $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574 + out $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574 + +=back + +In all the cases indentation of lines shows the call tree, if bit 2 of +C<frame> is set, then a line is printed on exit from a subroutine as +well, if bit 4 is set, then the arguments are printed as well as the +caller info, if bit 8 is set, the arguments are printed even if they +are tied or references. + +When a package is compiled, a line like this + + Package lib/Carp.pm. + +is printed with proper indentation. + +=back + +=head2 Debugging compile-time statements + If you have any compile-time executable statements (code within a BEGIN block or a C<use> statement), these will C<NOT> be stopped by debugger, although C<require>s will (and compile-time statements can be traced @@ -604,10 +809,19 @@ just typed the C<n> command, whereas a value of 1 means the C<s> command. The C<$DB::trace> variable should be set to 1 to simulate having typed the C<t> command. +Another way to debug compile-time code is to start debugger, set a +breakpoint on I<load> of some module thusly + + DB<7> b load f:/perllib/lib/Carp.pm + Will stop on load of `f:/perllib/lib/Carp.pm'. + +and restart debugger by C<R> command (if possible). One can use C<b +compile subname> for the same purpose. + =head2 Debugger Customization Most probably you not want to modify the debugger, it contains enough -hooks to satisfy most needs. You may change the behaviour of debugger +hooks to satisfy most needs. You may change the behaviour of debugger from the debugger itself, using C<O>ptions, from the command line via C<PERLDB_OPTS> environment variable, and from I<customization files>. @@ -624,10 +838,10 @@ One changes options from F<.perldb> file via calls like this one; parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2"); -(the code is executed in the package C<DB>). Note that F<.perldb> is -processed before processing C<PERLDB_OPTS>. If F<.perldb> defines the +(the code is executed in the package C<DB>). Note that F<.perldb> is +processed before processing C<PERLDB_OPTS>. If F<.perldb> defines the subroutine C<afterinit>, it is called after all the debugger -initialization ends. F<.perldb> may be contained in the current +initialization ends. F<.perldb> may be contained in the current directory, or in the C<LOGDIR>/C<HOME> directory. If you want to modify the debugger, copy F<perl5db.pl> from the Perl @@ -647,6 +861,10 @@ the Term::ReadKey and Term::ReadLine modules from CPAN, you will have full editing capabilities much like GNU I<readline>(3) provides. Look for these in the F<modules/by-module/Term> directory on CPAN. +A rudimentary command-line completion is also available. +Unfortunately, the names of lexical variables are not available for +completion. + =head2 Editor Support for Debugging If you have GNU B<emacs> installed on your system, it can interact with @@ -683,9 +901,9 @@ in that profile. =head2 Debugger support in perl -When you call the B<caller> function from package DB, Perl sets the -C<@DB::args> array to contain the arguments that stack frame was called -with. +When you call the B<caller> function (see L<perlfunc/caller>) from the +package DB, Perl sets the array @DB::args to contain the arguments the +corresponding stack frame was called with. If perl is run with B<-d> option, the following additional features are enabled: @@ -701,48 +919,48 @@ application. =item * The array C<@{"_<$filename"}> is the line-by-line contents of -$filename for all the compiled files. Same for C<eval>ed strings which -contain subroutines, or which are currently executed. The C<$filename> +$filename for all the compiled files. Same for C<eval>ed strings which +contain subroutines, or which are currently executed. The C<$filename> for C<eval>ed strings looks like C<(eval 34)>. =item * The hash C<%{"_<$filename"}> contains breakpoints and action (it is keyed by line number), and individual entries are settable (as opposed -to the whole hash). Only true/false is important to Perl, though the +to the whole hash). Only true/false is important to Perl, though the values used by F<perl5db.pl> have the form -C<"$break_condition\0$action">. Values are magical in numeric context: +C<"$break_condition\0$action">. Values are magical in numeric context: they are zeros if the line is not breakable. Same for evaluated strings which contain subroutines, or which are -currently executed. The C<$filename> for C<eval>ed strings looks like +currently executed. The C<$filename> for C<eval>ed strings looks like C<(eval 34)>. =item * -The scalar C<${"_<$filename"}> contains C<"_<$filename">. Same for +The scalar C<${"_<$filename"}> contains C<"_<$filename">. Same for evaluated strings which contain subroutines, or which are currently -executed. The C<$filename> for C<eval>ed strings looks like C<(eval +executed. The C<$filename> for C<eval>ed strings looks like C<(eval 34)>. =item * After each C<require>d file is compiled, but before it is executed, C<DB::postponed(*{"_<$filename"})> is called (if subroutine -C<DB::postponed> exists). Here the $filename is the expanded name of +C<DB::postponed> exists). Here the $filename is the expanded name of the C<require>d file (as found in values of C<%INC>). =item * After each subroutine C<subname> is compiled existence of -C<$DB::postponed{subname}> is checked. If this key exists, +C<$DB::postponed{subname}> is checked. If this key exists, C<DB::postponed(subname)> is called (if subroutine C<DB::postponed> exists). =item * A hash C<%DB::sub> is maintained, with keys being subroutine names, -values having the form C<filename:startline-endline>. C<filename> has +values having the form C<filename:startline-endline>. C<filename> has the form C<(eval 31)> for subroutines defined inside C<eval>s. =item * @@ -752,7 +970,7 @@ a breakpoint, a call to C<DB::DB()> is performed if any one of variables $DB::trace, $DB::single, or $DB::signal is true. (Note that these variables are not C<local>izable.) This feature is disabled when the control is inside C<DB::DB()> or functions called from it (unless -C<$^D & 1 E<lt>E<lt> 30>). +C<$^D & (1E<lt>E<lt>30)>). =item * @@ -764,10 +982,42 @@ in the package C<DB>.) =back Note that no subroutine call is possible until C<&DB::sub> is defined -(for subroutines outside of package C<DB>). (In fact, for the -standard debugger the same is true if C<$DB::deep> (how many levels of -recursion deep into the debugger you can go before a mandatory break) -is not defined.) +(for subroutines outside of package C<DB>). (This restriction is +recently lifted.) + +(In fact, for the standard debugger the same is true if C<$DB::deep> +(how many levels of recursion deep into the debugger you can go before +a mandatory break) is not defined.) + +With the recent updates the minimal possible debugger consists of one +line + + sub DB::DB {} + +which is quite handy as contents of C<PERL5DB> environment +variable: + + env "PERL5DB=sub DB::DB {}" perl -d your-script + +Another (a little bit more useful) minimal debugger can be created +with the only line being + + sub DB::DB {print ++$i; scalar <STDIN>} + +This debugger would print the sequential number of encountered +statement, and would wait for your C<CR> to continue. + +The following debugger is quite functional: + + { + package DB; + sub DB {} + sub sub {print ++$i, " $sub\n"; &$sub} + } + +It prints the sequential number of subroutine call and the name of the +called subroutine. Note that C<&DB::sub> should be compiled into the +package C<DB>. =head2 Debugger Internals @@ -781,21 +1031,21 @@ PERLDB_OPTS and parses it as a rest of C<O ...> line in debugger prompt. It also maintains magical internal variables, such as C<@DB::dbline>, C<%DB::dbline>, which are aliases for C<@{"::_<current_file"}> -C<%{"::_<current_file"}>. Here C<current_file> is the currently +C<%{"::_<current_file"}>. Here C<current_file> is the currently selected (with the debugger's C<f> command, or by flow of execution) file. -Some functions are provided to simplify customization. See L<"Debugger -Customization"> for description of C<DB::parse_options(string)>. The +Some functions are provided to simplify customization. See L<"Debugger +Customization"> for description of C<DB::parse_options(string)>. The function C<DB::dump_trace(skip[, count])> skips the specified number of frames, and returns an array containing info about the caller -frames (all if C<count> is missing). Each entry is a hash with keys +frames (all if C<count> is missing). Each entry is a hash with keys C<context> (C<$> or C<@>), C<sub> (subroutine name, or info about eval), C<args> (C<undef> or a reference to an array), C<file>, and C<line>. The function C<DB::print_trace(FH, skip[, count[, short]])> prints -formatted info about caller frames. The last two functions may be +formatted info about caller frames. The last two functions may be convenient as arguments to C<E<lt>>, C<E<lt>E<lt>> commands. =head2 Other resources diff --git a/pod/perldelta.pod b/pod/perldelta.pod index 3cd71de7d1..b33f1ff81f 100644 --- a/pod/perldelta.pod +++ b/pod/perldelta.pod @@ -1,6 +1,6 @@ =head1 NAME -perlnews - what's new for perl5.004 +perldelta - what's new for perl5.004 =head1 DESCRIPTION @@ -24,7 +24,8 @@ There is a new Configure question that asks if you want to maintain binary compatibility with Perl 5.003. If you choose binary compatibility, you do not have to recompile your extensions, but you might have symbol conflicts if you embed Perl in another application, -just as in the 5.003 release. +just as in the 5.003 release. By default, binary compatibility +is preserved at the expense of symbol table pollution. =head2 New Opcode Module and Revised Safe Module @@ -33,11 +34,26 @@ application of opcode masks. The revised Safe module has a new API and is implemented using the new Opcode module. Please read the new Opcode and Safe documentation. +=head2 Extended Fcntl Module + +The Fcntl module now supports these new constants + + F_GETOWN F_SETOWN + O_ASYNC O_DEFER O_DSYNC O_RSYNC O_SYNC + O_EXLOCK O_SHLOCK + +provided that your operating system supports these constants. The +constants are for use with the Perl sysopen() and fcntl(). These +constants are also visible for the basic database modules like the +SDBM_File. For the exact meaning of these contants and other Fcntl +constants please refer to the fcntl() documentation of your operating +system. Unsupported constants will cause run-time errors. + =head2 Internal Change: FileHandle Deprecated Filehandles are now stored internally as type IO::Handle. Although C<use FileHandle> and C<*STDOUT{FILEHANDLE}> -are still supported for backwards compatibility +are still supported for backwards compatibility, C<use IO::Handle> (or C<IO::Seekable> or C<IO::File>) and C<*STDOUT{IO}> are the way of the future. @@ -73,7 +89,7 @@ compiled with -DEMERGENCY_SBRK and used Perl's malloc. Then $^M = 'a' x (1<<16); -would allocate 64K buffer for use when in emergency. +would allocate a 64K buffer for use when in emergency. See the F<INSTALL> file for information on how to enable this option. As a disincentive to casual use of this advanced feature, there is no C<use English> long name for this variable. @@ -121,13 +137,13 @@ expressions of control structures such as: print $line; } - if ((my $answer = <STDIN>) =~ /^yes$/i) { + if ((my $answer = <STDIN>) =~ /^y(es)?$/i) { user_agrees(); - } elsif ($answer =~ /^no$/i) { + } elsif ($answer =~ /^n(o)?$/i) { user_disagrees(); } else { chomp $answer; - die "'$answer' is neither 'yes' nor 'no'"; + die "`$answer' is neither `yes' nor `no'"; } Also, you can declare a foreach loop control variable as lexical by @@ -156,10 +172,12 @@ which bit eight is clear. If the first argument to C<use> is a number, it is treated as a version number instead of a module name. If the version of the Perl interpreter is less than VERSION, then an error message is printed and Perl exits -immediately. This is often useful if you need to check the current -Perl version before C<use>ing library modules which have changed in -incompatible ways from older versions of Perl. (We try not to do -this more than we have to.) +immediately. Because C<use> occurs at compile time, this check happens +immediately during the compilation process, unlike C<require VERSION>, +which waits until run-time for the check. This is often useful if you +need to check the current Perl version before C<use>ing library modules +which have changed in incompatible ways from older versions of Perl. +(We try not to do this more than we have to.) =item use Module VERSION LIST @@ -187,7 +205,7 @@ function whose prototype you want to retrieve. Functions documented in the Camel to default to $_ now in fact do, and all those that do are so documented in L<perlfunc>. -=head2 C<m//g> does not trigger a pos() reset on failure +=item C<m//g> does not trigger a pos() reset on failure The C<m//g> match iteration construct used to reset the iteration when it failed to match (so that the next C<m//g> match would start at @@ -197,6 +215,27 @@ string in some way. This change makes it practical to chain C<m//g> matches together in conjunction with ordinary matches using the C<\G> zero-width assertion. See L<perlop> and L<perlre>. +=item nested C<sub{}> closures work now + +Prior to the 5.004 release, nested anonymous functions +didn't work right. They do now. + +=item formats work right on changing lexicals + +Just like anonymous functions that contain lexical variables +that change (like a lexical index variable for a C<foreach> loop), +formats now work properly. For example, this silently failed +before, and is fine now: + + my $i; + foreach $i ( 1 .. 10 ) { + format = + my i is @# + $i + . + write; + } + =back =head2 New Built-in Methods @@ -255,10 +294,21 @@ class, false if its object is the class (package) itself. Example $ref = bless [], 'A'; $ref->is_instance(); # True +This can be useful for methods that wish to easily distinguish +whether they were invoked as class or as instance methods. + + sub some_meth { + my $classname = shift; + if ($classname->is_instance()) { + die "unexpectedly called as instance not class method"; + } + ..... + } + =back B<NOTE:> C<can> directly uses Perl's internal code for method lookup, and -C<isa> uses a very similar method and cache-ing strategy. This may cause +C<isa> uses a very similar method and caching strategy. This may cause strange effects if the Perl code dynamically changes @ISA in any package. You may add other methods to the UNIVERSAL class via Perl or XS code. @@ -268,6 +318,8 @@ have C<isa> available as a plain subroutine in the current package. =head2 TIEHANDLE Now Supported +See L<perltie> for other kinds of tie()s. + =over =item TIEHANDLE classname, LIST @@ -276,7 +328,11 @@ This is the constructor for the class. That means it is expected to return an object of some sort. The reference can be used to hold some internal information. - sub TIEHANDLE { print "<shout>\n"; my $i; bless \$i, shift } + sub TIEHANDLE { + print "<shout>\n"; + my $i; + return bless \$i, shift; + } =item PRINT this, LIST @@ -284,14 +340,21 @@ This method will be triggered every time the tied handle is printed to. Beyond its self reference it also expects the list that was passed to the print function. - sub PRINT { $r = shift; $$r++; print join($,,map(uc($_),@_)),$\ } + sub PRINT { + $r = shift; + $$r++; + return print join( $, => map {uc} @_), $\; + } =item READLINE this This method will be called when the handle is read from. The method should return undef when there is no more data. - sub READLINE { $r = shift; "PRINT called $$r times\n"; } + sub READLINE { + $r = shift; + return "PRINT called $$r times\n"; + } =item DESTROY this @@ -299,10 +362,21 @@ As with the other types of ties, this method will be called when the tied handle is about to be destroyed. This is useful for debugging and possibly for cleaning up. - sub DESTROY { print "</shout>\n" } + sub DESTROY { + print "</shout>\n"; + } =back +=item Efficiency Enhancements + +All hash keys with the same string are only allocated once, so +even if you have 100 copies of the same hash, the immutable keys +never have to be re-allocated. + +Functions that have an empty prototype and that do nothing but return +a fixed value are now inlined (e.g. C<sub PI () { 3.14159 }>). + =head1 Pragmata Three new pragmatic modules exist: @@ -311,6 +385,8 @@ Three new pragmatic modules exist: =item use blib +=item use blib 'dir' + Looks for MakeMaker-like I<'blib'> directory structure starting in I<dir> (or current directory) and working back up to five levels of parent directories. @@ -344,9 +420,23 @@ Disable unsafe opcodes, or any named opcodes, when compiling Perl code. =head1 Modules +=head2 Fcntl + +New constants in the existing Fcntl modules are now supported, +provided that your operating system happens to support them: + + F_GETOWN F_SETOWN + O_ASYNC O_DEFER O_DSYNC O_FSYNC O_SYNC + O_EXLOCK O_SHLOCK + =head2 Module Information Summary -Brand new modules: +Brand new modules, arranged by topic rather than strictly +alphabetically: + + CPAN interface to Comprehensive Perl Archive Network + CPAN::FirstTime create a CPAN configuration file + CPAN::Nox run CPAN while avoiding compiled extensions IO.pm Top-level interface to IO::* classes IO/File.pm IO::File extension Perl module @@ -376,7 +466,7 @@ Brand new modules: User/grent.pm Object-oriented wrapper around CORE::getgr* User/pwent.pm Object-oriented wrapper around CORE::getpw* - lib/Tie/RefHash.pm Base class for tied hashes with references as keys + Tie/RefHash.pm Base class for tied hashes with references as keys UNIVERSAL.pm Base class for *ALL* classes @@ -430,14 +520,28 @@ For example, you can now say use User::pwent; $his = (stat($filename)->st_uid == pwent($whoever)->pw_uid); -=head1 Efficiency Enhancements +=head1 Utility Changes -All hash keys with the same string are only allocated once, so -even if you have 100 copies of the same hash, the immutable keys -never have to be re-allocated. +=head2 xsubpp -Functions that have an empty prototype and that do nothing but return -a fixed value are now inlined (e.g. C<sub PI () { 3.14159 }>). +=item C<void> XSUBs now default to returning nothing + +Due to a documentation/implementation bug in previous versions of +Perl, XSUBs with a return type of C<void> have actually been +returning one value. Usually that value was the GV for the XSUB, +but sometimes it was some already freed or reused value, which would +sometimes lead to program failure. + +In Perl 5.004, if an XSUB is declared as returning C<void>, it +actually returns no value, i.e. an empty list (though there is a +backward-compatibility exception; see below). If your XSUB really +does return an SV, you should give it a return type of C<SV *>. + +For backward compatibility, I<xsubpp> tries to guess whether a +C<void> XSUB is really C<void> or if it wants to return an C<SV *>. +It does so by examining the text of the XSUB: if I<xsubpp> finds +what looks like an assignment to C<ST(0)>, it assumes that the +XSUB's return type is really C<SV *>. =head1 Documentation Changes @@ -446,7 +550,7 @@ new pods are included in section 1: =over 4 -=item L<perlnews> +=item L<perldelta> This document. @@ -476,8 +580,17 @@ Although not new, this has been massively updated. Several new conditions will trigger warnings that were silent before. Some only affect certain platforms. -The following new warnings and errors -outline these: +The following new warnings and errors outline these. +These messages are classified as follows (listed in +increasing order of desperation): + + (W) A warning (optional). + (D) A deprecation (optional). + (S) A severe warning (mandatory). + (F) A fatal error (trappable). + (P) An internal error you should never see (trappable). + (X) A very fatal error (non-trappable). + (A) An alien error message (not generated by Perl). =over 4 @@ -489,6 +602,18 @@ a typographical error. Note that the earlier variable will still exist until the end of the scope or until all closure referents to it are destroyed. +=item %s argument is not a HASH element or slice + +(F) The argument to delete() must be either a hash element, such as + + $foo{$bar} + $ref->[12]->{"susie"} + +or a hash slice, such as + + @foo{$bar, $baz, $xyzzy} + @{$ref->[12]}{"susie", "queue"} + =item Allocation too large: %lx (X) You can't allocate more than 64K on an MSDOS machine. @@ -527,6 +652,22 @@ appear in %ENV. This may be a benign occurrence, as some software packages might directly modify logical name tables and introduce non-standard names, or it may indicate that a logical name table has been corrupted. +=item Can't use bareword ("%s") as %s ref while "strict refs" in use + +(F) Only hard references are allowed by "strict refs". Symbolic references +are disallowed. See L<perlref>. + +=item Constant subroutine %s redefined + +(S) You redefined a subroutine which had previously been eligible for +inlining. See L<perlsub/"Constant Functions"> for commentary and +workarounds. + +=item Died + +(F) You passed die() an empty string (the equivalent of C<die "">) or +you called it with no args and both C<$@> and C<$_> were empty. + =item Integer overflow in hex number (S) The literal hex number you have specified is too big for your @@ -539,6 +680,13 @@ architecture. On a 32-bit architecture the largest hex literal is architecture. On a 32-bit architecture the largest octal literal is 037777777777. +=item Name "%s::%s" used only once: possible typo + +(W) Typographical errors often show up as unique variable names. +If you had a good reason for having a unique name, then just mention +it again somehow to suppress the message (the C<use vars> pragma is +provided for just this purpose). + =item Null picture in formline (F) The first argument to formline must be a valid format picture @@ -552,6 +700,17 @@ pointing outside the buffer. This is difficult to imagine. The sole exception to this is that C<sysread()>ing past the buffer will extend the buffer and zero pad the new area. +=item Stub found while resolving method `%s' overloading `%s' in package `%s' + +(P) Overloading resolution over @ISA tree may be broken by importing stubs. +Stubs should never be implicitely created, but explicit calls to C<can> +may break this. + +=item Cannot resolve method `%s' overloading `%s' in package `s' + +(P) Internal error trying to resolve overloading specified by a method +name (as opposed to a subroutine reference). + =item Out of memory! (X|F) The malloc() function returned 0, indicating there was insufficient @@ -572,37 +731,125 @@ a possibility to shut down by trapping this error is granted. =item Possible attempt to put comments in qw() list -(W) You probably wrote something like this: +(W) qw() lists contain items separated by whitespace; as with literal +strings, comment characters are not ignored, but are instead treated +as literal data. (You may have used different delimiters than the +exclamation marks parentheses shown here; braces are also frequently +used.) + +You probably wrote something like this: - qw( a # a comment + @list = qw( + a # a comment b # another comment - ) ; + ); when you should have written this: - qw( a + @list = qw( + a b - ) ; + ); + +If you really want comments, build your list the +old-fashioned way, with quotes and commas: + + @list = ( + 'a', # a comment + 'b', # another comment + ); =item Possible attempt to separate words with commas -(W) You probably wrote something like this: +(W) qw() lists contain items separated by whitespace; therefore commas +aren't needed to separate the items. (You may have used different +delimiters than the parentheses shown here; braces are also frequently +used.) - qw( a, b, c ); +You probably wrote something like this: -when you should have written this: + qw! a, b, c !; + +which puts literal commas into some of the list items. Write it without +commas if you don't want them to appear in your data: + + qw! a b c !; - qw( a b c ); +=item Scalar value @%s{%s} better written as $%s{%s} + +(W) You've used a hash slice (indicated by @) to select a single element of +a hash. Generally it's better to ask for a scalar value (indicated by $). +The difference is that C<$foo{&bar}> always behaves like a scalar, both when +assigning to it and when evaluating its argument, while C<@foo{&bar}> behaves +like a list when you assign to it, and provides a list context to its +subscript, which can do weird things if you're expecting only one subscript. =item untie attempted while %d inner references still exist (W) A copy of the object returned from C<tie> (or C<tied>) was still valid when C<untie> was called. -=item Got an error from DosAllocMem: +=item Value of %s construct can be "0"; test with defined() + +(W) In a conditional expression, you used <HANDLE>, <*> (glob), or +C<readdir> as a boolean value. Each of these constructs can return a +value of "0"; that would make the conditional expression false, which +is probably not what you intended. When using these constructs in +conditional expressions, test their values with the C<defined> operator. + +=item Variable "%s" may be unavailable + +(W) An inner (nested) I<anonymous> subroutine is inside a I<named> +subroutine, and outside that is another subroutine; and the anonymous +(innermost) subroutine is referencing a lexical variable defined in +the outermost subroutine. For example: + + sub outermost { my $a; sub middle { sub { $a } } } + +If the anonymous subroutine is called or referenced (directly or +indirectly) from the outermost subroutine, it will share the variable +as you would expect. But if the anonymous subroutine is called or +referenced when the outermost subroutine is not active, it will see +the value of the shared variable as it was before and during the +*first* call to the outermost subroutine, which is probably not what +you want. + +In these circumstances, it is usually best to make the middle +subroutine anonymous, using the C<sub {}> syntax. Perl has specific +support for shared variables in nested anonymous subroutines; a named +subroutine in between interferes with this feature. + +=item Variable "%s" will not stay shared + +(W) An inner (nested) I<named> subroutine is referencing a lexical +variable defined in an outer subroutine. + +When the inner subroutine is called, it will probably see the value of +the outer subroutine's variable as it was before and during the +*first* call to the outer subroutine; in this case, after the first +call to the outer subroutine is complete, the inner and outer +subroutines will no longer share a common value for the variable. In +other words, the variable will no longer be shared. + +Furthermore, if the outer subroutine is anonymous and references a +lexical variable outside itself, then the outer and inner subroutines +will I<never> share the given variable. + +This problem can usually be solved by making the inner subroutine +anonymous, using the C<sub {}> syntax. When inner anonymous subs that +reference variables in outer subroutines are called or referenced, +they are automatically re-bound to the current values of such +variables. + +=item Warning: something's wrong + +(W) You passed warn() an empty string (the equivalent of C<warn "">) or +you called it with no args and C<$_> was empty. + +=item Got an error from DosAllocMem -(P) An error peculiar to OS/2. Most probably you use an obsolete version -of Perl, and should not happen anyway. +(P) An error peculiar to OS/2. Most probably you're using an obsolete +version of Perl, and this should not happen anyway. =item Malformed PERLLIB_PREFIX @@ -634,10 +881,10 @@ L<perlipc/"Signals">. See L<perlos2/"Process terminated by SIGTERM/SIGINT">. =head1 BUGS -If you find what you think is a bug, you might check the headers -of recently posted articles -in the comp.lang.perl.misc newsgroup. There may also be -information at http://www.perl.com/perl/, the Perl Home Page. +If you find what you think is a bug, you might check the headers of +recently posted articles in the comp.lang.perl.misc newsgroup. +There may also be information at http://www.perl.com/perl/, the Perl +Home Page. If you believe you have an unreported bug, please run the B<perlbug> program included with your release. Make sure you trim your bug diff --git a/pod/perldiag.pod b/pod/perldiag.pod index d08d2dc452..0f204a868a 100644 --- a/pod/perldiag.pod +++ b/pod/perldiag.pod @@ -799,6 +799,12 @@ Perhaps you need to copy the value to a temporary, and repeat that. (F) The create routine failed for some reason while trying to process a B<-e> switch. Maybe your /tmp partition is full, or clobbered. +=item Cannot resolve method `%s' overloading `%s' in package `%s' + +(F|P) Error resolving overloading specified by a method name (as +opposed to a subroutine reference): no such method callable via the +package. If method name is C<???>, this is an internal error. + =item chmod: mode argument is missing initial 0 (W) A novice will sometimes say @@ -823,6 +829,10 @@ the return value of your socket() call? See L<perlfunc/connect>. inlining. See L<perlsub/"Constant Functions"> for commentary and workarounds. +=item Copy method did not return a reference + +(F) The method which overloads "=" is buggy. See L<overload/Copy Constructor>. + =item Corrupt malloc ptr 0x%lx at 0x%lx (P) The malloc package that comes with Perl had an internal failure. @@ -1177,7 +1187,7 @@ assume that an unbackslashed @ interpolates an array.) =item Method for operation %s not found in package %s during blessing (F) An attempt was made to specify an entry in an overloading table that -doesn't somehow point to a valid method. See L<overload>. +doesn't resolve to a valid subroutine. See L<overload>. =item Might be a runaway multi-line %s string starting on line %d @@ -1420,7 +1430,7 @@ subroutine), but found a reference to something else instead. You can use the ref() function to find out what kind of ref it really was. See also L<perlref>. -=item Not a subroutine reference in %OVERLOAD +=item Not a subroutine reference in overload table (F) An attempt was made to specify an entry in an overloading table that doesn't somehow point to a valid subroutine. See L<overload>. @@ -1487,21 +1497,13 @@ will extend the buffer and zero pad the new area. (S) An internal warning that the grammar is screwed up. -=item Operation `%s' %s: no method found, - -(F) An attempt was made to use an entry in an overloading table that -somehow no longer points to a valid method. See L<overload>. - -=item Stub found while resolving method `%s' overloading `%s' in package `%s' - -(P) Overloading resolution over @ISA tree may be broken by importing stubs. -Stubs should never be implicitely created, but explicit calls to C<can> -may break this. - -=item Cannot resolve method `%s' overloading `%s' in package `s' +=item Operation `%s': no method found,%s -(P) Internal error trying to resolve overloading specified by a method -name (as opposed to a subroutine reference). +(F) An attempt was made to perform an overloaded operation for which +no handler was defined. While some handlers can be autogenerated in +terms of other handlers, there is no default handler for any +operation, unless C<fallback> overloading key is specified to be +true. See L<overload>. =item Operator or semicolon missing before %s @@ -1714,27 +1716,49 @@ the BSD version, which takes a pid. =item Possible attempt to put comments in qw() list -(W) You probably wrote something like this: +(W) qw() lists contain items separated by whitespace; as with literal +strings, comment characters are not ignored, but are instead treated +as literal data. (You may have used different delimiters than the +exclamation marks parentheses shown here; braces are also frequently +used.) - qw( a # a comment +You probably wrote something like this: + + @list = qw( + a # a comment b # another comment - ) ; + ); when you should have written this: - qw( a + @list = qw( + a b - ) ; + ); + +If you really want comments, build your list the +old-fashioned way, with quotes and commas: + + @list = ( + 'a', # a comment + 'b', # another comment + ); =item Possible attempt to separate words with commas -(W) You probably wrote something like this: +(W) qw() lists contain items separated by whitespace; therefore commas +aren't needed to separate the items. (You may have used different +delimiters than the parentheses shown here; braces are also frequently +used.) - qw( a, b, c ); +You probably wrote something like this: -when you should have written this: + qw! a, b, c !; + +which puts literal commas into some of the list items. Write it without +commas if you don't want them to appear in your data: - qw( a b c ); + qw! a b c !; =item Possible memory corruption: %s overflowed 3rd argument @@ -2002,6 +2026,12 @@ there was a failure. You probably wanted to use system() instead, which does return. To suppress this warning, put the exec() in a block by itself. +=item Stub found while resolving method `%s' overloading `%s' in package `%s' + +(P) Overloading resolution over @ISA tree may be broken by importation stubs. +Stubs should never be implicitely created, but explicit calls to C<can> +may break this. + =item Subroutine %s redefined (W) You redefined a subroutine. To suppress this warning, say @@ -2558,10 +2588,10 @@ streams, such as } close OUT; -=item Got an error from DosAllocMem: +=item Got an error from DosAllocMem -(P) An error peculiar to OS/2. Most probably you use an obsolete version -of perl, and this should not happen anyway. +(P) An error peculiar to OS/2. Most probably you're using an obsolete +version of Perl, and this should not happen anyway. =item Malformed PERLLIB_PREFIX diff --git a/pod/perlembed.pod b/pod/perlembed.pod index e55ee633c9..2a9ce58f30 100644 --- a/pod/perlembed.pod +++ b/pod/perlembed.pod @@ -930,7 +930,8 @@ B<ExtUtils::Embed> can also automate writing the I<xs_init> glue code. % perl -MExtUtils::Embed -e xsinit -o perlxsi.c % cc -c perlxsi.c `perl -MExtUtils::Embed -e ccopts` % cc -c interp.c `perl -MExtUtils::Embed -e ccopts` - % cc -o interp perlxsi.o interp.o `perl -MExtUtils::Embed -e ldopts` + % cc -o interp perlxsi.o interp.o \ + `perl -MExtUtils::Embed -e ccdlflags -e ldopts` Consult L<perlxs> and L<perlguts> for more details. diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 488c797c65..99231b9ffd 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -408,8 +408,17 @@ With EXPR, it returns some extra information that the debugger uses to print a stack trace. The value of EXPR indicates how many call frames to go back before the current one. - ($package, $filename, $line, - $subroutine, $hasargs, $wantarray) = caller($i); + ($package, $filename, $line, $subroutine, + $hasargs, $wantarray, $evaltext, $is_require) = caller($i); + +Here $subroutine may be C<"(eval)"> if the frame is not a subroutine +call, but C<L<eval>>. In such a case additional elements $evaltext and +$is_require are set: $is_require is true if the frame is created by +C<L<require>> or C<L<use>> statement, $evaltext contains the text of +C<L<eval EXPR>> statement. In particular, for C<L<eval BLOCK>> +statement $filename is C<"(eval)">, but $evaltext is undefined. (Note +also that C<L<use>> statement creates a C<L<require>> frame inside +an C<L<eval EXPR>>) frame. Furthermore, when called from within the DB package, caller returns more detailed information: it sets the list variable @DB::args to be the @@ -774,6 +783,12 @@ produce, respectively See also exit() and warn(). +You can arrange for a callback to be called just before the die() does +its deed, by setting the C<$SIG{__DIE__}> hook. The associated handler +will be called with the error text and can change the error message, if +it sees fit, by calling die() again. See L<perlvar> for details on +setting C<%SIG> entries, and eval() for some examples. + =item do BLOCK Not really a function. Returns the value of the last command in the @@ -919,8 +934,11 @@ context of the eval. If there is a syntax error or runtime error, or a die() statement is executed, an undefined value is returned by eval(), and C<$@> is set to the error message. If there was no error, C<$@> is guaranteed to be a null -string. If EXPR is omitted, evaluates $_. The final semicolon, if -any, may be omitted from the expression. +string. If EXPR is omitted, evaluates C<$_>. The final semicolon, if +any, may be omitted from the expression. Beware that using eval() +neither silences perl from printing warnings to STDERR, nor does it +stuff the text of warning messages into C<$@>. To do either of those, +you have to use the C<$SIG{__WARN__}> facility. See warn() and L<perlvar>. Note that, because eval() traps otherwise-fatal errors, it is useful for determining whether a particular feature (such as socket() or symlink()) @@ -944,6 +962,24 @@ Examples: # a run-time error eval '$answer ='; # sets $@ +When using the eval{} form as an exception trap in libraries, you may +wish not to trigger any C<__DIE__> hooks that user code may have +installed. You can use the C<local $SIG{__DIE__}> construct for this +purpose, as shown in this example: + + # a very private exception trap for divide-by-zero + eval { local $SIG{'__DIE__'}; $answer = $a / $b; }; warn $@ if $@; + +This is especially significant, given that C<__DIE__> hooks can call +die() again, which has the effect of changing their error messages: + + # __DIE__ hooks may modify error messages + { + local $SIG{'__DIE__'} = sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x }; + eval { die "foo foofs here" }; + print $@ if $@; # prints "bar barfs here" + } + With an eval(), you should be especially careful to remember what's being looked at when: @@ -3045,7 +3081,7 @@ meaning of the fields: size total size of file, in bytes atime last access time since the epoch mtime last modify time since the epoch - ctime inode change time (NOT creation type!) since the epoch + ctime inode change time (NOT creation time!) since the epoch blksize preferred block size for file system I/O blocks actual number of blocks allocated @@ -3640,8 +3676,38 @@ for a scalar. =item warn LIST -Produces a message on STDERR just like die(), but doesn't exit or -on an exception. +Produces a message on STDERR just like die(), but doesn't exit or throw +an exception. + +No message is printed if there is a C<$SIG{__WARN__}> handler +installed. It is the handler's responsibility to deal with the message +as it sees fit (like, for instance, converting it into a die()). Most +handlers must therefore make arrangements to actually display the +warnings that they are not prepared to deal with, by calling warn() +again in the handler. Note that this is quite safe and will not +produce an endless loop, since C<__WARN__> hooks are not called from +inside one. + +You will find this behavior is slightly different from that of +C<$SIG{__DIE__}> handlers (which don't suppress the error text, but can +instead call die() again to change it). + +Using a C<__WARN__> handler provides a powerful way to silence all +warnings (even the so-called mandatory ones). An example: + + # wipe out *all* compile-time warnings + BEGIN { $SIG{'__WARN__'} = sub { warn $_[0] if $DOWARN } } + my $foo = 10; + my $foo = 20; # no warning about duplicate my $foo, + # but hey, you asked for it! + # no compile-time or run-time warnings before here + $DOWARN = 1; + + # run-time warnings enabled after here + warn "\$foo is alive and $foo!"; # does show up + +See L<perlvar> for details on setting C<%SIG> entries, and for more +examples. =item write FILEHANDLE diff --git a/pod/perlop.pod b/pod/perlop.pod index dd3aeab663..55108f0328 100644 --- a/pod/perlop.pod +++ b/pod/perlop.pod @@ -737,6 +737,32 @@ The last example should print: Note how C<m//g> matches change the value reported by C<pos()>, but the non-global match doesn't. +A useful idiom for C<lex>-like scanners is C</\G.../g>. You can +combine several regexps like this to process a string part-by-part, +doing different actions depending on which regexp matched. The next +regexp would step in at the place the previous one left off. + + $_ = <<'EOL'; + $url = new URI::URL "http://www/"; die if $url eq "xXx"; +EOL + LOOP: + { + print(" digits"), redo LOOP if /\G\d+\b[,.;]?\s*/g; + print(" lowercase"), redo LOOP if /\G[a-z]+\b[,.;]?\s*/g; + print(" UPPERCASE"), redo LOOP if /\G[A-Z]+\b[,.;]?\s*/g; + print(" Capitalized"), redo LOOP if /\G[A-Z][a-z]+\b[,.;]?\s*/g; + print(" MiXeD"), redo LOOP if /\G[A-Za-z]+\b[,.;]?\s*/g; + print(" alphanumeric"), redo LOOP if /\G[A-Za-z0-9]+\b[,.;]?\s*/g; + print(" line-noise"), redo LOOP if /\G[^A-Za-z0-9]+/g; + print ". That's all!\n"; + } + +Here is the output (split into several lines): + + line-noise lowercase line-noise lowercase UPPERCASE line-noise + UPPERCASE line-noise lowercase line-noise lowercase line-noise + lowercase lowercase line-noise lowercase lowercase line-noise + MiXeD line-noise. That's all! =item q/STRING/ diff --git a/pod/perlre.pod b/pod/perlre.pod index a4c0a7d9de..cb3ce032d0 100644 --- a/pod/perlre.pod +++ b/pod/perlre.pod @@ -175,7 +175,11 @@ just like "^" and "$" except that they won't match multiple times when the C</m> modifier is used, while "^" and "$" will match at every internal line boundary. To match the actual end of the string, not ignoring newline, you can use C<\Z(?!\n)>. The C<\G> assertion can be used to mix global -matches (using C<m//g>) and non-global ones, as described in L<perlop>. +matches (using C<m//g>) and non-global ones, as described in +L<perlop/"Regexp Quote-Like Operators">. +It is also useful when writing C<lex>-like scanners, when you have several +regexps which you want to match against consequent substrings of your +string, see the previous reference. The actual location where C<\G> will match can also be influenced by using C<pos()> as an lvalue. See L<perlfunc/pos>. diff --git a/pod/perlrun.pod b/pod/perlrun.pod index 083b567e19..da355c17be 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -420,10 +420,12 @@ prints warnings about variable names that are mentioned only once, and scalar variables that are used before being set. Also warns about redefined subroutines, and references to undefined filehandles or filehandles opened read-only that you are attempting to write on. Also -warns you if you use values as a number that doesn't look like numbers, using -an array as though it were a scalar, if -your subroutines recurse more than 100 deep, and innumerable other things. -See L<perldiag> and L<perltrap>. +warns you if you use values as a number that doesn't look like numbers, +using an array as though it were a scalar, if your subroutines recurse +more than 100 deep, and innumerable other things. + +You can disable specific warnings using C<__WARN__> hooks, as described +in L<perlvar> and L<perlfunc/warn>. See also L<perldiag> and L<perltrap>. =item B<-x> I<directory> diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod index 91a601aebb..8bb557e7f5 100644 --- a/pod/perlsyn.pod +++ b/pod/perlsyn.pod @@ -508,3 +508,47 @@ ignored by both the compiler and the translators. You probably shouldn't rely upon the warn() being podded out forever. Not all pod translators are well-behaved in this regard, and perhaps the compiler will become pickier. + +One may also use pod directives to quickly comment out a section +of code. + +=head2 Plain Old Comments (Not!) + +Much like the C preprocessor, perl can process line directives. Using +this, one can control perl's idea of filenames and line numbers in +error or warning messages (especially for strings that are processed +with eval()). The syntax for this mechanism is the same as for most +C preprocessors: it matches the regular expression +C</^#\s*line\s+(\d+)\s*(?:\s"([^"])*")?/> with C<$1> being the line +number for the next line, and C<$2> being the optional filename +(specified within quotes). + +Here are some examples that you should be able to type into your command +shell: + + % perl + # line 200 "bzzzt" + # the `#' on the previous line must be the first char on line + die 'foo'; + __END__ + foo at bzzzt line 201. + + % perl + # line 200 "bzzzt" + eval qq[\n#line 2001 ""\ndie 'foo']; print $@; + __END__ + foo at - line 2001. + + % perl + eval qq[\n#line 200 "foo bar"\ndie 'foo']; print $@; + __END__ + foo at foo bar line 200. + + % perl + # line 345 "goop" + eval "\n#line " . __LINE__ . ' "' . __FILE__ ."\"\ndie 'foo'"; + print $@; + __END__ + foo at goop line 345. + +=cut diff --git a/pod/perltoc.pod b/pod/perltoc.pod index b8353fcdb1..f451606df5 100644 --- a/pod/perltoc.pod +++ b/pod/perltoc.pod @@ -40,7 +40,7 @@ HOME, LOGDIR, PATH, PERL5LIB, PERL5DB, PERL_DESTRUCT_LEVEL, PERLLIB =item NOTES -=head2 perlnews - what's new for perl5.004 +=head2 perldelta - what's new for perl5.004 =item DESCRIPTION @@ -54,6 +54,8 @@ HOME, LOGDIR, PATH, PERL5LIB, PERL5DB, PERL_DESTRUCT_LEVEL, PERLLIB =item New Opcode Module and Revised Safe Module +=item Extended Fcntl Module + =item Internal Change: FileHandle Deprecated =item Internal Change: PerlIO internal IO abstraction interface @@ -66,9 +68,9 @@ $^E, $^H, $^M delete on slices, flock, keys as an lvalue, my() in Control Structures, unpack() and pack(), use VERSION, use Module VERSION LIST, -prototype(FUNCTION), $_ as Default - -=item C<m//g> does not trigger a pos() reset on failure +prototype(FUNCTION), $_ as Default, C<m//g> does not trigger a pos() reset +on failure, nested C<sub{}> closures work now, formats work right on +changing lexicals =item New Built-in Methods @@ -76,18 +78,21 @@ isa(CLASS), can(METHOD), VERSION( [NEED] ), class(), is_instance() =item TIEHANDLE Now Supported -TIEHANDLE classname, LIST, PRINT this, LIST, READLINE this, DESTROY this +TIEHANDLE classname, LIST, PRINT this, LIST, READLINE this, DESTROY this, +Efficiency Enhancements =back =item Pragmata -use blib, use locale, use ops +use blib, use blib 'dir', use locale, use ops =item Modules =over +=item Fcntl + =item Module Information Summary =item IO @@ -98,25 +103,40 @@ use blib, use locale, use ops =back -=item Efficiency Enhancements +=item Utility Changes + +=over + +=item xsubpp + +C<void> XSUBs now default to returning nothing + +=back =item Documentation Changes -L<perlnews>, L<perllocale>, L<perltoot>, L<perlapio>, L<perldebug>, +L<perldelta>, L<perllocale>, L<perltoot>, L<perlapio>, L<perldebug>, L<perlsec> =item New Diagnostics -"my" variable %s masks earlier declaration in same scope, Allocation too -large: %lx, Allocation too large, Attempt to free non-existent shared -string, Attempt to use reference as lvalue in substr, Unsupported function -fork, Ill-formed logical name |%s| in prime_env_iter, Integer overflow in -hex number, Integer overflow in octal number, Null picture in formline, -Offset outside string, Out of memory!, Out of memory during request for %s, -Possible attempt to put comments in qw() list, Possible attempt to separate -words with commas, untie attempted while %d inner references still exist, -Got an error from DosAllocMem:, Malformed PERLLIB_PREFIX, PERL_SH_DIR too -long, Process terminated by SIG%s +"my" variable %s masks earlier declaration in same scope, %s argument is +not a HASH element or slice, Allocation too large: %lx, Allocation too +large, Attempt to free non-existent shared string, Attempt to use reference +as lvalue in substr, Unsupported function fork, Ill-formed logical name +|%s| in prime_env_iter, Can't use bareword ("%s") as %s ref while "strict +refs" in use, Constant subroutine %s redefined, Died, Integer overflow in +hex number, Integer overflow in octal number, Name "%s::%s" used only once: +possible typo, Null picture in formline, Offset outside string, Stub found +while resolving method `%s' overloading `%s' in package `%s', Cannot +resolve method `%s' overloading `%s' in package `s', Out of memory!, Out of +memory during request for %s, Possible attempt to put comments in qw() +list, Possible attempt to separate words with commas, Scalar value @%s{%s} +better written as $%s{%s}, untie attempted while %d inner references still +exist, Value of %s construct can be "0"; test with defined(), Variable "%s" +may be unavailable, Variable "%s" will not stay shared, Warning: +something's wrong, Got an error from DosAllocMem, Malformed PERLLIB_PREFIX, +PERL_SH_DIR too long, Process terminated by SIG%s =item BUGS @@ -168,6 +188,8 @@ long, Process terminated by SIG%s =item PODs: Embedded Documentation +=item Plain Old Comments (Not!) + =back =head2 perlop - Perl operators and precedence @@ -1007,19 +1029,27 @@ safe subprocesses, sockets, and semaphores) =item Debugger Commands -h [command], p expr, x expr, V [pkg [vars]], X [vars], T, s [expr], n, -E<lt>CRE<gt>, c [line|sub], l, l min+incr, l min-max, l line, l subname, -, -w [line], f filename, /pattern/, ?pattern?, L, S [[!]pattern], t, t expr, b -[line] [condition], b subname [condition], b postpone subname [condition], -b load filename, d [line], D, a [line] command, A, O [opt[=val]] [opt"val"] -[opt?].., recallCommand, ShellBang, pager, tkRunning, signalLevel, -warnLevel, dieLevel, AutoTrace, LineInfo, C<inhibit_exit>, C<PrintRet>, -C<frame>, arrayDepth, hashDepth, compactDump, veryCompact, globPrint, -DumpDBFiles, DumpPackages, quote, HighBit, undefPrint, C<TTY>, noTTY, -C<noTTY>, C<ReadLine>, C<NonStop>, E<lt> [ command ], E<lt>E<lt> command, -E<gt> command, E<gt>E<gt> command, { [ command ], {{ command, ! number, ! --number, ! pattern, !! cmd, H -number, q or ^D, R, |dbcmd, ||dbcmd, = -[alias value], command, p expr +h [command], p expr, x expr, V [pkg [vars]], X [vars], T, s [expr], n +[expr], E<lt>CRE<gt>, c [line|sub], l, l min+incr, l min-max, l line, l +subname, -, w [line], f filename, /pattern/, ?pattern?, L, S [[!]pattern], +t, t expr, b [line] [condition], b subname [condition], b postpone subname +[condition], b load filename, b compile subname, d [line], D, a [line] +command, A, O [opt[=val]] [opt"val"] [opt?].., C<recallCommand>, +C<ShellBang>, C<pager>, C<tkRunning>, C<signalLevel>, C<warnLevel>, +C<dieLevel>, C<AutoTrace>, C<LineInfo>, C<inhibit_exit>, C<PrintRet>, +C<frame>, C<maxTraceLen>, C<arrayDepth>, C<hashDepth>, C<compactDump>, +C<veryCompact>, C<globPrint>, C<DumpDBFiles>, C<DumpPackages>, C<quote>, +C<HighBit>, C<undefPrint>, C<UsageOnly>, C<TTY>, C<noTTY>, C<ReadLine>, +C<NonStop>, E<lt> [ command ], E<lt>E<lt> command, E<gt> command, +E<gt>E<gt> command, { [ command ], {{ command, ! number, ! -number, ! +pattern, !! cmd, H -number, q or ^D, R, |dbcmd, ||dbcmd, = [alias value], +command, m expr, m package + +=item Debugger input/output + +Prompt, Multi-line commands, Stack backtrace, Listing, Frame listing + +=item Debugging compile-time statements =item Debugger Customization @@ -1422,7 +1452,7 @@ av_shift, av_store, av_undef, av_unshift, CLASS, Copy, croak, CvSTASH, DBsingle, DBsub, DBtrace, dMARK, dORIGMARK, dowarn, dSP, dXSARGS, dXSI32, dXSI32, ENTER, EXTEND, FREETMPS, G_ARRAY, G_DISCARD, G_EVAL, GIMME, G_NOARGS, G_SCALAR, gv_fetchmeth, gv_fetchmethod, gv_stashpv, gv_stashsv, -he_free, he_delayfree, hv_clear, hv_delete, hv_exists, hv_fetch, +GvSV, he_delayfree, he_free, hv_clear, hv_delete, hv_exists, hv_fetch, hv_iterinit, hv_iterkey, hv_iternext, hv_iternextsv, hv_iterval, hv_magic, HvNAME, hv_store, hv_undef, isALNUM, isALPHA, isDIGIT, isLOWER, isSPACE, isUPPER, items, ix, LEAVE, MARK, mg_clear, mg_copy, mg_find, mg_free, @@ -1643,13 +1673,18 @@ I<Arithmetic operations>, I<Comparison operations>, I<Bit operations>, I<Increment and decrement>, I<Transcendental functions>, I<Boolean, string and numeric conversion>, I<Special> +=item Inheritance and overloading + +Strings as values of C<use overload> directive, Overloading of an operation +is inherited by derived classes + =back =item SPECIAL SYMBOLS FOR C<use overload> =over -=item Last Resort +=item Last Resort =item Fallback @@ -1818,19 +1853,26 @@ timeit(COUNT, CODE), timethis, timethese, timediff, timestr =item Interactive Mode Searching for authors, bundles, distribution files and modules, make, test, -install, clean modules or distributions +install, clean modules or distributions, readme, look module or +distribution =item CPAN::Shell +=item autobundle + +=item recompile + =item ProgrammerE<39>s interface =item Cache Manager =item Bundles -=item autobundle +=item Prerequisites -=item recompile +=item Debugging + +=item Floppy, Zip, and all that Jazz =back @@ -1845,13 +1887,7 @@ E<lt>listE<gt> =item EXPORT -=item Debugging - -=over - -=item Prerequisites - -=back +=item BUGS =item AUTHOR @@ -2028,9 +2064,11 @@ $value, $flags) ;>, B<$status = $X-E<gt>sync([$flags]) ;> =item DESCRIPTION -@dl_library_path, @dl_resolve_using, @dl_require_symbols, dl_error(), -$dl_debug, dl_findfile(), dl_expandspec(), dl_load_file(), -dl_find_symbol(), dl_undef_symbols(), dl_install_xsub(), bootstrap() +@dl_library_path, @dl_resolve_using, @dl_require_symbols, @dl_librefs, +@dl_modules, dl_error(), $dl_debug, dl_findfile(), dl_expandspec(), +dl_load_file(), dl_loadflags(), dl_find_symbol(), +dl_find_symbol_anywhere(), dl_undef_symbols(), dl_install_xsub(), +bootstrap() =item AUTHOR diff --git a/pod/perlvar.pod b/pod/perlvar.pod index de9bd22348..248c378614 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -729,7 +729,8 @@ is about to be thrown. The error message is passed as the first argument. When a __DIE__ hook routine returns, the exception processing continues as it would have in the absence of the hook, unless the hook routine itself exits via a C<goto>, a loop exit, or a die(). -The __DIE__ handler is explicitly disabled during the call, so that you -can die from a __DIE__ handler. Similarly for __WARN__. +The C<__DIE__> handler is explicitly disabled during the call, so that you +can die from a C<__DIE__> handler. Similarly for C<__WARN__>. See +L<perlfunc/die>, L<perlfunc/warn> and L<perlfunc/eval>. =back diff --git a/pod/perlxs.pod b/pod/perlxs.pod index 26418b51a9..35d74e9eed 100644 --- a/pod/perlxs.pod +++ b/pod/perlxs.pod @@ -167,7 +167,21 @@ be received by Perl as the return value of the XSUB. If the XSUB has a return type of C<void> then the compiler will not supply a RETVAL variable for that function. When using -the PPCODE: directive the RETVAL variable may not be needed. +the PPCODE: directive the RETVAL variable is not needed, unless used +explicitly. + +If PPCODE: directive is not used, C<void> return value should be used +only for subroutines which do not return a value, I<even if> CODE: +directive is used which sets ST(0) explicitly. + +Older versions of this document recommended to use C<void> return +value in such cases. It was discovered that this could lead to +segfaults in cases when XSUB was I<truely> C<void>. This practice is +now deprecated, and may be not supported at some future version. Use +the return value C<SV *> in such cases. (Currently C<xsubpp> contains +some heuristic code which tries to disambiguate between "truely-void" +and "old-practice-declared-as-void" functions. Hence your code is at +mercy of this heuristics unless you use C<SV *> as return value.) =head2 The MODULE Keyword @@ -570,13 +584,13 @@ of $timep will either be undef or it will be a valid time. $timep = rpcb_gettime( "localhost" ); -The following XSUB uses the C<void> return type to disable the generation of -the RETVAL variable and uses a CODE: block to indicate to the compiler +The following XSUB uses the C<SV *> return type as a mneumonic only, +and uses a CODE: block to indicate to the compiler that the programmer has supplied all the necessary code. The sv_newmortal() call will initialize the return value to undef, making that the default return value. - void + SV * rpcb_gettime(host) char * host PREINIT: @@ -590,7 +604,7 @@ the default return value. The next example demonstrates how one would place an explicit undef in the return value, should the need arise. - void + SV * rpcb_gettime(host) char * host PREINIT: @@ -1102,7 +1116,7 @@ File C<RPC.xs>: Interface to some ONC+ RPC bind library functions. MODULE = RPC PACKAGE = RPC - void + SV * rpcb_gettime(host="localhost") char *host PREINIT: diff --git a/pod/pod2html.PL b/pod/pod2html.PL index 816fb6ba4c..602a866e42 100644 --- a/pod/pod2html.PL +++ b/pod/pod2html.PL @@ -14,6 +14,7 @@ use File::Basename qw(&basename &dirname); # This is so that make depend always knows where to find PL derivatives. chdir dirname($0); $file = basename($0, '.PL'); +$file .= '.com' if $^O eq 'VMS'; open OUT,">$file" or die "Can't create $file: $!"; @@ -502,7 +503,7 @@ sub gensym { sub pre_escapes { # twiddle these, and stay up late :-) my($thing) = @_; for ($$thing) { - s/([\200-\377])/noremap("&".ord($1).";")/ge; + s/([\200-\377])/noremap("&#".ord($1).";")/ge; s/"(.*?)"/``$1''/gs; s/&/noremap("&")/ge; s/<</noremap("<<")/eg; diff --git a/pod/pod2latex.PL b/pod/pod2latex.PL index 9702614ffa..3d0b55b32f 100644 --- a/pod/pod2latex.PL +++ b/pod/pod2latex.PL @@ -14,6 +14,7 @@ use File::Basename qw(&basename &dirname); # This is so that make depend always knows where to find PL derivatives. chdir dirname($0); $file = basename($0, '.PL'); +$file .= '.com' if $^O eq 'VMS'; open OUT,">$file" or die "Can't create $file: $!"; diff --git a/pod/pod2man.PL b/pod/pod2man.PL index 5d1e193a34..c03e73db26 100644 --- a/pod/pod2man.PL +++ b/pod/pod2man.PL @@ -14,6 +14,7 @@ use File::Basename qw(&basename &dirname); # This is so that make depend always knows where to find PL derivatives. chdir dirname($0); $file = basename($0, '.PL'); +$file .= '.com' if $^O eq 'VMS'; open OUT,">$file" or die "Can't create $file: $!"; diff --git a/pod/pod2text.PL b/pod/pod2text.PL index 586da04e0f..da645b554e 100644 --- a/pod/pod2text.PL +++ b/pod/pod2text.PL @@ -14,6 +14,7 @@ use File::Basename qw(&basename &dirname); # This is so that make depend always knows where to find PL derivatives. chdir dirname($0); $file = basename($0, '.PL'); +$file .= '.com' if $^O eq 'VMS'; open OUT,">$file" or die "Can't create $file: $!"; diff --git a/pod/roffitall b/pod/roffitall index 7e33326ca7..06b39188f2 100755 --- a/pod/roffitall +++ b/pod/roffitall @@ -30,7 +30,7 @@ esac toroff=` echo \ $mandir/perl.1 \ - $mandir/perlnews.1 \ + $mandir/perldelta.1 \ $mandir/perldata.1 \ $mandir/perlsyn.1 \ $mandir/perlop.1 \ |