lib/FileHandle.t: seeking guidance prior to test revisions

As devoted readers of this list will know, I've been working
my way through the lib/ tree for the purpose of increasing
testing coverage.  Along the way I've been converting .t
files from use of hand-coded 'print ok' statements to use of
Test::More.

That assumes that I understand what the tests are saying
well enough to perform that conversion -- which I
occasionally do not!  In what follows, I've written a
"narrative" of what lib/FileHandle.t appears to be doing in
its last few tests.  If my narrative is not correct, I'd
like to have someone point that out so that I can correctly
convert these tests to Test::More.

#####
print "1..12\n";   # <- line 21
[snip many lines]
# no problem up to here

print "ok 10\n";

if ($^O eq 'dos') # <- line 67
{
     printf("ok %d\n",11);
     exit(0);
}
#####
"If the operating system is DOS, print an 'ok 11' and exit
the test program with a successful status."

But the program *won't* exit successfully if run through a
test harness:

   cd t;./perl -I../lib harness -v ../lib/FileHandle.t;cd -
   [snip]
   Test Summary Report
   -------------------
   ../lib/FileHandle.t (Wstat: 0 Tests: 11 Failed: 0)
     Parse errors: Bad plan.  You planned 12 tests but ran 11.
     Files=1, Tests=11

     Result: FAIL

 From this I infer that no one has attempted to test Perl 5
on 'dos' since March 24, 2003 -- the date the test plan for
this file was last revised.

#####
($rd,$wr) = FileHandle::pipe;   # <- line 73

if ($^O eq 'VMS' || $^O eq 'os2' || $^O eq 'amigaos' || $^O eq 'MSWin32' 
|| $^O eq 'NetWare' ||
     $Config{d_fork} ne 'define') {
   $wr->autoflush;
   $wr->printf("ok %d\n",11);
   print $rd->getline;
}
#####
"Open a pair of connected pipes like the corresponding
system call.  Then conduct a probe to see whether you're on
an operating system which does not support forking or on
which it does not perform in a Unix-like manner.  Flush
anything in the writehandle, then print 'ok 11'.  Then use
the 'getline' function to get the next line from the
readhandle -- much like '$header = <$IN>' -- and print
that."

Is the narrative correct so far?  What makes the
'$wr->printf' print to STDOUT -- if indeed it does?

And if '$rd->getline' is indeed getting the next line, where
is it getting that line from?

(I should note that line 73 above is found in the SYNOPSIS
to lib/FileHandle.pm but is not otherwise documented.)

####
else {
   if (fork) {           # <- line 82
    $wr->close;
    print $rd->getline;
   }
   else {
    $rd->close;
    $wr->printf("ok %d\n",11);
    exit(0);
   }
}
#####
"If you are on an OS that supports forking, call 'fork', and
if the fork is successful, close the writehandle, read the
next line through the readhandle, then print that.  If the
'fork' is unsuccessful, close the readhandle, then print 'ok
11' through the writehandle."

I'm almost sure that narrative is incorrect.  In fact, when
I rig this block up with manual coverage statements ('print
STDERR "XXX\n;', etc.), it appears that *both* the 'if'
and the 'else' blocks are being executed!

And, once again, I wonder where the '$rd->getline' is
getting its line from.

#####
print FileHandle->new('','r') ? "not ok 12\n" : "ok 12\n"; # <- line 93
#####
"Finally, use FileHandle.pm's 'new' method to open a handle
for reading, but don't specify a filename for that handle;
just give it an empty string.  Then, print 'ok 12' through that
readhandle."

Printing through a readhandle?

I've never had to use 'FileHandle::pipe', pipes in general,
or 'fork' in my own code and haven't often encountered
them in code others have written.  So, if anyone can guide
me through this thicket, I will use that guidance to convert
this file to use of Test::More.

Thank you very much.
Jim Keenan

• lib/FileHandle.t: seeking guidance prior to test revisions by James E Keenan
• Re: lib/FileHandle.t: seeking guidance prior to test revisions by ilmari
• Re: lib/FileHandle.t: seeking guidance prior to test revisions by Peter Martini