/ 
Tie-Handle-ToMemory-0.10
/ Tie::Handle::ToMemory

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
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

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.

SEE ALSO