NAME
    Tie::Handle::ToMemory - Print to or read from a scalar in memory

SYNOPSIS
      use Tie::Handle::ToMemory;
      my $data;

      # new returns a reference to an anonymous filehandle linked to memory
      my $fh = Tie::Handle::ToMemory->new( \$data );
      print $fh "winds up in memory";  # $data eq "winds up in memory"
      my $line = <$fh>;                # $line eq "winds up in memory"

      # tie links a specific handle to memory
      my $tied = tie *FH, 'Tie::Handle::ToMemory', \$data;
      print FH "blessed reference";    # $$tied eq "blessed reference"
      
  # same thing, but using anonymous scalars
      $fh = Tie::Handle::ToMemory->new();
      $tied = tie *FH, 'Tie::Handle::ToMemory';

DESCRIPTION
    As of Perl 5.8, filehandles can be opened to "in memory" files held in
    ordinary scalars. This module provides a similar capability that is
    backwards compatible by using tied filehandles.

    The scalar is treated as a FIFO communication stream. New data printed
    to the handle is appended. Data read from the handle is removed from the
    beginning.

USAGE
    new
         my $data;
         my $fh1 = Tie::Handle::ToMemory->new();
         my $fh2 = Tie::Handle::ToMemory->new( \$data );
         my $fh3 = Tie::Handle::ToMemory->new( $data );
         my $fh3 = Tie::Handle::ToMemory->new( "initial contents" );
         ${tied(*$fh3)} = "new contents"; # access the underlying scalar directly

        Unlike an ordinary constructor, this returns a reference to the
        anonymous tied filehandle, not the underlying tied object. This
        reference can be used directly with print() and similar functions.
        With no argument, this function ties the filehandle to an anonymous
        scalar. If provided with a scalar or scalar reference argument, the
        filehandle prints to and reads from that scalar. If if a string
        literal is provided as an argument, the filehandle is tied to an
        anonymous scalar containing the contents of the string.

    TIEHANDLE classname, LIST
         my $data;
         my $tied1 = tie *FH, 'Tie::Handle::ToMemory', \$data;
         my $tied2 = tie *FH, 'Tie::Handle::ToMemory', $data;
         my $tied3 = tie *FH, 'Tie::Handle::ToMemory', "initial contents";
         $$tied3 = "new contents"; # access the underlying scalar directly

        TIEHANDLE is called when tying to a specific filehandle. Only the
        first argument of the list is used and follows the same rules as
        with "new", above. The blessed object returned is a reference to the
        scalar which holds the underlying data.

    The following tying functions have been implemented. See "perldoc -f
    tie" and "perldoc perltie" for more details.

    WRITE this, scalar, length, offset
    PRINT this, LIST
    PRINTF this, format, LIST
    READ this, scalar, length, offset
    GETC this
    READLINE this
    EOF this
        Returns true if the underlying scalar is empty.

    OPEN this, mode, LIST
        This is a dummy function that always returns true.

    CLOSE this
        This is a dummy function that always returns true.

    FILENO this
        This is a dummy function that always returns true.

    The following functions have not been implemented.

    BINMODE this
    SEEK this, position, whence
    TELL this
    DESTROY this
    UNTIE this

SEE ALSO
    IO::Scalar, IO::String, perltie

INSTALLATION
    The following commands will build, test, and install this module:

     perl Build.PL
     perl Build
     perl Build test
     perl Build install

BUGS
    Please report bugs using the CPAN Request Tracker at
    http://rt.cpan.org/NoAuth/Bugs.html?Dist=Tie-Handle-ToMemory

AUTHOR
    David A Golden <dagolden@cpan.org>

    http://dagolden.com/

COPYRIGHT
    Copyright (c) 2005 by David A Golden

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

    The full text of the license can be found in the LICENSE file included
    with this module.

