1package Tie::Hash; 2 3=head1 NAME 4 5Tie::Hash, Tie::StdHash - base class definitions for tied hashes 6 7=head1 SYNOPSIS 8 9 package NewHash; 10 require Tie::Hash; 11 12 @ISA = (Tie::Hash); 13 14 sub DELETE { ... } # Provides needed method 15 sub CLEAR { ... } # Overrides inherited method 16 17 18 package NewStdHash; 19 require Tie::Hash; 20 21 @ISA = (Tie::StdHash); 22 23 # All methods provided by default, define only those needing overrides 24 sub DELETE { ... } 25 26 27 package main; 28 29 tie %new_hash, NewHash; 30 tie %new_std_hash, NewStdHash; 31 32=head1 DESCRIPTION 33 34This module provides some skeletal methods for hash-tying classes. See 35L<perltie> for a list of the functions required in order to tie a hash 36to a package. The basic B<Tie::Hash> package provides a C<new> method, as well 37as methods C<TIEHASH>, C<EXISTS> and C<CLEAR>. The B<Tie::StdHash> package 38provides most methods required for hashes in L<perltie>. It inherits from 39B<Tie::Hash>, and causes tied hashes to behave exactly like standard hashes, 40allowing for selective overloading of methods. The C<new> method is provided 41as grandfathering in the case a class forgets to include a C<TIEHASH> method. 42 43For developers wishing to write their own tied hashes, the required methods 44are briefly defined below. See the L<perltie> section for more detailed 45descriptive, as well as example code: 46 47=over 48 49=item TIEHASH classname, LIST 50 51The method invoked by the command C<tie %hash, classname>. Associates a new 52hash instance with the specified class. C<LIST> would represent additional 53arguments (along the lines of L<AnyDBM_File> and compatriots) needed to 54complete the association. 55 56=item STORE this, key, value 57 58Store datum I<value> into I<key> for the tied hash I<this>. 59 60=item FETCH this, key 61 62Retrieve the datum in I<key> for the tied hash I<this>. 63 64=item FIRSTKEY this 65 66Return the (key, value) pair for the first key in the hash. 67 68=item NEXTKEY this, lastkey 69 70Return the next (key, value) pair for the hash. 71 72=item EXISTS this, key 73 74Verify that I<key> exists with the tied hash I<this>. 75 76=item DELETE this, key 77 78Delete the key I<key> from the tied hash I<this>. 79 80=item CLEAR this 81 82Clear all values from the tied hash I<this>. 83 84=back 85 86=head1 CAVEATS 87 88The L<perltie> documentation includes a method called C<DESTROY> as 89a necessary method for tied hashes. Neither B<Tie::Hash> nor B<Tie::StdHash> 90define a default for this method. This is a standard for class packages, 91but may be omitted in favor of a simple default. 92 93=head1 MORE INFORMATION 94 95The packages relating to various DBM-related implemetations (F<DB_File>, 96F<NDBM_File>, etc.) show examples of general tied hashes, as does the 97L<Config> module. While these do not utilize B<Tie::Hash>, they serve as 98good working examples. 99 100=cut 101 102use Carp; 103 104sub new { 105 my $pkg = shift; 106 $pkg->TIEHASH(@_); 107} 108 109# Grandfather "new" 110 111sub TIEHASH { 112 my $pkg = shift; 113 if (defined &{"{$pkg}::new"}) { 114 carp "WARNING: calling ${pkg}->new since ${pkg}->TIEHASH is missing" 115 if $^W; 116 $pkg->new(@_); 117 } 118 else { 119 croak "$pkg doesn't define a TIEHASH method"; 120 } 121} 122 123sub EXISTS { 124 my $pkg = ref $_[0]; 125 croak "$pkg doesn't define an EXISTS method"; 126} 127 128sub CLEAR { 129 my $self = shift; 130 my $key = $self->FIRSTKEY(@_); 131 my @keys; 132 133 while (defined $key) { 134 push @keys, $key; 135 $key = $self->NEXTKEY(@_, $key); 136 } 137 foreach $key (@keys) { 138 $self->DELETE(@_, $key); 139 } 140} 141 142# The Tie::StdHash package implements standard perl hash behaviour. 143# It exists to act as a base class for classes which only wish to 144# alter some parts of their behaviour. 145 146package Tie::StdHash; 147@ISA = qw(Tie::Hash); 148 149sub TIEHASH { bless {}, $_[0] } 150sub STORE { $_[0]->{$_[1]} = $_[2] } 151sub FETCH { $_[0]->{$_[1]} } 152sub FIRSTKEY { my $a = scalar keys %{$_[0]}; each %{$_[0]} } 153sub NEXTKEY { each %{$_[0]} } 154sub EXISTS { exists $_[0]->{$_[1]} } 155sub DELETE { delete $_[0]->{$_[1]} } 156sub CLEAR { %{$_[0]} = () } 157 1581; 159