This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
5.004_56: Patch to Tie::Hash and docs
[perl5.git] / lib / Tie / Hash.pm
CommitLineData
64d0c973 1package Tie::Hash;
cb1a09d0
AD
2
3=head1 NAME
4
64d0c973 5Tie::Hash, Tie::StdHash - base class definitions for tied hashes
cb1a09d0
AD
6
7=head1 SYNOPSIS
8
9 package NewHash;
64d0c973 10 require Tie::Hash;
cb1a09d0 11
64d0c973 12 @ISA = (Tie::Hash);
cb1a09d0
AD
13
14 sub DELETE { ... } # Provides needed method
15 sub CLEAR { ... } # Overrides inherited method
16
17
18 package NewStdHash;
64d0c973 19 require Tie::Hash;
cb1a09d0 20
64d0c973 21 @ISA = (Tie::StdHash);
cb1a09d0
AD
22
23 # All methods provided by default, define only those needing overrides
24 sub DELETE { ... }
25
26
27 package main;
28
c954a603
PP
29 tie %new_hash, 'NewHash';
30 tie %new_std_hash, 'NewStdHash';
cb1a09d0
AD
31
32=head1 DESCRIPTION
33
34This module provides some skeletal methods for hash-tying classes. See
64d0c973
RR
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.
cb1a09d0
AD
42
43For developers wishing to write their own tied hashes, the required methods
64d0c973
RR
44are briefly defined below. See the L<perltie> section for more detailed
45descriptive, as well as example code:
46
47=over
cb1a09d0
AD
48
49=item TIEHASH classname, LIST
50
64d0c973 51The method invoked by the command C<tie %hash, classname>. Associates a new
cb1a09d0
AD
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
64d0c973
RR
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.
cb1a09d0
AD
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
64d0c973 97L<Config> module. While these do not utilize B<Tie::Hash>, they serve as
cb1a09d0
AD
98good working examples.
99
100=cut
a6006777 101
a0d0e21e
LW
102use Carp;
103
104sub new {
4633a7c4
LW
105 my $pkg = shift;
106 $pkg->TIEHASH(@_);
a0d0e21e
LW
107}
108
109# Grandfather "new"
110
111sub TIEHASH {
4633a7c4 112 my $pkg = shift;
cc6b7395 113 if (defined &{"${pkg}::new"}) {
4633a7c4 114 carp "WARNING: calling ${pkg}->new since ${pkg}->TIEHASH is missing"
a0d0e21e 115 if $^W;
4633a7c4 116 $pkg->new(@_);
a0d0e21e
LW
117 }
118 else {
4633a7c4 119 croak "$pkg doesn't define a TIEHASH method";
a0d0e21e
LW
120 }
121}
122
123sub EXISTS {
4633a7c4
LW
124 my $pkg = ref $_[0];
125 croak "$pkg doesn't define an EXISTS method";
a0d0e21e
LW
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
64d0c973 142# The Tie::StdHash package implements standard perl hash behaviour.
748a9306
LW
143# It exists to act as a base class for classes which only wish to
144# alter some parts of their behaviour.
145
64d0c973
RR
146package Tie::StdHash;
147@ISA = qw(Tie::Hash);
748a9306
LW
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
a0d0e21e 1581;