Commit | Line | Data |
---|---|---|
9fe6733a PM |
1 | =head1 NAME |
2 | ||
3 | perldbmfilter - Perl DBM Filters | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
84f709e7 | 7 | $db = tie %hash, 'DBM', ... |
9fe6733a | 8 | |
4358a253 SS |
9 | $old_filter = $db->filter_store_key ( sub { ... } ); |
10 | $old_filter = $db->filter_store_value( sub { ... } ); | |
11 | $old_filter = $db->filter_fetch_key ( sub { ... } ); | |
12 | $old_filter = $db->filter_fetch_value( sub { ... } ); | |
9fe6733a PM |
13 | |
14 | =head1 DESCRIPTION | |
15 | ||
16 | The four C<filter_*> methods shown above are available in all the DBM | |
17 | modules that ship with Perl, namely DB_File, GDBM_File, NDBM_File, | |
18 | ODBM_File and SDBM_File. | |
19 | ||
f78ac02b | 20 | Each of the methods works identically, and is used to install (or |
9fe6733a PM |
21 | uninstall) a single DBM Filter. The only difference between them is the |
22 | place that the filter is installed. | |
23 | ||
24 | To summarise: | |
25 | ||
26 | =over 5 | |
27 | ||
28 | =item B<filter_store_key> | |
29 | ||
30 | If a filter has been installed with this method, it will be invoked | |
31 | every time you write a key to a DBM database. | |
32 | ||
33 | =item B<filter_store_value> | |
34 | ||
35 | If a filter has been installed with this method, it will be invoked | |
36 | every time you write a value to a DBM database. | |
37 | ||
9fe6733a PM |
38 | =item B<filter_fetch_key> |
39 | ||
40 | If a filter has been installed with this method, it will be invoked | |
41 | every time you read a key from a DBM database. | |
42 | ||
43 | =item B<filter_fetch_value> | |
44 | ||
45 | If a filter has been installed with this method, it will be invoked | |
46 | every time you read a value from a DBM database. | |
47 | ||
48 | =back | |
49 | ||
50 | You can use any combination of the methods from none to all four. | |
51 | ||
52 | All filter methods return the existing filter, if present, or C<undef> | |
f78ac02b | 53 | if not. |
9fe6733a PM |
54 | |
55 | To delete a filter pass C<undef> to it. | |
56 | ||
57 | =head2 The Filter | |
58 | ||
59 | When each filter is called by Perl, a local copy of C<$_> will contain | |
60 | the key or value to be filtered. Filtering is achieved by modifying | |
61 | the contents of C<$_>. The return code from the filter is ignored. | |
62 | ||
ac036724 | 63 | =head2 An Example: the NULL termination problem. |
9fe6733a PM |
64 | |
65 | DBM Filters are useful for a class of problems where you I<always> | |
66 | want to make the same transformation to all keys, all values or both. | |
67 | ||
68 | For example, consider the following scenario. You have a DBM database | |
69 | that you need to share with a third-party C application. The C application | |
70 | assumes that I<all> keys and values are NULL terminated. Unfortunately | |
71 | when Perl writes to DBM databases it doesn't use NULL termination, so | |
72 | your Perl application will have to manage NULL termination itself. When | |
73 | you write to the database you will have to use something like this: | |
74 | ||
4358a253 | 75 | $hash{"$key\0"} = "$value\0"; |
9fe6733a PM |
76 | |
77 | Similarly the NULL needs to be taken into account when you are considering | |
78 | the length of existing keys/values. | |
79 | ||
80 | It would be much better if you could ignore the NULL terminations issue | |
81 | in the main application code and have a mechanism that automatically | |
82 | added the terminating NULL to all keys and values whenever you write to | |
83 | the database and have them removed when you read from the database. As I'm | |
84 | sure you have already guessed, this is a problem that DBM Filters can | |
85 | fix very easily. | |
86 | ||
4358a253 SS |
87 | use strict; |
88 | use warnings; | |
89 | use SDBM_File; | |
90 | use Fcntl; | |
9fe6733a | 91 | |
4358a253 SS |
92 | my %hash; |
93 | my $filename = "filt"; | |
94 | unlink $filename; | |
9fe6733a PM |
95 | |
96 | my $db = tie(%hash, 'SDBM_File', $filename, O_RDWR|O_CREAT, 0640) | |
4358a253 | 97 | or die "Cannot open $filename: $!\n"; |
9fe6733a PM |
98 | |
99 | # Install DBM Filters | |
4358a253 SS |
100 | $db->filter_fetch_key ( sub { s/\0$// } ); |
101 | $db->filter_store_key ( sub { $_ .= "\0" } ); | |
9f1b1f2d | 102 | $db->filter_fetch_value( |
4358a253 SS |
103 | sub { no warnings 'uninitialized'; s/\0$// } ); |
104 | $db->filter_store_value( sub { $_ .= "\0" } ); | |
9fe6733a | 105 | |
4358a253 SS |
106 | $hash{"abc"} = "def"; |
107 | my $a = $hash{"ABC"}; | |
9fe6733a | 108 | # ... |
4358a253 SS |
109 | undef $db; |
110 | untie %hash; | |
9fe6733a PM |
111 | |
112 | The code above uses SDBM_File, but it will work with any of the DBM | |
113 | modules. | |
114 | ||
115 | Hopefully the contents of each of the filters should be | |
116 | self-explanatory. Both "fetch" filters remove the terminating NULL, | |
117 | and both "store" filters add a terminating NULL. | |
118 | ||
119 | ||
ac036724 | 120 | =head2 Another Example: Key is a C int. |
9fe6733a PM |
121 | |
122 | Here is another real-life example. By default, whenever Perl writes to | |
123 | a DBM database it always writes the key and value as strings. So when | |
124 | you use this: | |
125 | ||
4358a253 | 126 | $hash{12345} = "something"; |
9fe6733a PM |
127 | |
128 | the key 12345 will get stored in the DBM database as the 5 byte string | |
129 | "12345". If you actually want the key to be stored in the DBM database | |
130 | as a C int, you will have to use C<pack> when writing, and C<unpack> | |
131 | when reading. | |
132 | ||
133 | Here is a DBM Filter that does it: | |
134 | ||
4358a253 SS |
135 | use strict; |
136 | use warnings; | |
137 | use DB_File; | |
138 | my %hash; | |
139 | my $filename = "filt"; | |
140 | unlink $filename; | |
9fe6733a PM |
141 | |
142 | ||
555bd962 BG |
143 | my $db = tie %hash, 'DB_File', $filename, O_CREAT|O_RDWR, 0666, |
144 | $DB_HASH or die "Cannot open $filename: $!\n"; | |
9fe6733a | 145 | |
4358a253 SS |
146 | $db->filter_fetch_key ( sub { $_ = unpack("i", $_) } ); |
147 | $db->filter_store_key ( sub { $_ = pack ("i", $_) } ); | |
148 | $hash{123} = "def"; | |
9fe6733a | 149 | # ... |
4358a253 SS |
150 | undef $db; |
151 | untie %hash; | |
9fe6733a PM |
152 | |
153 | The code above uses DB_File, but again it will work with any of the | |
154 | DBM modules. | |
155 | ||
ac036724 | 156 | This time only two filters have been used; we only need to manipulate |
9fe6733a PM |
157 | the contents of the key, so it wasn't necessary to install any value |
158 | filters. | |
159 | ||
160 | =head1 SEE ALSO | |
161 | ||
162 | L<DB_File>, L<GDBM_File>, L<NDBM_File>, L<ODBM_File> and L<SDBM_File>. | |
163 | ||
164 | =head1 AUTHOR | |
165 | ||
166 | Paul Marquess | |
167 |