lib/DBM/Deep/Cookbook.pod

   1 =head1 NAME
   2
   3 DBM::Deep::Cookbook
   4
   5 =head1 DESCRIPTION
   6
   7 This is the Cookbook for L<DBM::Deep/>. It contains useful tips and tricks,
   8 plus some examples of how to do common tasks.
   9
  10 =head1 RECIPES
  11
  12 =head2 UTF8 data
  13
  14 When you're using UTF8 data, you may run into the "Wide character in print"
  15 warning. To fix that in 5.8+, do the following:
  16
  17   my $db = DBM::Deep->new( ... );
  18   binmode $db->_fh, ":utf8";
  19
  20 In 5.6, you will have to do the following:
  21
  22   my $db = DBM::Deep->new( ... );
  23   $db->set_filter( 'store_value' => sub { pack "U0C*", unpack "C*", $_[0] } );
  24   $db->set_filter( 'retrieve_value' => sub { pack "C*", unpack "U0C*", $_[0] } );
  25
  26 In a future version, you will be able to specify C<utf8 =E<gt> 1> and
  27 L<DBM::Deep/> will do these things for you.
  28
  29 =head2 Real-time Encryption Example
  30
  31 Here is a working example that uses the I<Crypt::Blowfish> module to
  32 do real-time encryption / decryption of keys & values with DBM::Deep Filters.
  33 Please visit L<http://search.cpan.org/search?module=Crypt::Blowfish> for more
  34 on I<Crypt::Blowfish>. You'll also need the I<Crypt::CBC> module.
  35
  36   use DBM::Deep;
  37   use Crypt::Blowfish;
  38   use Crypt::CBC;
  39
  40   my $cipher = Crypt::CBC->new({
  41       'key'             => 'my secret key',
  42       'cipher'          => 'Blowfish',
  43       'iv'              => '$KJh#(}q',
  44       'regenerate_key'  => 0,
  45       'padding'         => 'space',
  46       'prepend_iv'      => 0
  47   });
  48
  49   my $db = DBM::Deep->new(
  50       file => "foo-encrypt.db",
  51       filter_store_key => \&my_encrypt,
  52       filter_store_value => \&my_encrypt,
  53       filter_fetch_key => \&my_decrypt,
  54       filter_fetch_value => \&my_decrypt,
  55   );
  56
  57   $db->{key1} = "value1";
  58   $db->{key2} = "value2";
  59   print "key1: " . $db->{key1} . "\n";
  60   print "key2: " . $db->{key2} . "\n";
  61
  62   undef $db;
  63   exit;
  64
  65   sub my_encrypt {
  66       return $cipher->encrypt( $_[0] );
  67   }
  68   sub my_decrypt {
  69       return $cipher->decrypt( $_[0] );
  70   }
  71
  72 =head2 Real-time Compression Example
  73
  74 Here is a working example that uses the I<Compress::Zlib> module to do real-time
  75 compression / decompression of keys & values with DBM::Deep Filters.
  76 Please visit L<http://search.cpan.org/search?module=Compress::Zlib> for
  77 more on I<Compress::Zlib>.
  78
  79   use DBM::Deep;
  80   use Compress::Zlib;
  81
  82   my $db = DBM::Deep->new(
  83       file => "foo-compress.db",
  84       filter_store_key => \&my_compress,
  85       filter_store_value => \&my_compress,
  86       filter_fetch_key => \&my_decompress,
  87       filter_fetch_value => \&my_decompress,
  88   );
  89
  90   $db->{key1} = "value1";
  91   $db->{key2} = "value2";
  92   print "key1: " . $db->{key1} . "\n";
  93   print "key2: " . $db->{key2} . "\n";
  94
  95   undef $db;
  96   exit;
  97
  98   sub my_compress {
  99       return Compress::Zlib::memGzip( $_[0] ) ;
 100   }
 101   sub my_decompress {
 102       return Compress::Zlib::memGunzip( $_[0] ) ;
 103   }
 104
 105 B<Note:> Filtering of keys only applies to hashes. Array "keys" are
 106 actually numerical index numbers, and are not filtered.
 107
 108 =head1 Custom Digest Algorithm
 109
 110 DBM::Deep by default uses the I<Message Digest 5> (MD5) algorithm for hashing
 111 keys. However you can override this, and use another algorithm (such as SHA-256)
 112 or even write your own. But please note that DBM::Deep currently expects zero
 113 collisions, so your algorithm has to be I<perfect>, so to speak. Collision
 114 detection may be introduced in a later version.
 115
 116 You can specify a custom digest algorithm by passing it into the parameter
 117 list for new(), passing a reference to a subroutine as the 'digest' parameter,
 118 and the length of the algorithm's hashes (in bytes) as the 'hash_size'
 119 parameter. Here is a working example that uses a 256-bit hash from the
 120 I<Digest::SHA256> module. Please see
 121 L<http://search.cpan.org/search?module=Digest::SHA256> for more information.
 122
 123   use DBM::Deep;
 124   use Digest::SHA256;
 125
 126   my $context = Digest::SHA256::new(256);
 127
 128   my $db = DBM::Deep->new(
 129       filename => "foo-sha.db",
 130       digest => \&my_digest,
 131       hash_size => 32,
 132   );
 133
 134   $db->{key1} = "value1";
 135   $db->{key2} = "value2";
 136   print "key1: " . $db->{key1} . "\n";
 137   print "key2: " . $db->{key2} . "\n";
 138
 139   undef $db;
 140   exit;
 141
 142   sub my_digest {
 143       return substr( $context->hash($_[0]), 0, 32 );
 144   }
 145
 146 B<Note:> Your returned digest strings must be B<EXACTLY> the number
 147 of bytes you specify in the hash_size parameter (in this case 32). Undefined
 148 behavior will occur otherwise.
 149
 150 B<Note:> If you do choose to use a custom digest algorithm, you must set it
 151 every time you access this file. Otherwise, the default (MD5) will be used.
 152
 153 =cut