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 for the hash. 71 72=item EXISTS this, key 73 74Verify that I<key> exists with the tied hash I<this>. 75 76The B<Tie::Hash> implementation is a stub that simply croaks. 77 78=item DELETE this, key 79 80Delete the key I<key> from the tied hash I<this>. 81 82=item CLEAR this 83 84Clear all values from the tied hash I<this>. 85 86=back 87 88=head1 CAVEATS 89 90The L<perltie> documentation includes a method called C<DESTROY> as 91a necessary method for tied hashes. Neither B<Tie::Hash> nor B<Tie::StdHash> 92define a default for this method. This is a standard for class packages, 93but may be omitted in favor of a simple default. 94 95=head1 MORE INFORMATION 96 97The packages relating to various DBM-related implementations (F<DB_File>, 98F<NDBM_File>, etc.) show examples of general tied hashes, as does the 99L<Config> module. While these do not utilize B<Tie::Hash>, they serve as 100good working examples. 101 102=cut 103 104use Carp; 105use warnings::register; 106 107sub new { 108 my $pkg = shift; 109 $pkg->TIEHASH(@_); 110} 111 112# Grandfather "new" 113 114sub TIEHASH { 115 my $pkg = shift; 116 if (defined &{"${pkg}::new"}) { 117 warnings::warn "WARNING: calling ${pkg}->new since ${pkg}->TIEHASH is missing" 118 if warnings::enabled(); 119 $pkg->new(@_); 120 } 121 else { 122 croak "$pkg doesn't define a TIEHASH method"; 123 } 124} 125 126sub EXISTS { 127 my $pkg = ref $_[0]; 128 croak "$pkg doesn't define an EXISTS method"; 129} 130 131sub CLEAR { 132 my $self = shift; 133 my $key = $self->FIRSTKEY(@_); 134 my @keys; 135 136 while (defined $key) { 137 push @keys, $key; 138 $key = $self->NEXTKEY(@_, $key); 139 } 140 foreach $key (@keys) { 141 $self->DELETE(@_, $key); 142 } 143} 144 145# The Tie::StdHash package implements standard perl hash behaviour. 146# It exists to act as a base class for classes which only wish to 147# alter some parts of their behaviour. 148 149package Tie::StdHash; 150@ISA = qw(Tie::Hash); 151 152sub TIEHASH { bless {}, $_[0] } 153sub STORE { $_[0]->{$_[1]} = $_[2] } 154sub FETCH { $_[0]->{$_[1]} } 155sub FIRSTKEY { my $a = scalar keys %{$_[0]}; each %{$_[0]} } 156sub NEXTKEY { each %{$_[0]} } 157sub EXISTS { exists $_[0]->{$_[1]} } 158sub DELETE { delete $_[0]->{$_[1]} } 159sub CLEAR { %{$_[0]} = () } 160 1611; 162