DBM_Filter(3pm)

1DBM_Filter(3pm)        Perl Programmers Reference Guide        DBM_Filter(3pm)
2
3
4

NAME

6       DBM_Filter -- Filter DBM keys/values
7

SYNOPSIS

9           use DBM_Filter ;
10           use SDBM_File; # or DB_File, or GDBM_File, or NDBM_File, or ODBM_File
11
12           $db = tie %hash, ...
13
14           $db->Filter_Push(Fetch => sub {...},
15                            Store => sub {...});
16
17           $db->Filter_Push('my_filter1');
18           $db->Filter_Push('my_filter2', params...);
19
20           $db->Filter_Key_Push(...) ;
21           $db->Filter_Value_Push(...) ;
22
23           $db->Filter_Pop();
24           $db->Filtered();
25
26           package DBM_Filter::my_filter1;
27
28           sub Store { ... }
29           sub Fetch { ... }
30
31           1;
32
33           package DBM_Filter::my_filter2;
34
35           sub Filter
36           {
37               my @opts = @_;
38               ...
39               return (
40                   sub Store { ... },
41                   sub Fetch { ... } );
42           }
43
44           1;
45

DESCRIPTION

47       This module provides an interface that allows filters to be applied to
48       tied Hashes associated with DBM files. It builds on the DBM Filter
49       hooks that are present in all the *DB*_File modules included with the
50       standard Perl source distribution from version 5.6.1 onwards. In
51       addition to the *DB*_File modules distributed with Perl, the BerkeleyDB
52       module, available on CPAN, supports the DBM Filter hooks. See
53       perldbmfilter for more details on the DBM Filter hooks.
54

What is a DBM Filter?

56       A DBM Filter allows the keys and/or values in a tied hash to be
57       modified by some user-defined code just before it is written to the DBM
58       file and just after it is read back from the DBM file. For example,
59       this snippet of code
60
61           $some_hash{"abc"} = 42;
62
63       could potentially trigger two filters, one for the writing of the key
64       "abc" and another for writing the value 42.  Similarly, this snippet
65
66           my ($key, $value) = each %some_hash
67
68       will trigger two filters, one for the reading of the key and one for
69       the reading of the value.
70
71       Like the existing DBM Filter functionality, this module arranges for
72       the $_ variable to be populated with the key or value that a filter
73       will check. This usually means that most DBM filters tend to be very
74       short.
75
76   So what's new?
77       The main enhancements over the standard DBM Filter hooks are:
78
79       ·   A cleaner interface.
80
81       ·   The ability to easily apply multiple filters to a single DBM file.
82
83       ·   The ability to create "canned" filters. These allow commonly used
84           filters to be packaged into a stand-alone module.
85

METHODS

87       This module will arrange for the following methods to be available via
88       the object returned from the "tie" call.
89
90   $db->Filter_Push()
91   $db->Filter_Key_Push()
92   $db->Filter_Value_Push()
93       Add a filter to filter stack for the database, $db. The three formats
94       vary only in whether they apply to the DBM key, the DBM value or both.
95
96       Filter_Push
97            The filter is applied to both keys and values.
98
99       Filter_Key_Push
100            The filter is applied to the key only.
101
102       Filter_Value_Push
103            The filter is applied to the value only.
104
105   $db->Filter_Pop()
106       Removes the last filter that was applied to the DBM file associated
107       with $db, if present.
108
109   $db->Filtered()
110       Returns TRUE if there are any filters applied to the DBM associated
111       with $db.  Otherwise returns FALSE.
112

Writing a Filter

114       Filters can be created in two main ways
115
116   Immediate Filters
117       An immediate filter allows you to specify the filter code to be used at
118       the point where the filter is applied to a dbm. In this mode the
119       Filter_*_Push methods expects to receive exactly two parameters.
120
121           my $db = tie %hash, 'SDBM_File', ...
122           $db->Filter_Push( Store => sub { },
123                             Fetch => sub { });
124
125       The code reference associated with "Store" will be called before any
126       key/value is written to the database and the code reference associated
127       with "Fetch" will be called after any key/value is read from the
128       database.
129
130       For example, here is a sample filter that adds a trailing NULL
131       character to all strings before they are written to the DBM file, and
132       removes the trailing NULL when they are read from the DBM file
133
134           my $db = tie %hash, 'SDBM_File', ...
135           $db->Filter_Push( Store => sub { $_ .= "\x00" ; },
136                             Fetch => sub { s/\x00$// ;    });
137
138       Points to note:
139
140       1.   Both the Store and Fetch filters manipulate $_.
141
142   Canned Filters
143       Immediate filters are useful for one-off situations. For more generic
144       problems it can be useful to package the filter up in its own module.
145
146       The usage is for a canned filter is:
147
148           $db->Filter_Push("name", params)
149
150       where
151
152       "name"
153            is the name of the module to load. If the string specified does
154            not contain the package separator characters "::", it is assumed
155            to refer to the full module name "DBM_Filter::name". This means
156            that the full names for canned filters, "null" and "utf8",
157            included with this module are:
158
159                DBM_Filter::null
160                DBM_Filter::utf8
161
162       params
163            any optional parameters that need to be sent to the filter. See
164            the encode filter for an example of a module that uses parameters.
165
166       The module that implements the canned filter can take one of two forms.
167       Here is a template for the first
168
169           package DBM_Filter::null ;
170
171           use strict;
172           use warnings;
173
174           sub Store
175           {
176               # store code here
177           }
178
179           sub Fetch
180           {
181               # fetch code here
182           }
183
184           1;
185
186       Notes:
187
188       1.   The package name uses the "DBM_Filter::" prefix.
189
190       2.   The module must have both a Store and a Fetch method. If only one
191            is present, or neither are present, a fatal error will be thrown.
192
193       The second form allows the filter to hold state information using a
194       closure, thus:
195
196           package DBM_Filter::encoding ;
197
198           use strict;
199           use warnings;
200
201           sub Filter
202           {
203               my @params = @_ ;
204
205               ...
206               return {
207                   Store   => sub { $_ = $encoding->encode($_) },
208                   Fetch   => sub { $_ = $encoding->decode($_) }
209                   } ;
210           }
211
212           1;
213
214       In this instance the "Store" and "Fetch" methods are encapsulated
215       inside a "Filter" method.
216

Filters Included

218       A number of canned filers are provided with this module. They cover a
219       number of the main areas that filters are needed when interfacing with
220       DBM files. They also act as templates for your own filters.
221
222       The filter included are:
223
224       ·    utf8
225
226            This module will ensure that all data written to the DBM will be
227            encoded in UTF-8.
228
229            This module needs the Encode module.
230
231       ·    encode
232
233            Allows you to choose the character encoding will be store in the
234            DBM file.
235
236       ·    compress
237
238            This filter will compress all data before it is written to the
239            database and uncompressed it on reading.
240
241            This module needs Compress::Zlib.
242
243       ·    int32
244
245            This module is used when interoperating with a C/C++ application
246            that uses a C int as either the key and/or value in the DBM file.
247
248       ·    null
249
250            This module ensures that all data written to the DBM file is null
251            terminated. This is useful when you have a perl script that needs
252            to interoperate with a DBM file that a C program also uses. A
253            fairly common issue is for the C application to include the
254            terminating null in a string when it writes to the DBM file. This
255            filter will ensure that all data written to the DBM file can be
256            read by the C application.
257

NOTES

259   Maintain Round Trip Integrity
260       When writing a DBM filter it is very important to ensure that it is
261       possible to retrieve all data that you have written when the DBM filter
262       is in place. In practice, this means that whatever transformation is
263       applied to the data in the Store method, the exact inverse operation
264       should be applied in the Fetch method.
265
266       If you don't provide an exact inverse transformation, you will find
267       that code like this will not behave as you expect.
268
269            while (my ($k, $v) = each %hash)
270            {
271                ...
272            }
273
274       Depending on the transformation, you will find that one or more of the
275       following will happen
276
277       1.   The loop will never terminate.
278
279       2.   Too few records will be retrieved.
280
281       3.   Too many will be retrieved.
282
283       4.   The loop will do the right thing for a while, but it will
284            unexpectedly fail.
285
286   Don't mix filtered & non-filtered data in the same database file.
287       This is just a restatement of the previous section. Unless you are
288       completely certain you know what you are doing, avoid mixing filtered &
289       non-filtered data.
290

EXAMPLE

292       Say you need to interoperate with a legacy C application that stores
293       keys as C ints and the values and null terminated UTF-8 strings. Here
294       is how you would set that up
295
296           my $db = tie %hash, 'SDBM_File', ...
297
298           $db->Filter_Key_Push('int32') ;
299
300           $db->Filter_Value_Push('utf8');
301           $db->Filter_Value_Push('null');
302

AUTHOR

307       Paul Marquess <pmqs@cpan.org>
308
309
310
311perl v5.10.1                      2009-02-12                   DBM_Filter(3pm)