Commit | Line | Data |
d8db2929 |
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 | |
eadd538f |
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 |