tie VARIABLE, CLASSNAME, LIST
+ $object = tied VARIABLE
+
untie VARIABLE
=head1 DESCRIPTION
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.)
-
+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.
my $pid = shift || $$; # 0 means me
if ($pid !~ /^\d+$/) {
- carp "Nice::TieScalar got non-numeric pid $pid" if $^W;
+ carp "Nice::Tie::Scalar got non-numeric pid $pid" if $^W;
return undef;
}
unless (kill 0, $pid) { # EPERM or ERSCH, no doubt
- carp "Nice::TieScalar got bad pid $pid: $!" if $^W;
+ carp "Nice::Tie::Scalar got bad pid $pid: $!" if $^W;
return undef;
}
=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: ";
In our example, just to show you that you don't I<really> have to return an
ARRAY reference, we'll choose a HASH reference to represent our object.
A HASH works out well as a generic record type: the C<{BOUND}> field will
-store the maximum bound allowed, and the C<{ARRAY} field will hold the
+store the maximum bound allowed, and the C<{ARRAY}> field will hold the
true ARRAY ref. If someone outside the class tries to dereference the
object returned (doubtless thinking it an ARRAY ref), they'll blow up.
This just goes to show you that you should respect an object's privacy.
=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.
tied variable is garbage collected.
If this seems like a lot, then feel free to merely inherit
-from the standard TieHash module for most of your methods, redefining only
-the interesting ones. See L<TieHash> for details.
+from the standard Tie::Hash module for most of your methods, redefining only
+the interesting ones. See L<Tie::Hash> for details.
Remember that Perl distinguishes between a key not existing in the hash,
and the key existing in the hash but having a corresponding value of
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};
$ob->clobber(1);
$daemon_dots{signature} = "A true daemon\n";
-Where the clobber method is simply:
+Another way to lay hands on a reference to the underlying object is to
+use the tied() function, so they might alternately have set clobber
+using:
+
+ tie %daemon_dots, 'daemon';
+ tied(%daemon_dots)->clobber(1);
+
+The clobber method is simply:
sub clobber {
my $self = shift;
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
sub FIRSTKEY {
carp &whowasi if $DEBUG;
my $self = shift;
- my $a = keys %{$self->{LIST}};
+ my $a = keys %{$self->{LIST}}; # reset each() iterator
each %{$self->{LIST}}
}
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>
projects / p5sagit/p5-mst-13.2.git / blobdiff