README for IO::Null
                                        Time-stamp: "2000-09-22 16:00:47 MDT"
[From the POD.]

NAME
     IO::Null -- class for null filehandles

SYNOPSIS
       use IO::Null;
       my $fh = IO::Null->new;
       print $fh "I have nothing to say\n";  # does nothing.
       # or:
       $fh->print("And I'm saying it.\n");   # ditto.
       # or:
       my $old = select($fh);
       print "and that is poetry / as I needed it --John Cage"; # nada!
       select($old);

     Or even:

       tie(*FOO, IO::Null);
       print FOO "Lalalalala!\n";  # does nothing.

DESCRIPTION
     This is a class for null filehandles.

     Calling a constructor of this class always succeeds,
     returning a new null filehandle.

     Writing to any object of this class is always a no-
     operation, and returns true.

     Reading from any object of this class is always no-
     operation, and returns empty-string or empty-list, as
     appropriate.

WHY
     You could say:

       open(NULL, '>/dev/null') || die "WHAAT?! $!";

     and get a null FH that way.  But not everyone is using an OS
     that has a /dev/null

IMPLEMENTATION
     This is a subclass of IO::Handle.  Applicable methods with
     subs that do nothing, and return an appropriate value.

SEE ALSO
     the IO::Handle manpage, the perltie manpage, IO::Scalar

CAVEATS
     * This:

       use IO::Null;
       $^W = 1;  # turn on warnings
       tie(*FOO, IO::Null);
       print FOO "Lalalalala!\n";  # does nothing.
       untie(*FOO);

     has been known to produce this odd warning:

       untie attempted while 3 inner references still exist.

     and I've no idea why.

     * Furthermore, this:

       use IO::Null;
       $^W = 1;
       *FOO = IO::Null->new;
       print FOO "Lalalalala!\n";  # does nothing.
       close(FOO);

     emits these warnings:

       Filehandle main::FOO never opened.
       Close on unopened file <GLOB>.

     ...which are, in fact, true; the FH behind the FOO{IO} was
     never opened on any real filehandle.  (I'd welcome anyone's
     (working) suggestions on how to suppress these warnings.)

     You get the same warnings with:

       use IO::Null;
       $^W = 1;
       my $fh = IO::Null->new;
       print $fh "Lalalalala!\n";  # does nothing.
       close $fh;

     Note that this, however:

       use IO::Null;
       $^W = 1;
       my $fh = IO::Null->new;
       $fh->print("Lalalalala!\n");  # does nothing.
       $fh->close();

     emits no warnings.

     * I don't know if you can successfully untaint a null
     filehandle.

     * This:

       $null_fh->fileno

     will return a defined and nonzero number, but one you're not
     likely to want to use for anything.  See the source.

     * These docs are longer than the source itself.  Read the
     source!

COPYRIGHT
     Copyright (c) 2000 Sean M. Burke. All rights reserved.

     This library is free software; you can redistribute it
     and/or modify it under the same terms as Perl itself.

AUTHOR
     Sean M. Burke sburke@cpan.org

[end POD excerpt]


PREREQUISITES

This suite requires Perl 5; I've only used it under Perl 5.004, so for
anything lower, you're on your own.

IO::Null doesn't use any nonstandard modules.


INSTALLATION

You install IO::Null, as you would install any perl module
library, by running these commands:

   perl Makefile.PL
   make
   make test
   make install

If you want to install a private copy of IO::Null in your home
directory, then you should try to produce the initial Makefile with
something like this command:

  perl Makefile.PL LIB=~/perl

Then you may need something like
  setenv PERLLIB "$HOME/perl"
in your shell initialization file (e.g., ~/.cshrc).


DOCUMENTATION

POD-format documentation is included in Null.pm.  POD is readable
with the 'perldoc' utility.  See ChangeLog for recent changes.


MACPERL INSTALLATION NOTES

Don't bother with the makefiles.  Just make an IO directory in your
MacPerl site_lib or lib directory, and move Null.pm into there.


SUPPORT

Questions, bug reports, useful code bits, and suggestions for
IO::Null should just be sent to me at sburke@cpan.org


AVAILABILITY

The latest version of IO::Null is available from the
Comprehensive Perl Archive Network (CPAN).  Visit
<http://www.perl.com/CPAN/> to find a CPAN site near you.