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