Mass Deface
for a list of the functions required in order to tie a hash
to a package. The basic B package provides a C method, as well
as methods C, C and C. The B and
B packages
provide most methods for hashes described in L (the exceptions
are C and C). They cause tied hashes to behave exactly like standard hashes,
and allow for selective overwriting of methods. B grandfathers the
C method: it is used if C is not defined
in the case a class forgets to include a C method.
For developers wishing to write their own tied hashes, the required methods
are briefly defined below. See the L section for more detailed
descriptive, as well as example code:
=over 4
=item TIEHASH classname, LIST
The method invoked by the command C. Associates a new
hash instance with the specified class. C would represent additional
arguments (along the lines of L and compatriots) needed to
complete the association.
=item STORE this, key, value
Store datum I into I for the tied hash I.
=item FETCH this, key
Retrieve the datum in I for the tied hash I.
=item FIRSTKEY this
Return the first key in the hash.
=item NEXTKEY this, lastkey
Return the next key in the hash.
=item EXISTS this, key
Verify that I exists with the tied hash I.
The B implementation is a stub that simply croaks.
=item DELETE this, key
Delete the key I from the tied hash I.
=item CLEAR this
Clear all values from the tied hash I.
=item SCALAR this
Returns what evaluating the hash in scalar context yields.
B does not implement this method (but B
and B do).
=back
=head1 Inheriting from B
The accessor methods assume that the actual storage for the data in the tied
hash is in the hash referenced by C. Thus overwritten
C method should return a hash reference, and the remaining methods
should operate on the hash referenced by the first argument:
package ReportHash;
our @ISA = 'Tie::StdHash';
sub TIEHASH {
my $storage = bless {}, shift;
warn "New ReportHash created, stored in $storage.\n";
$storage
}
sub STORE {
warn "Storing data with key $_[1] at $_[0].\n";
$_[0]{$_[1]} = $_[2]
}
=head1 Inheriting from B
The accessor methods assume that the actual storage for the data in the tied
hash is in the hash referenced by C<(tied(%tiedhash))-E[0]>. Thus overwritten
C method should return an array reference with the first
element being a hash reference, and the remaining methods should operate on the
hash C<< %{ $_[0]->[0] } >>:
package ReportHash;
our @ISA = 'Tie::ExtraHash';
sub TIEHASH {
my $class = shift;
my $storage = bless [{}, @_], $class;
warn "New ReportHash created, stored in $storage.\n";
$storage;
}
sub STORE {
warn "Storing data with key $_[1] at $_[0].\n";
$_[0][0]{$_[1]} = $_[2]
}
The default C method stores "extra" arguments to tie() starting
from offset 1 in the array referenced by C; this is the
same storage algorithm as in TIEHASH subroutine above. Hence, a typical
package inheriting from B does not need to overwrite this
method.
=head1 C, C and C
The methods C and C are not defined in B,
B, or B. Tied hashes do not require
presence of these methods, but if defined, the methods will be called in
proper time, see L.
C is only defined in B and B.
If needed, these methods should be defined by the package inheriting from
B, B, or B. See L
to find out what happens when C does not exist.
=head1 MORE INFORMATION
The packages relating to various DBM-related implementations (F,
F, etc.) show examples of general tied hashes, as does the
L module. While these do not utilize B, they serve as
good working examples.
=cut
use Carp;
use warnings::register;
sub new {
my $pkg = shift;
$pkg->TIEHASH(@_);
}
# Grandfather "new"
sub TIEHASH {
my $pkg = shift;
my $pkg_new = $pkg -> can ('new');
if ($pkg_new and $pkg ne __PACKAGE__) {
my $my_new = __PACKAGE__ -> can ('new');
if ($pkg_new == $my_new) {
#
# Prevent recursion
#
croak "$pkg must define either a TIEHASH() or a new() method";
}
warnings::warnif ("WARNING: calling ${pkg}->new since " .
"${pkg}->TIEHASH is missing");
$pkg -> new (@_);
}
else {
croak "$pkg doesn't define a TIEHASH method";
}
}
sub EXISTS {
my $pkg = ref $_[0];
croak "$pkg doesn't define an EXISTS method";
}
sub CLEAR {
my $self = shift;
my $key = $self->FIRSTKEY(@_);
my @keys;
while (defined $key) {
push @keys, $key;
$key = $self->NEXTKEY(@_, $key);
}
foreach $key (@keys) {
$self->DELETE(@_, $key);
}
}
# The Tie::StdHash package implements standard perl hash behaviour.
# It exists to act as a base class for classes which only wish to
# alter some parts of their behaviour.
package Tie::StdHash;
# @ISA = qw(Tie::Hash); # would inherit new() only
sub TIEHASH { bless {}, $_[0] }
sub STORE { $_[0]->{$_[1]} = $_[2] }
sub FETCH { $_[0]->{$_[1]} }
sub FIRSTKEY { my $a = scalar keys %{$_[0]}; each %{$_[0]} }
sub NEXTKEY { each %{$_[0]} }
sub EXISTS { exists $_[0]->{$_[1]} }
sub DELETE { delete $_[0]->{$_[1]} }
sub CLEAR { %{$_[0]} = () }
sub SCALAR { scalar %{$_[0]} }
package Tie::ExtraHash;
sub TIEHASH { my $p = shift; bless [{}, @_], $p }
sub STORE { $_[0][0]{$_[1]} = $_[2] }
sub FETCH { $_[0][0]{$_[1]} }
sub FIRSTKEY { my $a = scalar keys %{$_[0][0]}; each %{$_[0][0]} }
sub NEXTKEY { each %{$_[0][0]} }
sub EXISTS { exists $_[0][0]->{$_[1]} }
sub DELETE { delete $_[0][0]->{$_[1]} }
sub CLEAR { %{$_[0][0]} = () }
sub SCALAR { scalar %{$_[0][0]} }
1;