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.