NAME
Tie::Handle - tie arbitrary objects to file handles
See the module "Data::Locations" for an example of how to use this module.
SYNOPSIS
$object->tie('FILEHANDLE');$object->tie($filehandle);print @items;print FILEHANDLE @items;print $filehandle @items;printf $format, @items;printf FILEHANDLE $format, @items;printf $filehandle $format, @items;$item = <>;@list = <>;$item = <FILEHANDLE>;@list = <FILEHANDLE>;$item = <$filehandle>;@list = <$filehandle>;$key = getc();$key = getc(FILEHANDLE);$key = getc($filehandle);$bytes = [sys]read(FILEHANDLE,$buffer,$length[,$offset]);$bytes = [sys]read($filehandle,$buffer,$length[,$offset]);untie *FILEHANDLE;untie *{FILEHANDLE};untie $filehandle;untie *{$filehandle};
DESCRIPTION
This module facilitates the tying of file handles with (arbitrary) objects.
File handles must be given either as symbolic file handles (like "STDOUT", "MYHANDLE" or "MYPACKAGE::MYHANDLE") or as references as returned by the object constructor method "new()" from the "IO::Handle" or "FileHandle" class (either one works).
Your class "Your::Class" needs to:
require Tie::Handle;and to add "Tie::Handle" to the list of classes to inherit from:
@ISA = qw(Exporter Tie::Handle);in order to enable tying of file handles with objects of "Your::Class".
Note that your class "Your::Class" is also responsible for providing (i.e., overloading) the appropriate methods needed to access your objects:
$object->open();This method is invoked on the given object when a file handle is tied to it.
For example you can reset the state information associated with the given object (which is needed in most cases to be able to read item after item with "
$item = <FILEHANDLE>;" from an object) with this method.You can also define a dummy method of this name if nothing needs to be done.
Note that a fatal error will occur ("method not implemented") when you try to tie a file handle to one of your objects if you failed to provide this method.
$object->print(@items);This method is invoked on the given object when the associated file handle is printed to with Perl's built-in "print()" or "printf()" function.
The parameters given to a "print()" statement are simply handed over to the object's "print()" method.
The parameters of a "printf()" statement are first processed using Perl's built-in "sprintf()" function before being handed over to the object's "print()" method.
See the section on "printf()" in perlfunc(1) and printf(3) or sprintf(3) on your system for more information about the "printf()" function.
Note that a fatal error will occur ("method not implemented") when you try to print to a tied file handle if you failed to provide this method.
$item = $object->read();This method is called for the given object when the associated file handle is read from using a statement like "
$item = <FILEHANDLE>;", i.e., when the file handle is read from in SCALAR context.For an explanation of "scalar" versus "array" or "list" context, see the section on "Context" in perldata(1)!
The method should return the next item of data to be read from the given object or "undef" when there is no more data to read.
If no file handle is given explicitly, the statement "
$item = <>;" will read from STDIN (which may or may not be tied to an object).Note that a fatal error will occur ("method not implemented") when you try to read from a tied file handle if you failed to provide this method.
@list = $object->read();This method is called for the given object when the associated file handle is read from using a statement like "
@list = <FILEHANDLE>;", i.e., when the file handle is read from in ARRAY or LIST context.For an explanation of "scalar" versus "array" or "list" context, see the section on "Context" in perldata(1)!
The method should return the contents of the associated object as one (possibly very long) list (starting to read where the last "read()" left off!) or an empty list if there is no more data that can be returned.
If no file handle is given explicitly, the statement "
@list = <>;" will read from STDIN (which may or may not be tied to an object).Note that a fatal error will occur ("method not implemented") when you try to read from a tied file handle if you failed to provide this method.
$key = $object->getchar();This method is called for the given object when the associated file handle is read from using Perl's built-in function "getc()".
The method should return the next character (or byte) from the given object or a null string if there are no more characters to be returned.
See the section on "getc()" in perlfunc(1) for more details.
If no file handle is given explicitly, the statement "
$key = getc();" will read from STDIN (which may or may not be tied to an object).Note that a fatal error will occur ("method not implemented") when you try to read from a tied file handle in this way if you failed to provide this method.
$bytes = $object->blockread($buffer,$length[,$offset]);This method is called for the given object when the associated file handle is read from using Perl's built-in function "read()" or "sysread()".
The method should store the next "$length" characters (or bytes) from the given object in the scalar variable "$buffer", possibly at an offset "$offset" (possibly requiring padding the scalar variable "$buffer" with null characters!), and it should return the number of characters (or bytes) actually read or "undef" if there was an error.
See the section on "read()" and/or "sysread()" in perlfunc(1) for more details.
Note that a fatal error will occur ("method not implemented") when you try to read from a tied file handle in this way if you failed to provide this method.
$object->close();This method is invoked on the given object when the file handle is untied, i.e., when the bond between the file handle and its associated object is dissociated using one of the following alternatives:
untie *FILEHANDLE; untie *{FILEHANDLE}; untie $filehandle; untie *{$filehandle};(depending on wether you are using a symbolic file handle, a file handle object reference or a symbolic file handle stored in a scalar variable!)
For example you can reset the state information associated with the given object (which is needed in most cases to be able to read item after item with "
$item = <FILEHANDLE>;" from an object) with this method.You can also define a dummy method of this name if nothing needs to be done.
Note that a fatal error will occur ("method not implemented") when you try to untie a file handle from its associated object if you failed to provide this method.
See the module "Data::Locations" for an example of how to implement most of these methods.
REMEMBER that you may define the default output file handle using the Perl function "select()" so that any subsequent "print()" or "printf()" statement without an explicit file handle will send output to the chosen default file handle automatically!
See the section on "select()" in perlfunc(1) for more details!
IMPORTANT:
Note that calling the Perl (built-in) functions "open()" and "close()" on a tied file handle has no effect on the object which is tied to it!
(But beware that they attempt to open and close the specified file, respectively, even though this is useless in this case!)
Note also that you will get errors if you try to read from a tied file handle which you opened for output only using "open()", or vice-versa!
Therefore it is best not to use the built-in Perl functions "open()" and "close()" on tied file handles at all.
Instead, if you want to restart reading from the beginning of any given object, rather invoke the corresponding method of your class on it (if it provides one)!
In case your class "Your::Class" provides such a method (let's call it "reset()" here) which allows you to reset the state information associated with every object (needed to be able to read item after item from an object sequentially), then instead of invoking that method directly using:
$object->reset();you can also invoke this method via its associated file handle, like this:
${tied *FILEHANDLE}->reset();
${tied *{FILEHANDLE}}->reset();
${tied *{$filehandle}}->reset();SEE ALSO
Data::Locations(3), Data::Locations::Shell(3), perl(1), perldata(1), perlfunc(1), perlsub(1), perlmod(1), perlref(1), perlobj(1), perlbot(1), perltoot(1), perltie(1), printf(3), sprintf(3).
VERSION
This man page documents "Tie::Handle" version 3.0.
AUTHOR
Steffen Beyer <sb@sdm.de>.
COPYRIGHT
Copyright (c) 1997 by Steffen Beyer. All rights reserved.
LICENSE
This package is free software; you can redistribute and/or modify it under the same terms as Perl itself.