Debian Codegraph @

upstream/debian-unstable/man3/Tie::Hash.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Tie::Hash 3perl"
58 .TH Tie::Hash 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Tie::Hash, Tie::StdHash, Tie::ExtraHash \- base class definitions for tied hashes
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 2
68 \& package NewHash;
69 \& require Tie::Hash;
70 \&
71 \& @ISA = qw(Tie::Hash);
72 \&
73 \& sub DELETE { ... } # Provides needed method
74 \& sub CLEAR { ... } # Overrides inherited method
75 \&
76 \&
77 \& package NewStdHash;
78 \& require Tie::Hash;
79 \&
80 \& @ISA = qw(Tie::StdHash);
81 \&
82 \& # All methods provided by default, define
83 \& # only those needing overrides
84 \& # Accessors access the storage in %{$_[0]};
85 \& # TIEHASH should return a reference to the actual storage
86 \& sub DELETE { ... }
87 \&
88 \& package NewExtraHash;
89 \& require Tie::Hash;
90 \&
91 \& @ISA = qw(Tie::ExtraHash);
92 \&
93 \& # All methods provided by default, define
94 \& # only those needing overrides
95 \& # Accessors access the storage in %{$_[0][0]};
96 \& # TIEHASH should return an array reference with the first element
97 \& # being the reference to the actual storage
98 \& sub DELETE {
99 \& $_[0][1]\->(\*(Aqdel\*(Aq, $_[0][0], $_[1]); # Call the report writer
100 \& delete $_[0][0]\->{$_[1]}; # $_[0]\->SUPER::DELETE($_[1])
101 \& }
102 \&
103 \&
104 \& package main;
105 \&
106 \& tie %new_hash, \*(AqNewHash\*(Aq;
107 \& tie %new_std_hash, \*(AqNewStdHash\*(Aq;
108 \& tie %new_extra_hash, \*(AqNewExtraHash\*(Aq,
109 \& sub {warn "Doing \eU$_[1]\eE of $_[2].\en"};
110 .Ve
111 .SH DESCRIPTION
112 .IX Header "DESCRIPTION"
113 This module provides some skeletal methods for hash-tying classes. See
114 perltie for a list of the functions required in order to tie a hash
115 to a package. The basic \fBTie::Hash\fR package provides a \f(CW\*(C`new\*(C'\fR method, as well
116 as methods \f(CW\*(C`TIEHASH\*(C'\fR, \f(CW\*(C`EXISTS\*(C'\fR and \f(CW\*(C`CLEAR\*(C'\fR. The \fBTie::StdHash\fR and
117 \&\fBTie::ExtraHash\fR packages
118 provide most methods for hashes described in perltie (the exceptions
119 are \f(CW\*(C`UNTIE\*(C'\fR and \f(CW\*(C`DESTROY\*(C'\fR). They cause tied hashes to behave exactly like standard hashes,
120 and allow for selective overwriting of methods. \fBTie::Hash\fR has legacy support for the
121 \&\f(CW\*(C`new\*(C'\fR method: it is used if \f(CW\*(C`TIEHASH\*(C'\fR is not defined
122 in the case a class forgets to include a \f(CW\*(C`TIEHASH\*(C'\fR method.
123 .PP
124 For developers wishing to write their own tied hashes, the required methods
125 are briefly defined below. See the perltie section for more detailed
126 descriptive, as well as example code:
127 .IP "TIEHASH classname, LIST" 4
128 .IX Item "TIEHASH classname, LIST"
129 The method invoked by the command \f(CW\*(C`tie %hash, classname\*(C'\fR. Associates a new
130 hash instance with the specified class. \f(CW\*(C`LIST\*(C'\fR would represent additional
131 arguments (along the lines of AnyDBM_File and compatriots) needed to
132 complete the association.
133 .IP "STORE this, key, value" 4
134 .IX Item "STORE this, key, value"
135 Store datum \fIvalue\fR into \fIkey\fR for the tied hash \fIthis\fR.
136 .IP "FETCH this, key" 4
137 .IX Item "FETCH this, key"
138 Retrieve the datum in \fIkey\fR for the tied hash \fIthis\fR.
139 .IP "FIRSTKEY this" 4
140 .IX Item "FIRSTKEY this"
141 Return the first key in the hash.
142 .IP "NEXTKEY this, lastkey" 4
143 .IX Item "NEXTKEY this, lastkey"
144 Return the next key in the hash.
145 .IP "EXISTS this, key" 4
146 .IX Item "EXISTS this, key"
147 Verify that \fIkey\fR exists with the tied hash \fIthis\fR.
148 .Sp
149 The \fBTie::Hash\fR implementation is a stub that simply croaks.
150 .IP "DELETE this, key" 4
151 .IX Item "DELETE this, key"
152 Delete the key \fIkey\fR from the tied hash \fIthis\fR.
153 .IP "CLEAR this" 4
154 .IX Item "CLEAR this"
155 Clear all values from the tied hash \fIthis\fR.
156 .IP "SCALAR this" 4
157 .IX Item "SCALAR this"
158 Returns what evaluating the hash in scalar context yields.
159 .Sp
160 \&\fBTie::Hash\fR does not implement this method (but \fBTie::StdHash\fR
161 and \fBTie::ExtraHash\fR do).
162 .SH "Inheriting from \fBTie::StdHash\fP"
163 .IX Header "Inheriting from Tie::StdHash"
164 The accessor methods assume that the actual storage for the data in the tied
165 hash is in the hash referenced by \f(CWtied(%tiedhash)\fR. Thus overwritten
166 \&\f(CW\*(C`TIEHASH\*(C'\fR method should return a hash reference, and the remaining methods
167 should operate on the hash referenced by the first argument:
168 .PP
169 .Vb 2
170 \& package ReportHash;
171 \& our @ISA = \*(AqTie::StdHash\*(Aq;
172 \&
173 \& sub TIEHASH {
174 \& my $storage = bless {}, shift;
175 \& warn "New ReportHash created, stored in $storage.\en";
176 \& $storage
177 \& }
178 \& sub STORE {
179 \& warn "Storing data with key $_[1] at $_[0].\en";
180 \& $_[0]{$_[1]} = $_[2]
181 \& }
182 .Ve
183 .SH "Inheriting from \fBTie::ExtraHash\fP"
184 .IX Header "Inheriting from Tie::ExtraHash"
185 The accessor methods assume that the actual storage for the data in the tied
186 hash is in the hash referenced by \f(CW\*(C`(tied(%tiedhash))\->[0]\*(C'\fR. Thus overwritten
187 \&\f(CW\*(C`TIEHASH\*(C'\fR method should return an array reference with the first
188 element being a hash reference, and the remaining methods should operate on the
189 hash \f(CW\*(C`%{ $_[0]\->[0] }\*(C'\fR:
190 .PP
191 .Vb 2
192 \& package ReportHash;
193 \& our @ISA = \*(AqTie::ExtraHash\*(Aq;
194 \&
195 \& sub TIEHASH {
196 \& my $class = shift;
197 \& my $storage = bless [{}, @_], $class;
198 \& warn "New ReportHash created, stored in $storage.\en";
199 \& $storage;
200 \& }
201 \& sub STORE {
202 \& warn "Storing data with key $_[1] at $_[0].\en";
203 \& $_[0][0]{$_[1]} = $_[2]
204 \& }
205 .Ve
206 .PP
207 The default \f(CW\*(C`TIEHASH\*(C'\fR method stores "extra" arguments to \fBtie()\fR starting
208 from offset 1 in the array referenced by \f(CWtied(%tiedhash)\fR; this is the
209 same storage algorithm as in TIEHASH subroutine above. Hence, a typical
210 package inheriting from \fBTie::ExtraHash\fR does not need to overwrite this
211 method.
212 .ie n .SH """SCALAR"", ""UNTIE"" and ""DESTROY"""
213 .el .SH "\f(CWSCALAR\fP, \f(CWUNTIE\fP and \f(CWDESTROY\fP"
214 .IX Header "SCALAR, UNTIE and DESTROY"
215 The methods \f(CW\*(C`UNTIE\*(C'\fR and \f(CW\*(C`DESTROY\*(C'\fR are not defined in \fBTie::Hash\fR,
216 \&\fBTie::StdHash\fR, or \fBTie::ExtraHash\fR. Tied hashes do not require
217 presence of these methods, but if defined, the methods will be called in
218 proper time, see perltie.
219 .PP
220 \&\f(CW\*(C`SCALAR\*(C'\fR is only defined in \fBTie::StdHash\fR and \fBTie::ExtraHash\fR.
221 .PP
222 If needed, these methods should be defined by the package inheriting from
223 \&\fBTie::Hash\fR, \fBTie::StdHash\fR, or \fBTie::ExtraHash\fR. See "SCALAR" in perltie
224 to find out what happens when \f(CW\*(C`SCALAR\*(C'\fR does not exist.
225 .SH "MORE INFORMATION"
226 .IX Header "MORE INFORMATION"
227 The packages relating to various DBM-related implementations (\fIDB_File\fR,
228 \&\fINDBM_File\fR, etc.) show examples of general tied hashes, as does the
229 Config module. While these do not utilize \fBTie::Hash\fR, they serve as
230 good working examples.