- publishing free software manuals
Perl Language Reference Manual
by Larry Wall and others
Paperback (6"x9"), 724 pages
ISBN 9781906966027
RRP £29.95 ($39.95)

Sales of this book support The Perl Foundation! Get a printed copy>>>

18.4 Tying FileHandles

This is partially implemented now.

A class implementing a tied filehandle should define the following methods: TIEHANDLE, at least one of PRINT, PRINTF, WRITE, READLINE, GETC, READ, and possibly CLOSE, UNTIE and DESTROY. The class can also provide: BINMODE, OPEN, EOF, FILENO, SEEK, TELL - if the corresponding perl operators are used on the handle.

When STDERR is tied, its PRINT method will be called to issue warnings and error messages. This feature is temporarily disabled during the call, which means you can use warn() inside PRINT without starting a recursive loop. And just like __WARN__ and __DIE__ handlers, STDERR's PRINT method may be called to report parser errors, so the caveats mentioned under apply.

All of this is especially useful when perl is embedded in some other program, where output to STDOUT and STDERR may have to be redirected in some special way. See nvi and the Apache module for examples.

In our example we're going to create a shouting handle.

package Shout;
TIEHANDLE classname, LIST
This is the constructor for the class. That means it is expected to return a blessed reference of some sort. The reference can be used to hold some internal information.
sub TIEHANDLE { print "<shout>\n"; my $i; bless \$i, shift }
WRITE this, LIST
This method will be called when the handle is written to via the syswrite function.
sub WRITE {
    $r = shift;
    my($buf,$len,$offset) = @_;
    print "WRITE \$buf=$buf, \$len=$len, \$offset=$offset";
}
PRINT this, LIST
This method will be triggered every time the tied handle is printed to with the print() or say() functions. Beyond its self reference it also expects the list that was passed to the print function.
sub PRINT { $r = shift; $$r++; print join($,,map(uc($_),@_)),$\ }
say() acts just like print() except $\ will be localized to \n so you need do nothing special to handle say() in PRINT().
PRINTF this, LIST
This method will be triggered every time the tied handle is printed to with the printf() function. Beyond its self reference it also expects the format and list that was passed to the printf function.
sub PRINTF {
    shift;
    my $fmt = shift;
    print sprintf($fmt, @_);
}
READ this, LIST
This method will be called when the handle is read from via the read or sysread functions.
sub READ {
    my $self = shift;
    my $bufref = \$_[0];
    my(undef,$len,$offset) = @_;
    print "READ \$buf=$bufref, \$len=$len, \$offset=$offset";
    # add to $$bufref, set $len to number of characters read
    $len;
}
READLINE this
This method will be called when the handle is read from via <HANDLE>. The method should return undef when there is no more data.
sub READLINE { $r = shift; "READLINE called $$r times\n"; }
GETC this
This method will be called when the getc function is called.
sub GETC { print "Don't GETC, Get Perl"; return "a"; }
EOF this
This method will be called when the eof function is called. Starting with Perl 5.12, an additional integer parameter will be passed. It will be zero if eof is called without parameter; 1 if eof is given a filehandle as a parameter, e.g. eof(FH); and 2 in the very special case that the tied filehandle is ARGV and eof is called with an empty parameter list, e.g. eof().
sub EOF { not length $stringbuf }
CLOSE this
This method will be called when the handle is closed via the close function.
sub CLOSE { print "CLOSE called.\n" }
UNTIE this
As with the other types of ties, this method will be called when untie happens. It may be appropriate to "auto CLOSE" when this occurs. See 18.6 below.
DESTROY this
As with the other types of ties, this method will be called when the tied handle is about to be destroyed. This is useful for debugging and possibly cleaning up.
sub DESTROY { print "</shout>\n" }

Here's how to use our little example:

tie(*FOO,'Shout');
print FOO "hello\n";
$a = 4; $b = 6;
print FOO $a, " plus ", $b, " equals ", $a + $b, "\n";
print <FOO>;
ISBN 9781906966027Perl Language Reference ManualSee the print edition