Debian Codegraph @

upstream/opensuse-tumbleweed/man3/DBM_Filter.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 "DBM_Filter 3pm"
61 .TH DBM_Filter 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 DBM_Filter \-\- Filter DBM keys/values
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 2
71 \& use DBM_Filter ;
72 \& use SDBM_File; # or DB_File, GDBM_File, NDBM_File, or ODBM_File
73 \&
74 \& $db = tie %hash, ...
75 \&
76 \& $db\->Filter_Push(Fetch => sub {...},
77 \& Store => sub {...});
78 \&
79 \& $db\->Filter_Push(\*(Aqmy_filter1\*(Aq);
80 \& $db\->Filter_Push(\*(Aqmy_filter2\*(Aq, params...);
81 \&
82 \& $db\->Filter_Key_Push(...) ;
83 \& $db\->Filter_Value_Push(...) ;
84 \&
85 \& $db\->Filter_Pop();
86 \& $db\->Filtered();
87 \&
88 \& package DBM_Filter::my_filter1;
89 \&
90 \& sub Store { ... }
91 \& sub Fetch { ... }
92 \&
93 \& 1;
94 \&
95 \& package DBM_Filter::my_filter2;
96 \&
97 \& sub Filter
98 \& {
99 \& my @opts = @_;
100 \& ...
101 \& return (
102 \& sub Store { ... },
103 \& sub Fetch { ... } );
104 \& }
105 \&
106 \& 1;
107 .Ve
108 .SH DESCRIPTION
109 .IX Header "DESCRIPTION"
110 This module provides an interface that allows filters to be applied
111 to tied Hashes associated with DBM files. It builds on the DBM Filter
112 hooks that are present in all the *DB*_File modules included with the
113 standard Perl source distribution from version 5.6.1 onwards. In addition
114 to the *DB*_File modules distributed with Perl, the BerkeleyDB module,
115 available on CPAN, supports the DBM Filter hooks. See perldbmfilter
116 for more details on the DBM Filter hooks.
117 .SH "What is a DBM Filter?"
118 .IX Header "What is a DBM Filter?"
119 A DBM Filter allows the keys and/or values in a tied hash to be modified
120 by some user\-defined code just before it is written to the DBM file and
121 just after it is read back from the DBM file. For example, this snippet
122 of code
123 .PP
124 .Vb 1
125 \& $some_hash{"abc"} = 42;
126 .Ve
127 .PP
128 could potentially trigger two filters, one for the writing of the key
129 "abc" and another for writing the value 42. Similarly, this snippet
130 .PP
131 .Vb 1
132 \& my ($key, $value) = each %some_hash
133 .Ve
134 .PP
135 will trigger two filters, one for the reading of the key and one for
136 the reading of the value.
137 .PP
138 Like the existing DBM Filter functionality, this module arranges for the
139 \&\f(CW$_\fR variable to be populated with the key or value that a filter will
140 check. This usually means that most DBM filters tend to be very short.
141 .SS "So what\*(Aqs new?"
142 .IX Subsection "So what's new?"
143 The main enhancements over the standard DBM Filter hooks are:
144 .IP \(bu 4
145 A cleaner interface.
146 .IP \(bu 4
147 The ability to easily apply multiple filters to a single DBM file.
148 .IP \(bu 4
149 The ability to create "canned" filters. These allow commonly used filters
150 to be packaged into a stand\-alone module.
151 .SH METHODS
152 .IX Header "METHODS"
153 This module will arrange for the following methods to be available via
154 the object returned from the \f(CW\*(C`tie\*(C'\fR call.
155 .ie n .SS "$db\->\fBFilter_Push()\fP / $db\->\fBFilter_Key_Push()\fP / $db\->\fBFilter_Value_Push()\fP"
156 .el .SS "\f(CW$db\fP\->\fBFilter_Push()\fP / \f(CW$db\fP\->\fBFilter_Key_Push()\fP / \f(CW$db\fP\->\fBFilter_Value_Push()\fP"
157 .IX Subsection "$db->Filter_Push() / $db->Filter_Key_Push() / $db->Filter_Value_Push()"
158 Add a filter to filter stack for the database, \f(CW$db\fR. The three formats
159 vary only in whether they apply to the DBM key, the DBM value or both.
160 .IP Filter_Push 5
161 .IX Item "Filter_Push"
162 The filter is applied to \fIboth\fR keys and values.
163 .IP Filter_Key_Push 5
164 .IX Item "Filter_Key_Push"
165 The filter is applied to the key \fIonly\fR.
166 .IP Filter_Value_Push 5
167 .IX Item "Filter_Value_Push"
168 The filter is applied to the value \fIonly\fR.
169 .ie n .SS $db\->\fBFilter_Pop()\fP
170 .el .SS \f(CW$db\fP\->\fBFilter_Pop()\fP
171 .IX Subsection "$db->Filter_Pop()"
172 Removes the last filter that was applied to the DBM file associated with
173 \&\f(CW$db\fR, if present.
174 .ie n .SS $db\->\fBFiltered()\fP
175 .el .SS \f(CW$db\fP\->\fBFiltered()\fP
176 .IX Subsection "$db->Filtered()"
177 Returns TRUE if there are any filters applied to the DBM associated
178 with \f(CW$db\fR. Otherwise returns FALSE.
179 .SH "Writing a Filter"
180 .IX Header "Writing a Filter"
181 Filters can be created in two main ways
182 .SS "Immediate Filters"
183 .IX Subsection "Immediate Filters"
184 An immediate filter allows you to specify the filter code to be used
185 at the point where the filter is applied to a dbm. In this mode the
186 Filter_*_Push methods expects to receive exactly two parameters.
187 .PP
188 .Vb 3
189 \& my $db = tie %hash, \*(AqSDBM_File\*(Aq, ...
190 \& $db\->Filter_Push( Store => sub { },
191 \& Fetch => sub { });
192 .Ve
193 .PP
194 The code reference associated with \f(CW\*(C`Store\*(C'\fR will be called before any
195 key/value is written to the database and the code reference associated
196 with \f(CW\*(C`Fetch\*(C'\fR will be called after any key/value is read from the
197 database.
198 .PP
199 For example, here is a sample filter that adds a trailing NULL character
200 to all strings before they are written to the DBM file, and removes the
201 trailing NULL when they are read from the DBM file
202 .PP
203 .Vb 3
204 \& my $db = tie %hash, \*(AqSDBM_File\*(Aq, ...
205 \& $db\->Filter_Push( Store => sub { $_ .= "\ex00" ; },
206 \& Fetch => sub { s/\ex00$// ; });
207 .Ve
208 .PP
209 Points to note:
210 .IP 1. 5
211 Both the Store and Fetch filters manipulate \f(CW$_\fR.
212 .SS "Canned Filters"
213 .IX Subsection "Canned Filters"
214 Immediate filters are useful for one\-off situations. For more generic
215 problems it can be useful to package the filter up in its own module.
216 .PP
217 The usage is for a canned filter is:
218 .PP
219 .Vb 1
220 \& $db\->Filter_Push("name", params)
221 .Ve
222 .PP
223 where
224 .IP """name""" 5
225 .IX Item """name"""
226 is the name of the module to load. If the string specified does not
227 contain the package separator characters "::", it is assumed to refer to
228 the full module name "DBM_Filter::name". This means that the full names
229 for canned filters, "null" and "utf8", included with this module are:
230 .Sp
231 .Vb 2
232 \& DBM_Filter::null
233 \& DBM_Filter::utf8
234 .Ve
235 .IP params 5
236 .IX Item "params"
237 any optional parameters that need to be sent to the filter. See the
238 encode filter for an example of a module that uses parameters.
239 .PP
240 The module that implements the canned filter can take one of two
241 forms. Here is a template for the first
242 .PP
243 .Vb 1
244 \& package DBM_Filter::null ;
245 \&
246 \& use strict;
247 \& use warnings;
248 \&
249 \& sub Store
250 \& {
251 \& # store code here
252 \& }
253 \&
254 \& sub Fetch
255 \& {
256 \& # fetch code here
257 \& }
258 \&
259 \& 1;
260 .Ve
261 .PP
262 Notes:
263 .IP 1. 5
264 The package name uses the \f(CW\*(C`DBM_Filter::\*(C'\fR prefix.
265 .IP 2. 5
266 The module \fImust\fR have both a Store and a Fetch method. If only one is
267 present, or neither are present, a fatal error will be thrown.
268 .PP
269 The second form allows the filter to hold state information using a
270 closure, thus:
271 .PP
272 .Vb 1
273 \& package DBM_Filter::encoding ;
274 \&
275 \& use strict;
276 \& use warnings;
277 \&
278 \& sub Filter
279 \& {
280 \& my @params = @_ ;
281 \&
282 \& ...
283 \& return {
284 \& Store => sub { $_ = $encoding\->encode($_) },
285 \& Fetch => sub { $_ = $encoding\->decode($_) }
286 \& } ;
287 \& }
288 \&
289 \& 1;
290 .Ve
291 .PP
292 In this instance the "Store" and "Fetch" methods are encapsulated inside a
293 "Filter" method.
294 .SH "Filters Included"
295 .IX Header "Filters Included"
296 A number of canned filers are provided with this module. They cover a
297 number of the main areas that filters are needed when interfacing with
298 DBM files. They also act as templates for your own filters.
299 .PP
300 The filter included are:
301 .IP \(bu 5
302 utf8
303 .Sp
304 This module will ensure that all data written to the DBM will be encoded
305 in UTF\-8.
306 .Sp
307 This module needs the Encode module.
308 .IP \(bu 5
309 encode
310 .Sp
311 Allows you to choose the character encoding will be store in the DBM file.
312 .IP \(bu 5
313 compress
314 .Sp
315 This filter will compress all data before it is written to the database
316 and uncompressed it on reading.
317 .Sp
318 This module needs Compress::Zlib.
319 .IP \(bu 5
320 int32
321 .Sp
322 This module is used when interoperating with a C/C++ application that
323 uses a C int as either the key and/or value in the DBM file.
324 .IP \(bu 5
325 null
326 .Sp
327 This module ensures that all data written to the DBM file is null
328 terminated. This is useful when you have a perl script that needs
329 to interoperate with a DBM file that a C program also uses. A fairly
330 common issue is for the C application to include the terminating null
331 in a string when it writes to the DBM file. This filter will ensure that
332 all data written to the DBM file can be read by the C application.
333 .SH NOTES
334 .IX Header "NOTES"
335 .SS "Maintain Round Trip Integrity"
336 .IX Subsection "Maintain Round Trip Integrity"
337 When writing a DBM filter it is \fIvery\fR important to ensure that it is
338 possible to retrieve all data that you have written when the DBM filter
339 is in place. In practice, this means that whatever transformation is
340 applied to the data in the Store method, the \fIexact\fR inverse operation
341 should be applied in the Fetch method.
342 .PP
343 If you don\*(Aqt provide an exact inverse transformation, you will find that
344 code like this will not behave as you expect.
345 .PP
346 .Vb 4
347 \& while (my ($k, $v) = each %hash)
348 \& {
349 \& ...
350 \& }
351 .Ve
352 .PP
353 Depending on the transformation, you will find that one or more of the
354 following will happen
355 .IP 1. 5
356 The loop will never terminate.
357 .IP 2. 5
358 Too few records will be retrieved.
359 .IP 3. 5
360 Too many will be retrieved.
361 .IP 4. 5
362 The loop will do the right thing for a while, but it will unexpectedly fail.
363 .SS "Don\*(Aqt mix filtered & non\-filtered data in the same database file."
364 .IX Subsection "Don't mix filtered & non-filtered data in the same database file."
365 This is just a restatement of the previous section. Unless you are
366 completely certain you know what you are doing, avoid mixing filtered &
367 non\-filtered data.
368 .SH EXAMPLE
369 .IX Header "EXAMPLE"
370 Say you need to interoperate with a legacy C application that stores
371 keys as C ints and the values and null terminated UTF\-8 strings. Here
372 is how you would set that up
373 .PP
374 .Vb 1
375 \& my $db = tie %hash, \*(AqSDBM_File\*(Aq, ...
376 \&
377 \& $db\->Filter_Key_Push(\*(Aqint32\*(Aq) ;
378 \&
379 \& $db\->Filter_Value_Push(\*(Aqutf8\*(Aq);
380 \& $db\->Filter_Value_Push(\*(Aqnull\*(Aq);
381 .Ve
382 .SH "SEE ALSO"
383 .IX Header "SEE ALSO"
384 <DB_File>, GDBM_File, NDBM_File, ODBM_File, SDBM_File, perldbmfilter
385 .SH AUTHOR
386 .IX Header "AUTHOR"
387 Paul Marquess <[email protected]>