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::warnif("WARNING: calling ${pkg}->new since ${pkg}->TIEHASH is missing"); 118 $pkg->new(@_); 119 } 120 else { 121 croak "$pkg doesn't define a TIEHASH method"; 122 } 123} 124 125sub EXISTS { 126 my $pkg = ref $_[0]; 127 croak "$pkg doesn't define an EXISTS method"; 128} 129 130sub CLEAR { 131 my $self = shift; 132 my $key = $self->FIRSTKEY(@_); 133 my @keys; 134 135 while (defined $key) { 136 push @keys, $key; 137 $key = $self->NEXTKEY(@_, $key); 138 } 139 foreach $key (@keys) { 140 $self->DELETE(@_, $key); 141 } 142} 143 144# The Tie::StdHash package implements standard perl hash behaviour. 145# It exists to act as a base class for classes which only wish to 146# alter some parts of their behaviour. 147 148package Tie::StdHash; 149@ISA = qw(Tie::Hash); 150 151sub TIEHASH { bless {}, $_[0] } 152sub STORE { $_[0]->{$_[1]} = $_[2] } 153sub FETCH { $_[0]->{$_[1]} } 154sub FIRSTKEY { my $a = scalar keys %{$_[0]}; each %{$_[0]} } 155sub NEXTKEY { each %{$_[0]} } 156sub EXISTS { exists $_[0]->{$_[1]} } 157sub DELETE { delete $_[0]->{$_[1]} } 158sub CLEAR { %{$_[0]} = () } 159 1601; 161