CONTENTS

• NAME
• SYNOPSIS
• DESCRIPTION
• What is a DBM Filter?
  • So what's new?
• METHODS
  • $db->Filter_Push() / $db->Filter_Key_Push() / $db->Filter_Value_Push()
  • $db->Filter_Pop()
  • $db->Filtered()
• Writing a Filter
  • Immediate Filters
  • Canned Filters
• Filters Included
• NOTES
  • Maintain Round Trip Integrity
  • Don't mix filtered & non-filtered data in the same database file.
• EXAMPLE
• SEE ALSO
• AUTHOR

#NAME

DBM_Filter -- Filter DBM keys/values

#SYNOPSIS

use DBM_Filter ;
use SDBM_File; # or DB_File, GDBM_File, NDBM_File, or ODBM_File

$db = tie %hash, ...

$db->Filter_Push(Fetch => sub {...},
                 Store => sub {...});

$db->Filter_Push('my_filter1');
$db->Filter_Push('my_filter2', params...);

$db->Filter_Key_Push(...) ;
$db->Filter_Value_Push(...) ;

$db->Filter_Pop();
$db->Filtered();

package DBM_Filter::my_filter1;

sub Store { ... }
sub Fetch { ... }

1;

package DBM_Filter::my_filter2;

sub Filter
{
    my @opts = @_;
    ...
    return (
        sub Store { ... },
        sub Fetch { ... } );
}

1;

#DESCRIPTION

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

#What is a DBM Filter?

A DBM Filter allows the keys and/or values in a tied hash to be modified by some user-defined code just before it is written to the DBM file and just after it is read back from the DBM file. For example, this snippet of code

$some_hash{"abc"} = 42;

could potentially trigger two filters, one for the writing of the key "abc" and another for writing the value 42. Similarly, this snippet

my ($key, $value) = each %some_hash

will trigger two filters, one for the reading of the key and one for the reading of the value.

Like the existing DBM Filter functionality, this module arranges for the $_ variable to be populated with the key or value that a filter will check. This usually means that most DBM filters tend to be very short.