1Tie::Hash(3pm)         Perl Programmers Reference Guide         Tie::Hash(3pm)
2
3
4

NAME

6       Tie::Hash, Tie::StdHash, Tie::ExtraHash - base class definitions for
7       tied hashes
8

SYNOPSIS

10           package NewHash;
11           require Tie::Hash;
12
13           @ISA = qw(Tie::Hash);
14
15           sub DELETE { ... }          # Provides needed method
16           sub CLEAR { ... }           # Overrides inherited method
17
18
19           package NewStdHash;
20           require Tie::Hash;
21
22           @ISA = qw(Tie::StdHash);
23
24           # All methods provided by default, define
25           # only those needing overrides
26           # Accessors access the storage in %{$_[0]};
27           # TIEHASH should return a reference to the actual storage
28           sub DELETE { ... }
29
30           package NewExtraHash;
31           require Tie::Hash;
32
33           @ISA = qw(Tie::ExtraHash);
34
35           # All methods provided by default, define
36           # only those needing overrides
37           # Accessors access the storage in %{$_[0][0]};
38           # TIEHASH should return an array reference with the first element
39           # being the reference to the actual storage
40           sub DELETE {
41             $_[0][1]->('del', $_[0][0], $_[1]); # Call the report writer
42             delete $_[0][0]->{$_[1]};           #  $_[0]->SUPER::DELETE($_[1])
43           }
44
45
46           package main;
47
48           tie %new_hash, 'NewHash';
49           tie %new_std_hash, 'NewStdHash';
50           tie %new_extra_hash, 'NewExtraHash',
51               sub {warn "Doing \U$_[1]\E of $_[2].\n"};
52

DESCRIPTION

54       This module provides some skeletal methods for hash-tying classes. See
55       perltie for a list of the functions required in order to tie a hash to
56       a package. The basic Tie::Hash package provides a "new" method, as well
57       as methods "TIEHASH", "EXISTS" and "CLEAR". The Tie::StdHash and
58       Tie::ExtraHash packages provide most methods for hashes described in
59       perltie (the exceptions are "UNTIE" and "DESTROY").  They cause tied
60       hashes to behave exactly like standard hashes, and allow for selective
61       overwriting of methods.  Tie::Hash grandfathers the "new" method: it is
62       used if "TIEHASH" is not defined in the case a class forgets to include
63       a "TIEHASH" method.
64
65       For developers wishing to write their own tied hashes, the required
66       methods are briefly defined below. See the perltie section for more
67       detailed descriptive, as well as example code:
68
69       TIEHASH classname, LIST
70           The method invoked by the command "tie %hash, classname".
71           Associates a new hash instance with the specified class. "LIST"
72           would represent additional arguments (along the lines of
73           AnyDBM_File and compatriots) needed to complete the association.
74
75       STORE this, key, value
76           Store datum value into key for the tied hash this.
77
78       FETCH this, key
79           Retrieve the datum in key for the tied hash this.
80
81       FIRSTKEY this
82           Return the first key in the hash.
83
84       NEXTKEY this, lastkey
85           Return the next key in the hash.
86
87       EXISTS this, key
88           Verify that key exists with the tied hash this.
89
90           The Tie::Hash implementation is a stub that simply croaks.
91
92       DELETE this, key
93           Delete the key key from the tied hash this.
94
95       CLEAR this
96           Clear all values from the tied hash this.
97
98       SCALAR this
99           Returns what evaluating the hash in scalar context yields.
100
101           Tie::Hash does not implement this method (but Tie::StdHash and
102           Tie::ExtraHash do).
103

Inheriting from Tie::StdHash

105       The accessor methods assume that the actual storage for the data in the
106       tied hash is in the hash referenced by "tied(%tiedhash)".  Thus
107       overwritten "TIEHASH" method should return a hash reference, and the
108       remaining methods should operate on the hash referenced by the first
109       argument:
110
111         package ReportHash;
112         our @ISA = 'Tie::StdHash';
113
114         sub TIEHASH  {
115           my $storage = bless {}, shift;
116           warn "New ReportHash created, stored in $storage.\n";
117           $storage
118         }
119         sub STORE    {
120           warn "Storing data with key $_[1] at $_[0].\n";
121           $_[0]{$_[1]} = $_[2]
122         }
123

Inheriting from Tie::ExtraHash

125       The accessor methods assume that the actual storage for the data in the
126       tied hash is in the hash referenced by "(tied(%tiedhash))->[0]".  Thus
127       overwritten "TIEHASH" method should return an array reference with the
128       first element being a hash reference, and the remaining methods should
129       operate on the hash "%{ $_[0]->[0] }":
130
131         package ReportHash;
132         our @ISA = 'Tie::ExtraHash';
133
134         sub TIEHASH  {
135           my $class = shift;
136           my $storage = bless [{}, @_], $class;
137           warn "New ReportHash created, stored in $storage.\n";
138           $storage;
139         }
140         sub STORE    {
141           warn "Storing data with key $_[1] at $_[0].\n";
142           $_[0][0]{$_[1]} = $_[2]
143         }
144
145       The default "TIEHASH" method stores "extra" arguments to tie() starting
146       from offset 1 in the array referenced by "tied(%tiedhash)"; this is the
147       same storage algorithm as in TIEHASH subroutine above.  Hence, a
148       typical package inheriting from Tie::ExtraHash does not need to
149       overwrite this method.
150

"SCALAR", "UNTIE" and "DESTROY"

152       The methods "UNTIE" and "DESTROY" are not defined in Tie::Hash,
153       Tie::StdHash, or Tie::ExtraHash.  Tied hashes do not require presence
154       of these methods, but if defined, the methods will be called in proper
155       time, see perltie.
156
157       "SCALAR" is only defined in Tie::StdHash and Tie::ExtraHash.
158
159       If needed, these methods should be defined by the package inheriting
160       from Tie::Hash, Tie::StdHash, or Tie::ExtraHash. See "SCALAR" in
161       perltie to find out what happens when "SCALAR" does not exist.
162

MORE INFORMATION

164       The packages relating to various DBM-related implementations (DB_File,
165       NDBM_File, etc.) show examples of general tied hashes, as does the
166       Config module. While these do not utilize Tie::Hash, they serve as good
167       working examples.
168
169
170
171perl v5.32.1                      2021-03-31                    Tie::Hash(3pm)
Impressum