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