1Tie::Hash(3pm) Perl Programmers Reference Guide Tie::Hash(3pm)
2
6 Tie::Hash, Tie::StdHash, Tie::ExtraHash - base class definitions for
7 tied hashes
8
10 package NewHash;
11 require Tie::Hash;
12 @ISA = (Tie::Hash);
14 sub DELETE { ... } # Provides needed method
16 sub CLEAR { ... } # Overrides inherited method
17 package NewStdHash;
19 require Tie::Hash;
20 @ISA = (Tie::StdHash);
22 # All methods provided by default, define only those needing overrides
24 # Accessors access the storage in %{$_[0]};
25 # TIEHASH should return a reference to the actual storage
26 sub DELETE { ... }
27 package NewExtraHash;
29 require Tie::Hash;
30 @ISA = (Tie::ExtraHash);
32 # All methods provided by default, define only those needing overrides
34 # Accessors access the storage in %{$_[0][0]};
35 # TIEHASH should return an array reference with the first element being
36 # the reference to the actual storage
37 sub DELETE {
38 $_[0][1]->('del', $_[0][0], $_[1]); # Call the report writer
39 delete $_[0][0]->{$_[1]}; # $_[0]->SUPER::DELETE($_[1])
40 }
41 package main;
43 tie %new_hash, 'NewHash';
45 tie %new_std_hash, 'NewStdHash';
46 tie %new_extra_hash, 'NewExtraHash',
47 sub {warn "Doing \U$_[1]\E of $_[2].\n"};
48
50 This module provides some skeletal methods for hash-tying classes. See
51 perltie for a list of the functions required in order to tie a hash to
52 a package. The basic Tie::Hash package provides a "new" method, as well
53 as methods "TIEHASH", "EXISTS" and "CLEAR". The Tie::StdHash and
54 Tie::ExtraHash packages provide most methods for hashes described in
55 perltie (the exceptions are "UNTIE" and "DESTROY"). They cause tied
56 hashes to behave exactly like standard hashes, and allow for selective
57 overwriting of methods. Tie::Hash grandfathers the "new" method: it is
58 used if "TIEHASH" is not defined in the case a class forgets to include
59 a "TIEHASH" method.
60 For developers wishing to write their own tied hashes, the required
62 methods are briefly defined below. See the perltie section for more
63 detailed descriptive, as well as example code:
64 TIEHASH classname, LIST
66 The method invoked by the command "tie %hash, classname". Asso‐
67 ciates a new hash instance with the specified class. "LIST" would
68 represent additional arguments (along the lines of AnyDBM_File and
69 compatriots) needed to complete the association.
70 STORE this, key, value
72 Store datum value into key for the tied hash this.
73 FETCH this, key
75 Retrieve the datum in key for the tied hash this.
76 FIRSTKEY this
78 Return the first key in the hash.
79 NEXTKEY this, lastkey
81 Return the next key in the hash.
82 EXISTS this, key
84 Verify that key exists with the tied hash this.
85 The Tie::Hash implementation is a stub that simply croaks.
87 DELETE this, key
89 Delete the key key from the tied hash this.
90 CLEAR this
92 Clear all values from the tied hash this.
93 SCALAR this
95 Returns what evaluating the hash in scalar context yields.
96 Tie::Hash does not implement this method (but Tie::StdHash and
98 Tie::ExtraHash do).
99
101 The accessor methods assume that the actual storage for the data in the
102 tied hash is in the hash referenced by "tied(%tiedhash)". Thus over‐
103 written "TIEHASH" method should return a hash reference, and the
104 remaining methods should operate on the hash referenced by the first
105 argument:
106 package ReportHash;
108 our @ISA = 'Tie::StdHash';
109 sub TIEHASH {
111 my $storage = bless {}, shift;
112 warn "New ReportHash created, stored in $storage.\n";
113 $storage
114 }
115 sub STORE {
116 warn "Storing data with key $_[1] at $_[0].\n";
117 $_[0]{$_[1]} = $_[2]
118 }
119
121 The accessor methods assume that the actual storage for the data in the
122 tied hash is in the hash referenced by "(tied(%tiedhash))->[0]". Thus
123 overwritten "TIEHASH" method should return an array reference with the
124 first element being a hash reference, and the remaining methods should
125 operate on the hash "%{ $_[0]->[0] }":
126 package ReportHash;
128 our @ISA = 'Tie::ExtraHash';
129 sub TIEHASH {
131 my $class = shift;
132 my $storage = bless [{}, @_], $class;
133 warn "New ReportHash created, stored in $storage.\n";
134 $storage;
135 }
136 sub STORE {
137 warn "Storing data with key $_[1] at $_[0].\n";
138 $_[0][0]{$_[1]} = $_[2]
139 }
140 The default "TIEHASH" method stores "extra" arguments to tie() starting
142 from offset 1 in the array referenced by "tied(%tiedhash)"; this is the
143 same storage algorithm as in TIEHASH subroutine above. Hence, a typi‐
144 cal package inheriting from Tie::ExtraHash does not need to overwrite
145 this method.
146
148 The methods "UNTIE" and "DESTROY" are not defined in Tie::Hash,
149 Tie::StdHash, or Tie::ExtraHash. Tied hashes do not require presence
150 of these methods, but if defined, the methods will be called in proper
151 time, see perltie.
152 "SCALAR" is only defined in Tie::StdHash and Tie::ExtraHash.
154 If needed, these methods should be defined by the package inheriting
156 from Tie::Hash, Tie::StdHash, or Tie::ExtraHash. See "SCALAR" in pertie
157 to find out what happens when "SCALAR" does not exist.
158
160 The packages relating to various DBM-related implementations (DB_File,
161 NDBM_File, etc.) show examples of general tied hashes, as does the Con‐
162 fig module. While these do not utilize Tie::Hash, they serve as good
163 working examples.
164perl v5.8.8 2001-09-21 Tie::Hash(3pm)