diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/Tie::Hash.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/Tie::Hash.3pm | 230 |
1 files changed, 230 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/Tie::Hash.3pm b/upstream/mageia-cauldron/man3pm/Tie::Hash.3pm new file mode 100644 index 00000000..3cc2d410 --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/Tie::Hash.3pm @@ -0,0 +1,230 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "Tie::Hash 3pm" +.TH Tie::Hash 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +Tie::Hash, Tie::StdHash, Tie::ExtraHash \- base class definitions for tied hashes +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& package NewHash; +\& require Tie::Hash; +\& +\& @ISA = qw(Tie::Hash); +\& +\& sub DELETE { ... } # Provides needed method +\& sub CLEAR { ... } # Overrides inherited method +\& +\& +\& package NewStdHash; +\& require Tie::Hash; +\& +\& @ISA = qw(Tie::StdHash); +\& +\& # All methods provided by default, define +\& # only those needing overrides +\& # Accessors access the storage in %{$_[0]}; +\& # TIEHASH should return a reference to the actual storage +\& sub DELETE { ... } +\& +\& package NewExtraHash; +\& require Tie::Hash; +\& +\& @ISA = qw(Tie::ExtraHash); +\& +\& # All methods provided by default, define +\& # only those needing overrides +\& # Accessors access the storage in %{$_[0][0]}; +\& # TIEHASH should return an array reference with the first element +\& # being the reference to the actual storage +\& sub DELETE { +\& $_[0][1]\->(\*(Aqdel\*(Aq, $_[0][0], $_[1]); # Call the report writer +\& delete $_[0][0]\->{$_[1]}; # $_[0]\->SUPER::DELETE($_[1]) +\& } +\& +\& +\& package main; +\& +\& tie %new_hash, \*(AqNewHash\*(Aq; +\& tie %new_std_hash, \*(AqNewStdHash\*(Aq; +\& tie %new_extra_hash, \*(AqNewExtraHash\*(Aq, +\& sub {warn "Doing \eU$_[1]\eE of $_[2].\en"}; +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This module provides some skeletal methods for hash-tying classes. See +perltie for a list of the functions required in order to tie a hash +to a package. The basic \fBTie::Hash\fR package provides a \f(CW\*(C`new\*(C'\fR method, as well +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 +\&\fBTie::ExtraHash\fR packages +provide most methods for hashes described in perltie (the exceptions +are \f(CW\*(C`UNTIE\*(C'\fR and \f(CW\*(C`DESTROY\*(C'\fR). They cause tied hashes to behave exactly like standard hashes, +and allow for selective overwriting of methods. \fBTie::Hash\fR has legacy support for the +\&\f(CW\*(C`new\*(C'\fR method: it is used if \f(CW\*(C`TIEHASH\*(C'\fR is not defined +in the case a class forgets to include a \f(CW\*(C`TIEHASH\*(C'\fR method. +.PP +For developers wishing to write their own tied hashes, the required methods +are briefly defined below. See the perltie section for more detailed +descriptive, as well as example code: +.IP "TIEHASH classname, LIST" 4 +.IX Item "TIEHASH classname, LIST" +The method invoked by the command \f(CW\*(C`tie %hash, classname\*(C'\fR. Associates a new +hash instance with the specified class. \f(CW\*(C`LIST\*(C'\fR would represent additional +arguments (along the lines of AnyDBM_File and compatriots) needed to +complete the association. +.IP "STORE this, key, value" 4 +.IX Item "STORE this, key, value" +Store datum \fIvalue\fR into \fIkey\fR for the tied hash \fIthis\fR. +.IP "FETCH this, key" 4 +.IX Item "FETCH this, key" +Retrieve the datum in \fIkey\fR for the tied hash \fIthis\fR. +.IP "FIRSTKEY this" 4 +.IX Item "FIRSTKEY this" +Return the first key in the hash. +.IP "NEXTKEY this, lastkey" 4 +.IX Item "NEXTKEY this, lastkey" +Return the next key in the hash. +.IP "EXISTS this, key" 4 +.IX Item "EXISTS this, key" +Verify that \fIkey\fR exists with the tied hash \fIthis\fR. +.Sp +The \fBTie::Hash\fR implementation is a stub that simply croaks. +.IP "DELETE this, key" 4 +.IX Item "DELETE this, key" +Delete the key \fIkey\fR from the tied hash \fIthis\fR. +.IP "CLEAR this" 4 +.IX Item "CLEAR this" +Clear all values from the tied hash \fIthis\fR. +.IP "SCALAR this" 4 +.IX Item "SCALAR this" +Returns what evaluating the hash in scalar context yields. +.Sp +\&\fBTie::Hash\fR does not implement this method (but \fBTie::StdHash\fR +and \fBTie::ExtraHash\fR do). +.SH "Inheriting from \fBTie::StdHash\fP" +.IX Header "Inheriting from Tie::StdHash" +The accessor methods assume that the actual storage for the data in the tied +hash is in the hash referenced by \f(CWtied(%tiedhash)\fR. Thus overwritten +\&\f(CW\*(C`TIEHASH\*(C'\fR method should return a hash reference, and the remaining methods +should operate on the hash referenced by the first argument: +.PP +.Vb 2 +\& package ReportHash; +\& our @ISA = \*(AqTie::StdHash\*(Aq; +\& +\& sub TIEHASH { +\& my $storage = bless {}, shift; +\& warn "New ReportHash created, stored in $storage.\en"; +\& $storage +\& } +\& sub STORE { +\& warn "Storing data with key $_[1] at $_[0].\en"; +\& $_[0]{$_[1]} = $_[2] +\& } +.Ve +.SH "Inheriting from \fBTie::ExtraHash\fP" +.IX Header "Inheriting from Tie::ExtraHash" +The accessor methods assume that the actual storage for the data in the tied +hash is in the hash referenced by \f(CW\*(C`(tied(%tiedhash))\->[0]\*(C'\fR. Thus overwritten +\&\f(CW\*(C`TIEHASH\*(C'\fR method should return an array reference with the first +element being a hash reference, and the remaining methods should operate on the +hash \f(CW\*(C`%{ $_[0]\->[0] }\*(C'\fR: +.PP +.Vb 2 +\& package ReportHash; +\& our @ISA = \*(AqTie::ExtraHash\*(Aq; +\& +\& sub TIEHASH { +\& my $class = shift; +\& my $storage = bless [{}, @_], $class; +\& warn "New ReportHash created, stored in $storage.\en"; +\& $storage; +\& } +\& sub STORE { +\& warn "Storing data with key $_[1] at $_[0].\en"; +\& $_[0][0]{$_[1]} = $_[2] +\& } +.Ve +.PP +The default \f(CW\*(C`TIEHASH\*(C'\fR method stores "extra" arguments to \fBtie()\fR starting +from offset 1 in the array referenced by \f(CWtied(%tiedhash)\fR; this is the +same storage algorithm as in TIEHASH subroutine above. Hence, a typical +package inheriting from \fBTie::ExtraHash\fR does not need to overwrite this +method. +.ie n .SH """SCALAR"", ""UNTIE"" and ""DESTROY""" +.el .SH "\f(CWSCALAR\fP, \f(CWUNTIE\fP and \f(CWDESTROY\fP" +.IX Header "SCALAR, UNTIE and DESTROY" +The methods \f(CW\*(C`UNTIE\*(C'\fR and \f(CW\*(C`DESTROY\*(C'\fR are not defined in \fBTie::Hash\fR, +\&\fBTie::StdHash\fR, or \fBTie::ExtraHash\fR. Tied hashes do not require +presence of these methods, but if defined, the methods will be called in +proper time, see perltie. +.PP +\&\f(CW\*(C`SCALAR\*(C'\fR is only defined in \fBTie::StdHash\fR and \fBTie::ExtraHash\fR. +.PP +If needed, these methods should be defined by the package inheriting from +\&\fBTie::Hash\fR, \fBTie::StdHash\fR, or \fBTie::ExtraHash\fR. See "SCALAR" in perltie +to find out what happens when \f(CW\*(C`SCALAR\*(C'\fR does not exist. +.SH "MORE INFORMATION" +.IX Header "MORE INFORMATION" +The packages relating to various DBM-related implementations (\fIDB_File\fR, +\&\fINDBM_File\fR, etc.) show examples of general tied hashes, as does the +Config module. While these do not utilize \fBTie::Hash\fR, they serve as +good working examples. |