| 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. |