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