Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Tie::Hash.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Tie::Hash 3pm"
61 .TH Tie::Hash 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Tie::Hash, Tie::StdHash, Tie::ExtraHash \- base class definitions for tied hashes
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 2
71 \& package NewHash;
72 \& require Tie::Hash;
73 \&
74 \& @ISA = qw(Tie::Hash);
75 \&
76 \& sub DELETE { ... } # Provides needed method
77 \& sub CLEAR { ... } # Overrides inherited method
78 \&
79 \&
80 \& package NewStdHash;
81 \& require Tie::Hash;
82 \&
83 \& @ISA = qw(Tie::StdHash);
84 \&
85 \& # All methods provided by default, define
86 \& # only those needing overrides
87 \& # Accessors access the storage in %{$_[0]};
88 \& # TIEHASH should return a reference to the actual storage
89 \& sub DELETE { ... }
90 \&
91 \& package NewExtraHash;
92 \& require Tie::Hash;
93 \&
94 \& @ISA = qw(Tie::ExtraHash);
95 \&
96 \& # All methods provided by default, define
97 \& # only those needing overrides
98 \& # Accessors access the storage in %{$_[0][0]};
99 \& # TIEHASH should return an array reference with the first element
100 \& # being the reference to the actual storage
101 \& sub DELETE {
102 \& $_[0][1]\->(\*(Aqdel\*(Aq, $_[0][0], $_[1]); # Call the report writer
103 \& delete $_[0][0]\->{$_[1]}; # $_[0]\->SUPER::DELETE($_[1])
104 \& }
105 \&
106 \&
107 \& package main;
108 \&
109 \& tie %new_hash, \*(AqNewHash\*(Aq;
110 \& tie %new_std_hash, \*(AqNewStdHash\*(Aq;
111 \& tie %new_extra_hash, \*(AqNewExtraHash\*(Aq,
112 \& sub {warn "Doing \eU$_[1]\eE of $_[2].\en"};
113 .Ve
114 .SH DESCRIPTION
115 .IX Header "DESCRIPTION"
116 This module provides some skeletal methods for hash\-tying classes. See
117 perltie for a list of the functions required in order to tie a hash
118 to a package. The basic \fBTie::Hash\fR package provides a \f(CW\*(C`new\*(C'\fR method, as well
119 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
120 \&\fBTie::ExtraHash\fR packages
121 provide most methods for hashes described in perltie (the exceptions
122 are \f(CW\*(C`UNTIE\*(C'\fR and \f(CW\*(C`DESTROY\*(C'\fR). They cause tied hashes to behave exactly like standard hashes,
123 and allow for selective overwriting of methods. \fBTie::Hash\fR has legacy support for the
124 \&\f(CW\*(C`new\*(C'\fR method: it is used if \f(CW\*(C`TIEHASH\*(C'\fR is not defined
125 in the case a class forgets to include a \f(CW\*(C`TIEHASH\*(C'\fR method.
126 .PP
127 For developers wishing to write their own tied hashes, the required methods
128 are briefly defined below. See the perltie section for more detailed
129 descriptive, as well as example code:
130 .IP "TIEHASH classname, LIST" 4
131 .IX Item "TIEHASH classname, LIST"
132 The method invoked by the command \f(CW\*(C`tie %hash, classname\*(C'\fR. Associates a new
133 hash instance with the specified class. \f(CW\*(C`LIST\*(C'\fR would represent additional
134 arguments (along the lines of AnyDBM_File and compatriots) needed to
135 complete the association.
136 .IP "STORE this, key, value" 4
137 .IX Item "STORE this, key, value"
138 Store datum \fIvalue\fR into \fIkey\fR for the tied hash \fIthis\fR.
139 .IP "FETCH this, key" 4
140 .IX Item "FETCH this, key"
141 Retrieve the datum in \fIkey\fR for the tied hash \fIthis\fR.
142 .IP "FIRSTKEY this" 4
143 .IX Item "FIRSTKEY this"
144 Return the first key in the hash.
145 .IP "NEXTKEY this, lastkey" 4
146 .IX Item "NEXTKEY this, lastkey"
147 Return the next key in the hash.
148 .IP "EXISTS this, key" 4
149 .IX Item "EXISTS this, key"
150 Verify that \fIkey\fR exists with the tied hash \fIthis\fR.
151 .Sp
152 The \fBTie::Hash\fR implementation is a stub that simply croaks.
153 .IP "DELETE this, key" 4
154 .IX Item "DELETE this, key"
155 Delete the key \fIkey\fR from the tied hash \fIthis\fR.
156 .IP "CLEAR this" 4
157 .IX Item "CLEAR this"
158 Clear all values from the tied hash \fIthis\fR.
159 .IP "SCALAR this" 4
160 .IX Item "SCALAR this"
161 Returns what evaluating the hash in scalar context yields.
162 .Sp
163 \&\fBTie::Hash\fR does not implement this method (but \fBTie::StdHash\fR
164 and \fBTie::ExtraHash\fR do).
165 .SH "Inheriting from \fBTie::StdHash\fP"
166 .IX Header "Inheriting from Tie::StdHash"
167 The accessor methods assume that the actual storage for the data in the tied
168 hash is in the hash referenced by \f(CWtied(%tiedhash)\fR. Thus overwritten
169 \&\f(CW\*(C`TIEHASH\*(C'\fR method should return a hash reference, and the remaining methods
170 should operate on the hash referenced by the first argument:
171 .PP
172 .Vb 2
173 \& package ReportHash;
174 \& our @ISA = \*(AqTie::StdHash\*(Aq;
175 \&
176 \& sub TIEHASH {
177 \& my $storage = bless {}, shift;
178 \& warn "New ReportHash created, stored in $storage.\en";
179 \& $storage
180 \& }
181 \& sub STORE {
182 \& warn "Storing data with key $_[1] at $_[0].\en";
183 \& $_[0]{$_[1]} = $_[2]
184 \& }
185 .Ve
186 .SH "Inheriting from \fBTie::ExtraHash\fP"
187 .IX Header "Inheriting from Tie::ExtraHash"
188 The accessor methods assume that the actual storage for the data in the tied
189 hash is in the hash referenced by \f(CW\*(C`(tied(%tiedhash))\->[0]\*(C'\fR. Thus overwritten
190 \&\f(CW\*(C`TIEHASH\*(C'\fR method should return an array reference with the first
191 element being a hash reference, and the remaining methods should operate on the
192 hash \f(CW\*(C`%{ $_[0]\->[0] }\*(C'\fR:
193 .PP
194 .Vb 2
195 \& package ReportHash;
196 \& our @ISA = \*(AqTie::ExtraHash\*(Aq;
197 \&
198 \& sub TIEHASH {
199 \& my $class = shift;
200 \& my $storage = bless [{}, @_], $class;
201 \& warn "New ReportHash created, stored in $storage.\en";
202 \& $storage;
203 \& }
204 \& sub STORE {
205 \& warn "Storing data with key $_[1] at $_[0].\en";
206 \& $_[0][0]{$_[1]} = $_[2]
207 \& }
208 .Ve
209 .PP
210 The default \f(CW\*(C`TIEHASH\*(C'\fR method stores "extra" arguments to \fBtie()\fR starting
211 from offset 1 in the array referenced by \f(CWtied(%tiedhash)\fR; this is the
212 same storage algorithm as in TIEHASH subroutine above. Hence, a typical
213 package inheriting from \fBTie::ExtraHash\fR does not need to overwrite this
214 method.
215 .ie n .SH """SCALAR"", ""UNTIE"" and ""DESTROY"""
216 .el .SH "\f(CWSCALAR\fP, \f(CWUNTIE\fP and \f(CWDESTROY\fP"
217 .IX Header "SCALAR, UNTIE and DESTROY"
218 The methods \f(CW\*(C`UNTIE\*(C'\fR and \f(CW\*(C`DESTROY\*(C'\fR are not defined in \fBTie::Hash\fR,
219 \&\fBTie::StdHash\fR, or \fBTie::ExtraHash\fR. Tied hashes do not require
220 presence of these methods, but if defined, the methods will be called in
221 proper time, see perltie.
222 .PP
223 \&\f(CW\*(C`SCALAR\*(C'\fR is only defined in \fBTie::StdHash\fR and \fBTie::ExtraHash\fR.
224 .PP
225 If needed, these methods should be defined by the package inheriting from
226 \&\fBTie::Hash\fR, \fBTie::StdHash\fR, or \fBTie::ExtraHash\fR. See "SCALAR" in perltie
227 to find out what happens when \f(CW\*(C`SCALAR\*(C'\fR does not exist.
228 .SH "MORE INFORMATION"
229 .IX Header "MORE INFORMATION"
230 The packages relating to various DBM\-related implementations (\fIDB_File\fR,
231 \&\fINDBM_File\fR, etc.) show examples of general tied hashes, as does the
232 Config module. While these do not utilize \fBTie::Hash\fR, they serve as
233 good working examples.