Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Tie::Memoize.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::Memoize 3pm"
61 .TH Tie::Memoize 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::Memoize \- add data to hash when needed
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 5
71 \& require Tie::Memoize;
72 \& tie %hash, \*(AqTie::Memoize\*(Aq,
73 \& \e&fetch, # The rest is optional
74 \& $DATA, \e&exists,
75 \& {%ini_value}, {%ini_existence};
76 .Ve
77 .SH DESCRIPTION
78 .IX Header "DESCRIPTION"
79 This package allows a tied hash to autoload its values on the first access,
80 and to use the cached value on the following accesses.
81 .PP
82 Only read\-accesses (via fetching the value or \f(CW\*(C`exists\*(C'\fR) result in calls to
83 the functions; the modify\-accesses are performed as on a normal hash.
84 .PP
85 The required arguments during \f(CW\*(C`tie\*(C'\fR are the hash, the package, and
86 the reference to the \f(CW\*(C`FETCH\*(C'\fRing function. The optional arguments are
87 an arbitrary scalar \f(CW$data\fR, the reference to the \f(CW\*(C`EXISTS\*(C'\fR function,
88 and initial values of the hash and of the existence cache.
89 .PP
90 Both the \f(CW\*(C`FETCH\*(C'\fRing function and the \f(CW\*(C`EXISTS\*(C'\fR functions have the
91 same signature: the arguments are \f(CW\*(C`$key, $data\*(C'\fR; \f(CW$data\fR is the same
92 value as given as argument during \fBtie()\fRing. Both functions should
93 return an empty list if the value does not exist. If \f(CW\*(C`EXISTS\*(C'\fR
94 function is different from the \f(CW\*(C`FETCH\*(C'\fRing function, it should return
95 a TRUE value on success. The \f(CW\*(C`FETCH\*(C'\fRing function should return the
96 intended value if the key is valid.
97 .SH "Inheriting from \fBTie::Memoize\fP"
98 .IX Header "Inheriting from Tie::Memoize"
99 The structure of the \fBtied()\fR data is an array reference with elements
100 .PP
101 .Vb 5
102 \& 0: cache of known values
103 \& 1: cache of known existence of keys
104 \& 2: FETCH function
105 \& 3: EXISTS function
106 \& 4: $data
107 .Ve
108 .PP
109 The rest is for internal usage of this package. In particular, if
110 TIEHASH is overwritten, it should call SUPER::TIEHASH.
111 .SH EXAMPLE
112 .IX Header "EXAMPLE"
113 .Vb 6
114 \& sub slurp {
115 \& my ($key, $dir) = shift;
116 \& open my $h, \*(Aq<\*(Aq, "$dir/$key" or return;
117 \& local $/; <$h> # slurp it all
118 \& }
119 \& sub exists { my ($key, $dir) = shift; return \-f "$dir/$key" }
120 \&
121 \& tie %hash, \*(AqTie::Memoize\*(Aq, \e&slurp, $directory, \e&exists,
122 \& { fake_file1 => $content1, fake_file2 => $content2 },
123 \& { pretend_does_not_exists => 0, known_to_exist => 1 };
124 .Ve
125 .PP
126 This example treats the slightly modified contents of \f(CW$directory\fR as a
127 hash. The modifications are that the keys \fIfake_file1\fR and
128 \&\fIfake_file2\fR fetch values \f(CW$content1\fR and \f(CW$content2\fR, and
129 \&\fIpretend_does_not_exists\fR will never be accessed. Additionally, the
130 existence of \fIknown_to_exist\fR is never checked (so if it does not
131 exists when its content is needed, the user of \f(CW%hash\fR may be confused).
132 .SH BUGS
133 .IX Header "BUGS"
134 FIRSTKEY and NEXTKEY methods go through the keys which were already read,
135 not all the possible keys of the hash.
136 .SH AUTHOR
137 .IX Header "AUTHOR"
138 Ilya Zakharevich <mailto:perl\-module\-hash\[email protected]>.