Start fixing some pod pedantic errors
authorKarl Williamson <khw@cpan.org>
Fri, 4 Sep 2015 03:06:16 +0000 (21:06 -0600)
committerKarl Williamson <khw@cpan.org>
Fri, 4 Sep 2015 03:19:32 +0000 (21:19 -0600)
This fixes a bunch of them, but there are many more

32 files changed:
INSTALL
Porting/release_managers_guide.pod
Porting/todo.pod
README.aix
README.android
README.ce
README.cygwin
README.tru64
README.win32
ext/File-Find/lib/File/Find.pm
ext/File-Glob/Glob.pm
ext/Hash-Util-FieldHash/lib/Hash/Util/FieldHash.pm
ext/Pod-Html/testdir/perlpodspec-copy.pod
os2/OS2/OS2-ExtAttr/ExtAttr.pm
os2/OS2/OS2-Process/Process.pm
os2/OS2/OS2-REXX/DLL/DLL.pm
os2/OS2/OS2-REXX/REXX.pm
pod/perlapio.pod
pod/perlcall.pod
pod/perldebguts.pod
pod/perldebtut.pod
pod/perldebug.pod
pod/perldtrace.pod
pod/perlfunc.pod
pod/perlgpl.pod
pod/perlguts.pod
pod/perlootut.pod
pod/perlperf.pod
pod/perlsource.pod
pod/perlsub.pod
pod/perltrap.pod
t/porting/known_pod_issues.dat

diff --git a/INSTALL b/INSTALL
index 7571c48..59a8cae 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -1729,7 +1729,7 @@ bval settings.  Upgrade your DB library or OS.
 
 =item Bad arg length for semctl, is XX, should be ZZZ
 
-If you get this error message from the ext/IPC/SysV/t/sem test, your
+If you get this error message from the F<ext/IPC/SysV/t/sem.t> test, your
 System V IPC may be broken.  The XX typically is 20, and that is what ZZZ
 also should be.  Consider upgrading your OS, or reconfiguring your OS
 to include the System V semaphores.
@@ -1782,7 +1782,7 @@ NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR.
 
 UTS may need one or more of -K or -g, and #undef LSTAT.
 
-FreeBSD can fail the ext/IPC/SysV/t/sem.t test if SysV IPC has not been
+FreeBSD can fail the F<ext/IPC/SysV/t/sem.t> test if SysV IPC has not been
 configured in the kernel.  Perl tries to detect this, though, and
 you will get a message telling you what to do.
 
index 55b50bb..c13d3fb 100644 (file)
@@ -413,13 +413,13 @@ to guarantee binary compatibility in maint branches.
 After editing, regenerate uconfig.h (this must be run on a system with a
 /bin/sh available):
 
   $ perl regen/uconfig_h.pl
+ $ perl regen/uconfig_h.pl
 
 This might not cause any new changes.
 
 You may also need to regen opcodes:
 
   $ ./perl -Ilib regen/opcode.pl
+ $ ./perl -Ilib regen/opcode.pl
 
 You may have to add stub entries in C<%Module::CoreList::version>,
 C<%Module::CoreList::deprecated> and C<%Module::CoreList::Utils::delta>.
@@ -427,18 +427,18 @@ If so, you must up their version numbers as well.
 
 Test your changes:
 
   $ git clean -xdf   # careful if you don't have local files to keep!
   $ ./Configure -des -Dusedevel
   $ make
   $ make test
+ $ git clean -xdf   # careful if you don't have local files to keep!
+ $ ./Configure -des -Dusedevel
+ $ make
+ $ make test
 
 Commit your changes:
 
   $ git status
   $ git diff
   B<review the delta carefully>
+ $ git status
+ $ git diff
+ B<review the delta carefully>
 
   $ git commit -a -m 'Bump the perl version in various places for 5.x.y'
+ $ git commit -a -m 'Bump the perl version in various places for 5.x.y'
 
 At this point you may want to compare the commit with a previous bump to
 see if they look similar.  See commit f7cf42bb69 for an example of a
@@ -846,7 +846,7 @@ directory, they will still identify themselves using git tags and
 commits. (Note that for an odd-numbered version, perl will install
 itself as C<perl5.x.y>). C<perl -v> will identify itself as:
 
   This is perl 5, version X, subversion Y (v5.X.Y (v5.X.Z-NNN-gdeadbeef))
+ This is perl 5, version X, subversion Y (v5.X.Y (v5.X.Z-NNN-gdeadbeef))
 
 where 5.X.Z is the latest tag, NNN the number of commits since this tag,
 and C<< deadbeef >> commit of that tag.
@@ -885,14 +885,14 @@ L<http://tukaani.org/xz/>.
 Create a tarball. Use the C<-s> option to specify a suitable suffix for
 the tarball and directory name:
 
   $ cd root/of/perl/tree
   $ make distclean       # make sure distclean works
   $ git clean -xdf       # make sure perl and git agree on files
-                           # git clean should not output anything!
   $ git status           # and there's nothing lying around
+ $ cd root/of/perl/tree
+ $ make distclean       # make sure distclean works
+ $ git clean -xdf       # make sure perl and git agree on files
+                        # git clean should not output anything!
+ $ git status           # and there's nothing lying around
 
   $ perl Porting/makerel -bx -s RC1            # for a release candidate
   $ perl Porting/makerel -bx                   # for the release itself
+ $ perl Porting/makerel -bx -s RC1            # for a release candidate
+ $ perl Porting/makerel -bx                   # for the release itself
 
 This creates the  directory F<../perl-x.y.z-RC1> or similar, copies all
 the MANIFEST files into it, sets the correct permissions on them, then
@@ -940,9 +940,9 @@ Check that basic configuration and tests work on each test machine:
 
 Check that the test harness and install work on each test machine:
 
   $ make distclean
   $ ./Configure -des -Dprefix=/install/path && make all test_harness install
   $ cd /install/path
+ $ make distclean
+ $ ./Configure -des -Dprefix=/install/path && make all test_harness install
+ $ cd /install/path
 
 =head4 Check C<perl -v> and C<perl -V>
 
@@ -1317,9 +1317,9 @@ I<You MUST SKIP this step for RC, BLEAD-POINT>
 
 Copy the perldelta.pod for this release into blead; for example:
 
   $ cd ..../blead
   $ cp -i ../5.10.x/pod/perldelta.pod pod/perl5101delta.pod  # for example
   $ git add pod/perl5101delta.pod
+ $ cd ..../blead
$ cp -i ../5.10.x/pod/perldelta.pod pod/perl5101delta.pod  #for example
+ $ git add pod/perl5101delta.pod
 
 Don't forget to set the NAME correctly in the new file (e.g. perl5101delta
 rather than perldelta).
@@ -1423,8 +1423,8 @@ test_porting makefile target to check that they're ok.
 
 Run
 
   $ ./perl -Ilib -MModule::CoreList \
-        -le 'print Module::CoreList->find_version($]) ? "ok" : "not ok"'
+ $ ./perl -Ilib -MModule::CoreList \
+    -le 'print Module::CoreList->find_version($]) ? "ok" : "not ok"'
 
 and check that it outputs "ok" to prove that Module::CoreList now knows
 about blead's current version.
index c978e16..b23764b 100644 (file)
@@ -267,7 +267,7 @@ do a normal C<Configure>, but include Devel::Cover as a module to install
 
 =item *
 
   cd t; HARNESS_PERL_SWITCHES=-MDevel::Cover ./perl -I../lib harness
+ cd t; HARNESS_PERL_SWITCHES=-MDevel::Cover ./perl -I../lib harness
 
 =item *
 
@@ -549,8 +549,8 @@ Maybe create a utility that checks after each libperl.a creation that
 none of the above (nor sprintf(), vsprintf(), or *SHUDDER* gets())
 ever creep back to libperl.a.
 
 nm libperl.a | ./miniperl -alne '$o = $F[0] if /:$/;
-    print "$o $F[1]" if $F[0] eq "U" && $F[1] =~ /^(?:strn?c(?:at|py)|v?sprintf|gets)$/'
+ nm libperl.a | ./miniperl -alne '$o = $F[0] if /:$/;
+   print "$o $F[1]" if $F[0] eq "U" && $F[1] =~ /^(?:strn?c(?:at|py)|v?sprintf|gets)$/'
 
 Note, of course, that this will only tell whether B<your> platform
 is using those naughty interfaces.
@@ -793,11 +793,11 @@ extended.
 
 Change 25773 notes
 
   /* Need to check SvMAGICAL, as during global destruction it may be that
-       AvARYLEN(av) has been freed before av, and hence the SvANY() pointer
-       is now part of the linked list of SV heads, rather than pointing to
-       the original body.  */
   /* FIXME - audit the code for other bugs like this one.  */
+ /* Need to check SvMAGICAL, as during global destruction it may be that
+    AvARYLEN(av) has been freed before av, and hence the SvANY() pointer
+    is now part of the linked list of SV heads, rather than pointing to
+    the original body.  */
+ /* FIXME - audit the code for other bugs like this one.  */
 
 adding the C<SvMAGICAL> check to
 
@@ -1105,8 +1105,8 @@ most common and the most confusing). Ideally this code
 
 would produce this output
 
   Use of uninitialized value $undef in addition (+) at wrong.pl line 4.
   Use of uninitialized value $undef in addition (+) at wrong.pl line 7.
+ Use of uninitialized value $undef in addition (+) at wrong.pl line 4.
+ Use of uninitialized value $undef in addition (+) at wrong.pl line 7.
 
 (rather than lines 4 and 5), but this would seem to require every OP to carry
 (at least) line number information.
index 16409c2..2b02db9 100644 (file)
@@ -75,26 +75,26 @@ at least gdbm-devel-1.8.3-5 (or higher).
 
 =head2 Perl 5 was successfully compiled and tested on:
 
   Perl   | AIX Level           | Compiler Level          | w th | w/o th
   -------+---------------------+-------------------------+------+-------
   5.12.2 |5.1 TL9 32 bit       | XL C/C++ V7             | OK   | OK
   5.12.2 |5.1 TL9 64 bit       | XL C/C++ V7             | OK   | OK
   5.12.2 |5.2 TL10 SP8 32 bit  | XL C/C++ V8             | OK   | OK
   5.12.2 |5.2 TL10 SP8 32 bit  | gcc 3.2.2               | OK   | OK
   5.12.2 |5.2 TL10 SP8 64 bit  | XL C/C++ V8             | OK   | OK
   5.12.2 |5.3 TL8 SP8 32 bit   | XL C/C++ V9 + IZ35785   | OK   | OK
   5.12.2 |5.3 TL8 SP8 32 bit   | gcc 4.2.4               | OK   | OK
   5.12.2 |5.3 TL8 SP8 64 bit   | XL C/C++ V9 + IZ35785   | OK   | OK
   5.12.2 |5.3 TL10 SP3 32 bit  | XL C/C++ V11 + Apr 2010 | OK   | OK
   5.12.2 |5.3 TL10 SP3 64 bit  | XL C/C++ V11 + Apr 2010 | OK   | OK
   5.12.2 |6.1 TL1 SP7 32 bit   | XL C/C++ V10            | OK   | OK
   5.12.2 |6.1 TL1 SP7 64 bit   | XL C/C++ V10            | OK   | OK
   5.13   |7.1 TL0 SP1 32 bit   | XL C/C++ V11 + Jul 2010 | OK   | OK
   5.13   |7.1 TL0 SP1 64 bit   | XL C/C++ V11 + Jul 2010 | OK   | OK
-
   w th   = with thread support
   w/o th = without thread support
   OK     = tested
+ Perl   | AIX Level           | Compiler Level          | w th | w/o th
+ -------+---------------------+-------------------------+------+-------
+ 5.12.2 |5.1 TL9 32 bit       | XL C/C++ V7             | OK   | OK
+ 5.12.2 |5.1 TL9 64 bit       | XL C/C++ V7             | OK   | OK
+ 5.12.2 |5.2 TL10 SP8 32 bit  | XL C/C++ V8             | OK   | OK
+ 5.12.2 |5.2 TL10 SP8 32 bit  | gcc 3.2.2               | OK   | OK
+ 5.12.2 |5.2 TL10 SP8 64 bit  | XL C/C++ V8             | OK   | OK
+ 5.12.2 |5.3 TL8 SP8 32 bit   | XL C/C++ V9 + IZ35785   | OK   | OK
+ 5.12.2 |5.3 TL8 SP8 32 bit   | gcc 4.2.4               | OK   | OK
+ 5.12.2 |5.3 TL8 SP8 64 bit   | XL C/C++ V9 + IZ35785   | OK   | OK
+ 5.12.2 |5.3 TL10 SP3 32 bit  | XL C/C++ V11 + Apr 2010 | OK   | OK
+ 5.12.2 |5.3 TL10 SP3 64 bit  | XL C/C++ V11 + Apr 2010 | OK   | OK
+ 5.12.2 |6.1 TL1 SP7 32 bit   | XL C/C++ V10            | OK   | OK
+ 5.12.2 |6.1 TL1 SP7 64 bit   | XL C/C++ V10            | OK   | OK
+ 5.13   |7.1 TL0 SP1 32 bit   | XL C/C++ V11 + Jul 2010 | OK   | OK
+ 5.13   |7.1 TL0 SP1 64 bit   | XL C/C++ V11 + Jul 2010 | OK   | OK
+
+ w th   = with thread support
+ w/o th = without thread support
+ OK     = tested
 
 Successfully tested means that all "make test" runs finish with a
 result of 100% OK. All tests were conducted with -Duseshrplib set.
@@ -210,31 +210,31 @@ IBM AIX system Perl installation.
 With the following options you get a threaded Perl version which
 passes all make tests in 64-bit mode.
 
   export OBJECT_MODE=64 / setenv OBJECT_MODE 64 (depending on your shell)
+ export OBJECT_MODE=64 / setenv OBJECT_MODE 64 (depending on your shell)
 
   rm config.sh
   ./Configure \
   -d \
   -Dcc=cc_r \
   -Duseshrplib \
   -Dusethreads \
   -Duse64bitall \
   -Dprefix=/usr/opt/perl5_64
+ rm config.sh
+ ./Configure \
+ -d \
+ -Dcc=cc_r \
+ -Duseshrplib \
+ -Dusethreads \
+ -Duse64bitall \
+ -Dprefix=/usr/opt/perl5_64
 
 =head2 Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (64-bit)
 
 With the following options you get a Perl version which passes all
 make tests in 64-bit mode. 
 
   export OBJECT_MODE=64 / setenv OBJECT_MODE 64 (depending on your shell)
+ export OBJECT_MODE=64 / setenv OBJECT_MODE 64 (depending on your shell)
 
   rm config.sh
   ./Configure \
   -d \
   -Dcc=cc_r \
   -Duseshrplib \
   -Duse64bitall \
   -Dprefix=/usr/opt/perl5_64
+ rm config.sh
+ ./Configure \
+ -d \
+ -Dcc=cc_r \
+ -Duseshrplib \
+ -Duse64bitall \
+ -Dprefix=/usr/opt/perl5_64
 
 The -Dprefix option will install Perl in a directory parallel to the
 IBM AIX system Perl installation.
@@ -357,7 +357,8 @@ in the developer snapshots of Perl), or to one version up where the
 cumulative.
 
  vac.C.4.4.0.1 => vac.C.4.4.0.3  is OK     (vac.C.4.4.0.2 not needed)
- xlC.C.3.1.3.3 => xlC.C.3.1.4.10 is NOT OK (xlC.C.3.1.4.0 is not available)
+ xlC.C.3.1.3.3 => xlC.C.3.1.4.10 is NOT OK (xlC.C.3.1.4.0 is not
+                                                              available)
 
  # ftp ftp.software.ibm.com
  Connected to service.boulder.ibm.com.
@@ -389,16 +390,16 @@ On AIX 4.2 using xlC, we continue:
    xlC.C                     3.1.4.9  COMMITTED  C for AIX Compiler
    xlC.C                     3.1.4.0  COMMITTED  C for AIX Compiler
  # grep 'xlC.C.3.1.4.*.bff' xlc.ll
- -rw-r--r--   1 45776101 1        6286336 Jul 22 1996  xlC.C.3.1.4.1.bff
- -rw-rw-r--   1 45776101 1        6173696 Aug 24 1998  xlC.C.3.1.4.10.bff
- -rw-r--r--   1 45776101 1        6319104 Aug 14 1996  xlC.C.3.1.4.2.bff
- -rw-r--r--   1 45776101 1        6316032 Oct 21 1996  xlC.C.3.1.4.3.bff
- -rw-r--r--   1 45776101 1        6315008 Dec 20 1996  xlC.C.3.1.4.4.bff
- -rw-rw-r--   1 45776101 1        6178816 Mar 28 1997  xlC.C.3.1.4.5.bff
- -rw-rw-r--   1 45776101 1        6188032 May 22 1997  xlC.C.3.1.4.6.bff
- -rw-rw-r--   1 45776101 1        6191104 Sep  5 1997  xlC.C.3.1.4.7.bff
- -rw-rw-r--   1 45776101 1        6185984 Jan 13 1998  xlC.C.3.1.4.8.bff
- -rw-rw-r--   1 45776101 1        6169600 May 27 1998  xlC.C.3.1.4.9.bff
+ -rw-r--r--   1 45776101 1       6286336 Jul 22 1996  xlC.C.3.1.4.1.bff
+ -rw-rw-r--   1 45776101 1       6173696 Aug 24 1998  xlC.C.3.1.4.10.bff
+ -rw-r--r--   1 45776101 1       6319104 Aug 14 1996  xlC.C.3.1.4.2.bff
+ -rw-r--r--   1 45776101 1       6316032 Oct 21 1996  xlC.C.3.1.4.3.bff
+ -rw-r--r--   1 45776101 1       6315008 Dec 20 1996  xlC.C.3.1.4.4.bff
+ -rw-rw-r--   1 45776101 1       6178816 Mar 28 1997  xlC.C.3.1.4.5.bff
+ -rw-rw-r--   1 45776101 1       6188032 May 22 1997  xlC.C.3.1.4.6.bff
+ -rw-rw-r--   1 45776101 1       6191104 Sep  5 1997  xlC.C.3.1.4.7.bff
+ -rw-rw-r--   1 45776101 1       6185984 Jan 13 1998  xlC.C.3.1.4.8.bff
+ -rw-rw-r--   1 45776101 1       6169600 May 27 1998  xlC.C.3.1.4.9.bff
  # wget ftp://ftp.software.ibm.com/aix/fixes/v4/xlc/xlC.C.3.1.4.10.bff
  #
 
@@ -408,10 +409,10 @@ On AIX 4.3 using vac, we continue:
   vac.C                      5.0.2.2  COMMITTED  C for AIX Compiler
   vac.C                      5.0.2.0  COMMITTED  C for AIX Compiler
  # grep 'vac.C.5.0.2.*.bff' other.ll
- -rw-rw-r--   1 45776101 1        13592576 Apr 16 2001  vac.C.5.0.2.0.bff
- -rw-rw-r--   1 45776101 1        14133248 Apr  9 2002  vac.C.5.0.2.3.bff
- -rw-rw-r--   1 45776101 1        14173184 May 20 2002  vac.C.5.0.2.4.bff
- -rw-rw-r--   1 45776101 1        14192640 Nov 22 2002  vac.C.5.0.2.6.bff
+ -rw-rw-r--   1 45776101 1       13592576 Apr 16 2001  vac.C.5.0.2.0.bff
+ -rw-rw-r--   1 45776101 1       14133248 Apr  9 2002  vac.C.5.0.2.3.bff
+ -rw-rw-r--   1 45776101 1       14173184 May 20 2002  vac.C.5.0.2.4.bff
+ -rw-rw-r--   1 45776101 1       14192640 Nov 22 2002  vac.C.5.0.2.6.bff
  # wget ftp://ftp.software.ibm.com/aix/fixes/v4/other/vac.C.5.0.2.6.bff
  #
 
@@ -445,7 +446,8 @@ causes error like this
  ld: 0711-317 ERROR: Undefined symbol: .setresuid
  ld: 0711-317 ERROR: Undefined symbol: .setresgid
  ld: 0711-317 ERROR: Undefined symbol: .setproctitle
- ld: 0711-345 Use the -bloadmap or -bnoquiet option to obtain more information.
+ ld: 0711-345 Use the -bloadmap or -bnoquiet option to obtain more
+                                                            information.
 
 you could retry with
 
index d319936..b774d9f 100644 (file)
@@ -190,9 +190,9 @@ in.  For example, CCTools installs its toolchain in
 /data/data/com.pdaxrom.cctools/root/cctools.  With the path in hand,
 compiling perl is little more than:
 
   export SYSROOT=<location of the native toolchain>
   export LD_LIBRARY_PATH="$SYSROOT/lib:`pwd`:`pwd`/lib:`pwd`/lib/auto:$LD_LIBRARY_PATH"
   sh Configure -des -Dsysroot=$SYSROOT -Alibpth="/system/lib /vendor/lib"
+ export SYSROOT=<location of the native toolchain>
+ export LD_LIBRARY_PATH="$SYSROOT/lib:`pwd`:`pwd`/lib:`pwd`/lib/auto:$LD_LIBRARY_PATH"
+ sh Configure -des -Dsysroot=$SYSROOT -Alibpth="/system/lib /vendor/lib"
 
 =head1 AUTHOR
 
index 3559f1f..bb7a6ab 100644 (file)
--- a/README.ce
+++ b/README.ce
@@ -73,11 +73,11 @@ Windows then change "C:\Program Files" to "C:\Program Files (x86)" throughout.)
 
 1. Install EVC4 from
 
-    http://download.microsoft.com/download/c/3/f/c3f8b58b-9753-4c2e-8b96-2dfe3476a2f7/eVC4.exe 
+ http://download.microsoft.com/download/c/3/f/c3f8b58b-9753-4c2e-8b96-2dfe3476a2f7/eVC4.exe
 
 Use the key mentioned at 
 
-    http://download.cnet.com/Microsoft-eMbedded-Visual-C/3000-2212_4-10108490.html?tag=bc 
+ http://download.cnet.com/Microsoft-eMbedded-Visual-C/3000-2212_4-10108490.html?tag=bc
 
 The installer is ancient and has a few bugs on the paths it uses. You 
 will have to fix them later. Basically, some things go into "C:/Program 
@@ -101,7 +101,7 @@ Mobile/WinCE are backwards compatible with machine code like Desktop Windows.
 
 3. Download console-1.3-src.tar.gz from 
 
-    http://sourceforge.net/projects/perlce/files/PerlCE%20support%20files/console/ 
+ http://sourceforge.net/projects/perlce/files/PerlCE%20support%20files/console/
 
 Extract it to a spaceless path but not into the perl build source. 
 Don't extract it into the same directory as celib. Make a copy of the 
index 691da50..388dc1a 100644 (file)
@@ -553,188 +553,188 @@ be kept as clean as possible.
 
 =item Documentation
 
 INSTALL README.cygwin README.win32 MANIFEST
 pod/perl.pod pod/perlport.pod pod/perlfaq3.pod
 pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod
 pod/perl561delta.pod pod/perl570delta.pod pod/perl572delta.pod
 pod/perl573delta.pod pod/perl58delta.pod pod/perl581delta.pod
 pod/perl590delta.pod pod/perlhist.pod pod/perlmodlib.pod
 pod/perltoc.pod Porting/Glossary pod/perlgit.pod
 Porting/checkAUTHORS.pl
 dist/Cwd/Changes ext/Compress-Raw-Zlib/Changes
 ext/Compress-Raw-Zlib/README ext/Compress-Zlib/Changes
 ext/DB_File/Changes ext/Encode/Changes ext/Sys-Syslog/Changes
 ext/Time-HiRes/Changes ext/Win32API-File/Changes
 lib/ExtUtils/CBuilder/Changes lib/ExtUtils/Changes lib/ExtUtils/NOTES
 lib/ExtUtils/PATCHING lib/ExtUtils/README
 lib/Net/Ping/Changes lib/Test/Harness/Changes
 lib/Term/ANSIColor/ChangeLog lib/Term/ANSIColor/README README.symbian
 symbian/TODO
+ INSTALL README.cygwin README.win32 MANIFEST
+ pod/perl.pod pod/perlport.pod pod/perlfaq3.pod
+ pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod
+ pod/perl561delta.pod pod/perl570delta.pod pod/perl572delta.pod
+ pod/perl573delta.pod pod/perl58delta.pod pod/perl581delta.pod
+ pod/perl590delta.pod pod/perlhist.pod pod/perlmodlib.pod
+ pod/perltoc.pod Porting/Glossary pod/perlgit.pod
+ Porting/checkAUTHORS.pl
+ dist/Cwd/Changes ext/Compress-Raw-Zlib/Changes
+ ext/Compress-Raw-Zlib/README ext/Compress-Zlib/Changes
+ ext/DB_File/Changes ext/Encode/Changes ext/Sys-Syslog/Changes
+ ext/Time-HiRes/Changes ext/Win32API-File/Changes
+ lib/ExtUtils/CBuilder/Changes lib/ExtUtils/Changes lib/ExtUtils/NOTES
+ lib/ExtUtils/PATCHING lib/ExtUtils/README
+ lib/Net/Ping/Changes lib/Test/Harness/Changes
+ lib/Term/ANSIColor/ChangeLog lib/Term/ANSIColor/README README.symbian
+ symbian/TODO
 
 =item Build, Configure, Make, Install
 
 cygwin/Makefile.SHs
 ext/IPC/SysV/hints/cygwin.pl
 ext/NDBM_File/hints/cygwin.pl
 ext/ODBM_File/hints/cygwin.pl
 hints/cygwin.sh
 Configure             - help finding hints from uname,
-                          shared libperl required for dynamic loading
 Makefile.SH Cross/Makefile-cross-SH
-                        - linklibperl
 Porting/patchls       - cygwin in port list
 installman            - man pages with :: translated to .
 installperl           - install dll, install to 'pods'
 makedepend.SH         - uwinfix
 regen_lib.pl          - file permissions
-
 NetWare/Makefile
 plan9/mkfile
 symbian/sanity.pl symbian/sisify.pl
 hints/uwin.sh
 vms/descrip_mms.template
 win32/Makefile win32/makefile.mk
+ cygwin/Makefile.SHs
+ ext/IPC/SysV/hints/cygwin.pl
+ ext/NDBM_File/hints/cygwin.pl
+ ext/ODBM_File/hints/cygwin.pl
+ hints/cygwin.sh
+ Configure             - help finding hints from uname,
+                         shared libperl required for dynamic loading
+ Makefile.SH Cross/Makefile-cross-SH
+                       - linklibperl
+ Porting/patchls       - cygwin in port list
+ installman            - man pages with :: translated to .
+ installperl           - install dll, install to 'pods'
+ makedepend.SH         - uwinfix
+ regen_lib.pl          - file permissions
+
+ NetWare/Makefile
+ plan9/mkfile
+ symbian/sanity.pl symbian/sisify.pl
+ hints/uwin.sh
+ vms/descrip_mms.template
+ win32/Makefile win32/makefile.mk
 
 =item Tests
 
 t/io/fs.t             - no file mode checks if not ntsec
-                          skip rename() check when not check_case:relaxed
 t/io/tell.t           - binmode
 t/lib/cygwin.t        - builtin cygwin function tests
 t/op/groups.t         - basegroup has ID = 0
 t/op/magic.t          - $^X/symlink WORKAROUND, s/.exe//
 t/op/stat.t           - no /dev, skip Win32 ftCreationTime quirk
-                          (cache manager sometimes preserves ctime of file
-                          previously created and deleted), no -u (setuid)
 t/op/taint.t          - can't use empty path under Cygwin Perl
 t/op/time.t           - no tzset()
+ t/io/fs.t             - no file mode checks if not ntsec
+                         skip rename() check when not check_case:relaxed
+ t/io/tell.t           - binmode
+ t/lib/cygwin.t        - builtin cygwin function tests
+ t/op/groups.t         - basegroup has ID = 0
+ t/op/magic.t          - $^X/symlink WORKAROUND, s/.exe//
+ t/op/stat.t           - no /dev, skip Win32 ftCreationTime quirk
+                         (cache manager sometimes preserves ctime of file
+                         previously created and deleted), no -u (setuid)
+ t/op/taint.t          - can't use empty path under Cygwin Perl
+ t/op/time.t           - no tzset()
 
 =item Compiled Perl Source
 
 EXTERN.h              - __declspec(dllimport)
 XSUB.h                - __declspec(dllexport)
 cygwin/cygwin.c       - os_extras (getcwd, spawn, and several Cygwin:: functions)
 perl.c                - os_extras, -i.bak
 perl.h                - binmode
 doio.c                - win9x can not rename a file when it is open
 pp_sys.c              - do not define h_errno, init _pwent_struct.pw_comment
 util.c                - use setenv
 util.h                - PERL_FILE_IS_ABSOLUTE macro
 pp.c                  - Comment about Posix vs IEEE math under Cygwin
 perlio.c              - CR/LF mode
 perliol.c             - Comment about EXTCONST under Cygwin
+ EXTERN.h              - __declspec(dllimport)
+ XSUB.h                - __declspec(dllexport)
+ cygwin/cygwin.c       - os_extras (getcwd, spawn, and several Cygwin:: functions)
+ perl.c                - os_extras, -i.bak
+ perl.h                - binmode
+ doio.c                - win9x can not rename a file when it is open
+ pp_sys.c              - do not define h_errno, init _pwent_struct.pw_comment
+ util.c                - use setenv
+ util.h                - PERL_FILE_IS_ABSOLUTE macro
+ pp.c                  - Comment about Posix vs IEEE math under Cygwin
+ perlio.c              - CR/LF mode
+ perliol.c             - Comment about EXTCONST under Cygwin
 
 =item Compiled Module Source
 
 ext/Compress-Raw-Zlib/Makefile.PL
-                        - Can't install via CPAN shell under Cygwin
 ext/Compress-Raw-Zlib/zlib-src/zutil.h
-                        - Cygwin is Unix-like and has vsnprintf
 ext/Errno/Errno_pm.PL - Special handling for Win32 Perl under Cygwin
 ext/POSIX/POSIX.xs    - tzname defined externally
 ext/SDBM_File/sdbm/pair.c
-                        - EXTCONST needs to be redefined from EXTERN.h
 ext/SDBM_File/sdbm/sdbm.c
-                        - binary open
 ext/Sys/Syslog/Syslog.xs
-                        - Cygwin has syslog.h
 ext/Sys/Syslog/win32/compile.pl
-                        - Convert paths to Windows paths
 ext/Time-HiRes/HiRes.xs
-                        - Various timers not available
 ext/Time-HiRes/Makefile.PL
-                        - Find w32api/windows.h
 ext/Win32/Makefile.PL - Use various libraries under Cygwin
 ext/Win32/Win32.xs    - Child dir and child env under Cygwin
 ext/Win32API-File/File.xs
-                        - _open_osfhandle not implemented under Cygwin
 ext/Win32CORE/Win32CORE.c
-                        - __declspec(dllexport)
+ ext/Compress-Raw-Zlib/Makefile.PL
+                       - Can't install via CPAN shell under Cygwin
+ ext/Compress-Raw-Zlib/zlib-src/zutil.h
+                       - Cygwin is Unix-like and has vsnprintf
+ ext/Errno/Errno_pm.PL - Special handling for Win32 Perl under Cygwin
+ ext/POSIX/POSIX.xs    - tzname defined externally
+ ext/SDBM_File/sdbm/pair.c
+                       - EXTCONST needs to be redefined from EXTERN.h
+ ext/SDBM_File/sdbm/sdbm.c
+                       - binary open
+ ext/Sys/Syslog/Syslog.xs
+                       - Cygwin has syslog.h
+ ext/Sys/Syslog/win32/compile.pl
+                       - Convert paths to Windows paths
+ ext/Time-HiRes/HiRes.xs
+                       - Various timers not available
+ ext/Time-HiRes/Makefile.PL
+                       - Find w32api/windows.h
+ ext/Win32/Makefile.PL - Use various libraries under Cygwin
+ ext/Win32/Win32.xs    - Child dir and child env under Cygwin
+ ext/Win32API-File/File.xs
+                       - _open_osfhandle not implemented under Cygwin
+ ext/Win32CORE/Win32CORE.c
+                       - __declspec(dllexport)
 
 =item Perl Modules/Scripts
 
 ext/B/t/OptreeCheck.pm - Comment about stderr/stdout order under Cygwin
 ext/Digest-SHA/bin/shasum
-                        - Use binary mode under Cygwin
 ext/Sys/Syslog/win32/Win32.pm
-                        - Convert paths to Windows paths
 ext/Time-HiRes/HiRes.pm
-                        - Comment about various timers not available
 ext/Win32API-File/File.pm
-                        - _open_osfhandle not implemented under Cygwin
 ext/Win32CORE/Win32CORE.pm
-                        - History of Win32CORE under Cygwin
 lib/Cwd.pm            - hook to internal Cwd::cwd
 lib/ExtUtils/CBuilder/Platform/cygwin.pm
-                        - use gcc for ld, and link to libperl.dll.a
 lib/ExtUtils/CBuilder.pm
-                        - Cygwin is Unix-like
 lib/ExtUtils/Install.pm - Install and rename issues under Cygwin
 lib/ExtUtils/MM.pm    - OS classifications
 lib/ExtUtils/MM_Any.pm - Example for Cygwin
 lib/ExtUtils/MakeMaker.pm
-                        - require MM_Cygwin.pm
 lib/ExtUtils/MM_Cygwin.pm
-                        - canonpath, cflags, manifypods, perl_archive
 lib/File/Fetch.pm     - Comment about quotes using a Cygwin example
 lib/File/Find.pm      - on remote drives stat() always sets st_nlink to 1
 lib/File/Spec/Cygwin.pm - case_tolerant
 lib/File/Spec/Unix.pm - preserve //unc
 lib/File/Spec/Win32.pm - References a message on cygwin.com
 lib/File/Spec.pm      - Pulls in lib/File/Spec/Cygwin.pm
 lib/File/Temp.pm      - no directory sticky bit
 lib/Module/CoreList.pm - List of all module files and versions
 lib/Net/Domain.pm     - No domainname command under Cygwin
 lib/Net/Netrc.pm      - Bypass using stat() under Cygwin
 lib/Net/Ping.pm       - ECONREFUSED is EAGAIN under Cygwin
 lib/Pod/Find.pm       - Set 'pods' dir
 lib/Pod/Perldoc/ToMan.pm - '-c' switch for pod2man
 lib/Pod/Perldoc.pm    - Use 'less' pager, and use .exe extension
 lib/Term/ANSIColor.pm - Cygwin terminal info
 lib/perl5db.pl        - use stdin not /dev/tty
 utils/perlbug.PL      - Add CYGWIN environment variable to report
+ ext/B/t/OptreeCheck.pm - Comment about stderr/stdout order under Cygwin
+ ext/Digest-SHA/bin/shasum
+                       - Use binary mode under Cygwin
+ ext/Sys/Syslog/win32/Win32.pm
+                       - Convert paths to Windows paths
+ ext/Time-HiRes/HiRes.pm
+                       - Comment about various timers not available
+ ext/Win32API-File/File.pm
+                       - _open_osfhandle not implemented under Cygwin
+ ext/Win32CORE/Win32CORE.pm
+                       - History of Win32CORE under Cygwin
+ lib/Cwd.pm            - hook to internal Cwd::cwd
+ lib/ExtUtils/CBuilder/Platform/cygwin.pm
+                       - use gcc for ld, and link to libperl.dll.a
+ lib/ExtUtils/CBuilder.pm
+                       - Cygwin is Unix-like
+ lib/ExtUtils/Install.pm - Install and rename issues under Cygwin
+ lib/ExtUtils/MM.pm    - OS classifications
+ lib/ExtUtils/MM_Any.pm - Example for Cygwin
+ lib/ExtUtils/MakeMaker.pm
+                       - require MM_Cygwin.pm
+ lib/ExtUtils/MM_Cygwin.pm
+                       - canonpath, cflags, manifypods, perl_archive
+ lib/File/Fetch.pm     - Comment about quotes using a Cygwin example
+ lib/File/Find.pm      - on remote drives stat() always sets st_nlink to 1
+ lib/File/Spec/Cygwin.pm - case_tolerant
+ lib/File/Spec/Unix.pm - preserve //unc
+ lib/File/Spec/Win32.pm - References a message on cygwin.com
+ lib/File/Spec.pm      - Pulls in lib/File/Spec/Cygwin.pm
+ lib/File/Temp.pm      - no directory sticky bit
+ lib/Module/CoreList.pm - List of all module files and versions
+ lib/Net/Domain.pm     - No domainname command under Cygwin
+ lib/Net/Netrc.pm      - Bypass using stat() under Cygwin
+ lib/Net/Ping.pm       - ECONREFUSED is EAGAIN under Cygwin
+ lib/Pod/Find.pm       - Set 'pods' dir
+ lib/Pod/Perldoc/ToMan.pm - '-c' switch for pod2man
+ lib/Pod/Perldoc.pm    - Use 'less' pager, and use .exe extension
+ lib/Term/ANSIColor.pm - Cygwin terminal info
+ lib/perl5db.pl        - use stdin not /dev/tty
+ utils/perlbug.PL      - Add CYGWIN environment variable to report
 
 =item Perl Module Tests
 
 dist/Cwd/t/cwd.t
 ext/Compress-Zlib/t/14gzopen.t
 ext/DB_File/t/db-btree.t
 ext/DB_File/t/db-hash.t
 ext/DB_File/t/db-recno.t
 ext/DynaLoader/t/DynaLoader.t
 ext/File-Glob/t/basic.t
 ext/GDBM_File/t/gdbm.t
 ext/POSIX/t/sysconf.t
 ext/POSIX/t/time.t
 ext/SDBM_File/t/sdbm.t
 ext/Sys/Syslog/t/syslog.t
 ext/Time-HiRes/t/HiRes.t
 ext/Win32/t/Unicode.t
 ext/Win32API-File/t/file.t
 ext/Win32CORE/t/win32core.t
 lib/AnyDBM_File.t
 lib/Archive/Extract/t/01_Archive-Extract.t
 lib/Archive/Tar/t/02_methods.t
 lib/ExtUtils/t/Embed.t
 lib/ExtUtils/t/eu_command.t
 lib/ExtUtils/t/MM_Cygwin.t
 lib/ExtUtils/t/MM_Unix.t
 lib/File/Compare.t
 lib/File/Copy.t
 lib/File/Find/t/find.t
 lib/File/Path.t
 lib/File/Spec/t/crossplatform.t
 lib/File/Spec/t/Spec.t
 lib/Net/hostent.t
 lib/Net/Ping/t/110_icmp_inst.t
 lib/Net/Ping/t/500_ping_icmp.t
 lib/Net/t/netrc.t
 lib/Pod/Simple/t/perlcyg.pod
 lib/Pod/Simple/t/perlcygo.txt
 lib/Pod/Simple/t/perlfaq.pod
 lib/Pod/Simple/t/perlfaqo.txt
 lib/User/grent.t
 lib/User/pwent.t
+ dist/Cwd/t/cwd.t
+ ext/Compress-Zlib/t/14gzopen.t
+ ext/DB_File/t/db-btree.t
+ ext/DB_File/t/db-hash.t
+ ext/DB_File/t/db-recno.t
+ ext/DynaLoader/t/DynaLoader.t
+ ext/File-Glob/t/basic.t
+ ext/GDBM_File/t/gdbm.t
+ ext/POSIX/t/sysconf.t
+ ext/POSIX/t/time.t
+ ext/SDBM_File/t/sdbm.t
+ ext/Sys/Syslog/t/syslog.t
+ ext/Time-HiRes/t/HiRes.t
+ ext/Win32/t/Unicode.t
+ ext/Win32API-File/t/file.t
+ ext/Win32CORE/t/win32core.t
+ lib/AnyDBM_File.t
+ lib/Archive/Extract/t/01_Archive-Extract.t
+ lib/Archive/Tar/t/02_methods.t
+ lib/ExtUtils/t/Embed.t
+ lib/ExtUtils/t/eu_command.t
+ lib/ExtUtils/t/MM_Cygwin.t
+ lib/ExtUtils/t/MM_Unix.t
+ lib/File/Compare.t
+ lib/File/Copy.t
+ lib/File/Find/t/find.t
+ lib/File/Path.t
+ lib/File/Spec/t/crossplatform.t
+ lib/File/Spec/t/Spec.t
+ lib/Net/hostent.t
+ lib/Net/Ping/t/110_icmp_inst.t
+ lib/Net/Ping/t/500_ping_icmp.t
+ lib/Net/t/netrc.t
+ lib/Pod/Simple/t/perlcyg.pod
+ lib/Pod/Simple/t/perlcygo.txt
+ lib/Pod/Simple/t/perlfaq.pod
+ lib/Pod/Simple/t/perlfaqo.txt
+ lib/User/grent.t
+ lib/User/pwent.t
 
 =back
 
index 5e3ae85..d171460 100644 (file)
@@ -145,7 +145,7 @@ instructs Perl not to use the feature.
 
 =head1 Testing Perl on Tru64
 
-During "make test" the C<comp/cpp> will be skipped because on Tru64 it
+During "make test" the C<comp>/C<cpp> will be skipped because on Tru64 it
 cannot be tested before Perl has been installed.  The test refers to
 the use of the C<-P> option of Perl.
 
index b4a07a6..d6c50d7 100644 (file)
@@ -156,7 +156,7 @@ changing so often.)
 
 Install Visual C++ 2008-2013 Express, then setup your environment using, e.g.
 
      C:\Program Files\Microsoft Visual Studio 12.0\Common7\Tools\vsvars32.bat
+ C:\Program Files\Microsoft Visual Studio 12.0\Common7\Tools\vsvars32.bat
 
 (assuming the default installation location was chosen).
 
@@ -185,15 +185,15 @@ also runs on Windows XP SP2 and Windows 2000.
 Install Visual C++ 2005 first, then the Platform SDK.  Setup your environment
 as follows (assuming default installation locations were chosen):
 
      SET PlatformSDKDir=C:\Program Files\Microsoft Platform SDK
+ SET PlatformSDKDir=C:\Program Files\Microsoft Platform SDK
 
      SET PATH=%SystemRoot%\system32;%SystemRoot%;C:\Program Files\Microsoft Visual Studio 8\Common7\IDE;C:\Program Files\Microsoft Visual Studio 8\VC\BIN;C:\Program Files\Microsoft Visual Studio 8\Common7\Tools;C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\bin;C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727;C:\Program Files\Microsoft Visual Studio 8\VC\VCPackages;%PlatformSDKDir%\Bin
+ SET PATH=%SystemRoot%\system32;%SystemRoot%;C:\Program Files\Microsoft Visual Studio 8\Common7\IDE;C:\Program Files\Microsoft Visual Studio 8\VC\BIN;C:\Program Files\Microsoft Visual Studio 8\Common7\Tools;C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\bin;C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727;C:\Program Files\Microsoft Visual Studio 8\VC\VCPackages;%PlatformSDKDir%\Bin
 
      SET INCLUDE=C:\Program Files\Microsoft Visual Studio 8\VC\INCLUDE;%PlatformSDKDir%\include
+ SET INCLUDE=C:\Program Files\Microsoft Visual Studio 8\VC\INCLUDE;%PlatformSDKDir%\include
 
      SET LIB=C:\Program Files\Microsoft Visual Studio 8\VC\LIB;C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\lib;%PlatformSDKDir%\lib
+ SET LIB=C:\Program Files\Microsoft Visual Studio 8\VC\LIB;C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\lib;%PlatformSDKDir%\lib
 
      SET LIBPATH=C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727
+ SET LIBPATH=C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727
 
 (The PlatformSDKDir might need to be set differently depending on which version
 you are using. Earlier versions installed into "C:\Program Files\Microsoft SDK",
@@ -203,7 +203,7 @@ while the latest versions install into version-specific locations such as
 Perl should now build using the win32/Makefile.  You will need to edit that
 file to set
 
      CCTYPE = MSVC80FREE
+ CCTYPE = MSVC80FREE
 
 and to set CCHOME, CCINCDIR and CCLIBDIR as per the environment setup above.
 
@@ -234,13 +234,13 @@ Install the Toolkit first, then the Platform SDK, then the .NET Framework SDK.
 Setup your environment as follows (assuming default installation locations
 were chosen):
 
      SET PlatformSDKDir=C:\Program Files\Microsoft Platform SDK
+ SET PlatformSDKDir=C:\Program Files\Microsoft Platform SDK
 
      SET PATH=%SystemRoot%\system32;%SystemRoot%;C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin;%PlatformSDKDir%\Bin;C:\Program Files\Microsoft.NET\SDK\v1.1\Bin
+ SET PATH=%SystemRoot%\system32;%SystemRoot%;C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin;%PlatformSDKDir%\Bin;C:\Program Files\Microsoft.NET\SDK\v1.1\Bin
 
      SET INCLUDE=C:\Program Files\Microsoft Visual C++ Toolkit 2003\include;%PlatformSDKDir%\include;C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\include
+ SET INCLUDE=C:\Program Files\Microsoft Visual C++ Toolkit 2003\include;%PlatformSDKDir%\include;C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\include
 
      SET LIB=C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib;%PlatformSDKDir%\lib;C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\lib
+ SET LIB=C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib;%PlatformSDKDir%\lib;C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\lib
 
 (The PlatformSDKDir might need to be set differently depending on which version
 you are using. Earlier versions installed into "C:\Program Files\Microsoft SDK",
@@ -257,7 +257,7 @@ cvtres.exe is required by link.exe when using a .res file.  It is actually
 installed by the .NET Framework SDK, but into a location such as the
 following:
 
      C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322
+ C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322
 
 Copy it from there to %PlatformSDKDir%\Bin
 
@@ -488,13 +488,13 @@ C<HKEY_CURRENT_USER\Software\Perl> and C<HKEY_LOCAL_MACHINE\Software\Perl>.
 Entries in the former override entries in the latter.  One or more of the
 following entries (of type REG_SZ or REG_EXPAND_SZ) may be set:
 
   lib-$]             version-specific standard library path to add to @INC
   lib                        standard library path to add to @INC
   sitelib-$]         version-specific site library path to add to @INC
   sitelib            site library path to add to @INC
   vendorlib-$]       version-specific vendor library path to add to @INC
   vendorlib          vendor library path to add to @INC
   PERL*              fallback for all %ENV lookups that begin with "PERL"
lib-$]        version-specific standard library path to add to @INC
lib           standard library path to add to @INC
sitelib-$]    version-specific site library path to add to @INC
sitelib       site library path to add to @INC
vendorlib-$]  version-specific vendor library path to add to @INC
vendorlib     vendor library path to add to @INC
PERL*         fallback for all %ENV lookups that begin with "PERL"
 
 Note the C<$]> in the above is not literal.  Substitute whatever version
 of perl you want to honor that entry, e.g. C<5.6.0>.  Paths must be
@@ -681,26 +681,26 @@ powerful, because it will do the right thing with a pattern like
 4) you can extend the method to add any customizations (or even
 entirely different kinds of wildcard expansion).
 
      C:\> copy con c:\perl\lib\Wild.pm
      # Wild.pm - emulate shell @ARGV expansion on shells that don't
      use File::DosGlob;
      @ARGV = map {
-                     my @g = File::DosGlob::glob($_) if /[*?]/;
-                     @g ? @g : $_;
-                   } @ARGV;
      1;
      ^Z
      C:\> set PERL5OPT=-MWild
      C:\> perl -le "for (@ARGV) { print }" */*/perl*.c
      p4view/perl/perl.c
      p4view/perl/perlio.c
      p4view/perl/perly.c
      perl5.005/win32/perlglob.c
      perl5.005/win32/perllib.c
      perl5.005/win32/perlglob.c
      perl5.005/win32/perllib.c
      perl5.005/win32/perlglob.c
      perl5.005/win32/perllib.c
+ C:\> copy con c:\perl\lib\Wild.pm
+ # Wild.pm - emulate shell @ARGV expansion on shells that don't
+ use File::DosGlob;
+ @ARGV = map {
+             my @g = File::DosGlob::glob($_) if /[*?]/;
+             @g ? @g : $_;
+           } @ARGV;
+ 1;
+ ^Z
+ C:\> set PERL5OPT=-MWild
+ C:\> perl -le "for (@ARGV) { print }" */*/perl*.c
+ p4view/perl/perl.c
+ p4view/perl/perlio.c
+ p4view/perl/perly.c
+ perl5.005/win32/perlglob.c
+ perl5.005/win32/perllib.c
+ perl5.005/win32/perlglob.c
+ perl5.005/win32/perllib.c
+ perl5.005/win32/perlglob.c
+ perl5.005/win32/perllib.c
 
 Note there are two distinct steps there: 1) You'll have to create
 Wild.pm and put it in your perl lib directory. 2) You'll need to
index a888925..094d5ea 100644 (file)
@@ -3,7 +3,7 @@ use 5.006;
 use strict;
 use warnings;
 use warnings::register;
-our $VERSION = '1.30';
+our $VERSION = '1.31';
 require Exporter;
 require Cwd;
 
@@ -1054,8 +1054,8 @@ C<$File::Find::topmode> and C<$File::Find::topnlink>.
 This library is useful for the C<find2perl> tool (distribued as part of the
 App-find2perl CPAN distribution), which when fed,
 
-    find2perl / -name .nfs\* -mtime +7 \
-        -exec rm -f {} \; -o -fstype nfs -prune
+  find2perl / -name .nfs\* -mtime +7 \
+    -exec rm -f {} \; -o -fstype nfs -prune
 
 produces something like:
 
index de6f72d..c23b7df 100644 (file)
@@ -37,7 +37,7 @@ pop @{$EXPORT_TAGS{bsd_glob}}; # no "glob"
 
 @EXPORT_OK   = (@{$EXPORT_TAGS{'glob'}}, 'csh_glob');
 
-$VERSION = '1.24';
+$VERSION = '1.25';
 
 sub import {
     require Exporter;
@@ -363,35 +363,35 @@ E<lt>gsar@activestate.comE<gt>, and Thomas Wegner
 E<lt>wegner_thomas@yahoo.comE<gt>.  The C glob code has the
 following copyright:
 
   Copyright (c) 1989, 1993 The Regents of the University of California.
   All rights reserved.
-
   This code is derived from software contributed to Berkeley by
   Guido van Rossum.
-
   Redistribution and use in source and binary forms, with or without
   modification, are permitted provided that the following conditions
   are met:
-
   1. Redistributions of source code must retain the above copyright
-       notice, this list of conditions and the following disclaimer.
   2. Redistributions in binary form must reproduce the above copyright
-       notice, this list of conditions and the following disclaimer in the
-       documentation and/or other materials provided with the distribution.
   3. Neither the name of the University nor the names of its contributors
-       may be used to endorse or promote products derived from this software
-       without specific prior written permission.
-
   THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND
   ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
   ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
   FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
   DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
   OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
   HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
   OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   SUCH DAMAGE.
+ Copyright (c) 1989, 1993 The Regents of the University of California.
+ All rights reserved.
+
+ This code is derived from software contributed to Berkeley by
+ Guido van Rossum.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+ 3. Neither the name of the University nor the names of its contributors
+    may be used to endorse or promote products derived from this software
+    without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND
+ ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ SUCH DAMAGE.
 
 =cut
index 2441491..484f900 100644 (file)
@@ -5,7 +5,7 @@ use strict;
 use warnings;
 use Scalar::Util qw( reftype);
 
-our $VERSION = '1.15';
+our $VERSION = '1.16';
 
 require Exporter;
 our @ISA = qw(Exporter);
@@ -103,7 +103,7 @@ Returns the reference address of a reference $obj.  If $obj is
 not a reference, returns $obj.
 
 This function is a stand-in replacement for
-L<Scalar::Util::refaddr|Scalar::Util/"$addr = refaddr( $ref )">,
+L<Scalar::Util::refaddr|Scalar::Util/$addr = refaddr( $ref )>,
 that is, it returns
 the reference address of its argument as a numeric value.  The only
 difference is that C<refaddr()> returns C<undef> when given a
index 97319c9..593a4e2 100644 (file)
@@ -1165,53 +1165,53 @@ a requirement that these be passed as an actual list or array.)
 
 For example:
 
 L<Foo::Bar>
-    =>  undef,                          # link text
-        "Foo::Bar",                     # possibly inferred link text
-        "Foo::Bar",                     # name
-        undef,                          # section
-        'pod',                          # what sort of link
-        "Foo::Bar"                      # original content
-
 L<Perlport's section on NL's|perlport/Newlines>
-    =>  "Perlport's section on NL's",   # link text
-        "Perlport's section on NL's",   # possibly inferred link text
-        "perlport",                     # name
-        "Newlines",                     # section
-        'pod',                          # what sort of link
-        "Perlport's section on NL's|perlport/Newlines" # orig. content
-
 L<perlport/Newlines>
-    =>  undef,                          # link text
-        '"Newlines" in perlport',       # possibly inferred link text
-        "perlport",                     # name
-        "Newlines",                     # section
-        'pod',                          # what sort of link
-        "perlport/Newlines"             # original content
-
 L<crontab(5)/"DESCRIPTION">
-    =>  undef,                          # link text
-        '"DESCRIPTION" in crontab(5)',  # possibly inferred link text
-        "crontab(5)",                   # name
-        "DESCRIPTION",                  # section
-        'man',                          # what sort of link
-        'crontab(5)/"DESCRIPTION"'      # original content
-
 L</Object Attributes>
-    =>  undef,                          # link text
-        '"Object Attributes"',          # possibly inferred link text
-        undef,                          # name
-        "Object Attributes",            # section
-        'pod',                          # what sort of link
-        "/Object Attributes"            # original content
-
 L<http://www.perl.org/>
-    =>  undef,                          # link text
-        "http://www.perl.org/",         # possibly inferred link text
-        "http://www.perl.org/",         # name
-        undef,                          # section
-        'url',                          # what sort of link
-        "http://www.perl.org/"          # original content
+ L<Foo::Bar>
+   =>  undef,                          # link text
+       "Foo::Bar",                     # possibly inferred link text
+       "Foo::Bar",                     # name
+       undef,                          # section
+       'pod',                          # what sort of link
+       "Foo::Bar"                      # original content
+
+ L<Perlport's section on NL's|perlport/Newlines>
+   =>  "Perlport's section on NL's",   # link text
+       "Perlport's section on NL's",   # possibly inferred link text
+       "perlport",                     # name
+       "Newlines",                     # section
+       'pod',                          # what sort of link
+       "Perlport's section on NL's|perlport/Newlines" # orig. content
+
+ L<perlport/Newlines>
+   =>  undef,                          # link text
+       '"Newlines" in perlport',       # possibly inferred link text
+       "perlport",                     # name
+       "Newlines",                     # section
+       'pod',                          # what sort of link
+       "perlport/Newlines"             # original content
+
+ L<crontab(5)/"DESCRIPTION">
+   =>  undef,                          # link text
+       '"DESCRIPTION" in crontab(5)',  # possibly inferred link text
+       "crontab(5)",                   # name
+       "DESCRIPTION",                  # section
+       'man',                          # what sort of link
+       'crontab(5)/"DESCRIPTION"'      # original content
+
+ L</Object Attributes>
+   =>  undef,                          # link text
+       '"Object Attributes"',          # possibly inferred link text
+       undef,                          # name
+       "Object Attributes",            # section
+       'pod',                          # what sort of link
+       "/Object Attributes"            # original content
+
+ L<http://www.perl.org/>
+   =>  undef,                          # link text
+       "http://www.perl.org/",         # possibly inferred link text
+       "http://www.perl.org/",         # name
+       undef,                          # section
+       'url',                          # what sort of link
+       "http://www.perl.org/"          # original content
 
 Note that you can distinguish URL-links from anything else by the
 fact that they match C<m/\A\w+:[^:\s]\S*\z/>.  So
index a48a662..06c80c3 100644 (file)
@@ -3,7 +3,7 @@ package OS2::ExtAttr;
 use strict;
 use XSLoader;
 
-our $VERSION = '0.03';
+our $VERSION = '0.04';
 XSLoader::load 'OS2::ExtAttr', $VERSION;
 
 # Preloaded methods go here.
@@ -162,7 +162,7 @@ Three convenience functions are provided:
 The default value for C<flag> is 0.
 
 In addition, all the C<_ea_*> and C<_ead_*> functions defined in EMX
-library are supported, with leading C<_ea/_ead> stripped.
+library are supported, with leading C<_ea> and C<_ead> stripped.
 
 =head1 AUTHOR
 
index babe470..08b619f 100644 (file)
@@ -20,7 +20,7 @@ BEGIN {
   #require AutoLoader;
 
   our @ISA = qw(Exporter);
-  our $VERSION = "1.10";
+  our $VERSION = "1.11";
   XSLoader::load('OS2::Process', $VERSION);
 }
 
@@ -1410,7 +1410,8 @@ message id $msg, they default to 0.  E.g.,
                      SC_MAXIMIZE SC_RESTORE);
   $hwnd = process_hentry()->{owner_hwnd};
   # Emulate choosing `Restore' from the window menu:
-  PostMsg $hwnd, WM_SYSCOMMAND, MPFROMSHORT(SC_RESTORE); # Not immediate
+  PostMsg $hwnd, WM_SYSCOMMAND, MPFROMSHORT(SC_RESTORE); # Not
+                                                         # immediate
 
   # Emulate `Show-Contextmenu' (Double-Click-2), two ways:
   PostMsg ActiveWindow, WM_CONTEXTMENU;
@@ -1874,8 +1875,10 @@ a combination of
      MB_YESNOCANCEL        YES, NO, and CANCEL
 
  Color or Icon 
-     MB_ICONHAND           a small red circle with a red line across it. 
-     MB_ERROR              a small red circle with a red line across it. 
+     MB_ICONHAND           a small red circle with a red line across
+                           it.
+     MB_ERROR              a small red circle with a red line across
+                           it.
      MB_ICONASTERISK       an information (i) icon. 
      MB_INFORMATION        an information (i) icon. 
      MB_ICONEXCLAMATION    an exclamation point (!) icon. 
@@ -1885,12 +1888,16 @@ a combination of
      MB_NOICON             No icon.
 
  Default action (i.e., focussed button; default is MB_DEFBUTTON1)
-     MB_DEFBUTTON1         The first button is the default selection.
-     MB_DEFBUTTON2         The second button is the default selection. 
-     MB_DEFBUTTON3         The third button is the default selection. 
+     MB_DEFBUTTON1         The first button is the default
+                           selection.
+     MB_DEFBUTTON2         The second button is the default
+                           selection.
+     MB_DEFBUTTON3         The third button is the default
+                           selection.
 
  Modality indicator 
-     MB_APPLMODAL                  Message box is application modal (default).
+     MB_APPLMODAL                  Message box is application modal
+                                   (default).
      MB_SYSTEMMODAL                Message box is system modal. 
 
  Mobility indicator 
@@ -1912,9 +1919,9 @@ specify the owner as the parent if this option is used.
 Additionally, the following flag is possible, but probably not very useful:
 
  Help button
-     MB_HELP             a HELP button appears, which sends a WM_HELP
-                                message is sent to the window procedure of the
-                                message box. 
+     MB_HELP            a HELP button appears, which sends a WM_HELP
+                        message is sent to the window procedure of
+                        the message box.
 
 Other optional arguments: $parent window, $owner_window, $helpID (used with
 C<WM_HELP> message if C<MB_HELP> style is given).
@@ -1930,7 +1937,7 @@ The return value is one of
   MBID_YES             YES was selected 
   MBID_NO              NO was selected 
 
-  0                       Function not successful; an error occurred. 
+  0                    Function not successful; an error occurred.
 
 B<BUGS???> keyboard transversal by pressing C<TAB> key does not work.
 Do not appear in window list, so may be hard to find if covered by other
@@ -2164,10 +2171,10 @@ Implement SOMETHINGFROMMR.
   >
   >No matter what message I send it, it's being ignored.
 
-  You need to get the style of the buttons using WinQueryWindowULong/QWL_STYLE,
-  set and reset the BS_DEFAULT bits as appropriate and then use
-  WinSetWindowULong/QWL_STYLE to set the button style.
-  Something like this:
+  You need to get the style of the buttons using
+  WinQueryWindowULong/QWL_STYLE, set and reset the BS_DEFAULT bits as
+  appropriate and then use WinSetWindowULong/QWL_STYLE to set the
+  button style.  Something like this:
     hwnd1 = WinWindowFromID (hwnd, id1);
     hwnd2 = WinWindowFromID (hwnd, id2);
     style1 = WinQueryWindowULong (hwnd1, QWL_STYLE);
@@ -2177,11 +2184,12 @@ Implement SOMETHINGFROMMR.
     WinSetWindowULong (hwnd1, QWL_STYLE, style1);
     WinSetWindowULong (hwnd2, QWL_STYLE, style2);
 
- > How to do query and change a frame creation flags for existing window?
+ > How to do query and change a frame creation flags for existing
+ > window?
 
  Set the style bits that correspond to the FCF_* flag for the frame
- window and then send a WM_UPDATEFRAME message with the appropriate FCF_*
- flag in mp1.
+ window and then send a WM_UPDATEFRAME message with the appropriate
FCF_* flag in mp1.
 
  ULONG ulFrameStyle;
  ulFrameStyle = WinQueryWindowULong( WinQueryWindow(hwnd, QW_PARENT),
@@ -2195,25 +2203,25 @@ Implement SOMETHINGFROMMR.
              MPFROMP(FCF_SIZEBORDER),
              MPVOID );
 
- If the FCF_* flags you want to change does not have a corresponding FS_*
- style (i.e. the FCF_* flag corresponds to the presence/lack of a frame
- control rather than a property of the frame itself) then you create or
- destroy the appropriate control window using the correct FID_* window
- identifier and then send the WM_UPDATEFRAME message with the appropriate
- FCF_* flag in mp1.
-
- /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*
-  |  SetFrameBorder()                                                          |
-  |    Changes a frame window's border to the requested type.                  |
-  |                                                                            |
-  |  Parameters on entry:                                                      |
-  |    hwndFrame     -> Frame window whose border is to be changed.            |
-  |    ulBorderStyle -> Type of border to change to.                           |
-  |                                                                            |
-  |  Returns:                                                                  |
-  |    BOOL          -> Success indicator.                                     |
-  |                                                                            |
-  * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/
+ If the FCF_* flags you want to change does not have a corresponding
+ FS_* style (i.e. the FCF_* flag corresponds to the presence/lack of a
+ frame control rather than a property of the frame itself) then you
+ create or destroy the appropriate control window using the correct
+ FID_* window identifier and then send the WM_UPDATEFRAME message with
the appropriate FCF_* flag in mp1.
+
+ /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - *
+  |  SetFrameBorder()                                                 |
+  |    Changes a frame window's border to the requested type.         |
+  |                                                                   |
+  |  Parameters on entry:                                             |
+  |    hwndFrame     -> Frame window whose border is to be changed.   |
+  |    ulBorderStyle -> Type of border to change to.                  |
+  |                                                                   |
+  |  Returns:                                                         |
+  |    BOOL          -> Success indicator.                            |
+  |                                                                   |
+  * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
  BOOL SetFrameBorder( HWND hwndFrame, ULONG ulBorderType )  {
    ULONG  ulFrameStyle;
    BOOL   fSuccess = TRUE;
index a7d4504..7db9488 100644 (file)
@@ -1,6 +1,6 @@
 package OS2::DLL;
 
-our $VERSION = '1.05';
+our $VERSION = '1.06';
 
 use Carp;
 use XSLoader;
@@ -144,11 +144,11 @@ See documentation of L<OS2::REXX> module if you need the variable pool.
 
 =head1 SYNOPSIS
 
      use OS2::DLL;
      $emx_dll = OS2::DLL->module('emx');
      $emx_version = $emx_dll->emx_revision();
      $func_emx_version = $emx_dll->wrapper_REXX('#128'); # emx_revision
      $emx_version = $func_emx_version->();
+ use OS2::DLL;
+ $emx_dll = OS2::DLL->module('emx');
+ $emx_version = $emx_dll->emx_revision();
+ $func_emx_version = $emx_dll->wrapper_REXX('#128'); # emx_revision
+ $emx_version = $func_emx_version->();
 
 =head1 DESCRIPTION
 
@@ -266,7 +266,8 @@ If a function takes up to 20 ULONGs and returns ULONG:
 
 =item Same for a function which returns non-0 and sets system-error on error
 
- call20_Dos( $msg, $pointer, $arg0, $arg1, ...); # die("$msg: $^E") if error
+ call20_Dos( $msg, $pointer, $arg0, $arg1, ...); # die("$msg: $^E")
+                                                            if error
 
 [Good for C<Dos*> API - and rare C<Win*> calls.]
 
index ca9fee6..6d0ca4b 100644 (file)
@@ -11,7 +11,7 @@ require OS2::DLL;
 # Other items we are prepared to export if requested
 @EXPORT_OK = qw(drop register);
 
-$VERSION = '1.04';
+$VERSION = '1.05';
 
 # We cannot just put OS2::DLL in @ISA, since some scripts would use
 # function interface, not method interface...
@@ -432,37 +432,38 @@ See C<t/rx*.t> and the next section for examples.
 
 =head1 EXAMPLE
 
 use OS2::REXX;
+ use OS2::REXX;
 
 sub Ender::DESTROY { $vrexx->VExit; print "Exiting...\n" }
+ sub Ender::DESTROY { $vrexx->VExit; print "Exiting...\n" }
 
 $vrexx = OS2::REXX->load('VREXX');
 REXX_call {                  # VOpenWindow takes a stem
-    local $SIG{TERM} = sub {die}; # enable Ender::DESTROY
-    local $SIG{INT} = sub {die};       # enable Ender::DESTROY
+ $vrexx = OS2::REXX->load('VREXX');
REXX_call {                   # VOpenWindow takes a stem
+   local $SIG{TERM} = sub {die}; # enable Ender::DESTROY
+   local $SIG{INT} = sub {die};        # enable Ender::DESTROY
 
-    $code = $vrexx->VInit;
-    print "Init code = `$code'\n";
-    die "error initializing VREXX" if $code eq 'ERROR';
+   $code = $vrexx->VInit;
+   print "Init code = `$code'\n";
+   die "error initializing VREXX" if $code eq 'ERROR';
 
-    my $ender = bless [], 'Ender'; # Call Ender::DESTROY on exit
+   my $ender = bless [], 'Ender'; # Call Ender::DESTROY on exit
 
-    print "VREXX Version ", $vrexx->VGetVersion, "\n";
+   print "VREXX Version ", $vrexx->VGetVersion, "\n";
 
-    tie %pos, 'OS2::REXX', 'POS.' or die;
-    %pos = ( LEFT   => 0, RIGHT  => 7, TOP    => 5, BOTTOM => 0 );
+   tie %pos, 'OS2::REXX', 'POS.' or die;
+   %pos = ( LEFT   => 0, RIGHT  => 7, TOP    => 5, BOTTOM => 0 );
 
-    $id = $vrexx->VOpenWindow('To disconnect:', 'WHITE', 'POS');
-    $vrexx->VForeColor($id, 'BLACK');
-    $vrexx->VSetFont($id, 'TIME', '30');
-    $tlim = time + 60;
-    while ( ($r = $tlim - time) >= 0 ) {
-      $vrexx->VClearWindow($id);
-      $vrexx->VSay($id, 100, 50, (sprintf "%02i:%02i", int($r/60), $r % 60));
-      sleep 1;
-    }
-    print "Close code = `$res'\n" if $res = $vrexx->VCloseWindow($id);
-  };
+   $id = $vrexx->VOpenWindow('To disconnect:', 'WHITE', 'POS');
+   $vrexx->VForeColor($id, 'BLACK');
+   $vrexx->VSetFont($id, 'TIME', '30');
+   $tlim = time + 60;
+   while ( ($r = $tlim - time) >= 0 ) {
+     $vrexx->VClearWindow($id);
+     $vrexx->VSay($id, 100, 50, (sprintf "%02i:%02i", int($r/60),
+                                                              $r % 60));
+     sleep 1;
+   }
+   print "Close code = `$res'\n" if $res = $vrexx->VCloseWindow($id);
+ };
 
 
 
index a7f3cc8..a879809 100644 (file)
@@ -4,66 +4,69 @@ perlapio - perl's IO abstraction interface.
 
 =head1 SYNOPSIS
 
-    #define PERLIO_NOT_STDIO 0    /* For co-existence with stdio only */
-    #include <perlio.h>           /* Usually via #include <perl.h> */
-
-    PerlIO *PerlIO_stdin(void);
-    PerlIO *PerlIO_stdout(void);
-    PerlIO *PerlIO_stderr(void);
-
-    PerlIO *PerlIO_open(const char *path,const char *mode);
-    PerlIO *PerlIO_fdopen(int fd, const char *mode);
-    PerlIO *PerlIO_reopen(const char *path, const char *mode, PerlIO *old);  /* deprecated */
-    int     PerlIO_close(PerlIO *f);
-
-    int     PerlIO_stdoutf(const char *fmt,...)
-    int     PerlIO_puts(PerlIO *f,const char *string);
-    int     PerlIO_putc(PerlIO *f,int ch);
-    SSize_t PerlIO_write(PerlIO *f,const void *buf,size_t numbytes);
-    int     PerlIO_printf(PerlIO *f, const char *fmt,...);
-    int     PerlIO_vprintf(PerlIO *f, const char *fmt, va_list args);
-    int     PerlIO_flush(PerlIO *f);
-
-    int     PerlIO_eof(PerlIO *f);
-    int     PerlIO_error(PerlIO *f);
-    void    PerlIO_clearerr(PerlIO *f);
-
-    int     PerlIO_getc(PerlIO *d);
-    int     PerlIO_ungetc(PerlIO *f,int ch);
-    SSize_t PerlIO_read(PerlIO *f, void *buf, size_t numbytes);
-
-    int     PerlIO_fileno(PerlIO *f);
-
-    void    PerlIO_setlinebuf(PerlIO *f);
-
-    Off_t   PerlIO_tell(PerlIO *f);
-    int     PerlIO_seek(PerlIO *f, Off_t offset, int whence);
-    void    PerlIO_rewind(PerlIO *f);
-
-    int     PerlIO_getpos(PerlIO *f, SV *save);        /* prototype changed */
-    int     PerlIO_setpos(PerlIO *f, SV *saved);       /* prototype changed */
-
-    int     PerlIO_fast_gets(PerlIO *f);
-    int     PerlIO_has_cntptr(PerlIO *f);
-    SSize_t PerlIO_get_cnt(PerlIO *f);
-    char   *PerlIO_get_ptr(PerlIO *f);
-    void    PerlIO_set_ptrcnt(PerlIO *f, char *ptr, SSize_t count);
-
-    int     PerlIO_canset_cnt(PerlIO *f);              /* deprecated */
-    void    PerlIO_set_cnt(PerlIO *f, int count);      /* deprecated */
-
-    int     PerlIO_has_base(PerlIO *f);
-    char   *PerlIO_get_base(PerlIO *f);
-    SSize_t PerlIO_get_bufsiz(PerlIO *f);
-
-    PerlIO *PerlIO_importFILE(FILE *stdio, const char *mode);
-    FILE   *PerlIO_exportFILE(PerlIO *f, int flags);
-    FILE   *PerlIO_findFILE(PerlIO *f);
-    void    PerlIO_releaseFILE(PerlIO *f,FILE *stdio);
-
-    int     PerlIO_apply_layers(PerlIO *f, const char *mode, const char *layers);
-    int     PerlIO_binmode(PerlIO *f, int ptype, int imode, const char *layers);
-    void    PerlIO_debug(const char *fmt,...)
+  #define PERLIO_NOT_STDIO 0    /* For co-existence with stdio only */
+  #include <perlio.h>           /* Usually via #include <perl.h> */
+
+  PerlIO *PerlIO_stdin(void);
+  PerlIO *PerlIO_stdout(void);
+  PerlIO *PerlIO_stderr(void);
+
+  PerlIO *PerlIO_open(const char *path,const char *mode);
+  PerlIO *PerlIO_fdopen(int fd, const char *mode);
+  PerlIO *PerlIO_reopen(const char *path, /* deprecated */
+          const char *mode, PerlIO *old);
+  int     PerlIO_close(PerlIO *f);
+
+  int     PerlIO_stdoutf(const char *fmt,...)
+  int     PerlIO_puts(PerlIO *f,const char *string);
+  int     PerlIO_putc(PerlIO *f,int ch);
+  SSize_t PerlIO_write(PerlIO *f,const void *buf,size_t numbytes);
+  int     PerlIO_printf(PerlIO *f, const char *fmt,...);
+  int     PerlIO_vprintf(PerlIO *f, const char *fmt, va_list args);
+  int     PerlIO_flush(PerlIO *f);
+
+  int     PerlIO_eof(PerlIO *f);
+  int     PerlIO_error(PerlIO *f);
+  void    PerlIO_clearerr(PerlIO *f);
+
+  int     PerlIO_getc(PerlIO *d);
+  int     PerlIO_ungetc(PerlIO *f,int ch);
+  SSize_t PerlIO_read(PerlIO *f, void *buf, size_t numbytes);
+
+  int     PerlIO_fileno(PerlIO *f);
+
+  void    PerlIO_setlinebuf(PerlIO *f);
+
+  Off_t   PerlIO_tell(PerlIO *f);
+  int     PerlIO_seek(PerlIO *f, Off_t offset, int whence);
+  void    PerlIO_rewind(PerlIO *f);
+
+  int     PerlIO_getpos(PerlIO *f, SV *save);    /* prototype changed */
+  int     PerlIO_setpos(PerlIO *f, SV *saved);   /* prototype changed */
+
+  int     PerlIO_fast_gets(PerlIO *f);
+  int     PerlIO_has_cntptr(PerlIO *f);
+  SSize_t PerlIO_get_cnt(PerlIO *f);
+  char   *PerlIO_get_ptr(PerlIO *f);
+  void    PerlIO_set_ptrcnt(PerlIO *f, char *ptr, SSize_t count);
+
+  int     PerlIO_canset_cnt(PerlIO *f);              /* deprecated */
+  void    PerlIO_set_cnt(PerlIO *f, int count);      /* deprecated */
+
+  int     PerlIO_has_base(PerlIO *f);
+  char   *PerlIO_get_base(PerlIO *f);
+  SSize_t PerlIO_get_bufsiz(PerlIO *f);
+
+  PerlIO *PerlIO_importFILE(FILE *stdio, const char *mode);
+  FILE   *PerlIO_exportFILE(PerlIO *f, int flags);
+  FILE   *PerlIO_findFILE(PerlIO *f);
+  void    PerlIO_releaseFILE(PerlIO *f,FILE *stdio);
+
+  int     PerlIO_apply_layers(PerlIO *f, const char *mode,
+                                                    const char *layers);
+  int     PerlIO_binmode(PerlIO *f, int ptype, int imode,
+                                                    const char *layers);
+  void    PerlIO_debug(const char *fmt,...)
 
 =head1 DESCRIPTION
 
index c0af7e8..327e253 100644 (file)
@@ -1909,7 +1909,9 @@ done inside our C code:
 
  ...
 
- SV *cvrv = eval_pv("sub { print 'You will not find me cluttering any namespace!' }", TRUE);
+ SV *cvrv = eval_pv("sub {
+                    print 'You will not find me cluttering any namespace!'
+                    }", TRUE);
 
  ...
 
index eb0a6ca..6bd38c1 100644 (file)
@@ -275,122 +275,122 @@ is not a complete listing, but only excerpts.
 
 =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
+ 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
+ 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 3
 
 in  $=main::BEGIN() from /dev/null: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/null:0
-    in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li
 in  @=Config::myconfig() from /dev/null: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), 'PERL_VERSION') from lib/Config.pm:574
-   in  $=Config::FETCH(ref(Config), 'PERL_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
+ in  $=main::BEGIN() from /dev/null: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/null:0
+   in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li
+ in  @=Config::myconfig() from /dev/null: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), 'PERL_VERSION') from lib/Config.pm:574
+  in  $=Config::FETCH(ref(Config), 'PERL_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 4
 
 in  $=main::BEGIN() from /dev/null: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/null: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/null:0
 out $=main::BEGIN() from /dev/null:0
 in  @=Config::myconfig() from /dev/null: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), 'PERL_VERSION') from lib/Config.pm:574
-   out $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
-   in  $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574
+ in  $=main::BEGIN() from /dev/null: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/null: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/null:0
+ out $=main::BEGIN() from /dev/null:0
+ in  @=Config::myconfig() from /dev/null: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), 'PERL_VERSION') from lib/Config.pm:574
+  out $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
+  in  $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574
 
 =item 5
 
 in  $=main::BEGIN() from /dev/null: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/null: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/null:0
 out $=main::BEGIN() from /dev/null:0
 in  @=Config::myconfig() from /dev/null: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
+ in  $=main::BEGIN() from /dev/null: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/null: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/null:0
+ out $=main::BEGIN() from /dev/null:0
+ in  @=Config::myconfig() from /dev/null: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
 
 =item 6
 
 in  $=CODE(0x15eca4)() from /dev/null:0
-   in  $=CODE(0x182528)() from lib/Config.pm:2
-    Package lib/Exporter.pm.
-   out $=CODE(0x182528)() from lib/Config.pm:0
-   scalar context return from CODE(0x182528): undef
-   Package lib/Config.pm.
-   in  $=Config::TIEHASH('Config') from lib/Config.pm:628
-   out $=Config::TIEHASH('Config') from lib/Config.pm:628
-   scalar context return from Config::TIEHASH:   empty hash
-   in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
-    in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
-    out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
-    scalar context return from Exporter::export: ''
-   out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
-   scalar context return from Exporter::import: ''
+ in  $=CODE(0x15eca4)() from /dev/null:0
+  in  $=CODE(0x182528)() from lib/Config.pm:2
+   Package lib/Exporter.pm.
+  out $=CODE(0x182528)() from lib/Config.pm:0
+  scalar context return from CODE(0x182528): undef
+  Package lib/Config.pm.
+  in  $=Config::TIEHASH('Config') from lib/Config.pm:628
+  out $=Config::TIEHASH('Config') from lib/Config.pm:628
+  scalar context return from Config::TIEHASH:   empty hash
+  in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
+   in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
+   out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
+   scalar context return from Exporter::export: ''
+  out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
+  scalar context return from Exporter::import: ''
 
 =back
 
@@ -921,19 +921,19 @@ usage statistics after compiling your code when C<< $ENV{PERL_DEBUG_MSTATS}
 $ENV{PERL_DEBUG_MSTATS} >= 1 >>.  The report format is similar to
 the following example:
 
 $ PERL_DEBUG_MSTATS=2 perl -e "require Carp"
 Memory allocation statistics after compilation: (buckets 4(4)..8188(8192)
-     14216 free:   130   117    28     7     9   0   2     2   1 0 0
+ $ PERL_DEBUG_MSTATS=2 perl -e "require Carp"
+ Memory allocation statistics after compilation: (buckets 4(4)..8188(8192)
+    14216 free:   130   117    28     7     9   0   2     2   1 0 0
                437    61    36     0     5
-     60924 used:   125   137   161    55     7   8   6    16   2 0 1
+    60924 used:   125   137   161    55     7   8   6    16   2 0 1
                 74   109   304    84    20
 Total sbrk(): 77824/21:119. Odd ends: pad+heads+chain+tail: 0+636+0+2048.
 Memory allocation statistics after execution:   (buckets 4(4)..8188(8192)
-     30888 free:   245    78    85    13     6   2   1     3   2 0 1
+ Total sbrk(): 77824/21:119. Odd ends: pad+heads+chain+tail: 0+636+0+2048.
+ Memory allocation statistics after execution:   (buckets 4(4)..8188(8192)
+    30888 free:   245    78    85    13     6   2   1     3   2 0 1
                315   162    39    42    11
-    175816 used:   265   176  1112   111    26  22  11    27   2 1 1
+   175816 used:   265   176  1112   111    26  22  11    27   2 1 1
                196   178  1066   798    39
 Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144.
+ Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144.
 
 It is possible to ask for such a statistic at arbitrary points in
 your execution using the mstat() function out of the standard
@@ -973,7 +973,7 @@ of two buckets "above".
 For example, suppose under the previous example, the memory footprints
 were
 
-     free:    8     16    32    64    128  256 512 1024 2048 4096 8192
+   free:    8     16    32    64    128  256 512 1024 2048 4096 8192
           4     12    24    48    80
 
 With a non-C<DEBUGGING> perl, the buckets starting from C<128> have
index cc4f505..2558ed2 100644 (file)
@@ -154,26 +154,40 @@ DB<1>h
 
  List/search source lines:               Control script execution:
   l [ln|sub]  List source code            T           Stack trace
-  - or .      List previous/current line  s [expr]    Single step [in expr]
-  v [line]    View around line            n [expr]    Next, steps over subs
+  - or .      List previous/current line  s [expr]    Single step
+                                                               [in expr]
+  v [line]    View around line            n [expr]    Next, steps over
+                                                                    subs
   f filename  View source in file         <CR/Enter>  Repeat last n or s
-  /pattern/ ?patt?   Search forw/backw    r           Return from subroutine
-  M           Show module versions        c [ln|sub]  Continue until position
- Debugger controls:                       L           List break/watch/actions
-  o [...]     Set debugger options        t [expr]    Toggle trace [trace expr]
-  <[<]|{[{]|>[>] [cmd] Do pre/post-prompt b [ln|event|sub] [cnd] Set breakpoint
-  ! [N|pat]   Redo a previous command     B ln|*      Delete a/all breakpoints
+  /pattern/ ?patt?   Search forw/backw    r           Return from
+                                                              subroutine
+  M           Show module versions        c [ln|sub]  Continue until
+                                                                position
+ Debugger controls:                       L           List break/watch/
+                                                                 actions
+  o [...]     Set debugger options        t [expr]    Toggle trace
+                                                            [trace expr]
+  <[<]|{[{]|>[>] [cmd] Do pre/post-prompt b [ln|event|sub] [cnd] Set
+                                                              breakpoint
+  ! [N|pat]   Redo a previous command     B ln|*      Delete a/all
+                                                             breakpoints
   H [-num]    Display last num commands   a [ln] cmd  Do cmd before line
-  = [a val]   Define/list an alias        A ln|*      Delete a/all actions
-  h [db_cmd]  Get help on command         w expr      Add a watch expression
-  h h         Complete help page          W expr|*    Delete a/all watch exprs
-  |[|]db_cmd  Send output to pager        ![!] syscmd Run cmd in a subprocess
+  = [a val]   Define/list an alias        A ln|*      Delete a/all
+                                                                 actions
+  h [db_cmd]  Get help on command         w expr      Add a watch
+                                                              expression
+  h h         Complete help page          W expr|*    Delete a/all watch
+                                                                   exprs
+  |[|]db_cmd  Send output to pager        ![!] syscmd Run cmd in a
+                                                              subprocess
   q or ^D     Quit                        R           Attempt a restart
  Data Examination:     expr     Execute perl code, also see: s,n,t expr
-  x|m expr       Evals expr in list context, dumps the result or lists methods.
+  x|m expr       Evals expr in list context, dumps the result or lists
+                                                                methods.
   p expr         Print expression (uses script's current package).
   S [[!]pat]     List subroutine names [not] matching pattern
-  V [Pk [Vars]]  List Variables in Package.  Vars can be ~pattern or !pattern.
+  V [Pk [Vars]]  List Variables in Package.  Vars can be ~pattern or
+                                                               !pattern.
   X [Vars]       Same as "V current_package [Vars]".
   y [n [Vars]]   List lexicals in higher scope <n>.  Vars same as V.
  For more help, type h cmd_letter, or run man perldebug for all docs. 
@@ -335,25 +349,25 @@ Let's make a quick object and x-plode it, first we'll start the debugger:
 it wants some form of input from STDIN, so we give it something non-committal,
 a zero:
 
      > perl -de 0
      Default die handler restored.
+ > perl -de 0
+ Default die handler restored.
 
      Loading DB routines from perl5db.pl version 1.07
      Editor support available.
+ Loading DB routines from perl5db.pl version 1.07
+ Editor support available.
 
      Enter h or `h h' for help, or `man perldebug' for more help.
+ Enter h or `h h' for help, or `man perldebug' for more help.
 
-       main::(-e:1):   0                       
+ main::(-e:1):   0
 
 Now build an on-the-fly object over a couple of lines (note the backslash):
 
      DB<1> $obj = bless({'unique_id'=>'123', 'attr'=> \
      cont:   {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
+ DB<1> $obj = bless({'unique_id'=>'123', 'attr'=> \
cont:         {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
 
 And let's have a look at it:
 
        DB<2> x $obj
      0  MY_class=HASH(0x828ad98)
+ 0  MY_class=HASH(0x828ad98)
                'attr' => HASH(0x828ad68)
        'col' => 'black'
        'things' => ARRAY(0x828abb8)
@@ -366,38 +380,38 @@ And let's have a look at it:
 Useful, huh?  You can eval nearly anything in there, and experiment with bits
 of code or regexes until the cows come home:
 
      DB<3> @data = qw(this that the other atheism leather theory scythe)
+ DB<3> @data = qw(this that the other atheism leather theory scythe)
 
      DB<4> p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
      atheism
      leather
      other
      scythe
      the
-       theory  
      saw -> 6
+ DB<4> p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
+ atheism
+ leather
+ other
+ scythe
+ the
+ theory
+ saw -> 6
 
 If you want to see the command History, type an 'B<H>':
 
      DB<5> H
      4: p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
      3: @data = qw(this that the other atheism leather theory scythe)
      2: x $obj
      1: $obj = bless({'unique_id'=>'123', 'attr'=>
      {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
      DB<5>
+ DB<5> H
+ 4: p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
+ 3: @data = qw(this that the other atheism leather theory scythe)
+ 2: x $obj
+ 1: $obj = bless({'unique_id'=>'123', 'attr'=>
+ {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
+ DB<5>
 
 And if you want to repeat any previous command, use the exclamation: 'B<!>':
 
      DB<5> !4
      p 'saw -> '.($cnt += map { print "$_\n" } grep(/the/, sort @data))
      atheism
      leather
      other
      scythe
      the
-       theory  
      saw -> 12
+ DB<5> !4
+ p 'saw -> '.($cnt += map { print "$_\n" } grep(/the/, sort @data))
+ atheism
+ leather
+ other
+ scythe
+ the
+ theory
+ saw -> 12
 
 For more on references see L<perlref> and L<perlreftut>
 
@@ -407,50 +421,50 @@ For more on references see L<perlref> and L<perlreftut>
 Here's a simple program which converts between Celsius and Fahrenheit, it too
 has a problem:
 
-       #!/usr/bin/perl -w
-       use strict;
-
-       my $arg = $ARGV[0] || '-c20';
-
-       if ($arg =~ /^\-(c|f)((\-|\+)*\d+(\.\d+)*)$/) {
-               my ($deg, $num) = ($1, $2);
-               my ($in, $out) = ($num, $num);
-               if ($deg eq 'c') {
-                       $deg = 'f';
-                       $out = &c2f($num);
-               } else {
-                       $deg = 'c';
-                       $out = &f2c($num);
-               }
-               $out = sprintf('%0.2f', $out);
-               $out =~ s/^((\-|\+)*\d+)\.0+$/$1/;
-               print "$out $deg\n";
-       } else {
-               print "Usage: $0 -[c|f] num\n";
-       }
-       exit;
+ #!/usr/bin/perl -w
+ use strict;
 
-       sub f2c {
-               my $f = shift;
-               my $c = 5 * $f - 32 / 9;
-               return $c;
-       }
+ my $arg = $ARGV[0] || '-c20';
 
-       sub c2f {
-               my $c = shift;
-               my $f = 9 * $c / 5 + 32;
-               return $f;
+ if ($arg =~ /^\-(c|f)((\-|\+)*\d+(\.\d+)*)$/) {
+       my ($deg, $num) = ($1, $2);
+       my ($in, $out) = ($num, $num);
+       if ($deg eq 'c') {
+               $deg = 'f';
+               $out = &c2f($num);
+       } else {
+               $deg = 'c';
+               $out = &f2c($num);
        }
+       $out = sprintf('%0.2f', $out);
+       $out =~ s/^((\-|\+)*\d+)\.0+$/$1/;
+       print "$out $deg\n";
+ } else {
+       print "Usage: $0 -[c|f] num\n";
+ }
+ exit;
+
+ sub f2c {
+       my $f = shift;
+       my $c = 5 * $f - 32 / 9;
+       return $c;
+ }
+
+ sub c2f {
+       my $c = shift;
+       my $f = 9 * $c / 5 + 32;
+       return $f;
+ }
 
 
 For some reason, the Fahrenheit to Celsius conversion fails to return the
 expected output.  This is what it does:
 
      > temp -c0.72
      33.30 f
+ > temp -c0.72
+ 33.30 f
 
      > temp -f33.3
      162.94 c
+ > temp -f33.3
+ 162.94 c
 
 Not very consistent!  We'll set a breakpoint in the code manually and run it
 under the debugger to see what's going on.  A breakpoint is a flag, to which
@@ -600,28 +614,28 @@ Actions, watch variables, stack traces etc.: on the TODO list.
 Ever wanted to know what a regex looked like?  You'll need perl compiled with
 the DEBUGGING flag for this one:
 
-       > perl -Dr -e '/^pe(a)*rl$/i'
-       Compiling REx `^pe(a)*rl$'
-       size 17 first at 2
-       rarest char
-        at 0
-          1: BOL(2)
-          2: EXACTF <pe>(4)
-          4: CURLYN[1] {0,32767}(14)
-          6:   NOTHING(8)
-          8:   EXACTF <a>(0)
-         12:   WHILEM(0)
-         13: NOTHING(14)
-         14: EXACTF <rl>(16)
-         16: EOL(17)
-         17: END(0)
-       floating `'$ at 4..2147483647 (checking floating) stclass `EXACTF <pe>'
-anchored(BOL) minlen 4
-       Omitting $` $& $' support.
-
-       EXECUTING...
-
-       Freeing REx: `^pe(a)*rl$'  
+  > perl -Dr -e '/^pe(a)*rl$/i'
+  Compiling REx `^pe(a)*rl$'
+  size 17 first at 2
+  rarest char
+   at 0
+     1: BOL(2)
+     2: EXACTF <pe>(4)
+     4: CURLYN[1] {0,32767}(14)
+     6:   NOTHING(8)
+     8:   EXACTF <a>(0)
+    12:   WHILEM(0)
+    13: NOTHING(14)
+    14: EXACTF <rl>(16)
+    16: EOL(17)
+    17: END(0)
+  floating `'$ at 4..2147483647 (checking floating) stclass
+    `EXACTF <pe>' anchored(BOL) minlen 4
+  Omitting $` $& $' support.
+
+  EXECUTING...
+
+  Freeing REx: `^pe(a)*rl$'
 
 Did you really want to know? :-)
 For more gory details on getting regular expressions to work, have a look at
@@ -644,7 +658,7 @@ To watch the tail of a dynamically growing logfile, (from the command line):
 Wrapping all die calls in a handler routine can be useful to see how, and from
 where, they're being called, L<perlvar> has more information:
 
-       BEGIN { $SIG{__DIE__} = sub { require Carp; Carp::confess(@_) } }
+    BEGIN { $SIG{__DIE__} = sub { require Carp; Carp::confess(@_) } }
 
 Various useful techniques for the redirection of STDOUT and STDERR filehandles
 are explained in L<perlopentut> and L<perlfaq8>.
index d4d7af9..fee5e2d 100644 (file)
@@ -990,9 +990,11 @@ X<backtrace> X<stack, backtrace>
 Here's an example of what a stack backtrace 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
-    $ = main::pests('bactrian', 4) called from file 'camel_flea' line 4
+ $ = main::infested called from file 'Ambulation.pm' line 10
+ @ = Ambulation::legs(1, 2, 3, 4) called from file 'camel_flea'
+                                                          line 7
+ $ = main::pests('bactrian', 4) called from file 'camel_flea'
+                                                          line 4
 
 The left-hand character up there indicates the context in which the
 function was called, with C<$> and C<@> meaning scalar or list
@@ -1015,17 +1017,17 @@ an C<eval> frame.
 
 This shows the sorts of output the C<l> command can produce:
 
-    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);
+   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);
 
 Breakable lines are marked with C<:>.  Lines with breakpoints are
 marked by C<b> and those with actions by C<a>.  The line that's
index ef93657..2b60351 100644 (file)
@@ -4,22 +4,22 @@ perldtrace - Perl's support for DTrace
 
 =head1 SYNOPSIS
 
   # dtrace -Zn 'perl::sub-entry, perl::sub-return { trace(copyinstr(arg0)) }'
   dtrace: description 'perl::sub-entry, perl::sub-return ' matched 10 probes
-
   # perl -E 'sub outer { inner(@_) } sub inner { say shift } outer("hello")'
   hello
-
   (dtrace output)
   CPU     ID                    FUNCTION:NAME
-      0  75915       Perl_pp_entersub:sub-entry   BEGIN
-      0  75915       Perl_pp_entersub:sub-entry   import
-      0  75922      Perl_pp_leavesub:sub-return   import
-      0  75922      Perl_pp_leavesub:sub-return   BEGIN
-      0  75915       Perl_pp_entersub:sub-entry   outer
-      0  75915       Perl_pp_entersub:sub-entry   inner
-      0  75922      Perl_pp_leavesub:sub-return   inner
-      0  75922      Perl_pp_leavesub:sub-return   outer
+ # dtrace -Zn 'perl::sub-entry, perl::sub-return { trace(copyinstr(arg0)) }'
+ dtrace: description 'perl::sub-entry, perl::sub-return ' matched 10 probes
+
+ # perl -E 'sub outer { inner(@_) } sub inner { say shift } outer("hello")'
+ hello
+
+ (dtrace output)
+ CPU     ID                    FUNCTION:NAME
+   0  75915       Perl_pp_entersub:sub-entry   BEGIN
+   0  75915       Perl_pp_entersub:sub-entry   import
+   0  75922      Perl_pp_leavesub:sub-return   import
+   0  75922      Perl_pp_leavesub:sub-return   BEGIN
+   0  75915       Perl_pp_entersub:sub-entry   outer
+   0  75915       Perl_pp_entersub:sub-entry   inner
+   0  75922      Perl_pp_leavesub:sub-return   inner
+   0  75922      Perl_pp_leavesub:sub-return   outer
 
 =head1 DESCRIPTION
 
@@ -72,10 +72,10 @@ refer to the subroutine that is being invoked; there is currently
 no way to get ahold of any information about the subroutine's
 I<caller> from a DTrace action.
 
   :*perl*::sub-entry {
-        printf("%s::%s entered at %s line %d\n",
-               copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);
   }
+ :*perl*::sub-entry {
+     printf("%s::%s entered at %s line %d\n",
+           copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);
+ }
 
 =item sub-return(SUBNAME, FILE, LINE, PACKAGE)
 
@@ -84,10 +84,10 @@ refer to the subroutine that is returning; there is currently no
 way to get ahold of any information about the subroutine's I<caller>
 from a DTrace action.
 
   :*perl*::sub-return {
-        printf("%s::%s returned at %s line %d\n",
-               copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);
   }
+ :*perl*::sub-return {
+     printf("%s::%s returned at %s line %d\n",
+           copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);
+ }
 
 =item phase-change(NEWPHASE, OLDPHASE)
 
@@ -96,10 +96,10 @@ as tracing changes to Perl's C<${^GLOBAL_PHASE}> variable, especially
 since the values for C<NEWPHASE> and C<OLDPHASE> are the strings that
 C<${^GLOBAL_PHASE}> reports.
 
   :*perl*::phase-change {
-        printf("Phase changed from %s to %s\n",
-            copyinstr(arg1), copyinstr(arg0));
   }
+ :*perl*::phase-change {
+     printf("Phase changed from %s to %s\n",
+         copyinstr(arg1), copyinstr(arg0));
+ }
 
 =item op-entry(OPNAME)
 
@@ -108,9 +108,9 @@ is fired before the opcode is executed. When the Perl debugger is
 enabled, the DTrace probe is fired I<after> the debugger hooks (but
 still before the opcode itself is executed).
 
   :*perl*::op-entry {
-        printf("About to execute opcode %s\n", copyinstr(arg0));
   }
+ :*perl*::op-entry {
+     printf("About to execute opcode %s\n", copyinstr(arg0));
+ }
 
 =item loading-file(FILENAME)
 
@@ -119,9 +119,9 @@ C<use>, C<require>, or C<do>. This probe fires before the file is
 read from disk. The filename argument is converted to local filesystem
 paths instead of providing C<Module::Name>-style names.
 
   :*perl*:loading-file {
-        printf("About to load %s\n", copyinstr(arg0));
   }
+ :*perl*:loading-file {
+     printf("About to load %s\n", copyinstr(arg0));
+ }
 
 =item loaded-file(FILENAME)
 
@@ -131,9 +131,9 @@ is read from disk and its contents evaluated. The filename argument
 is converted to local filesystem paths instead of providing
 C<Module::Name>-style names.
 
   :*perl*:loaded-file {
-        printf("Successfully loaded %s\n", copyinstr(arg0));
   }
+ :*perl*:loaded-file {
+     printf("Successfully loaded %s\n", copyinstr(arg0));
+ }
 
 =back
 
@@ -143,64 +143,64 @@ C<Module::Name>-style names.
 
 =item Most frequently called functions
 
   # dtrace -qZn 'sub-entry { @[strjoin(strjoin(copyinstr(arg3),"::"),copyinstr(arg0))] = count() } END {trunc(@, 10)}'
+ # dtrace -qZn 'sub-entry { @[strjoin(strjoin(copyinstr(arg3),"::"),copyinstr(arg0))] = count() } END {trunc(@, 10)}'
 
   Class::MOP::Attribute::slots                                    400
   Try::Tiny::catch                                                411
   Try::Tiny::try                                                  411
   Class::MOP::Instance::inline_slot_access                        451
   Class::MOP::Class::Immutable::Trait:::around                    472
   Class::MOP::Mixin::AttributeCore::has_initializer               496
   Class::MOP::Method::Wrapped::__ANON__                           544
   Class::MOP::Package::_package_stash                             737
   Class::MOP::Class::initialize                                  1128
   Class::MOP::get_metaclass_by_name                              1204
+ Class::MOP::Attribute::slots                                    400
+ Try::Tiny::catch                                                411
+ Try::Tiny::try                                                  411
+ Class::MOP::Instance::inline_slot_access                        451
+ Class::MOP::Class::Immutable::Trait:::around                    472
+ Class::MOP::Mixin::AttributeCore::has_initializer               496
+ Class::MOP::Method::Wrapped::__ANON__                           544
+ Class::MOP::Package::_package_stash                             737
+ Class::MOP::Class::initialize                                  1128
+ Class::MOP::get_metaclass_by_name                              1204
 
 =item Trace function calls
 
   # dtrace -qFZn 'sub-entry, sub-return { trace(copyinstr(arg0)) }'
-
   0  -> Perl_pp_entersub                        BEGIN
   0  <- Perl_pp_leavesub                        BEGIN
   0  -> Perl_pp_entersub                        BEGIN
   0    -> Perl_pp_entersub                      import
   0    <- Perl_pp_leavesub                      import
   0  <- Perl_pp_leavesub                        BEGIN
   0  -> Perl_pp_entersub                        BEGIN
   0    -> Perl_pp_entersub                      dress
   0    <- Perl_pp_leavesub                      dress
   0    -> Perl_pp_entersub                      dirty
   0    <- Perl_pp_leavesub                      dirty
   0    -> Perl_pp_entersub                      whiten
   0    <- Perl_pp_leavesub                      whiten
   0  <- Perl_dounwind                           BEGIN
+ # dtrace -qFZn 'sub-entry, sub-return { trace(copyinstr(arg0)) }'
+
+ 0  -> Perl_pp_entersub                        BEGIN
+ 0  <- Perl_pp_leavesub                        BEGIN
+ 0  -> Perl_pp_entersub                        BEGIN
+ 0    -> Perl_pp_entersub                      import
+ 0    <- Perl_pp_leavesub                      import
+ 0  <- Perl_pp_leavesub                        BEGIN
+ 0  -> Perl_pp_entersub                        BEGIN
+ 0    -> Perl_pp_entersub                      dress
+ 0    <- Perl_pp_leavesub                      dress
+ 0    -> Perl_pp_entersub                      dirty
+ 0    <- Perl_pp_leavesub                      dirty
+ 0    -> Perl_pp_entersub                      whiten
+ 0    <- Perl_pp_leavesub                      whiten
+ 0  <- Perl_dounwind                           BEGIN
 
 =item Function calls during interpreter cleanup
 
   # dtrace -Zn 'phase-change /copyinstr(arg0) == "END"/ { self->ending = 1 } sub-entry /self->ending/ { trace(copyinstr(arg0)) }'
+ # dtrace -Zn 'phase-change /copyinstr(arg0) == "END"/ { self->ending = 1 } sub-entry /self->ending/ { trace(copyinstr(arg0)) }'
 
   CPU     ID                    FUNCTION:NAME
-      1  77214       Perl_pp_entersub:sub-entry   END
-      1  77214       Perl_pp_entersub:sub-entry   END
-      1  77214       Perl_pp_entersub:sub-entry   cleanup
-      1  77214       Perl_pp_entersub:sub-entry   _force_writable
-      1  77214       Perl_pp_entersub:sub-entry   _force_writable
+ CPU     ID                    FUNCTION:NAME
+   1  77214       Perl_pp_entersub:sub-entry   END
+   1  77214       Perl_pp_entersub:sub-entry   END
+   1  77214       Perl_pp_entersub:sub-entry   cleanup
+   1  77214       Perl_pp_entersub:sub-entry   _force_writable
+   1  77214       Perl_pp_entersub:sub-entry   _force_writable
 
 =item System calls at compile time
 
   # dtrace -qZn 'phase-change /copyinstr(arg0) == "START"/ { self->interesting = 1 } phase-change /copyinstr(arg0) == "RUN"/ { self->interesting = 0 } syscall::: /self->interesting/ { @[probefunc] = count() } END { trunc(@, 3) }'
+ # dtrace -qZn 'phase-change /copyinstr(arg0) == "START"/ { self->interesting = 1 } phase-change /copyinstr(arg0) == "RUN"/ { self->interesting = 0 } syscall::: /self->interesting/ { @[probefunc] = count() } END { trunc(@, 3) }'
 
   lseek                                                           310
   read                                                            374
   stat64                                                         1056
+ lseek                                                           310
+ read                                                            374
+ stat64                                                         1056
 
 =item Perl functions that execute the most opcodes
 
   # dtrace -qZn 'sub-entry { self->fqn = strjoin(copyinstr(arg3), strjoin("::", copyinstr(arg0))) } op-entry /self->fqn != ""/ { @[self->fqn] = count() } END { trunc(@, 3) }'
+ # dtrace -qZn 'sub-entry { self->fqn = strjoin(copyinstr(arg3), strjoin("::", copyinstr(arg0))) } op-entry /self->fqn != ""/ { @[self->fqn] = count() } END { trunc(@, 3) }'
 
   warnings::unimport                                             4589
   Exporter::Heavy::_rebuild_cache                                5039
   Exporter::import                                              14578
+ warnings::unimport                                             4589
+ Exporter::Heavy::_rebuild_cache                                5039
+ Exporter::import                                              14578
 
 =back
 
index 485109f..68d190f 100644 (file)
@@ -5792,7 +5792,7 @@ subclasses, like C<isa> does.
 Instead, use C<blessed> (in the L<Scalar::Util> module) for boolean
 checks, C<isa> for specific class checks and C<reftype> (also from
 L<Scalar::Util>) for type checks.  (See L<perlobj> for details and a
-C<blessed/isa> example.)
+C<blessed>/C<isa> example.)
 
 See also L<perlref>.
 
index cd8a1d6..a6a927b 100644 (file)
@@ -37,7 +37,7 @@ For the Perl Artistic License, see L<perlartistic>.
                      Version 1, February 1989
 
   Copyright (C) 1989 Free Software Foundation, Inc.
-                     51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+                51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 
   Everyone is permitted to copy and distribute verbatim copies
   of this license document, but changing it is not allowed.
@@ -69,16 +69,16 @@ For the Perl Artistic License, see L<perlartistic>.
  you have.  You must make sure that they, too, receive or can get the
  source code.  And you must tell them their rights.
 
-   We protect your rights with two steps: (1) copyright the software, and
- (2) offer you this license which gives you legal permission to copy,
- distribute and/or modify the software.
+   We protect your rights with two steps: (1) copyright the software,
+ and (2) offer you this license which gives you legal permission to
copy, distribute and/or modify the software.
 
    Also, for each author's protection and ours, we want to make certain
  that everyone understands that there is no warranty for this free
- software.  If the software is modified by someone else and passed on, we
- want its recipients to know that what they have is not the original, so
- that any problems introduced by others will not reflect on the original
- authors' reputations.
+ software.  If the software is modified by someone else and passed on,
+ we want its recipients to know that what they have is not the original,
+ so that any problems introduced by others will not reflect on the
original authors' reputations.
 
    The precise terms and conditions for copying, distribution and
  modification follow.
@@ -91,52 +91,53 @@ For the Perl Artistic License, see L<perlartistic>.
  distributed under the terms of this General Public License.  The
  "Program", below, refers to any such program or work, and a "work based
  on the Program" means either the Program or any work containing the
- Program or a portion of it, either verbatim or with modifications.  Each
- licensee is addressed as "you".
-
-   1. You may copy and distribute verbatim copies of the Program's source
- code as you receive it, in any medium, provided that you conspicuously and
- appropriately publish on each copy an appropriate copyright notice and
- disclaimer of warranty; keep intact all the notices that refer to this
- General Public License and to the absence of any warranty; and give any
- other recipients of the Program a copy of this General Public License
- along with the Program.  You may charge a fee for the physical act of
- transferring a copy.
-
-   2. You may modify your copy or copies of the Program or any portion of
- it, and copy and distribute such modifications under the terms of Paragraph
- 1 above, provided that you also do the following:
+ Program or a portion of it, either verbatim or with modifications.
Each licensee is addressed as "you".
+
+   1. You may copy and distribute verbatim copies of the Program's
+ source code as you receive it, in any medium, provided that you
+ conspicuously and appropriately publish on each copy an appropriate
+ copyright notice and disclaimer of warranty; keep intact all the
+ notices that refer to this General Public License and to the absence of
+ any warranty; and give any other recipients of the Program a copy of
+ this General Public License along with the Program.  You may charge a
fee for the physical act of transferring a copy.
+
+   2. You may modify your copy or copies of the Program or any portion
+ of it, and copy and distribute such modifications under the terms of
Paragraph 1 above, provided that you also do the following:
 
      a) cause the modified files to carry prominent notices stating that
      you changed the files and the date of any change; and
 
      b) cause the whole of any work that you distribute or publish, that
-     in whole or in part contains the Program or any part thereof, either
-     with or without modifications, to be licensed at no charge to all
-     third parties under the terms of this General Public License (except
-     that you may choose to grant warranty protection to some or all
-     third parties, at your option).
-
-     c) If the modified program normally reads commands interactively when
-     run, you must cause it, when started running for such interactive use
-     in the simplest and most usual way, to print or display an
-     announcement including an appropriate copyright notice and a notice
-     that there is no warranty (or else, saying that you provide a
-     warranty) and that users may redistribute the program under these
-     conditions, and telling the user how to view a copy of this General
-     Public License.
+     in whole or in part contains the Program or any part thereof,
+     either with or without modifications, to be licensed at no charge
+     to all third parties under the terms of this General Public License
+     (except that you may choose to grant warranty protection to some or
+     all third parties, at your option).
+
+     c) If the modified program normally reads commands interactively
+     when run, you must cause it, when started running for such
+     interactive use in the simplest and most usual way, to print or
+     display an announcement including an appropriate copyright notice
+     and a notice that there is no warranty (or else, saying that you
+     provide a warranty) and that users may redistribute the program
+     under these conditions, and telling the user how to view a copy of
+     this General Public License.
 
      d) You may charge a fee for the physical act of transferring a
      copy, and you may at your option offer warranty protection in
      exchange for a fee.
 
  Mere aggregation of another independent work with the Program (or its
- derivative) on a volume of a storage or distribution medium does not bring
- the other work under the scope of these terms.
+ derivative) on a volume of a storage or distribution medium does not
bring the other work under the scope of these terms.
 
-   3. You may copy and distribute the Program (or a portion or derivative of
- it, under Paragraph 2) in object code or executable form under the terms of
- Paragraphs 1 and 2 above provided that you also do one of the following:
+   3. You may copy and distribute the Program (or a portion or
+ derivative of it, under Paragraph 2) in object code or executable form
+ under the terms of Paragraphs 1 and 2 above provided that you also do
+ one of the following:
 
      a) accompany it with the complete corresponding machine-readable
      source code, which must be distributed under the terms of
@@ -144,8 +145,8 @@ For the Perl Artistic License, see L<perlartistic>.
 
      b) accompany it with a written offer, valid for at least three
      years, to give any third party free (except for a nominal charge
-     for the cost of distribution) a complete machine-readable copy of the
-     corresponding source code, to be distributed under the terms of
+     for the cost of distribution) a complete machine-readable copy of
+     the corresponding source code, to be distributed under the terms of
      Paragraphs 1 and 2 above; or,
 
      c) accompany it with the information you received as to where the
@@ -154,74 +155,75 @@ For the Perl Artistic License, see L<perlartistic>.
      received the program in object code or executable form alone.)
 
  Source code for a work means the preferred form of the work for making
- modifications to it.  For an executable file, complete source code means
- all the source code for all modules it contains; but, as a special
- exception, it need not include source code for modules which are standard
libraries that accompany the operating system on which the executable
- file runs, or for standard header files or definitions files that
- accompany that operating system.
+ modifications to it.  For an executable file, complete source code
+ means all the source code for all modules it contains; but, as a
+ special exception, it need not include source code for modules which
are standard libraries that accompany the operating system on which the
+ executable file runs, or for standard header files or definitions files
that accompany that operating system.
 
    4. You may not copy, modify, sublicense, distribute or transfer the
  Program except as expressly provided under this General Public License.
- Any attempt otherwise to copy, modify, sublicense, distribute or transfer
- the Program is void, and will automatically terminate your rights to use
- the Program under this License.  However, parties who have received
- copies, or rights to use copies, from you under this General Public
- License will not have their licenses terminated so long as such parties
- remain in full compliance.
+ Any attempt otherwise to copy, modify, sublicense, distribute or
+ transfer the Program is void, and will automatically terminate your
+ rights to use the Program under this License.  However, parties who
+ have received copies, or rights to use copies, from you under this
+ General Public License will not have their licenses terminated so long
as such parties remain in full compliance.
 
-   5. By copying, distributing or modifying the Program (or any work based
- on the Program) you indicate your acceptance of this license to do so,
- and all its terms and conditions.
+   5. By copying, distributing or modifying the Program (or any work
+ based on the Program) you indicate your acceptance of this license to
do so, and all its terms and conditions.
 
    6. Each time you redistribute the Program (or any work based on the
- Program), the recipient automatically receives a license from the original
- licensor to copy, distribute or modify the Program subject to these
- terms and conditions.  You may not impose any further restrictions on the
- recipients' exercise of the rights granted herein.
+ Program), the recipient automatically receives a license from the
+ original licensor to copy, distribute or modify the Program subject to
+ these terms and conditions.  You may not impose any further
+ restrictions on the recipients' exercise of the rights granted herein.
 
-   7. The Free Software Foundation may publish revised and/or new versions
- of the General Public License from time to time.  Such new versions will
- be similar in spirit to the present version, but may differ in detail to
- address new problems or concerns.
+   7. The Free Software Foundation may publish revised and/or new
+ versions of the General Public License from time to time.  Such new
+ versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.
 
  Each version is given a distinguishing version number.  If the Program
  specifies a version number of the license which applies to it and "any
- later version", you have the option of following the terms and conditions
- either of that version or of any later version published by the Free
- Software Foundation.  If the Program does not specify a version number of
- the license, you may choose any version ever published by the Free Software
- Foundation.
+ later version", you have the option of following the terms and
+ conditions either of that version or of any later version published by
+ the Free Software Foundation.  If the Program does not specify a
+ version number of the license, you may choose any version ever
published by the Free Software Foundation.
 
    8. If you wish to incorporate parts of the Program into other free
- programs whose distribution conditions are different, write to the author
to ask for permission.  For software which is copyrighted by the Free
- Software Foundation, write to the Free Software Foundation; we sometimes
- make exceptions for this.  Our decision will be guided by the two goals
- of preserving the free status of all derivatives of our free software and
- of promoting the sharing and reuse of software generally.
+ programs whose distribution conditions are different, write to the
author to ask for permission.  For software which is copyrighted by the
+ Free Software Foundation, write to the Free Software Foundation; we
+ sometimes make exceptions for this.  Our decision will be guided by the
+ two goals of preserving the free status of all derivatives of our free
software and of promoting the sharing and reuse of software generally.
 
                             NO WARRANTY
 
-   9. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
- FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
- OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
- PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
- OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
- MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
- TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
- PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
- REPAIR OR CORRECTION.
-
-   10. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
- WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
- REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
- INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
- OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
- TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
- YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
- PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
- POSSIBILITY OF SUCH DAMAGES.
+   9. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
+ WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+ EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+ OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND,
+ EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+ THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS
+ WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+   10. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+ WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+ AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
+ FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+ CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+ PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+ RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+ FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF
+ SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+ DAMAGES.
 
                      END OF TERMS AND CONDITIONS
 
@@ -232,18 +234,19 @@ For the Perl Artistic License, see L<perlartistic>.
  free software which everyone can redistribute and change under these
  terms.
 
-   To do so, attach the following notices to the program.  It is safest to
attach them to the start of each source file to most effectively convey
- the exclusion of warranty; and each file should have at least the
- "copyright" line and a pointer to where the full notice is found.
+   To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
+ convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
 
-     <one line to give the program's name and a brief idea of what it does.>
+     <one line to give the program's name and a brief idea of what it
+     does.>
      Copyright (C) 19yy  <name of author>
 
-     This program is free software; you can redistribute it and/or modify
-     it under the terms of the GNU General Public License as published by
-     the Free Software Foundation; either version 1, or (at your option)
-     any later version.
+     This program is free software; you can redistribute it and/or
+     modify it under the terms of the GNU General Public License as
+     published by the Free Software Foundation; either version 1, or (at
+     your option) any later version.
 
      This program is distributed in the hope that it will be useful,
      but WITHOUT ANY WARRANTY; without even the implied warranty of
@@ -256,15 +259,17 @@ For the Perl Artistic License, see L<perlartistic>.
      02110-1301 USA
 
 
- Also add information on how to contact you by electronic and paper mail.
+ Also add information on how to contact you by electronic and paper
+ mail.
 
  If the program is interactive, make it output a short notice like this
  when it starts in an interactive mode:
 
      Gnomovision version 69, Copyright (C) 19xx name of author
-     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
-     This is free software, and you are welcome to redistribute it
-     under certain conditions; type 'show c' for details.
+     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type
+     'show w'.  This is free software, and you are welcome to
+     redistribute it under certain conditions; type 'show c' for
+     details.
 
  The hypothetical commands 'show w' and 'show c' should show the
  appropriate parts of the General Public License.  Of course, the
index a667a10..345200f 100644 (file)
@@ -2150,7 +2150,7 @@ code like
 
 creates two scopes: the first starts at the C<(> and has C<full == 1>,
 the second starts at the C<{> and has C<full == 0>.  Both end at the
-C<}>, so calls to C<start> and C<pre/post_end> will match.  Anything
+C<}>, so calls to C<start> and C<pre>/C<post_end> will match.  Anything
 pushed onto the save stack by this hook will be popped just before the
 scope ends (between the C<pre_> and C<post_end> hooks, in fact).
 
@@ -2190,7 +2190,7 @@ is probably the best way, so the effect is lexically scoped; however it
 is also possible to use the C<BhkDISABLE> and C<BhkENABLE> macros to
 temporarily switch entries on and off.  You should also be aware that
 generally speaking at least one scope will have opened before your
-extension is loaded, so you will see some C<pre/post_end> pairs that
+extension is loaded, so you will see some C<pre>/C<post_end> pairs that
 didn't have a matching C<start>.
 
 =head1 Examining internal data structures with the C<dump> functions
index a95ecc8..6d0ae03 100644 (file)
@@ -232,7 +232,7 @@ from C<File>. An C<File::MP3> B<is-a> I<more specific> type of C<File>.
 All mp3 files are files, but not all files are mp3 files.
 
 We often refer to inheritance relationships as B<parent-child> or
-C<superclass/subclass> relationships. Sometimes we say that the child
+C<superclass>/C<subclass> relationships. Sometimes we say that the child
 has an B<is-a> relationship with its parent class.
 
 C<File> is a B<superclass> of C<File::MP3>, and C<File::MP3> is a
index ad9d493..5884a54 100644 (file)
@@ -11,7 +11,7 @@ where appropriate, there are many other people who might benefit from a few
 perl specific pointers.  If you want the condensed version, perhaps the best
 advice comes from the renowned Japanese Samurai, Miyamoto Musashi, who said:
 
   "Do Not Engage in Useless Activity"
+ "Do Not Engage in Useless Activity"
 
 in 1645.
 
@@ -110,8 +110,8 @@ Here are a few examples to demonstrate usage of Perl's benchmarking tools.
 
 I'm sure most of us have seen code which looks like, (or worse than), this:
 
   if ( $obj->{_ref}->{_myscore} >= $obj->{_ref}->{_yourscore} ) {
-        ...
+ if ( $obj->{_ref}->{_myscore} >= $obj->{_ref}->{_yourscore} ) {
+     ...
 
 This sort of code can be a real eyesore to read, as well as being very
 sensitive to typos, and it's much clearer to dereference the variable
@@ -124,31 +124,31 @@ comparative code in a file and running a C<Benchmark> test.
 
 # dereference
 
   #!/usr/bin/perl
+ #!/usr/bin/perl
 
   use strict;
   use warnings;
+ use strict;
+ use warnings;
 
   use Benchmark;
+ use Benchmark;
 
   my $ref = {
-            'ref'   => {
-                _myscore    => '100 + 1',
-                _yourscore  => '102 - 1',
-            },
   };
+ my $ref = {
+         'ref'   => {
+             _myscore    => '100 + 1',
+             _yourscore  => '102 - 1',
+         },
+ };
 
   timethese(1000000, {
-            'direct'       => sub {
-                my $x = $ref->{ref}->{_myscore} . $ref->{ref}->{_yourscore} ;
-            },
-            'dereference'  => sub {
-                my $ref  = $ref->{ref};
-                my $myscore = $ref->{_myscore};
-                my $yourscore = $ref->{_yourscore};
-                my $x = $myscore . $yourscore;
-            },
   });
+ timethese(1000000, {
+         'direct'       => sub {
+           my $x = $ref->{ref}->{_myscore} . $ref->{ref}->{_yourscore} ;
+         },
+         'dereference'  => sub {
+             my $ref  = $ref->{ref};
+             my $myscore = $ref->{_myscore};
+             my $yourscore = $ref->{_yourscore};
+             my $x = $myscore . $yourscore;
+         },
+ });
 
 It's essential to run any timing measurements a sufficient number of times so
 the numbers settle on a numerical average, otherwise each run will naturally
@@ -157,11 +157,11 @@ contention for C<CPU> resources and network bandwidth for instance.  Running
 the above code for one million iterations, we can take a look at the report
 output by the C<Benchmark> module, to see which approach is the most effective.
 
   $> perl dereference
+ $> perl dereference
 
   Benchmark: timing 1000000 iterations of dereference, direct...
   dereference:  2 wallclock secs ( 1.59 usr +  0.00 sys =  1.59 CPU) @ 628930.82/s (n=1000000)
-        direct:  1 wallclock secs ( 1.20 usr +  0.00 sys =  1.20 CPU) @ 833333.33/s (n=1000000)
+ Benchmark: timing 1000000 iterations of dereference, direct...
+ dereference:  2 wallclock secs ( 1.59 usr +  0.00 sys =  1.59 CPU) @ 628930.82/s (n=1000000)
+     direct:  1 wallclock secs ( 1.20 usr +  0.00 sys =  1.20 CPU) @ 833333.33/s (n=1000000)
 
 The difference is clear to see and the dereferencing approach is slower.  While
 it managed to execute an average of 628,930 times a second during our test, the
@@ -178,11 +178,11 @@ always be much more flexible, C<tr>, an oft underused tool, can still be a
 useful.  One scenario might be replace all vowels with another character.  The
 regex solution might look like this:
 
   $str =~ s/[aeiou]/x/g
+ $str =~ s/[aeiou]/x/g
 
 The C<tr> alternative might look like this:
 
   $str =~ tr/aeiou/xxxxx/
+ $str =~ tr/aeiou/xxxxx/
 
 We can put that into a test file which we can run to check which approach is
 the fastest, using a global C<$STR> variable to assign to the C<my $str>
@@ -191,27 +191,27 @@ noticing it's assigned only the once.
 
 # regex-transliterate
 
   #!/usr/bin/perl
+ #!/usr/bin/perl
 
   use strict;
   use warnings;
+ use strict;
+ use warnings;
 
   use Benchmark;
+ use Benchmark;
 
   my $STR = "$$-this and that";
+ my $STR = "$$-this and that";
 
   timethese( 1000000, {
           'sr'  => sub { my $str = $STR; $str =~ s/[aeiou]/x/g; return $str; },
           'tr'  => sub { my $str = $STR; $str =~ tr/aeiou/xxxxx/; return $str; },
   });
+ timethese( 1000000, {
+ 'sr'  => sub { my $str = $STR; $str =~ s/[aeiou]/x/g; return $str; },
+ 'tr'  => sub { my $str = $STR; $str =~ tr/aeiou/xxxxx/; return $str; },
+ });
 
 Running the code gives us our results:
 
   $> perl regex-transliterate
+ $> perl regex-transliterate
 
   Benchmark: timing 1000000 iterations of sr, tr...
-            sr:  2 wallclock secs ( 1.19 usr +  0.00 sys =  1.19 CPU) @ 840336.13/s (n=1000000)
-            tr:  0 wallclock secs ( 0.49 usr +  0.00 sys =  0.49 CPU) @ 2040816.33/s (n=1000000)
+ Benchmark: timing 1000000 iterations of sr, tr...
+         sr:  2 wallclock secs ( 1.19 usr +  0.00 sys =  1.19 CPU) @ 840336.13/s (n=1000000)
+         tr:  0 wallclock secs ( 0.49 usr +  0.00 sys =  0.49 CPU) @ 2040816.33/s (n=1000000)
 
 The C<tr> version is a clear winner.  One solution is flexible, the other is
 fast - and it's appropriately the programmer's choice which to use.
@@ -227,117 +227,118 @@ report on the contents.
 
 # wordmatch
 
-    #!/usr/bin/perl
+ #!/usr/bin/perl
+
+ use strict;
+ use warnings;
+
+ =head1 NAME
+
+ filewords - word analysis of input file
+
+ =head1 SYNOPSIS
+
+     filewords -f inputfilename [-d]
 
-    use strict;
-    use warnings;
+ =head1 DESCRIPTION
 
-    =head1 NAME
-
-    filewords - word analysis of input file
-
-    =head1 SYNOPSIS
-
-        filewords -f inputfilename [-d]
+ This program parses the given filename, specified with C<-f>, and
+ displays a simple analysis of the words found therein.  Use the C<-d>
+ switch to enable debugging messages.
 
-    =head1 DESCRIPTION
+ =cut
 
-    This program parses the given filename, specified with C<-f>, and displays a
-    simple analysis of the words found therein.  Use the C<-d> switch to enable
-    debugging messages.
+ use FileHandle;
+ use Getopt::Long;
 
-    =cut
+ my $debug   =  0;
+ my $file    = '';
 
-    use FileHandle;
-    use Getopt::Long;
+ my $result = GetOptions (
+     'debug'         => \$debug,
+     'file=s'        => \$file,
+ );
+ die("invalid args") unless $result;
 
-    my $debug   =  0;
-    my $file    = '';
+ unless ( -f $file ) {
+     die("Usage: $0 -f filename [-d]");
+ }
+ my $FH = FileHandle->new("< $file")
+                               or die("unable to open file($file): $!");
 
-    my $result = GetOptions (
-        'debug'         => \$debug,
-        'file=s'        => \$file,
-    );
-    die("invalid args") unless $result;
+ my $i_LINES = 0;
+ my $i_WORDS = 0;
+ my %count   = ();
 
-    unless ( -f $file ) {
-        die("Usage: $0 -f filename [-d]");
-    }
-    my $FH = FileHandle->new("< $file") or die("unable to open file($file): $!");
+ my @lines = <$FH>;
+ foreach my $line ( @lines ) {
+     $i_LINES++;
+     $line =~ s/\n//;
+     my @words = split(/ +/, $line);
+     my $i_words = scalar(@words);
+     $i_WORDS = $i_WORDS + $i_words;
+     debug("line: $i_LINES supplying $i_words words: @words");
+     my $i_word = 0;
+     foreach my $word ( @words ) {
+         $i_word++;
+         $count{$i_LINES}{spec} += matches($i_word, $word, '[^a-zA-Z0-9]');
+         $count{$i_LINES}{only} += matches($i_word, $word, '^[^a-zA-Z0-9]+$');
+         $count{$i_LINES}{cons} += matches($i_word, $word, '^[(?i:bcdfghjklmnpqrstvwxyz)]+$');
+         $count{$i_LINES}{vows} += matches($i_word, $word, '^[(?i:aeiou)]+$');
+         $count{$i_LINES}{caps} += matches($i_word, $word, '^[(A-Z)]+$');
+     }
+ }
 
-    my $i_LINES = 0;
-    my $i_WORDS = 0;
-    my %count   = ();
+ print report( %count );
 
-    my @lines = <$FH>;
-    foreach my $line ( @lines ) {
-        $i_LINES++;
-        $line =~ s/\n//;
-        my @words = split(/ +/, $line);
-        my $i_words = scalar(@words);
-        $i_WORDS = $i_WORDS + $i_words;
-        debug("line: $i_LINES supplying $i_words words: @words");
-        my $i_word = 0;
-        foreach my $word ( @words ) {
-            $i_word++;
-            $count{$i_LINES}{spec} += matches($i_word, $word, '[^a-zA-Z0-9]');
-            $count{$i_LINES}{only} += matches($i_word, $word, '^[^a-zA-Z0-9]+$');
-            $count{$i_LINES}{cons} += matches($i_word, $word, '^[(?i:bcdfghjklmnpqrstvwxyz)]+$');
-            $count{$i_LINES}{vows} += matches($i_word, $word, '^[(?i:aeiou)]+$');
-            $count{$i_LINES}{caps} += matches($i_word, $word, '^[(A-Z)]+$');
-        }
-    }
+ sub matches {
+     my $i_wd  = shift;
+     my $word  = shift;
+     my $regex = shift;
+     my $has = 0;
 
-    print report( %count );
+     if ( $word =~ /($regex)/ ) {
+         $has++ if $1;
+     }
 
-    sub matches {
-        my $i_wd  = shift;
-        my $word  = shift;
-        my $regex = shift;
-        my $has = 0;
+     debug("word: $i_wd ".($has ? 'matches' : 'does not match')." chars: /$regex/");
 
-        if ( $word =~ /($regex)/ ) {
-            $has++ if $1;
-        }
+     return $has;
+ }
 
-        debug("word: $i_wd ".($has ? 'matches' : 'does not match')." chars: /$regex/");
+ sub report {
+     my %report = @_;
+     my %rep;
 
-        return $has;
-    }
+     foreach my $line ( keys %report ) {
+         foreach my $key ( keys %{ $report{$line} } ) {
+             $rep{$key} += $report{$line}{$key};
+         }
+     }
 
-    sub report {
-        my %report = @_;
-        my %rep;
+     my $report = qq|
+ $0 report for $file:
+ lines in file: $i_LINES
+ words in file: $i_WORDS
+ words with special (non-word) characters: $i_spec
+ words with only special (non-word) characters: $i_only
+ words with only consonants: $i_cons
+ words with only capital letters: $i_caps
+ words with only vowels: $i_vows
+ |;
 
-        foreach my $line ( keys %report ) {
-            foreach my $key ( keys %{ $report{$line} } ) {
-                $rep{$key} += $report{$line}{$key};
-            }
-        }
-
-        my $report = qq|
-    $0 report for $file:
-    lines in file: $i_LINES
-    words in file: $i_WORDS
-    words with special (non-word) characters: $i_spec
-    words with only special (non-word) characters: $i_only
-    words with only consonants: $i_cons
-    words with only capital letters: $i_caps
-    words with only vowels: $i_vows
-    |;
-
-        return $report;
-    }
-
-    sub debug {
-        my $message = shift;
-
-        if ( $debug ) {
-            print STDERR "DBG: $message\n";
-        }
-    }
-
-    exit 0;
+     return $report;
+ }
+
+ sub debug {
+     my $message = shift;
+
+     if ( $debug ) {
+         print STDERR "DBG: $message\n";
+     }
+ }
+
+ exit 0;
 
 =head2 Devel::DProf
 
@@ -351,18 +352,18 @@ L<Devel::DProf> first, to set a baseline for Perl profiling tools.  Run the
 above program under the control of C<Devel::DProf> by using the C<-d> switch on
 the command-line.
 
   $> perl -d:DProf wordmatch -f perl5db.pl
+ $> perl -d:DProf wordmatch -f perl5db.pl
 
   <...multiple lines snipped...>
+ <...multiple lines snipped...>
 
   wordmatch report for perl5db.pl:
   lines in file: 9428
   words in file: 50243
   words with special (non-word) characters: 20480
   words with only special (non-word) characters: 7790
   words with only consonants: 4801
   words with only capital letters: 1316
   words with only vowels: 1701
+ wordmatch report for perl5db.pl:
+ lines in file: 9428
+ words in file: 50243
+ words with special (non-word) characters: 20480
+ words with only special (non-word) characters: 7790
+ words with only consonants: 4801
+ words with only capital letters: 1316
+ words with only vowels: 1701
 
 C<Devel::DProf> produces a special file, called F<tmon.out> by default, and
 this file is read by the C<dprofpp> program, which is already installed as part
@@ -371,27 +372,27 @@ it will read the F<tmon.out> file in the current directory and produce a human
 readable statistics report of the run of your program.  Note that this may take
 a little time.
 
   $> dprofpp
-
   Total Elapsed Time = 2.951677 Seconds
-      User+System Time = 2.871677 Seconds
   Exclusive Times
   %Time ExclSec CumulS #Calls sec/call Csec/c  Name
-     102.   2.945  3.003 251215   0.0000 0.0000  main::matches
-     2.40   0.069  0.069 260643   0.0000 0.0000  main::debug
-     1.74   0.050  0.050      1   0.0500 0.0500  main::report
-     1.04   0.030  0.049      4   0.0075 0.0123  main::BEGIN
-     0.35   0.010  0.010      3   0.0033 0.0033  Exporter::as_heavy
-     0.35   0.010  0.010      7   0.0014 0.0014  IO::File::BEGIN
-     0.00       - -0.000      1        -      -  Getopt::Long::FindOption
-     0.00       - -0.000      1        -      -  Symbol::BEGIN
-     0.00       - -0.000      1        -      -  Fcntl::BEGIN
-     0.00       - -0.000      1        -      -  Fcntl::bootstrap
-     0.00       - -0.000      1        -      -  warnings::BEGIN
-     0.00       - -0.000      1        -      -  IO::bootstrap
-     0.00       - -0.000      1        -      -  Getopt::Long::ConfigDefaults
-     0.00       - -0.000      1        -      -  Getopt::Long::Configure
-     0.00       - -0.000      1        -      -  Symbol::gensym
+ $> dprofpp
+
+ Total Elapsed Time = 2.951677 Seconds
+   User+System Time = 2.871677 Seconds
+ Exclusive Times
+ %Time ExclSec CumulS #Calls sec/call Csec/c  Name
+  102.   2.945  3.003 251215   0.0000 0.0000  main::matches
+  2.40   0.069  0.069 260643   0.0000 0.0000  main::debug
+  1.74   0.050  0.050      1   0.0500 0.0500  main::report
+  1.04   0.030  0.049      4   0.0075 0.0123  main::BEGIN
+  0.35   0.010  0.010      3   0.0033 0.0033  Exporter::as_heavy
+  0.35   0.010  0.010      7   0.0014 0.0014  IO::File::BEGIN
+  0.00       - -0.000      1        -      -  Getopt::Long::FindOption
+  0.00       - -0.000      1        -      -  Symbol::BEGIN
+  0.00       - -0.000      1        -      -  Fcntl::BEGIN
+  0.00       - -0.000      1        -      -  Fcntl::bootstrap
+  0.00       - -0.000      1        -      -  warnings::BEGIN
+  0.00       - -0.000      1        -      -  IO::bootstrap
+  0.00       - -0.000      1        -      -  Getopt::Long::ConfigDefaults
+  0.00       - -0.000      1        -      -  Getopt::Long::Configure
+  0.00       - -0.000      1        -      -  Symbol::gensym
 
 C<dprofpp> will produce some quite detailed reporting on the activity of the
 C<wordmatch> program.  The wallclock, user and system, times are at the top of
@@ -407,40 +408,40 @@ C<Devel::Profiler>, a drop-in Perl-only replacement for C<Devel::DProf>.  The
 usage is very slightly different in that instead of using the special C<-d:>
 flag, you pull C<Devel::Profiler> in directly as a module using C<-M>.
 
   $> perl -MDevel::Profiler wordmatch -f perl5db.pl
+ $> perl -MDevel::Profiler wordmatch -f perl5db.pl
 
   <...multiple lines snipped...>
+ <...multiple lines snipped...>
 
   wordmatch report for perl5db.pl:
   lines in file: 9428
   words in file: 50243
   words with special (non-word) characters: 20480
   words with only special (non-word) characters: 7790
   words with only consonants: 4801
   words with only capital letters: 1316
   words with only vowels: 1701
+ wordmatch report for perl5db.pl:
+ lines in file: 9428
+ words in file: 50243
+ words with special (non-word) characters: 20480
+ words with only special (non-word) characters: 7790
+ words with only consonants: 4801
+ words with only capital letters: 1316
+ words with only vowels: 1701
 
 
 C<Devel::Profiler> generates a tmon.out file which is compatible with the
 C<dprofpp> program, thus saving the construction of a dedicated statistics
 reader program.  C<dprofpp> usage is therefore identical to the above example.
 
   $> dprofpp
-
   Total Elapsed Time =   20.984 Seconds
-      User+System Time =   19.981 Seconds
   Exclusive Times
   %Time ExclSec CumulS #Calls sec/call Csec/c  Name
-     49.0   9.792 14.509 251215   0.0000 0.0001  main::matches
-     24.4   4.887  4.887 260643   0.0000 0.0000  main::debug
-     0.25   0.049  0.049      1   0.0490 0.0490  main::report
-     0.00   0.000  0.000      1   0.0000 0.0000  Getopt::Long::GetOptions
-     0.00   0.000  0.000      2   0.0000 0.0000  Getopt::Long::ParseOptionSpec
-     0.00   0.000  0.000      1   0.0000 0.0000  Getopt::Long::FindOption
-     0.00   0.000  0.000      1   0.0000 0.0000  IO::File::new
-     0.00   0.000  0.000      1   0.0000 0.0000  IO::Handle::new
-     0.00   0.000  0.000      1   0.0000 0.0000  Symbol::gensym
-     0.00   0.000  0.000      1   0.0000 0.0000  IO::File::open
+ $> dprofpp
+
+ Total Elapsed Time =   20.984 Seconds
+   User+System Time =   19.981 Seconds
+ Exclusive Times
+ %Time ExclSec CumulS #Calls sec/call Csec/c  Name
+  49.0   9.792 14.509 251215   0.0000 0.0001  main::matches
+  24.4   4.887  4.887 260643   0.0000 0.0000  main::debug
+  0.25   0.049  0.049      1   0.0490 0.0490  main::report
+  0.00   0.000  0.000      1   0.0000 0.0000  Getopt::Long::GetOptions
+  0.00   0.000  0.000      2   0.0000 0.0000  Getopt::Long::ParseOptionSpec
+  0.00   0.000  0.000      1   0.0000 0.0000  Getopt::Long::FindOption
+  0.00   0.000  0.000      1   0.0000 0.0000  IO::File::new
+  0.00   0.000  0.000      1   0.0000 0.0000  IO::Handle::new
+  0.00   0.000  0.000      1   0.0000 0.0000  Symbol::gensym
+  0.00   0.000  0.000      1   0.0000 0.0000  IO::File::open
 
 Interestingly we get slightly different results, which is mostly because the
 algorithm which generates the report is different, even though the output file
@@ -453,11 +454,12 @@ cons, before using them.  Interestingly, the numbers of calls for each
 subroutine are identical in the two reports, it's the percentages which differ.
 As the author of C<Devel::Proviler> writes:
 
-    ...running HTML::Template's test suite under Devel::DProf shows output()
-    taking NO time but Devel::Profiler shows around 10% of the time is in output().
-    I don't know which to trust but my gut tells me something is wrong with
-    Devel::DProf.  HTML::Template::output() is a big routine that's called for
-    every test. Either way, something needs fixing.
+ ...running HTML::Template's test suite under Devel::DProf shows
+ output() taking NO time but Devel::Profiler shows around 10% of the
+ time is in output().  I don't know which to trust but my gut tells me
+ something is wrong with Devel::DProf.  HTML::Template::output() is a
+ big routine that's called for every test. Either way, something needs
+ fixing.
 
 YMMV.
 
@@ -470,50 +472,50 @@ produces a line-by-line listing to show how many times each line was called,
 and how long each line took to execute.  It is called by supplying the familiar
 C<-d> flag to Perl at runtime.
 
   $> perl -d:SmallProf wordmatch -f perl5db.pl
+ $> perl -d:SmallProf wordmatch -f perl5db.pl
 
   <...multiple lines snipped...>
+ <...multiple lines snipped...>
 
   wordmatch report for perl5db.pl:
   lines in file: 9428
   words in file: 50243
   words with special (non-word) characters: 20480
   words with only special (non-word) characters: 7790
   words with only consonants: 4801
   words with only capital letters: 1316
   words with only vowels: 1701
+ wordmatch report for perl5db.pl:
+ lines in file: 9428
+ words in file: 50243
+ words with special (non-word) characters: 20480
+ words with only special (non-word) characters: 7790
+ words with only consonants: 4801
+ words with only capital letters: 1316
+ words with only vowels: 1701
 
 C<Devel::SmallProf> writes it's output into a file called F<smallprof.out>, by
 default.  The format of the file looks like this:
 
   <num> <time> <ctime> <line>:<text>
+ <num> <time> <ctime> <line>:<text>
 
 When the program has terminated, the output may be examined and sorted using
 any standard text filtering utilities.  Something like the following may be
 sufficient:
 
   $> cat smallprof.out | grep \d*: | sort -k3 | tac | head -n20
-
   251215   1.65674   7.68000    75: if ( $word =~ /($regex)/ ) {
   251215   0.03264   4.40000    79: debug("word: $i_wd ".($has ? 'matches' :
   251215   0.02693   4.10000    81: return $has;
   260643   0.02841   4.07000   128: if ( $debug ) {
   260643   0.02601   4.04000   126: my $message = shift;
   251215   0.02641   3.91000    73: my $has = 0;
   251215   0.03311   3.71000    70: my $i_wd  = shift;
   251215   0.02699   3.69000    72: my $regex = shift;
   251215   0.02766   3.68000    71: my $word  = shift;
-     50243   0.59726   1.00000    59:  $count{$i_LINES}{cons} =
-     50243   0.48175   0.92000    61:  $count{$i_LINES}{spec} =
-     50243   0.00644   0.89000    56:  my $i_cons = matches($i_word, $word,
-     50243   0.48837   0.88000    63:  $count{$i_LINES}{caps} =
-     50243   0.00516   0.88000    58:  my $i_caps = matches($i_word, $word, '^[(A-
-     50243   0.00631   0.81000    54:  my $i_spec = matches($i_word, $word, '[^a-
-     50243   0.00496   0.80000    57:  my $i_vows = matches($i_word, $word,
-     50243   0.00688   0.80000    53:  $i_word++;
-     50243   0.48469   0.79000    62:  $count{$i_LINES}{only} =
-     50243   0.48928   0.77000    60:  $count{$i_LINES}{vows} =
-     50243   0.00683   0.75000    55:  my $i_only = matches($i_word, $word, '^[^a-
+ $> cat smallprof.out | grep \d*: | sort -k3 | tac | head -n20
+
+ 251215   1.65674   7.68000    75: if ( $word =~ /($regex)/ ) {
+ 251215   0.03264   4.40000    79: debug("word: $i_wd ".($has ? 'matches' :
+ 251215   0.02693   4.10000    81: return $has;
+ 260643   0.02841   4.07000   128: if ( $debug ) {
+ 260643   0.02601   4.04000   126: my $message = shift;
+ 251215   0.02641   3.91000    73: my $has = 0;
+ 251215   0.03311   3.71000    70: my $i_wd  = shift;
+ 251215   0.02699   3.69000    72: my $regex = shift;
+ 251215   0.02766   3.68000    71: my $word  = shift;
+  50243   0.59726   1.00000    59:  $count{$i_LINES}{cons} =
+  50243   0.48175   0.92000    61:  $count{$i_LINES}{spec} =
+  50243   0.00644   0.89000    56:  my $i_cons = matches($i_word, $word,
+  50243   0.48837   0.88000    63:  $count{$i_LINES}{caps} =
+  50243   0.00516   0.88000    58:  my $i_caps = matches($i_word, $word, '^[(A-
+  50243   0.00631   0.81000    54:  my $i_spec = matches($i_word, $word, '[^a-
+  50243   0.00496   0.80000    57:  my $i_vows = matches($i_word, $word,
+  50243   0.00688   0.80000    53:  $i_word++;
+  50243   0.48469   0.79000    62:  $count{$i_LINES}{only} =
+  50243   0.48928   0.77000    60:  $count{$i_LINES}{vows} =
+  50243   0.00683   0.75000    55:  my $i_only = matches($i_word, $word, '^[^a-
 
 You can immediately see a slightly different focus to the subroutine profiling
 modules, and we start to see exactly which line of code is taking the most
@@ -530,35 +532,35 @@ to getting a faster line profiler, than is possible with for example
 C<Devel::SmallProf>, because it's written in C<C>.  To use C<Devel::FastProf>,
 supply the C<-d> argument to Perl:
 
   $> perl -d:FastProf wordmatch -f perl5db.pl
+ $> perl -d:FastProf wordmatch -f perl5db.pl
 
   <...multiple lines snipped...>
+ <...multiple lines snipped...>
 
   wordmatch report for perl5db.pl:
   lines in file: 9428
   words in file: 50243
   words with special (non-word) characters: 20480
   words with only special (non-word) characters: 7790
   words with only consonants: 4801
   words with only capital letters: 1316
   words with only vowels: 1701
+ wordmatch report for perl5db.pl:
+ lines in file: 9428
+ words in file: 50243
+ words with special (non-word) characters: 20480
+ words with only special (non-word) characters: 7790
+ words with only consonants: 4801
+ words with only capital letters: 1316
+ words with only vowels: 1701
 
 C<Devel::FastProf> writes statistics to the file F<fastprof.out> in the current
 directory.  The output file, which can be specified, can be interpreted by using
 the C<fprofpp> command-line program.
 
   $> fprofpp | head -n20
+ $> fprofpp | head -n20
 
   # fprofpp output format is:
   # filename:line time count: source
   wordmatch:75 3.93338 251215: if ( $word =~ /($regex)/ ) {
   wordmatch:79 1.77774 251215: debug("word: $i_wd ".($has ? 'matches' : 'does not match')." chars: /$regex/");
   wordmatch:81 1.47604 251215: return $has;
   wordmatch:126 1.43441 260643: my $message = shift;
   wordmatch:128 1.42156 260643: if ( $debug ) {
   wordmatch:70 1.36824 251215: my $i_wd  = shift;
   wordmatch:71 1.36739 251215: my $word  = shift;
   wordmatch:72 1.35939 251215: my $regex = shift;
+ # fprofpp output format is:
+ # filename:line time count: source
+ wordmatch:75 3.93338 251215: if ( $word =~ /($regex)/ ) {
+ wordmatch:79 1.77774 251215: debug("word: $i_wd ".($has ? 'matches' : 'does not match')." chars: /$regex/");
+ wordmatch:81 1.47604 251215: return $has;
+ wordmatch:126 1.43441 260643: my $message = shift;
+ wordmatch:128 1.42156 260643: if ( $debug ) {
+ wordmatch:70 1.36824 251215: my $i_wd  = shift;
+ wordmatch:71 1.36739 251215: my $word  = shift;
+ wordmatch:72 1.35939 251215: my $regex = shift;
 
 Straightaway we can see that the number of times each line has been called is
 identical to the C<Devel::SmallProf> output, and the sequence is only very
@@ -583,16 +585,16 @@ available for Perl.  The list of coolness just goes on.  Enough of that, let's
 see how to it works - just use the familiar C<-d> switch to plug it in and run
 the code.
 
   $> perl -d:NYTProf wordmatch -f perl5db.pl
+ $> perl -d:NYTProf wordmatch -f perl5db.pl
 
   wordmatch report for perl5db.pl:
   lines in file: 9427
   words in file: 50243
   words with special (non-word) characters: 20480
   words with only special (non-word) characters: 7790
   words with only consonants: 4801
   words with only capital letters: 1316
   words with only vowels: 1701
+ wordmatch report for perl5db.pl:
+ lines in file: 9427
+ words in file: 50243
+ words with special (non-word) characters: 20480
+ words with only special (non-word) characters: 7790
+ words with only consonants: 4801
+ words with only capital letters: 1316
+ words with only vowels: 1701
 
 C<NYTProf> will generate a report database into the file F<nytprof.out> by
 default.  Human readable reports can be generated from here by using the
@@ -600,69 +602,69 @@ supplied C<nytprofhtml> (HTML output) and C<nytprofcsv> (CSV output) programs.
 We've used the Unix system C<html2text> utility to convert the
 F<nytprof/index.html> file for convenience here.
 
   $> html2text nytprof/index.html
-
   Performance Profile Index
   For wordmatch
-      Run on Fri Sep 26 13:46:39 2008
   Reported on Fri Sep 26 13:47:23 2008
-
-             Top 15 Subroutines -- ordered by exclusive time
   |Calls |P |F |Inclusive|Exclusive|Subroutine                          |
   |      |  |  |Time     |Time     |                                    |
   |251215|5 |1 |13.09263 |10.47692 |main::              |matches        |
   |260642|2 |1 |2.71199  |2.71199  |main::              |debug          |
   |1     |1 |1 |0.21404  |0.21404  |main::              |report         |
   |2     |2 |2 |0.00511  |0.00511  |XSLoader::          |load (xsub)    |
   |14    |14|7 |0.00304  |0.00298  |Exporter::          |import         |
   |3     |1 |1 |0.00265  |0.00254  |Exporter::          |as_heavy       |
   |10    |10|4 |0.00140  |0.00140  |vars::              |import         |
   |13    |13|1 |0.00129  |0.00109  |constant::          |import         |
   |1     |1 |1 |0.00360  |0.00096  |FileHandle::        |import         |
   |3     |3 |3 |0.00086  |0.00074  |warnings::register::|import         |
   |9     |3 |1 |0.00036  |0.00036  |strict::            |bits           |
   |13    |13|13|0.00032  |0.00029  |strict::            |import         |
   |2     |2 |2 |0.00020  |0.00020  |warnings::          |import         |
   |2     |1 |1 |0.00020  |0.00020  |Getopt::Long::      |ParseOptionSpec|
   |7     |7 |6 |0.00043  |0.00020  |strict::            |unimport       |
-
   For more information see the full list of 189 subroutines.
+ $> html2text nytprof/index.html
+
+ Performance Profile Index
+ For wordmatch
+   Run on Fri Sep 26 13:46:39 2008
+ Reported on Fri Sep 26 13:47:23 2008
+
+          Top 15 Subroutines -- ordered by exclusive time
+ |Calls |P |F |Inclusive|Exclusive|Subroutine                          |
+ |      |  |  |Time     |Time     |                                    |
+ |251215|5 |1 |13.09263 |10.47692 |main::              |matches        |
+ |260642|2 |1 |2.71199  |2.71199  |main::              |debug          |
+ |1     |1 |1 |0.21404  |0.21404  |main::              |report         |
+ |2     |2 |2 |0.00511  |0.00511  |XSLoader::          |load (xsub)    |
+ |14    |14|7 |0.00304  |0.00298  |Exporter::          |import         |
+ |3     |1 |1 |0.00265  |0.00254  |Exporter::          |as_heavy       |
+ |10    |10|4 |0.00140  |0.00140  |vars::              |import         |
+ |13    |13|1 |0.00129  |0.00109  |constant::          |import         |
+ |1     |1 |1 |0.00360  |0.00096  |FileHandle::        |import         |
+ |3     |3 |3 |0.00086  |0.00074  |warnings::register::|import         |
+ |9     |3 |1 |0.00036  |0.00036  |strict::            |bits           |
+ |13    |13|13|0.00032  |0.00029  |strict::            |import         |
+ |2     |2 |2 |0.00020  |0.00020  |warnings::          |import         |
+ |2     |1 |1 |0.00020  |0.00020  |Getopt::Long::      |ParseOptionSpec|
+ |7     |7 |6 |0.00043  |0.00020  |strict::            |unimport       |
+
+ For more information see the full list of 189 subroutines.
 
 The first part of the report already shows the critical information regarding
 which subroutines are using the most time.  The next gives some statistics
 about the source files profiled.
 
-            Source Code Files -- ordered by exclusive time then name
   |Stmts  |Exclusive|Avg.   |Reports                     |Source File         |
   |       |Time     |       |                            |                    |
   |2699761|15.66654 |6e-06  |line   .    block   .    sub|wordmatch           |
   |35     |0.02187  |0.00062|line   .    block   .    sub|IO/Handle.pm        |
   |274    |0.01525  |0.00006|line   .    block   .    sub|Getopt/Long.pm      |
   |20     |0.00585  |0.00029|line   .    block   .    sub|Fcntl.pm            |
   |128    |0.00340  |0.00003|line   .    block   .    sub|Exporter/Heavy.pm   |
   |42     |0.00332  |0.00008|line   .    block   .    sub|IO/File.pm          |
   |261    |0.00308  |0.00001|line   .    block   .    sub|Exporter.pm         |
   |323    |0.00248  |8e-06  |line   .    block   .    sub|constant.pm         |
   |12     |0.00246  |0.00021|line   .    block   .    sub|File/Spec/Unix.pm   |
   |191    |0.00240  |0.00001|line   .    block   .    sub|vars.pm             |
   |77     |0.00201  |0.00003|line   .    block   .    sub|FileHandle.pm       |
   |12     |0.00198  |0.00016|line   .    block   .    sub|Carp.pm             |
   |14     |0.00175  |0.00013|line   .    block   .    sub|Symbol.pm           |
   |15     |0.00130  |0.00009|line   .    block   .    sub|IO.pm               |
   |22     |0.00120  |0.00005|line   .    block   .    sub|IO/Seekable.pm      |
   |198    |0.00085  |4e-06  |line   .    block   .    sub|warnings/register.pm|
   |114    |0.00080  |7e-06  |line   .    block   .    sub|strict.pm           |
   |47     |0.00068  |0.00001|line   .    block   .    sub|warnings.pm         |
   |27     |0.00054  |0.00002|line   .    block   .    sub|overload.pm         |
   |9      |0.00047  |0.00005|line   .    block   .    sub|SelectSaver.pm      |
   |13     |0.00045  |0.00003|line   .    block   .    sub|File/Spec.pm        |
   |2701595|15.73869 |       |Total                       |
   |128647 |0.74946  |       |Average                     |
   |       |0.00201  |0.00003|Median                      |
   |       |0.00121  |0.00003|Deviation                   |
-
   Report produced by the NYTProf 2.03 Perl profiler, developed by Tim Bunce and
   Adam Kaplan.
+         Source Code Files -- ordered by exclusive time then name
+ |Stmts  |Exclusive|Avg.   |Reports                     |Source File         |
+ |       |Time     |       |                            |                    |
+ |2699761|15.66654 |6e-06  |line   .    block   .    sub|wordmatch           |
+ |35     |0.02187  |0.00062|line   .    block   .    sub|IO/Handle.pm        |
+ |274    |0.01525  |0.00006|line   .    block   .    sub|Getopt/Long.pm      |
+ |20     |0.00585  |0.00029|line   .    block   .    sub|Fcntl.pm            |
+ |128    |0.00340  |0.00003|line   .    block   .    sub|Exporter/Heavy.pm   |
+ |42     |0.00332  |0.00008|line   .    block   .    sub|IO/File.pm          |
+ |261    |0.00308  |0.00001|line   .    block   .    sub|Exporter.pm         |
+ |323    |0.00248  |8e-06  |line   .    block   .    sub|constant.pm         |
+ |12     |0.00246  |0.00021|line   .    block   .    sub|File/Spec/Unix.pm   |
+ |191    |0.00240  |0.00001|line   .    block   .    sub|vars.pm             |
+ |77     |0.00201  |0.00003|line   .    block   .    sub|FileHandle.pm       |
+ |12     |0.00198  |0.00016|line   .    block   .    sub|Carp.pm             |
+ |14     |0.00175  |0.00013|line   .    block   .    sub|Symbol.pm           |
+ |15     |0.00130  |0.00009|line   .    block   .    sub|IO.pm               |
+ |22     |0.00120  |0.00005|line   .    block   .    sub|IO/Seekable.pm      |
+ |198    |0.00085  |4e-06  |line   .    block   .    sub|warnings/register.pm|
+ |114    |0.00080  |7e-06  |line   .    block   .    sub|strict.pm           |
+ |47     |0.00068  |0.00001|line   .    block   .    sub|warnings.pm         |
+ |27     |0.00054  |0.00002|line   .    block   .    sub|overload.pm         |
+ |9      |0.00047  |0.00005|line   .    block   .    sub|SelectSaver.pm      |
+ |13     |0.00045  |0.00003|line   .    block   .    sub|File/Spec.pm        |
+ |2701595|15.73869 |       |Total                       |
+ |128647 |0.74946  |       |Average                     |
+ |       |0.00201  |0.00003|Median                      |
+ |       |0.00121  |0.00003|Deviation                   |
+
+ Report produced by the NYTProf 2.03 Perl profiler, developed by Tim Bunce and
+ Adam Kaplan.
 
 At this point, if you're using the I<html> report, you can click through the
 various links to bore down into each subroutine and each line of code.  Because
@@ -671,72 +673,72 @@ reports built for each source file, we'll just display a part of the
 corresponding F<wordmatch-line.html> file, sufficient to give an idea of the
 sort of output you can expect from this cool tool.
 
   $> html2text nytprof/wordmatch-line.html
-
   Performance Profile -- -block view-.-line view-.-sub view-
   For wordmatch
   Run on Fri Sep 26 13:46:39 2008
   Reported on Fri Sep 26 13:47:22 2008
-
   File wordmatch
-
-     Subroutines -- ordered by exclusive time
   |Calls |P|F|Inclusive|Exclusive|Subroutine    |
   |      | | |Time     |Time     |              |
   |251215|5|1|13.09263 |10.47692 |main::|matches|
   |260642|2|1|2.71199  |2.71199  |main::|debug  |
   |1     |1|1|0.21404  |0.21404  |main::|report |
   |0     |0|0|0        |0        |main::|BEGIN  |
-
-
   |Line|Stmts.|Exclusive|Avg.   |Code                                           |
   |    |      |Time     |       |                                               |
   |1   |      |         |       |#!/usr/bin/perl                                |
   |2   |      |         |       |                                               |
   |    |      |         |       |use strict;                                    |
   |3   |3     |0.00086  |0.00029|# spent 0.00003s making 1 calls to strict::    |
   |    |      |         |       |import                                         |
   |    |      |         |       |use warnings;                                  |
   |4   |3     |0.01563  |0.00521|# spent 0.00012s making 1 calls to warnings::  |
   |    |      |         |       |import                                         |
   |5   |      |         |       |                                               |
   |6   |      |         |       |=head1 NAME                                    |
   |7   |      |         |       |                                               |
   |8   |      |         |       |filewords - word analysis of input file        |
   <...snip...>
   |62  |1     |0.00445  |0.00445|print report( %count );                        |
   |    |      |         |       |# spent 0.21404s making 1 calls to main::report|
   |63  |      |         |       |                                               |
   |    |      |         |       |# spent 23.56955s (10.47692+2.61571) within    |
   |    |      |         |       |main::matches which was called 251215 times,   |
   |    |      |         |       |avg 0.00005s/call: # 50243 times               |
   |    |      |         |       |(2.12134+0.51939s) at line 57 of wordmatch, avg|
   |    |      |         |       |0.00005s/call # 50243 times (2.17735+0.54550s) |
   |64  |      |         |       |at line 56 of wordmatch, avg 0.00005s/call #   |
   |    |      |         |       |50243 times (2.10992+0.51797s) at line 58 of   |
   |    |      |         |       |wordmatch, avg 0.00005s/call # 50243 times     |
   |    |      |         |       |(2.12696+0.51598s) at line 55 of wordmatch, avg|
   |    |      |         |       |0.00005s/call # 50243 times (1.94134+0.51687s) |
   |    |      |         |       |at line 54 of wordmatch, avg 0.00005s/call     |
   |    |      |         |       |sub matches {                                  |
   <...snip...>
   |102 |      |         |       |                                               |
   |    |      |         |       |# spent 2.71199s within main::debug which was  |
   |    |      |         |       |called 260642 times, avg 0.00001s/call: #      |
   |    |      |         |       |251215 times (2.61571+0s) by main::matches at  |
   |103 |      |         |       |line 74 of wordmatch, avg 0.00001s/call # 9427 |
   |    |      |         |       |times (0.09628+0s) at line 50 of wordmatch, avg|
   |    |      |         |       |0.00001s/call                                  |
   |    |      |         |       |sub debug {                                    |
   |104 |260642|0.58496  |2e-06  |my $message = shift;                           |
   |105 |      |         |       |                                               |
   |106 |260642|1.09917  |4e-06  |if ( $debug ) {                                |
   |107 |      |         |       |print STDERR "DBG: $message\n";                |
   |108 |      |         |       |}                                              |
   |109 |      |         |       |}                                              |
   |110 |      |         |       |                                               |
   |111 |1     |0.01501  |0.01501|exit 0;                                        |
   |112 |      |         |       |                                               |
+ $> html2text nytprof/wordmatch-line.html
+
+ Performance Profile -- -block view-.-line view-.-sub view-
+ For wordmatch
+ Run on Fri Sep 26 13:46:39 2008
+ Reported on Fri Sep 26 13:47:22 2008
+
+ File wordmatch
+
+  Subroutines -- ordered by exclusive time
+ |Calls |P|F|Inclusive|Exclusive|Subroutine    |
+ |      | | |Time     |Time     |              |
+ |251215|5|1|13.09263 |10.47692 |main::|matches|
+ |260642|2|1|2.71199  |2.71199  |main::|debug  |
+ |1     |1|1|0.21404  |0.21404  |main::|report |
+ |0     |0|0|0        |0        |main::|BEGIN  |
+
+
+ |Line|Stmts.|Exclusive|Avg.   |Code                                           |
+ |    |      |Time     |       |                                               |
+ |1   |      |         |       |#!/usr/bin/perl                                |
+ |2   |      |         |       |                                               |
+ |    |      |         |       |use strict;                                    |
+ |3   |3     |0.00086  |0.00029|# spent 0.00003s making 1 calls to strict::    |
+ |    |      |         |       |import                                         |
+ |    |      |         |       |use warnings;                                  |
+ |4   |3     |0.01563  |0.00521|# spent 0.00012s making 1 calls to warnings::  |
+ |    |      |         |       |import                                         |
+ |5   |      |         |       |                                               |
+ |6   |      |         |       |=head1 NAME                                    |
+ |7   |      |         |       |                                               |
+ |8   |      |         |       |filewords - word analysis of input file        |
+ <...snip...>
+ |62  |1     |0.00445  |0.00445|print report( %count );                        |
+ |    |      |         |       |# spent 0.21404s making 1 calls to main::report|
+ |63  |      |         |       |                                               |
+ |    |      |         |       |# spent 23.56955s (10.47692+2.61571) within    |
+ |    |      |         |       |main::matches which was called 251215 times,   |
+ |    |      |         |       |avg 0.00005s/call: # 50243 times               |
+ |    |      |         |       |(2.12134+0.51939s) at line 57 of wordmatch, avg|
+ |    |      |         |       |0.00005s/call # 50243 times (2.17735+0.54550s) |
+ |64  |      |         |       |at line 56 of wordmatch, avg 0.00005s/call #   |
+ |    |      |         |       |50243 times (2.10992+0.51797s) at line 58 of   |
+ |    |      |         |       |wordmatch, avg 0.00005s/call # 50243 times     |
+ |    |      |         |       |(2.12696+0.51598s) at line 55 of wordmatch, avg|
+ |    |      |         |       |0.00005s/call # 50243 times (1.94134+0.51687s) |
+ |    |      |         |       |at line 54 of wordmatch, avg 0.00005s/call     |
+ |    |      |         |       |sub matches {                                  |
+ <...snip...>
+ |102 |      |         |       |                                               |
+ |    |      |         |       |# spent 2.71199s within main::debug which was  |
+ |    |      |         |       |called 260642 times, avg 0.00001s/call: #      |
+ |    |      |         |       |251215 times (2.61571+0s) by main::matches at  |
+ |103 |      |         |       |line 74 of wordmatch, avg 0.00001s/call # 9427 |
+ |    |      |         |       |times (0.09628+0s) at line 50 of wordmatch, avg|
+ |    |      |         |       |0.00001s/call                                  |
+ |    |      |         |       |sub debug {                                    |
+ |104 |260642|0.58496  |2e-06  |my $message = shift;                           |
+ |105 |      |         |       |                                               |
+ |106 |260642|1.09917  |4e-06  |if ( $debug ) {                                |
+ |107 |      |         |       |print STDERR "DBG: $message\n";                |
+ |108 |      |         |       |}                                              |
+ |109 |      |         |       |}                                              |
+ |110 |      |         |       |                                               |
+ |111 |1     |0.01501  |0.01501|exit 0;                                        |
+ |112 |      |         |       |                                               |
 
 Oodles of very useful information in there - this seems to be the way forward.
 
@@ -757,7 +759,7 @@ Firstly, an often overlooked point when sorting large amounts of data, one can
 attempt to reduce the data set to be dealt with and in many cases C<grep()> can
 be quite useful as a simple filter:
 
   @data = sort grep { /$filter/ } @incoming
+ @data = sort grep { /$filter/ } @incoming
 
 A command such as this can vastly reduce the volume of material to actually
 sort through in the first place, and should not be too lightly disregarded
@@ -769,30 +771,30 @@ million lines, is 50M in size, and a snippet of it looks like this:
 
 # logfile
 
   188.209-65-87.adsl-dyn.isp.belgacom.be - - [08/Feb/2007:12:57:16 +0000] "GET /favicon.ico HTTP/1.1" 404 209 "-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
   188.209-65-87.adsl-dyn.isp.belgacom.be - - [08/Feb/2007:12:57:16 +0000] "GET /favicon.ico HTTP/1.1" 404 209 "-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
   151.56.71.198 - - [08/Feb/2007:12:57:41 +0000] "GET /suse-on-vaio.html HTTP/1.1" 200 2858 "http://www.linux-on-laptops.com/sony.html" "Mozilla/5.0 (Windows; U; Windows NT 5.2; en-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1"
   151.56.71.198 - - [08/Feb/2007:12:57:42 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net/suse-on-vaio.html" "Mozilla/5.0 (Windows; U; Windows NT 5.2; en-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1"
   151.56.71.198 - - [08/Feb/2007:12:57:43 +0000] "GET /favicon.ico HTTP/1.1" 404 209 "-" "Mozilla/5.0 (Windows; U; Windows NT 5.2; en-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1"
   217.113.68.60 - - [08/Feb/2007:13:02:15 +0000] "GET / HTTP/1.1" 304 - "-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
   217.113.68.60 - - [08/Feb/2007:13:02:16 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net/" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
   debora.to.isac.cnr.it - - [08/Feb/2007:13:03:58 +0000] "GET /suse-on-vaio.html HTTP/1.1" 200 2858 "http://www.linux-on-laptops.com/sony.html" "Mozilla/5.0 (compatible; Konqueror/3.4; Linux) KHTML/3.4.0 (like Gecko)"
   debora.to.isac.cnr.it - - [08/Feb/2007:13:03:58 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net/suse-on-vaio.html" "Mozilla/5.0 (compatible; Konqueror/3.4; Linux) KHTML/3.4.0 (like Gecko)"
   debora.to.isac.cnr.it - - [08/Feb/2007:13:03:58 +0000] "GET /favicon.ico HTTP/1.1" 404 209 "-" "Mozilla/5.0 (compatible; Konqueror/3.4; Linux) KHTML/3.4.0 (like Gecko)"
   195.24.196.99 - - [08/Feb/2007:13:26:48 +0000] "GET / HTTP/1.0" 200 3309 "-" "Mozilla/5.0 (Windows; U; Windows NT 5.1; fr; rv:1.8.0.9) Gecko/20061206 Firefox/1.5.0.9"
   195.24.196.99 - - [08/Feb/2007:13:26:58 +0000] "GET /data/css HTTP/1.0" 404 206 "http://www.rfi.net/" "Mozilla/5.0 (Windows; U; Windows NT 5.1; fr; rv:1.8.0.9) Gecko/20061206 Firefox/1.5.0.9"
   195.24.196.99 - - [08/Feb/2007:13:26:59 +0000] "GET /favicon.ico HTTP/1.0" 404 209 "-" "Mozilla/5.0 (Windows; U; Windows NT 5.1; fr; rv:1.8.0.9) Gecko/20061206 Firefox/1.5.0.9"
   crawl1.cosmixcorp.com - - [08/Feb/2007:13:27:57 +0000] "GET /robots.txt HTTP/1.0" 200 179 "-" "voyager/1.0"
   crawl1.cosmixcorp.com - - [08/Feb/2007:13:28:25 +0000] "GET /links.html HTTP/1.0" 200 3413 "-" "voyager/1.0"
   fhm226.internetdsl.tpnet.pl - - [08/Feb/2007:13:37:32 +0000] "GET /suse-on-vaio.html HTTP/1.1" 200 2858 "http://www.linux-on-laptops.com/sony.html" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
   fhm226.internetdsl.tpnet.pl - - [08/Feb/2007:13:37:34 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net/suse-on-vaio.html" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
   80.247.140.134 - - [08/Feb/2007:13:57:35 +0000] "GET / HTTP/1.1" 200 3309 "-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.1.4322)"
   80.247.140.134 - - [08/Feb/2007:13:57:37 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.1.4322)"
   pop.compuscan.co.za - - [08/Feb/2007:14:10:43 +0000] "GET / HTTP/1.1" 200 3309 "-" "www.clamav.net"
   livebot-207-46-98-57.search.live.com - - [08/Feb/2007:14:12:04 +0000] "GET /robots.txt HTTP/1.0" 200 179 "-" "msnbot/1.0 (+http://search.msn.com/msnbot.htm)"
   livebot-207-46-98-57.search.live.com - - [08/Feb/2007:14:12:04 +0000] "GET /html/oracle.html HTTP/1.0" 404 214 "-" "msnbot/1.0 (+http://search.msn.com/msnbot.htm)"
   dslb-088-064-005-154.pools.arcor-ip.net - - [08/Feb/2007:14:12:15 +0000] "GET / HTTP/1.1" 200 3309 "-" "www.clamav.net"
   196.201.92.41 - - [08/Feb/2007:14:15:01 +0000] "GET / HTTP/1.1" 200 3309 "-" "MOT-L7/08.B7.DCR MIB/2.2.1 Profile/MIDP-2.0 Configuration/CLDC-1.1"
+ 188.209-65-87.adsl-dyn.isp.belgacom.be - - [08/Feb/2007:12:57:16 +0000] "GET /favicon.ico HTTP/1.1" 404 209 "-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
+ 188.209-65-87.adsl-dyn.isp.belgacom.be - - [08/Feb/2007:12:57:16 +0000] "GET /favicon.ico HTTP/1.1" 404 209 "-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
+ 151.56.71.198 - - [08/Feb/2007:12:57:41 +0000] "GET /suse-on-vaio.html HTTP/1.1" 200 2858 "http://www.linux-on-laptops.com/sony.html" "Mozilla/5.0 (Windows; U; Windows NT 5.2; en-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1"
+ 151.56.71.198 - - [08/Feb/2007:12:57:42 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net/suse-on-vaio.html" "Mozilla/5.0 (Windows; U; Windows NT 5.2; en-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1"
+ 151.56.71.198 - - [08/Feb/2007:12:57:43 +0000] "GET /favicon.ico HTTP/1.1" 404 209 "-" "Mozilla/5.0 (Windows; U; Windows NT 5.2; en-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1"
+ 217.113.68.60 - - [08/Feb/2007:13:02:15 +0000] "GET / HTTP/1.1" 304 - "-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
+ 217.113.68.60 - - [08/Feb/2007:13:02:16 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net/" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
+ debora.to.isac.cnr.it - - [08/Feb/2007:13:03:58 +0000] "GET /suse-on-vaio.html HTTP/1.1" 200 2858 "http://www.linux-on-laptops.com/sony.html" "Mozilla/5.0 (compatible; Konqueror/3.4; Linux) KHTML/3.4.0 (like Gecko)"
+ debora.to.isac.cnr.it - - [08/Feb/2007:13:03:58 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net/suse-on-vaio.html" "Mozilla/5.0 (compatible; Konqueror/3.4; Linux) KHTML/3.4.0 (like Gecko)"
+ debora.to.isac.cnr.it - - [08/Feb/2007:13:03:58 +0000] "GET /favicon.ico HTTP/1.1" 404 209 "-" "Mozilla/5.0 (compatible; Konqueror/3.4; Linux) KHTML/3.4.0 (like Gecko)"
+ 195.24.196.99 - - [08/Feb/2007:13:26:48 +0000] "GET / HTTP/1.0" 200 3309 "-" "Mozilla/5.0 (Windows; U; Windows NT 5.1; fr; rv:1.8.0.9) Gecko/20061206 Firefox/1.5.0.9"
+ 195.24.196.99 - - [08/Feb/2007:13:26:58 +0000] "GET /data/css HTTP/1.0" 404 206 "http://www.rfi.net/" "Mozilla/5.0 (Windows; U; Windows NT 5.1; fr; rv:1.8.0.9) Gecko/20061206 Firefox/1.5.0.9"
+ 195.24.196.99 - - [08/Feb/2007:13:26:59 +0000] "GET /favicon.ico HTTP/1.0" 404 209 "-" "Mozilla/5.0 (Windows; U; Windows NT 5.1; fr; rv:1.8.0.9) Gecko/20061206 Firefox/1.5.0.9"
+ crawl1.cosmixcorp.com - - [08/Feb/2007:13:27:57 +0000] "GET /robots.txt HTTP/1.0" 200 179 "-" "voyager/1.0"
+ crawl1.cosmixcorp.com - - [08/Feb/2007:13:28:25 +0000] "GET /links.html HTTP/1.0" 200 3413 "-" "voyager/1.0"
+ fhm226.internetdsl.tpnet.pl - - [08/Feb/2007:13:37:32 +0000] "GET /suse-on-vaio.html HTTP/1.1" 200 2858 "http://www.linux-on-laptops.com/sony.html" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
+ fhm226.internetdsl.tpnet.pl - - [08/Feb/2007:13:37:34 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net/suse-on-vaio.html" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)"
+ 80.247.140.134 - - [08/Feb/2007:13:57:35 +0000] "GET / HTTP/1.1" 200 3309 "-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.1.4322)"
+ 80.247.140.134 - - [08/Feb/2007:13:57:37 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.1.4322)"
+ pop.compuscan.co.za - - [08/Feb/2007:14:10:43 +0000] "GET / HTTP/1.1" 200 3309 "-" "www.clamav.net"
+ livebot-207-46-98-57.search.live.com - - [08/Feb/2007:14:12:04 +0000] "GET /robots.txt HTTP/1.0" 200 179 "-" "msnbot/1.0 (+http://search.msn.com/msnbot.htm)"
+ livebot-207-46-98-57.search.live.com - - [08/Feb/2007:14:12:04 +0000] "GET /html/oracle.html HTTP/1.0" 404 214 "-" "msnbot/1.0 (+http://search.msn.com/msnbot.htm)"
+ dslb-088-064-005-154.pools.arcor-ip.net - - [08/Feb/2007:14:12:15 +0000] "GET / HTTP/1.1" 200 3309 "-" "www.clamav.net"
+ 196.201.92.41 - - [08/Feb/2007:14:15:01 +0000] "GET / HTTP/1.1" 200 3309 "-" "MOT-L7/08.B7.DCR MIB/2.2.1 Profile/MIDP-2.0 Configuration/CLDC-1.1"
 
 The specific task here is to sort the 286,525 lines of this file by Response
 Code, Query, Browser, Referring Url, and lastly Date.  One solution might be to
@@ -801,69 +803,69 @@ command-line.
 
 # sort-apache-log
 
   #!/usr/bin/perl -n
-
   use strict;
   use warnings;
-
   my @data;
-
   LINE:
   while ( <> ) {
-        my $line = $_;
-        if (
-            $line =~ m/^(
-                ([\w\.\-]+)             # client
-                \s*-\s*-\s*\[
-                ([^]]+)                 # date
-                \]\s*"\w+\s*
-                (\S+)                   # query
-                [^"]+"\s*
-                (\d+)                   # status
-                \s+\S+\s+"[^"]*"\s+"
-                ([^"]*)                 # browser
-                "
-                .*
-            )$/x
-        ) {
-            my @chunks = split(/ +/, $line);
-            my $ip      = $1;
-            my $date    = $2;
-            my $query   = $3;
-            my $status  = $4;
-            my $browser = $5;
-
-            push(@data, [$ip, $date, $query, $status, $browser, $line]);
-        }
   }
-
   my @sorted = sort {
-        $a->[3] cmp $b->[3]
-                ||
-        $a->[2] cmp $b->[2]
-                ||
-        $a->[0] cmp $b->[0]
-                ||
-        $a->[1] cmp $b->[1]
-                ||
-        $a->[4] cmp $b->[4]
   } @data;
-
   foreach my $data ( @sorted ) {
-        print $data->[5];
   }
-
   exit 0;
+ #!/usr/bin/perl -n
+
+ use strict;
+ use warnings;
+
+ my @data;
+
+ LINE:
+ while ( <> ) {
+     my $line = $_;
+     if (
+         $line =~ m/^(
+             ([\w\.\-]+)             # client
+             \s*-\s*-\s*\[
+             ([^]]+)                 # date
+             \]\s*"\w+\s*
+             (\S+)                   # query
+             [^"]+"\s*
+             (\d+)                   # status
+             \s+\S+\s+"[^"]*"\s+"
+             ([^"]*)                 # browser
+             "
+             .*
+         )$/x
+     ) {
+         my @chunks = split(/ +/, $line);
+         my $ip      = $1;
+         my $date    = $2;
+         my $query   = $3;
+         my $status  = $4;
+         my $browser = $5;
+
+         push(@data, [$ip, $date, $query, $status, $browser, $line]);
+     }
+ }
+
+ my @sorted = sort {
+     $a->[3] cmp $b->[3]
+             ||
+     $a->[2] cmp $b->[2]
+             ||
+     $a->[0] cmp $b->[0]
+             ||
+     $a->[1] cmp $b->[1]
+             ||
+     $a->[4] cmp $b->[4]
+ } @data;
+
+ foreach my $data ( @sorted ) {
+     print $data->[5];
+ }
+
+ exit 0;
 
 When running this program, redirect C<STDOUT> so it is possible to check the
 output is correct from following test runs and use the system C<time> utility
 to check the overall runtime.
 
   $> time ./sort-apache-log logfile > out-sort
+ $> time ./sort-apache-log logfile > out-sort
 
   real    0m17.371s
   user    0m15.757s
   sys     0m0.592s
+ real    0m17.371s
+ user    0m15.757s
+ sys     0m0.592s
 
 The program took just over 17 wallclock seconds to run.  Note the different
 values C<time> outputs, it's important to always use the same one, and to not
@@ -896,59 +898,59 @@ input directly as it arrives too.  Otherwise, the code looks fairly similar:
 
 # sort-apache-log-schwarzian
 
   #!/usr/bin/perl -n
-
   use strict;
   use warnings;
-
   print
-
-        map $_->[0] =>
-
-        sort {
-            $a->[4] cmp $b->[4]
-                    ||
-            $a->[3] cmp $b->[3]
-                    ||
-            $a->[1] cmp $b->[1]
-                    ||
-            $a->[2] cmp $b->[2]
-                    ||
-            $a->[5] cmp $b->[5]
-        }
-        map  [ $_, m/^(
-            ([\w\.\-]+)             # client
-            \s*-\s*-\s*\[
-            ([^]]+)                 # date
-            \]\s*"\w+\s*
-            (\S+)                   # query
-            [^"]+"\s*
-            (\d+)                   # status
-            \s+\S+\s+"[^"]*"\s+"
-            ([^"]*)                 # browser
-            "
-            .*
-        )$/xo ]
-
-        => <>;
-
   exit 0;
+ #!/usr/bin/perl -n
+
+ use strict;
+ use warnings;
+
+ print
+
+     map $_->[0] =>
+
+     sort {
+         $a->[4] cmp $b->[4]
+                 ||
+         $a->[3] cmp $b->[3]
+                 ||
+         $a->[1] cmp $b->[1]
+                 ||
+         $a->[2] cmp $b->[2]
+                 ||
+         $a->[5] cmp $b->[5]
+     }
+     map  [ $_, m/^(
+         ([\w\.\-]+)             # client
+         \s*-\s*-\s*\[
+         ([^]]+)                 # date
+         \]\s*"\w+\s*
+         (\S+)                   # query
+         [^"]+"\s*
+         (\d+)                   # status
+         \s+\S+\s+"[^"]*"\s+"
+         ([^"]*)                 # browser
+         "
+         .*
+     )$/xo ]
+
+     => <>;
+
+ exit 0;
 
 Run the new code against the same logfile, as above, to check the new time.
 
   $> time ./sort-apache-log-schwarzian logfile > out-schwarz
+ $> time ./sort-apache-log-schwarzian logfile > out-schwarz
 
   real    0m9.664s
   user    0m8.873s
   sys     0m0.704s
+ real    0m9.664s
+ user    0m8.873s
+ sys     0m0.704s
 
 The time has been cut in half, which is a respectable speed improvement by any
 standard.  Naturally, it is important to check the output is consistent with
 the first program run, this is where the Unix system C<cksum> utility comes in.
 
   $> cksum out-sort out-schwarz
   3044173777 52029194 out-sort
   3044173777 52029194 out-schwarz
+ $> cksum out-sort out-schwarz
+ 3044173777 52029194 out-sort
+ 3044173777 52029194 out-schwarz
 
 BTW. Beware too of pressure from managers who see you speed a program up by 50%
 of the runtime once, only to get a request one month later to do the same again
@@ -965,7 +967,7 @@ any way an issue, this approach is wrong.
 
 A common sight is code which looks something like this:
 
   logger->debug( "A logging message via process-id: $$ INC: " . Dumper(\%INC) )
+ logger->debug( "A logging message via process-id: $$ INC: " . Dumper(\%INC) )
 
 The problem is that this code will always be parsed and executed, even when the
 debug level set in the logging configuration file is zero.  Once the debug()
@@ -975,46 +977,46 @@ the program will continue.  In the example given though, the C<\%INC> hash will
 already have been dumped, and the message string constructed, all of which work
 could be bypassed by a debug variable at the statement level, like this:
 
   logger->debug( "A logging message via process-id: $$ INC: " . Dumper(\%INC) ) if $DEBUG;
+ logger->debug( "A logging message via process-id: $$ INC: " . Dumper(\%INC) ) if $DEBUG;
 
 This effect can be demonstrated by setting up a test script with both forms,
 including a C<debug()> subroutine to emulate typical C<logger()> functionality.
 
 # ifdebug
 
   #!/usr/bin/perl
+ #!/usr/bin/perl
 
   use strict;
   use warnings;
+ use strict;
+ use warnings;
 
   use Benchmark;
   use Data::Dumper;
   my $DEBUG = 0;
+ use Benchmark;
+ use Data::Dumper;
+ my $DEBUG = 0;
 
   sub debug {
-        my $msg = shift;
+ sub debug {
+     my $msg = shift;
 
-        if ( $DEBUG ) {
-            print "DEBUG: $msg\n";
-        }
   };
+     if ( $DEBUG ) {
+         print "DEBUG: $msg\n";
+     }
+ };
 
   timethese(100000, {
-            'debug'       => sub {
-                debug( "A $0 logging message via process-id: $$" . Dumper(\%INC) )
-            },
-            'ifdebug'  => sub {
-                debug( "A $0 logging message via process-id: $$" . Dumper(\%INC) ) if $DEBUG
-            },
   });
+ timethese(100000, {
+         'debug'       => sub {
+             debug( "A $0 logging message via process-id: $$" . Dumper(\%INC) )
+         },
+         'ifdebug'  => sub {
+             debug( "A $0 logging message via process-id: $$" . Dumper(\%INC) ) if $DEBUG
+         },
+ });
 
 Let's see what C<Benchmark> makes of this:
 
   $> perl ifdebug
   Benchmark: timing 100000 iterations of constant, sub...
-       ifdebug:  0 wallclock secs ( 0.01 usr +  0.00 sys =  0.01 CPU) @ 10000000.00/s (n=100000)
-                (warning: too few iterations for a reliable count)
-         debug: 14 wallclock secs (13.18 usr +  0.04 sys = 13.22 CPU) @ 7564.30/s (n=100000)
+ $> perl ifdebug
+ Benchmark: timing 100000 iterations of constant, sub...
+    ifdebug:  0 wallclock secs ( 0.01 usr +  0.00 sys =  0.01 CPU) @ 10000000.00/s (n=100000)
+             (warning: too few iterations for a reliable count)
+      debug: 14 wallclock secs (13.18 usr +  0.04 sys = 13.22 CPU) @ 7564.30/s (n=100000)
 
 In the one case the code, which does exactly the same thing as far as
 outputting any debugging information is concerned, in other words nothing,
@@ -1029,40 +1031,40 @@ time C<DEBUG> constant.
 
 # ifdebug-constant
 
   #!/usr/bin/perl
-
   use strict;
   use warnings;
-
   use Benchmark;
   use Data::Dumper;
   use constant
-        DEBUG => 0
   ;
-
   sub debug {
-        if ( DEBUG ) {
-            my $msg = shift;
-            print "DEBUG: $msg\n";
-        }
   };
-
   timethese(100000, {
-            'debug'       => sub {
-                debug( "A $0 logging message via process-id: $$" . Dumper(\%INC) )
-            },
-            'constant'  => sub {
-                debug( "A $0 logging message via process-id: $$" . Dumper(\%INC) ) if DEBUG
-            },
   });
+ #!/usr/bin/perl
+
+ use strict;
+ use warnings;
+
+ use Benchmark;
+ use Data::Dumper;
+ use constant
+     DEBUG => 0
+ ;
+
+ sub debug {
+     if ( DEBUG ) {
+         my $msg = shift;
+         print "DEBUG: $msg\n";
+     }
+ };
+
+ timethese(100000, {
+         'debug'       => sub {
+             debug( "A $0 logging message via process-id: $$" . Dumper(\%INC) )
+         },
+         'constant'  => sub {
+             debug( "A $0 logging message via process-id: $$" . Dumper(\%INC) ) if DEBUG
+         },
+ });
 
 Running this program produces the following output:
 
   $> perl ifdebug-constant
   Benchmark: timing 100000 iterations of constant, sub...
-      constant:  0 wallclock secs (-0.00 usr +  0.00 sys = -0.00 CPU) @ -7205759403792793600000.00/s (n=100000)
-                (warning: too few iterations for a reliable count)
-           sub: 14 wallclock secs (13.09 usr +  0.00 sys = 13.09 CPU) @ 7639.42/s (n=100000)
+ $> perl ifdebug-constant
+ Benchmark: timing 100000 iterations of constant, sub...
+   constant:  0 wallclock secs (-0.00 usr +  0.00 sys = -0.00 CPU) @ -7205759403792793600000.00/s (n=100000)
+             (warning: too few iterations for a reliable count)
+        sub: 14 wallclock secs (13.09 usr +  0.00 sys = 13.09 CPU) @ 7639.42/s (n=100000)
 
 The C<DEBUG> constant wipes the floor with even the C<$debug> variable,
 clocking in at minus zero seconds, and generates a "warning: too few iterations
@@ -1070,26 +1072,26 @@ for a reliable count" message into the bargain.  To see what is really going
 on, and why we had too few iterations when we thought we asked for 100000, we
 can use the very useful C<B::Deparse> to inspect the new code:
 
   $> perl -MO=Deparse ifdebug-constant
-
   use Benchmark;
   use Data::Dumper;
   use constant ('DEBUG', 0);
   sub debug {
-        use warnings;
-        use strict 'refs';
-        0;
   }
   use warnings;
   use strict 'refs';
   timethese(100000, {'sub', sub {
-        debug "A $0 logging message via process-id: $$" . Dumper(\%INC);
   }
   , 'constant', sub {
-        0;
   }
   });
   ifdebug-constant syntax OK
+ $> perl -MO=Deparse ifdebug-constant
+
+ use Benchmark;
+ use Data::Dumper;
+ use constant ('DEBUG', 0);
+ sub debug {
+     use warnings;
+     use strict 'refs';
+     0;
+ }
+ use warnings;
+ use strict 'refs';
+ timethese(100000, {'sub', sub {
+     debug "A $0 logging message via process-id: $$" . Dumper(\%INC);
+ }
+ , 'constant', sub {
+     0;
+ }
+ });
+ ifdebug-constant syntax OK
 
 The output shows the constant() subroutine we're testing being replaced with
 the value of the C<DEBUG> constant: zero.  The line to be tested has been
@@ -1106,7 +1108,7 @@ principle can be written as: I<useful programs are slow> by their very
 definition.  It is of course possible to write a nearly instantaneous program,
 but it's not going to do very much, here's a very efficient one:
 
   $> perl -e 0
+ $> perl -e 0
 
 Optimizing that any further is a job for C<p5p>.
 
@@ -1134,43 +1136,43 @@ It's not possible to individually showcase all the performance related code for
 Perl here, naturally, but here's a short list of modules from the CPAN which
 deserve further attention.
 
   Apache::DProf
   Apache::SmallProf
   Benchmark
   DBIx::Profile
   Devel::AutoProfiler
   Devel::DProf
   Devel::DProfLB
   Devel::FastProf
   Devel::GraphVizProf
   Devel::NYTProf
   Devel::NYTProf::Apache
   Devel::Profiler
   Devel::Profile
   Devel::Profit
   Devel::SmallProf
   Devel::WxProf
   POE::Devel::Profiler
   Sort::Key
   Sort::Maker
+ Apache::DProf
+ Apache::SmallProf
+ Benchmark
+ DBIx::Profile
+ Devel::AutoProfiler
+ Devel::DProf
+ Devel::DProfLB
+ Devel::FastProf
+ Devel::GraphVizProf
+ Devel::NYTProf
+ Devel::NYTProf::Apache
+ Devel::Profiler
+ Devel::Profile
+ Devel::Profit
+ Devel::SmallProf
+ Devel::WxProf
+ POE::Devel::Profiler
+ Sort::Key
+ Sort::Maker
 
 =head2 URLS
 
 Very useful online reference material:
 
   http://www.ccl4.org/~nick/P/Fast_Enough/
+ http://www.ccl4.org/~nick/P/Fast_Enough/
 
   http://www-128.ibm.com/developerworks/library/l-optperl.html
+ http://www-128.ibm.com/developerworks/library/l-optperl.html
 
   http://perlbuzz.com/2007/11/bind-output-variables-in-dbi-for-speed-and-safety.html
+ http://perlbuzz.com/2007/11/bind-output-variables-in-dbi-for-speed-and-safety.html
 
   http://en.wikipedia.org/wiki/Performance_analysis
+ http://en.wikipedia.org/wiki/Performance_analysis
 
   http://apache.perl.org/docs/1.0/guide/performance.html
+ http://apache.perl.org/docs/1.0/guide/performance.html
 
   http://perlgolf.sourceforge.net/
+ http://perlgolf.sourceforge.net/
 
   http://www.sysarch.com/Perl/sort_paper.html
+ http://www.sysarch.com/Perl/sort_paper.html
 
 =head1 AUTHOR
 
index 82a48f5..502ba42 100644 (file)
@@ -101,7 +101,7 @@ broken.
 
 =item * F<t/cmd/>
 
-Tests for basic control structures, C<if/else>, C<while>, subroutines,
+Tests for basic control structures, C<if>/C<else>, C<while>, subroutines,
 etc.
 
 =item * F<t/comp/>
index de2cc10..4a3e6fd 100644 (file)
@@ -513,9 +513,10 @@ evolving.  The current semantics and interface are subject to change.
 See L<attributes> and L<Attribute::Handlers>.
 
 The C<my> operator declares the listed variables to be lexically
-confined to the enclosing block, conditional (C<if/unless/elsif/else>),
-loop (C<for/foreach/while/until/continue>), subroutine, C<eval>,
-or C<do/require/use>'d file.  If more than one value is listed, the
+confined to the enclosing block, conditional
+(C<if>/C<unless>/C<elsif>/C<else>), loop
+(C<for>/C<foreach>/C<while>/C<until>/C<continue>), subroutine, C<eval>,
+or C<do>/C<require>/C<use>'d file.  If more than one value is listed, the
 list must be placed in parentheses.  All listed elements must be
 legal lvalues.  Only alphanumeric identifiers may be lexically
 scoped--magical built-ins like C<$/> must currently be C<local>ized
index 7954b7a..acb4392 100644 (file)
@@ -170,7 +170,7 @@ C<do { } while> construct.  See L<perlsyn/"Loop Control">.
 
 =item *
 
-The switch statement is called C<given/when> and only available in
+The switch statement is called C<given>/C<when> and only available in
 perl 5.10 or newer.  See L<perlsyn/"Switch Statements">.
 
 =item *
index 0674678..104cf83 100644 (file)
@@ -252,36 +252,26 @@ dist/tie-file/lib/tie/file.pm     Verbatim line length including indents exceeds 79
 ext/devel-peek/peek.pm ? Should you be using L<...> instead of 2
 ext/dynaloader/dynaloader.pm   Verbatim line length including indents exceeds 79 by    1
 ext/file-find/lib/file/find.pm Verbatim line length including indents exceeds 79 by    1
-ext/file-glob/glob.pm  Verbatim line length including indents exceeds 79 by    15
+ext/file-glob/glob.pm  Verbatim line length including indents exceeds 79 by    6
 ext/hash-util-fieldhash/lib/hash/util/fieldhash.pm     Apparent broken link    1
 ext/hash-util/lib/hash/util.pm Verbatim line length including indents exceeds 79 by    2
-ext/pod-html/testdir/perlpodspec-copy.pod      Verbatim line length including indents exceeds 79 by    8
+ext/pod-html/testdir/perlpodspec-copy.pod      Verbatim line length including indents exceeds 79 by    2
 ext/pod-html/testdir/perlvar-copy.pod  ? Should you be using L<...> instead of 3
 ext/pod-html/testdir/perlvar-copy.pod  Verbatim line length including indents exceeds 79 by    6
 ext/posix/lib/posix.pod        ? Should you be using F<...> or maybe L<...> instead of 1
 ext/vms-dclsym/dclsym.pm       ? Should you be using L<...> instead of 1
 ext/vms-filespec/lib/vms/filespec.pm   Verbatim line length including indents exceeds 79 by    1
 install        ? Should you be using F<...> or maybe L<...> instead of 1
-os2/os2/os2-extattr/extattr.pm ? Should you be using F<...> or maybe L<...> instead of 1
-os2/os2/os2-process/process.pm Verbatim line length including indents exceeds 79 by    27
-os2/os2/os2-rexx/dll/dll.pm    Verbatim line length including indents exceeds 79 by    2
-os2/os2/os2-rexx/rexx.pm       Verbatim line length including indents exceeds 79 by    1
 pod/perl.pod   Verbatim line length including indents exceeds 79 by    8
-pod/perlaix.pod        Verbatim line length including indents exceeds 79 by    11
-pod/perlandroid.pod    Verbatim line length including indents exceeds 79 by    2
-pod/perlapio.pod       Verbatim line length including indents exceeds 79 by    5
+pod/perlandroid.pod    Verbatim line length including indents exceeds 79 by    1
 pod/perlbook.pod       Verbatim line length including indents exceeds 79 by    1
 pod/perlcall.pod       Verbatim line length including indents exceeds 79 by    2
 pod/perlce.pod Verbatim line length including indents exceeds 79 by    3
-pod/perlcygwin.pod     Verbatim line length including indents exceeds 79 by    24
-pod/perldebguts.pod    Verbatim line length including indents exceeds 79 by    34
-pod/perldebtut.pod     Verbatim line length including indents exceeds 79 by    22
-pod/perldebug.pod      Verbatim line length including indents exceeds 79 by    3
-pod/perldtrace.pod     Verbatim line length including indents exceeds 79 by    26
-pod/perlfunc.pod       ? Should you be using F<...> or maybe L<...> instead of 1
+pod/perlcygwin.pod     Verbatim line length including indents exceeds 79 by    20
+pod/perldebguts.pod    Verbatim line length including indents exceeds 79 by    27
+pod/perldebtut.pod     Verbatim line length including indents exceeds 79 by    3
+pod/perldtrace.pod     Verbatim line length including indents exceeds 79 by    7
 pod/perlgit.pod        Verbatim line length including indents exceeds 79 by    11
-pod/perlgpl.pod        Verbatim line length including indents exceeds 79 by    50
-pod/perlguts.pod       ? Should you be using F<...> or maybe L<...> instead of 2
 pod/perlguts.pod       ? Should you be using L<...> instead of 1
 pod/perlguts.pod       Verbatim line length including indents exceeds 79 by    1
 pod/perlhack.pod       ? Should you be using L<...> instead of 1
@@ -299,26 +289,21 @@ pod/perlmodstyle.pod      Verbatim line length including indents exceeds 79 by    1
 pod/perlmroapi.pod     ? Should you be using L<...> instead of 1
 pod/perlnetware.pod    Verbatim line length including indents exceeds 79 by    4
 pod/perlnewmod.pod     Verbatim line length including indents exceeds 79 by    1
-pod/perlootut.pod      ? Should you be using F<...> or maybe L<...> instead of 1
 pod/perlos2.pod        ? Should you be using L<...> instead of 2
 pod/perlos2.pod        Verbatim line length including indents exceeds 79 by    21
 pod/perlos390.pod      Verbatim line length including indents exceeds 79 by    11
-pod/perlperf.pod       Verbatim line length including indents exceeds 79 by    154
+pod/perlperf.pod       Verbatim line length including indents exceeds 79 by    122
 pod/perlport.pod       ? Should you be using L<...> instead of 1
 pod/perlrun.pod        Verbatim line length including indents exceeds 79 by    3
 pod/perlsolaris.pod    Verbatim line length including indents exceeds 79 by    14
-pod/perlsource.pod     ? Should you be using F<...> or maybe L<...> instead of 1
-pod/perlsub.pod        ? Should you be using F<...> or maybe L<...> instead of 3
 pod/perlsymbian.pod    Verbatim line length including indents exceeds 79 by    20
 pod/perltie.pod        Verbatim line length including indents exceeds 79 by    13
-pod/perltrap.pod       ? Should you be using F<...> or maybe L<...> instead of 1
-pod/perltru64.pod      ? Should you be using F<...> or maybe L<...> instead of 1
 pod/perltru64.pod      Verbatim line length including indents exceeds 79 by    5
-pod/perlwin32.pod      Verbatim line length including indents exceeds 79 by    12
+pod/perlwin32.pod      Verbatim line length including indents exceeds 79 by    7
 porting/epigraphs.pod  Verbatim line length including indents exceeds 79 by    16
 porting/expand-macro.pl        Verbatim line length including indents exceeds 79 by    2
-porting/release_managers_guide.pod     Verbatim line length including indents exceeds 79 by    7
-porting/todo.pod       Verbatim line length including indents exceeds 79 by    7
+porting/release_managers_guide.pod     Verbatim line length including indents exceeds 79 by    1
+porting/todo.pod       Verbatim line length including indents exceeds 79 by    1
 utils/c2ph     Verbatim line length including indents exceeds 79 by    44
 utils/encguess Apparent broken link    1
 utils/encguess There is no NAME        1