← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/libdbm-deep-perl/oneiric

« back to all changes in this revision

Viewing changes to lib/DBM/Deep/Cookbook.pod

  • Committer: Bazaar Package Importer
  • Author(s): Ansgar Burchardt, Ansgar Burchardt, gregor herrmann
  • Date: 2010-07-24 15:10:26 UTC
  • mfrom: (1.2.3 upstream)
  • Revision ID: james.westby@ubuntu.com-20100724151026-377gwhxey77moumk
Tags: 2.0000-1
[ Ansgar Burchardt ]
* New upstream release.
  + This version introduces a new file format for the File backend.  It can
    still read databases from version 1.0003 and later.  See NEWS.Debian or
    upstream changelog for details.
* Remove build-dep on perl (>= 5.10) | libmodule-build-perl: stable has
  perl 5.10.
* Bump Standards-Version to 3.9.0 (no changes).

[ gregor herrmann ]
* Refresh manpage-has-bad-whatis-entry.patch.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/DBM/Deep/Cookbook.pod
9
9
 
10
10
=head1 RECIPES
11
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.
 
12
=head2 Unicode data
 
13
 
 
14
If possible, it is highly recommended that you upgrade your database to
 
15
version 2 (using the F<utils/upgrade_db.pl> script in the CPAN
 
16
distribution), in order to use Unicode.
 
17
 
 
18
If your databases are still shared by perl installations with older
 
19
DBM::Deep versions, you can use filters to encode strings on the fly:
 
20
 
 
21
  my $db = DBM::Deep->new( ... );
 
22
  my $encode_sub = sub { my $s = shift; utf8::encode($s); $s };
 
23
  my $decode_sub = sub { my $s = shift; utf8::decode($s); $s };
 
24
  $db->set_filter( 'store_value' => $encode_sub );
 
25
  $db->set_filter( 'fetch_value' => $decode_sub );
 
26
  $db->set_filter( 'store_key' => $encode_sub );
 
27
  $db->set_filter( 'fetch_key' => $decode_sub );
 
28
 
 
29
A previous version of this cookbook recommended using
 
30
C<binmode $db-E<gt>_fh, ":utf8">, but that is I<not> a good idea, as it
 
31
could easily corrupt the database.
28
32
 
29
33
=head2 Real-time Encryption Example
30
34
 
31
35
B<NOTE>: This is just an example of how to write a filter. This most
32
36
definitely should B<NOT> be taken as a proper way to write a filter that does
33
 
encryption.
 
37
encryption. (Furthermore, it fails to take Unicode into account.)
34
38
 
35
39
Here is a working example that uses the I<Crypt::Blowfish> module to
36
40
do real-time encryption / decryption of keys & values with DBM::Deep Filters.
100
104
  exit;
101
105
 
102
106
  sub my_compress {
103
 
      return Compress::Zlib::memGzip( $_[0] ) ;
 
107
      my $s = shift;
 
108
      utf8::encode($s);
 
109
      return Compress::Zlib::memGzip( $s ) ;
104
110
  }
105
111
  sub my_decompress {
106
 
      return Compress::Zlib::memGunzip( $_[0] ) ;
 
112
      my $s = Compress::Zlib::memGunzip( shift ) ;
 
113
      utf8::decode($s);
 
114
      return $s;
107
115
  }
108
116
 
109
117
B<Note:> Filtering of keys only applies to hashes. Array "keys" are
124
132
I<Digest::SHA256> module. Please see
125
133
L<http://search.cpan.org/search?module=Digest::SHA256> for more information.
126
134
 
 
135
The value passed to your digest function will be encoded as UTF-8 if the
 
136
database is in version 2 format or higher.
 
137
 
127
138
  use DBM::Deep;
128
139
  use Digest::SHA256;
129
140
 
196
207
 
197
208
=back
198
209
 
 
210
=head1 SEE ALSO
 
211
 
 
212
L<DBM::Deep(3)>, L<Digest::MD5(3)>, L<Digest::SHA256(3)>,
 
213
L<Crypt::Blowfish(3)>, L<Compress::Zlib(3)>
 
214
 
199
215
=cut