=head1 NAME
+X<tie>
perltie - how to hide an object class in a simple variable
for you--you need to do that explicitly yourself.
=head2 Tying Scalars
+X<scalar, tying>
A class implementing a tied scalar should define the following methods:
TIESCALAR, FETCH, STORE, and possibly UNTIE and/or DESTROY.
=over 4
=item TIESCALAR classname, LIST
+X<TIESCALAR>
This is the constructor for the class. That means it is
expected to return a blessed reference to a new scalar
variable C<$^W> to see whether to emit a bit of noise anyway.
=item FETCH this
+X<FETCH>
This method will be triggered every time the tied variable is accessed
(read). It takes no arguments beyond its self reference, which is the
probably the right thing to do.
=item STORE this, value
+X<STORE>
This method will be triggered every time the tied variable is set
(assigned). Beyond its self reference, it also expects one (and only one)
}
=item UNTIE this
+X<UNTIE>
This method will be triggered when the C<untie> occurs. This can be useful
if the class needs to know when no further calls will be made. (Except DESTROY
of course.) See L<The C<untie> Gotcha> below for more details.
=item DESTROY this
+X<DESTROY>
This method will be triggered when the tied variable needs to be destructed.
As with other object classes, such a method is seldom necessary, because Perl
TIESCALAR classes are certainly possible.
=head2 Tying Arrays
+X<array, tying>
A class implementing a tied ordinary array should define the following
methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE and perhaps UNTIE and/or DESTROY.
=over 4
=item TIEARRAY classname, LIST
+X<TIEARRAY>
This is the constructor for the class. That means it is expected to
return a blessed reference through which the new array (probably an
}
=item FETCH this, index
+X<FETCH>
This method will be triggered every time an individual element the tied array
is accessed (read). It takes one argument beyond its self reference: the
to keep them at simply one tie type per class.
=item STORE this, index, value
+X<STORE>
This method will be triggered every time an element in the tied array is set
(written). It takes two arguments beyond its self reference: the index at
Negative indexes are treated the same as with FETCH.
=item FETCHSIZE this
+X<FETCHSIZE>
Returns the total number of items in the tied array associated with
object I<this>. (Equivalent to C<scalar(@array)>). For example:
}
=item STORESIZE this, count
+X<STORESIZE>
Sets the total number of items in the tied array associated with
object I<this> to be I<count>. If this makes the array larger then
}
=item EXTEND this, count
+X<EXTEND>
Informative call that array is likely to grow to have I<count> entries.
Can be used to optimize allocation. This method need do nothing.
}
=item EXISTS this, key
+X<EXISTS>
Verify that the element at index I<key> exists in the tied array I<this>.
}
=item DELETE this, key
+X<DELETE>
Delete the element at index I<key> from the tied array I<this>.
}
=item CLEAR this
+X<CLEAR>
Clear (remove, delete, ...) all values from the tied array associated with
object I<this>. For example:
}
=item PUSH this, LIST
+X<PUSH>
Append elements of I<LIST> to the array. For example:
}
=item POP this
+X<POP>
Remove last element of the array and return it. For example:
}
=item SHIFT this
+X<SHIFT>
Remove the first element of the array (shifting other elements down)
and return it. For example:
}
=item UNSHIFT this, LIST
+X<UNSHIFT>
Insert LIST elements at the beginning of the array, moving existing elements
up to make room. For example:
}
=item SPLICE this, offset, length, LIST
+X<SPLICE>
Perform the equivalent of C<splice> on the array.
}
=item UNTIE this
+X<UNTIE>
Will be called when C<untie> happens. (See L<The C<untie> Gotcha> below.)
=item DESTROY this
+X<DESTROY>
This method will be triggered when the tied variable needs to be destructed.
As with the scalar tie class, this is almost never needed in a
=back
=head2 Tying Hashes
+X<hash, tying>
Hashes were the first Perl data type to be tied (see dbmopen()). A class
implementing a tied hash should define the following methods: TIEHASH is
=over 4
=item TIEHASH classname, LIST
+X<TIEHASH>
This is the constructor for the class. That means it is expected to
return a blessed reference through which the new object (probably but not
have been testing the wrong file.
=item FETCH this, key
+X<FETCH>
This method will be triggered every time an element in the tied hash is
accessed (read). It takes one argument beyond its self reference: the key
not that concerned.
=item STORE this, key, value
+X<STORE>
This method will be triggered every time an element in the tied hash is set
(written). It takes two arguments beyond its self reference: the index at
}
=item DELETE this, key
+X<DELETE>
This method is triggered when we remove an element from the hash,
typically by using the delete() function. Again, we'll
the caller whether the file was successfully deleted.
=item CLEAR this
+X<CLEAR>
This method is triggered when the whole hash is to be cleared, usually by
assigning the empty list to it.
}
=item EXISTS this, key
+X<EXISTS>
This method is triggered when the user uses the exists() function
on a particular hash. In our example, we'll look at the C<{LIST}>
}
=item FIRSTKEY this
+X<FIRSTKEY>
This method will be triggered when the user is going
to iterate through the hash, such as via a keys() or each()
}
=item NEXTKEY this, lastkey
+X<NEXTKEY>
This method gets triggered during a keys() or each() iteration. It has a
second argument which is the last key that had been accessed. This is
}
=item SCALAR this
+X<SCALAR>
This is called when the hash is evaluated in scalar context. In order
to mimic the behaviour of untied hashes, this method should return a
}
=item UNTIE this
+X<UNTIE>
This is called when C<untie> occurs. See L<The C<untie> Gotcha> below.
=item DESTROY this
+X<DESTROY>
This method is triggered when a tied hash is about to go out of
scope. You don't really need it unless you're trying to add debugging
untie(%HIST);
=head2 Tying FileHandles
+X<filehandle, tying>
This is partially implemented now.
=over 4
=item TIEHANDLE classname, LIST
+X<TIEHANDLE>
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
sub TIEHANDLE { print "<shout>\n"; my $i; bless \$i, shift }
=item WRITE this, LIST
+X<WRITE>
This method will be called when the handle is written to via the
C<syswrite> function.
}
=item PRINT this, LIST
+X<PRINT>
This method will be triggered every time the tied handle is printed to
-with the C<print()> function.
-Beyond its self reference it also expects the list that was passed to
-the print function.
+with the C<print()> or C<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($_),@_)),$\ }
+C<say()> acts just like C<print()> except $\ will be localized to C<\n> so
+you need do nothing special to handle C<say()> in C<PRINT()>.
+
=item PRINTF this, LIST
+X<PRINTF>
This method will be triggered every time the tied handle is printed to
with the C<printf()> function.
}
=item READ this, LIST
+X<READ>
This method will be called when the handle is read from via the C<read>
or C<sysread> functions.
}
=item READLINE this
+X<READLINE>
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"; }
=item GETC this
+X<GETC>
This method will be called when the C<getc> function is called.
sub GETC { print "Don't GETC, Get Perl"; return "a"; }
+=item EOF this
+X<EOF>
+
+This method will be called when the C<eof> function is called.
+
+Starting with Perl 5.12, an additional integer parameter will be passed. It
+will be zero if C<eof> is called without parameter; C<1> if C<eof> is given
+a filehandle as a parameter, e.g. C<eof(FH)>; and C<2> in the very special
+case that the tied filehandle is C<ARGV> and C<eof> is called with an empty
+parameter list, e.g. C<eof()>.
+
+ sub EOF { not length $stringbuf }
+
=item CLOSE this
+X<CLOSE>
This method will be called when the handle is closed via the C<close>
function.
sub CLOSE { print "CLOSE called.\n" }
=item UNTIE this
+X<UNTIE>
As with the other types of ties, this method will be called when C<untie> happens.
It may be appropriate to "auto CLOSE" when this occurs. See
L<The C<untie> Gotcha> below.
=item DESTROY this
+X<DESTROY>
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
print <FOO>;
=head2 UNTIE this
+X<UNTIE>
You can define for all tie types an UNTIE method that will be called
at untie(). See L<The C<untie> Gotcha> below.
=head2 The C<untie> Gotcha
+X<untie>
If you intend making use of the object returned from either tie() or
tied(), and if the tie's target class defines a destructor, there is a
sub TIESCALAR {
my $class = shift;
my $filename = shift;
- my $handle = new IO::File "> $filename"
+ my $handle = IO::File->new( "> $filename" )
or die "Cannot open $filename: $!\n";
print $handle "The Start\n";
You cannot easily tie a multilevel data structure (such as a hash of
hashes) to a dbm file. The first problem is that all but GDBM and
Berkeley DB have size limitations, but beyond that, you also have problems
-with how references are to be represented on disk. One experimental
-module that does attempt to address this need partially is the MLDBM
-module. Check your nearest CPAN site as described in L<perlmodlib> for
-source code to MLDBM.
+with how references are to be represented on disk. One
+module that does attempt to address this need is DBM::Deep. Check your
+nearest CPAN site as described in L<perlmodlib> for source code. Note
+that despite its name, DBM::Deep does not use dbm. Another earlier attempt
+at solving the problem is MLDBM, which is also available on the CPAN, but
+which has some fairly serious limitations.
Tied filehandles are still incomplete. sysopen(), truncate(),
flock(), fcntl(), stat() and -X can't currently be trapped.
https://perl5.git.perl.org / perl5.git / blobdiff