enchanted. C<CLASSNAME> is the name of a class implementing objects of
the correct type. Any additional arguments in the C<LIST> are passed to
the appropriate constructor method for that class--meaning TIESCALAR(),
-TIEARRAY(), or TIEHASH(). (Typically these are arguments such as might be
-passed to the dbminit() function of C.) The object returned by the "new"
-method is also returned by the tie() function, which would be useful if
-you wanted to access other methods in C<CLASSNAME>. (You don't actually
-have to return a reference to a right "type" (e.g. HASH or C<CLASSNAME>)
-so long as it's a properly blessed object.) You can also retrieve
-a reference to the underlying object using the tied() function.
+TIEARRAY(), TIEHASH() or TIEHANDLE(). (Typically these are arguments
+such as might be passed to the dbminit() function of C.) The object
+returned by the "new" method is also returned by the tie() function,
+which would be useful if you wanted to access other methods in
+C<CLASSNAME>. (You don't actually have to return a reference to a right
+"type" (e.g. HASH or C<CLASSNAME>) so long as it's a properly blessed
+object.) You can also retrieve a reference to the underlying object
+using the tied() function.
Unlike dbmopen(), the tie() function will not C<use> or C<require> a module
for you--you need to do that explicitly yourself.
=item DESTROY this
This method will be triggered when the tied variable needs to be destructed.
-As with other object classes, such a method is seldom ncessary, since Perl
+As with other object classes, such a method is seldom necessary, since Perl
deallocates its moribund object's memory for you automatically--this isn't
C++, you know. We'll use a DESTROY method here for debugging purposes only.
aggregate assignment would be missed.) For example:
require Bounded_Array;
- tie @ary, Bounded_Array, 2;
+ tie @ary, 'Bounded_Array', 2;
$| = 1;
for $i (0 .. 10) {
print "setting index $i: ";
=item DESTROY this
This method will be triggered when the tied variable needs to be destructed.
-As with the sclar tie class, this is almost never needed in a
+As with the scalar tie class, this is almost never needed in a
language that does its own garbage collection, so this time we'll
just leave it out.
contents. For example:
use DotFiles;
- tie %dot, DotFiles;
+ tie %dot, 'DotFiles';
if ( $dot{profile} =~ /MANPATH/ ||
$dot{login} =~ /MANPATH/ ||
$dot{cshrc} =~ /MANPATH/ )
Or here's another sample of using our tied class:
- tie %him, DotFiles, 'daemon';
+ tie %him, 'DotFiles', 'daemon';
foreach $f ( keys %him ) {
printf "daemon dot file %s is size %d\n",
$f, length $him{$f};
croak "@{[&whowasi]}: won't remove file $file"
unless $self->{CLOBBER};
delete $self->{LIST}->{$dot};
- unlink($file) || carp "@{[&whowasi]}: can't unlink $file: $!";
+ my $success = unlink($file);
+ carp "@{[&whowasi]}: can't unlink $file: $!" unless $success;
+ $success;
}
+The value returned by DELETE becomes the return value of the call
+to delete(). If you want to emulate the normal behavior of delete(),
+you should return whatever FETCH would have returned for this key.
+In this example, we have chosen instead to return a value which tells
+the caller whether the file was successfully deleted.
+
=item CLEAR this
This method is triggered when the whole hash is to be cleared, usually by
useful if you're carrying about ordering or calling the iterator from more
than one sequence, or not really storing things in a hash anywhere.
-For our example, we our using a real hash so we'll just do the simple
+For our example, we're using a real hash so we'll just do the simple
thing, but we'll have to indirect through the LIST field.
sub NEXTKEY {
# print out history file offsets
use NDBM_File;
- tie(%HIST, NDBM_File, '/usr/lib/news/history', 1, 0);
+ tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
while (($key,$val) = each %HIST) {
print $key, ' = ', unpack('L',$val), "\n";
}
=head2 Tying FileHandles
-This isn't implemented yet. Sorry; maybe someday.
+This is partially implemented now.
+
+A class implementing a tied filehandle should define the following methods:
+TIEHANDLE, PRINT and/or READLINE, and possibly DESTROY.
+
+It 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;
+
+=over
+
+=item 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. We won't use it in out example.
+
+ sub TIEHANDLE { print "<shout>\n"; my $i; bless \$i, shift }
+
+=item PRINT this, LIST
+
+This method will be triggered every time the tied handle is printed to.
+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($_),@_)),$\ }
+
+=item READLINE this
+
+This method will be called when the handle is read from. The method
+should return undef when there is no more data.
+
+ sub READLINE { $r = shift; "PRINT called $$r times\n"; }
+
+=item 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" }
+
+=back
+
+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>;
=head1 SEE ALSO
=head1 AUTHOR
Tom Christiansen
+
+TIEHANDLE by Sven Verdoolaege E<lt>F<skimo@dns.ufsia.ac.be>E<gt>