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