Commit | Line | Data |
ffed8b01 |
1 | package DBM::Deep; |
2 | |
3 | ## |
4 | # DBM::Deep |
5 | # |
6 | # Description: |
d0b74c17 |
7 | # Multi-level database module for storing hash trees, arrays and simple |
8 | # key/value pairs into FTP-able, cross-platform binary database files. |
ffed8b01 |
9 | # |
d0b74c17 |
10 | # Type `perldoc DBM::Deep` for complete documentation. |
ffed8b01 |
11 | # |
12 | # Usage Examples: |
d0b74c17 |
13 | # my %db; |
14 | # tie %db, 'DBM::Deep', 'my_database.db'; # standard tie() method |
ffed8b01 |
15 | # |
d0b74c17 |
16 | # my $db = new DBM::Deep( 'my_database.db' ); # preferred OO method |
17 | # |
18 | # $db->{my_scalar} = 'hello world'; |
19 | # $db->{my_hash} = { larry => 'genius', hashes => 'fast' }; |
20 | # $db->{my_array} = [ 1, 2, 3, time() ]; |
21 | # $db->{my_complex} = [ 'hello', { perl => 'rules' }, 42, 99 ]; |
22 | # push @{$db->{my_array}}, 'another value'; |
23 | # my @key_list = keys %{$db->{my_hash}}; |
24 | # print "This module " . $db->{my_complex}->[1]->{perl} . "!\n"; |
ffed8b01 |
25 | # |
26 | # Copyright: |
d0b74c17 |
27 | # (c) 2002-2006 Joseph Huckaby. All Rights Reserved. |
28 | # This program is free software; you can redistribute it and/or |
29 | # modify it under the same terms as Perl itself. |
ffed8b01 |
30 | ## |
31 | |
460b1067 |
32 | use 5.6.0; |
33 | |
ffed8b01 |
34 | use strict; |
460b1067 |
35 | use warnings; |
8b957036 |
36 | |
d8db2929 |
37 | our $VERSION = q(0.99_03); |
86867f3a |
38 | |
05be6af2 |
39 | use Fcntl qw( :flock ); |
12b96196 |
40 | |
41 | use Clone::Any '_clone_data'; |
ffed8b01 |
42 | use Digest::MD5 (); |
a8fdabda |
43 | use FileHandle::Fmode (); |
ffed8b01 |
44 | use Scalar::Util (); |
ffed8b01 |
45 | |
662db255 |
46 | use DBM::Deep::Engine; |
460b1067 |
47 | use DBM::Deep::File; |
95967a5e |
48 | |
ffed8b01 |
49 | ## |
50 | # Setup constants for users to pass to new() |
51 | ## |
662db255 |
52 | sub TYPE_HASH () { DBM::Deep::Engine->SIG_HASH } |
53 | sub TYPE_ARRAY () { DBM::Deep::Engine->SIG_ARRAY } |
ffed8b01 |
54 | |
696cadb7 |
55 | # This is used in all the children of this class in their TIE<type> methods. |
0ca7ea98 |
56 | sub _get_args { |
57 | my $proto = shift; |
58 | |
59 | my $args; |
60 | if (scalar(@_) > 1) { |
61 | if ( @_ % 2 ) { |
62 | $proto->_throw_error( "Odd number of parameters to " . (caller(1))[2] ); |
63 | } |
64 | $args = {@_}; |
65 | } |
d0b74c17 |
66 | elsif ( ref $_[0] ) { |
4d35d856 |
67 | unless ( eval { local $SIG{'__DIE__'}; %{$_[0]} || 1 } ) { |
0ca7ea98 |
68 | $proto->_throw_error( "Not a hashref in args to " . (caller(1))[2] ); |
69 | } |
70 | $args = $_[0]; |
71 | } |
d0b74c17 |
72 | else { |
0ca7ea98 |
73 | $args = { file => shift }; |
74 | } |
75 | |
76 | return $args; |
77 | } |
78 | |
ffed8b01 |
79 | sub new { |
d0b74c17 |
80 | ## |
81 | # Class constructor method for Perl OO interface. |
82 | # Calls tie() and returns blessed reference to tied hash or array, |
83 | # providing a hybrid OO/tie interface. |
84 | ## |
85 | my $class = shift; |
86 | my $args = $class->_get_args( @_ ); |
87 | |
88 | ## |
89 | # Check if we want a tied hash or array. |
90 | ## |
91 | my $self; |
92 | if (defined($args->{type}) && $args->{type} eq TYPE_ARRAY) { |
6fe26b29 |
93 | $class = 'DBM::Deep::Array'; |
94 | require DBM::Deep::Array; |
d0b74c17 |
95 | tie @$self, $class, %$args; |
96 | } |
97 | else { |
6fe26b29 |
98 | $class = 'DBM::Deep::Hash'; |
99 | require DBM::Deep::Hash; |
d0b74c17 |
100 | tie %$self, $class, %$args; |
101 | } |
ffed8b01 |
102 | |
d0b74c17 |
103 | return bless $self, $class; |
ffed8b01 |
104 | } |
105 | |
96041a25 |
106 | # This initializer is called from the various TIE* methods. new() calls tie(), |
107 | # which allows for a single point of entry. |
0795f290 |
108 | sub _init { |
0795f290 |
109 | my $class = shift; |
994ccd8e |
110 | my ($args) = @_; |
0795f290 |
111 | |
83371fe3 |
112 | $args->{storage} = DBM::Deep::File->new( $args ) |
113 | unless exists $args->{storage}; |
460b1067 |
114 | |
115 | # locking implicitly enables autoflush |
116 | if ($args->{locking}) { $args->{autoflush} = 1; } |
117 | |
0795f290 |
118 | # These are the defaults to be optionally overridden below |
119 | my $self = bless { |
95967a5e |
120 | type => TYPE_HASH, |
e06824f8 |
121 | base_offset => undef, |
8af340bf |
122 | staleness => undef, |
359a01ac |
123 | |
83371fe3 |
124 | storage => undef, |
c9f02899 |
125 | engine => undef, |
0795f290 |
126 | }, $class; |
c9f02899 |
127 | |
662db255 |
128 | $args->{engine} = DBM::Deep::Engine->new( { %{$args}, obj => $self } ) |
c9f02899 |
129 | unless exists $args->{engine}; |
8db25060 |
130 | |
fde3db1a |
131 | # Grab the parameters we want to use |
0795f290 |
132 | foreach my $param ( keys %$self ) { |
133 | next unless exists $args->{$param}; |
3e9498a1 |
134 | $self->{$param} = $args->{$param}; |
ffed8b01 |
135 | } |
d0b74c17 |
136 | |
696cadb7 |
137 | eval { |
138 | local $SIG{'__DIE__'}; |
3ed26433 |
139 | |
696cadb7 |
140 | $self->lock; |
141 | $self->_engine->setup_fh( $self ); |
3ed26433 |
142 | $self->_storage->set_inode; |
696cadb7 |
143 | $self->unlock; |
144 | }; if ( $@ ) { |
145 | my $e = $@; |
146 | eval { local $SIG{'__DIE__'}; $self->unlock; }; |
147 | die $e; |
148 | } |
359a01ac |
149 | |
0795f290 |
150 | return $self; |
ffed8b01 |
151 | } |
152 | |
ffed8b01 |
153 | sub TIEHASH { |
6fe26b29 |
154 | shift; |
155 | require DBM::Deep::Hash; |
156 | return DBM::Deep::Hash->TIEHASH( @_ ); |
ffed8b01 |
157 | } |
158 | |
159 | sub TIEARRAY { |
6fe26b29 |
160 | shift; |
161 | require DBM::Deep::Array; |
162 | return DBM::Deep::Array->TIEARRAY( @_ ); |
ffed8b01 |
163 | } |
164 | |
ffed8b01 |
165 | sub lock { |
994ccd8e |
166 | my $self = shift->_get_self; |
83371fe3 |
167 | return $self->_storage->lock( $self, @_ ); |
ffed8b01 |
168 | } |
169 | |
170 | sub unlock { |
994ccd8e |
171 | my $self = shift->_get_self; |
83371fe3 |
172 | return $self->_storage->unlock( $self, @_ ); |
ffed8b01 |
173 | } |
174 | |
906c8e01 |
175 | sub _copy_value { |
176 | my $self = shift->_get_self; |
177 | my ($spot, $value) = @_; |
178 | |
179 | if ( !ref $value ) { |
180 | ${$spot} = $value; |
181 | } |
182 | elsif ( eval { local $SIG{__DIE__}; $value->isa( 'DBM::Deep' ) } ) { |
f9c33187 |
183 | ${$spot} = $value->_repr; |
906c8e01 |
184 | $value->_copy_node( ${$spot} ); |
185 | } |
186 | else { |
187 | my $r = Scalar::Util::reftype( $value ); |
188 | my $c = Scalar::Util::blessed( $value ); |
189 | if ( $r eq 'ARRAY' ) { |
190 | ${$spot} = [ @{$value} ]; |
191 | } |
192 | else { |
193 | ${$spot} = { %{$value} }; |
194 | } |
95bbd935 |
195 | ${$spot} = bless ${$spot}, $c |
906c8e01 |
196 | if defined $c; |
197 | } |
198 | |
199 | return 1; |
200 | } |
201 | |
261d1296 |
202 | sub _copy_node { |
f9c33187 |
203 | die "Must be implemented in a child class\n"; |
204 | } |
906c8e01 |
205 | |
f9c33187 |
206 | sub _repr { |
207 | die "Must be implemented in a child class\n"; |
ffed8b01 |
208 | } |
209 | |
210 | sub export { |
d0b74c17 |
211 | ## |
212 | # Recursively export into standard Perl hashes and arrays. |
213 | ## |
994ccd8e |
214 | my $self = shift->_get_self; |
d0b74c17 |
215 | |
f9c33187 |
216 | my $temp = $self->_repr; |
d0b74c17 |
217 | |
218 | $self->lock(); |
219 | $self->_copy_node( $temp ); |
220 | $self->unlock(); |
221 | |
c9f02899 |
222 | my $classname = $self->_engine->get_classname( $self ); |
84467b9f |
223 | if ( defined $classname ) { |
224 | bless $temp, $classname; |
68f943b3 |
225 | } |
226 | |
d0b74c17 |
227 | return $temp; |
ffed8b01 |
228 | } |
229 | |
230 | sub import { |
d0b74c17 |
231 | ## |
232 | # Recursively import Perl hash/array structure |
233 | ## |
d0b74c17 |
234 | if (!ref($_[0])) { return; } # Perl calls import() on use -- ignore |
235 | |
994ccd8e |
236 | my $self = shift->_get_self; |
237 | my ($struct) = @_; |
d0b74c17 |
238 | |
c9cec40e |
239 | # struct is not a reference, so just import based on our type |
d0b74c17 |
240 | if (!ref($struct)) { |
f9c33187 |
241 | $struct = $self->_repr( @_ ); |
d0b74c17 |
242 | } |
243 | |
12b96196 |
244 | #XXX This isn't the best solution. Better would be to use Data::Walker, |
245 | #XXX but that's a lot more thinking than I want to do right now. |
7a960a12 |
246 | eval { |
84467b9f |
247 | #$self->begin_work; |
12b96196 |
248 | $self->_import( _clone_data( $struct ) ); |
84467b9f |
249 | #$self->commit; |
7a960a12 |
250 | }; if ( $@ ) { |
84467b9f |
251 | #$self->rollback; |
7a960a12 |
252 | die $@; |
253 | } |
254 | |
255 | return 1; |
ffed8b01 |
256 | } |
257 | |
13ff93d5 |
258 | #XXX Need to keep track of who has a fh to this file in order to |
259 | #XXX close them all prior to optimize on Win32/cygwin |
ffed8b01 |
260 | sub optimize { |
d0b74c17 |
261 | ## |
262 | # Rebuild entire database into new file, then move |
263 | # it back on top of original. |
264 | ## |
994ccd8e |
265 | my $self = shift->_get_self; |
cc4bef86 |
266 | |
267 | #XXX Need to create a new test for this |
83371fe3 |
268 | # if ($self->_storage->{links} > 1) { |
1400a48e |
269 | # $self->_throw_error("Cannot optimize: reference count is greater than 1"); |
d0b74c17 |
270 | # } |
271 | |
7a960a12 |
272 | #XXX Do we have to lock the tempfile? |
273 | |
d0b74c17 |
274 | my $db_temp = DBM::Deep->new( |
83371fe3 |
275 | file => $self->_storage->{file} . '.tmp', |
d0b74c17 |
276 | type => $self->_type |
277 | ); |
d0b74c17 |
278 | |
279 | $self->lock(); |
280 | $self->_copy_node( $db_temp ); |
281 | undef $db_temp; |
282 | |
283 | ## |
284 | # Attempt to copy user, group and permissions over to new file |
285 | ## |
286 | my @stats = stat($self->_fh); |
287 | my $perms = $stats[2] & 07777; |
288 | my $uid = $stats[4]; |
289 | my $gid = $stats[5]; |
83371fe3 |
290 | chown( $uid, $gid, $self->_storage->{file} . '.tmp' ); |
291 | chmod( $perms, $self->_storage->{file} . '.tmp' ); |
d0b74c17 |
292 | |
ffed8b01 |
293 | # q.v. perlport for more information on this variable |
90f93b43 |
294 | if ( $^O eq 'MSWin32' || $^O eq 'cygwin' ) { |
d0b74c17 |
295 | ## |
296 | # Potential race condition when optmizing on Win32 with locking. |
297 | # The Windows filesystem requires that the filehandle be closed |
298 | # before it is overwritten with rename(). This could be redone |
299 | # with a soft copy. |
300 | ## |
301 | $self->unlock(); |
83371fe3 |
302 | $self->_storage->close; |
d0b74c17 |
303 | } |
304 | |
83371fe3 |
305 | if (!rename $self->_storage->{file} . '.tmp', $self->_storage->{file}) { |
306 | unlink $self->_storage->{file} . '.tmp'; |
d0b74c17 |
307 | $self->unlock(); |
1400a48e |
308 | $self->_throw_error("Optimize failed: Cannot copy temp file over original: $!"); |
d0b74c17 |
309 | } |
310 | |
311 | $self->unlock(); |
83371fe3 |
312 | $self->_storage->close; |
313 | $self->_storage->open; |
72e315ac |
314 | $self->_engine->setup_fh( $self ); |
70b55428 |
315 | |
d0b74c17 |
316 | return 1; |
ffed8b01 |
317 | } |
318 | |
319 | sub clone { |
d0b74c17 |
320 | ## |
321 | # Make copy of object and return |
322 | ## |
994ccd8e |
323 | my $self = shift->_get_self; |
d0b74c17 |
324 | |
325 | return DBM::Deep->new( |
c3aafc14 |
326 | type => $self->_type, |
d0b74c17 |
327 | base_offset => $self->_base_offset, |
8af340bf |
328 | staleness => $self->_staleness, |
83371fe3 |
329 | storage => $self->_storage, |
c9f02899 |
330 | engine => $self->_engine, |
d0b74c17 |
331 | ); |
ffed8b01 |
332 | } |
333 | |
334 | { |
335 | my %is_legal_filter = map { |
336 | $_ => ~~1, |
337 | } qw( |
338 | store_key store_value |
339 | fetch_key fetch_value |
340 | ); |
341 | |
342 | sub set_filter { |
343 | ## |
344 | # Setup filter function for storing or fetching the key or value |
345 | ## |
994ccd8e |
346 | my $self = shift->_get_self; |
347 | my $type = lc shift; |
348 | my $func = shift; |
d0b74c17 |
349 | |
ffed8b01 |
350 | if ( $is_legal_filter{$type} ) { |
83371fe3 |
351 | $self->_storage->{"filter_$type"} = $func; |
ffed8b01 |
352 | return 1; |
353 | } |
354 | |
355 | return; |
356 | } |
357 | } |
358 | |
fee0243f |
359 | sub begin_work { |
360 | my $self = shift->_get_self; |
8cb9205a |
361 | return $self->_engine->begin_work( $self, @_ ); |
fee0243f |
362 | } |
363 | |
364 | sub rollback { |
365 | my $self = shift->_get_self; |
8cb9205a |
366 | return $self->_engine->rollback( $self, @_ ); |
fee0243f |
367 | } |
368 | |
359a01ac |
369 | sub commit { |
370 | my $self = shift->_get_self; |
8cb9205a |
371 | return $self->_engine->commit( $self, @_ ); |
359a01ac |
372 | } |
fee0243f |
373 | |
ffed8b01 |
374 | ## |
375 | # Accessor methods |
376 | ## |
377 | |
72e315ac |
378 | sub _engine { |
379 | my $self = $_[0]->_get_self; |
380 | return $self->{engine}; |
381 | } |
382 | |
83371fe3 |
383 | sub _storage { |
2ac02042 |
384 | my $self = $_[0]->_get_self; |
83371fe3 |
385 | return $self->{storage}; |
ffed8b01 |
386 | } |
387 | |
4d35d856 |
388 | sub _type { |
2ac02042 |
389 | my $self = $_[0]->_get_self; |
d0b74c17 |
390 | return $self->{type}; |
ffed8b01 |
391 | } |
392 | |
4d35d856 |
393 | sub _base_offset { |
2ac02042 |
394 | my $self = $_[0]->_get_self; |
d0b74c17 |
395 | return $self->{base_offset}; |
ffed8b01 |
396 | } |
397 | |
8af340bf |
398 | sub _staleness { |
399 | my $self = $_[0]->_get_self; |
400 | return $self->{staleness}; |
401 | } |
402 | |
994ccd8e |
403 | sub _fh { |
994ccd8e |
404 | my $self = $_[0]->_get_self; |
83371fe3 |
405 | return $self->_storage->{fh}; |
994ccd8e |
406 | } |
407 | |
ffed8b01 |
408 | ## |
409 | # Utility methods |
410 | ## |
411 | |
261d1296 |
412 | sub _throw_error { |
95967a5e |
413 | die "DBM::Deep: $_[1]\n"; |
ffed8b01 |
414 | } |
415 | |
ffed8b01 |
416 | sub STORE { |
d0b74c17 |
417 | ## |
418 | # Store single hash key/value or array element in database. |
419 | ## |
420 | my $self = shift->_get_self; |
7dd04e76 |
421 | my ($key, $value) = @_; |
81d3d316 |
422 | |
a8fdabda |
423 | if ( !FileHandle::Fmode::is_W( $self->_fh ) ) { |
acd4faf2 |
424 | $self->_throw_error( 'Cannot write to a readonly filehandle' ); |
425 | } |
d0b74c17 |
426 | |
427 | ## |
428 | # Request exclusive lock for writing |
429 | ## |
430 | $self->lock( LOCK_EX ); |
431 | |
0cb639bd |
432 | # User may be storing a complex value, in which case we do not want it run |
433 | # through the filtering system. |
83371fe3 |
434 | if ( !ref($value) && $self->_storage->{filter_store_value} ) { |
435 | $value = $self->_storage->{filter_store_value}->( $value ); |
d0b74c17 |
436 | } |
437 | |
7dd04e76 |
438 | $self->_engine->write_value( $self, $key, $value); |
d0b74c17 |
439 | |
440 | $self->unlock(); |
441 | |
86867f3a |
442 | return 1; |
ffed8b01 |
443 | } |
444 | |
445 | sub FETCH { |
d0b74c17 |
446 | ## |
447 | # Fetch single value or element given plain key or array index |
448 | ## |
cb79ec85 |
449 | my $self = shift->_get_self; |
7dd04e76 |
450 | my ($key) = @_; |
ffed8b01 |
451 | |
d0b74c17 |
452 | ## |
453 | # Request shared lock for reading |
454 | ## |
455 | $self->lock( LOCK_SH ); |
456 | |
7dd04e76 |
457 | my $result = $self->_engine->read_value( $self, $key); |
d0b74c17 |
458 | |
459 | $self->unlock(); |
460 | |
a86430bd |
461 | # Filters only apply to scalar values, so the ref check is making |
462 | # sure the fetched bucket is a scalar, not a child hash or array. |
83371fe3 |
463 | return ($result && !ref($result) && $self->_storage->{filter_fetch_value}) |
464 | ? $self->_storage->{filter_fetch_value}->($result) |
cb79ec85 |
465 | : $result; |
ffed8b01 |
466 | } |
467 | |
468 | sub DELETE { |
d0b74c17 |
469 | ## |
470 | # Delete single key/value pair or element given plain key or array index |
471 | ## |
a97c8f67 |
472 | my $self = shift->_get_self; |
7dd04e76 |
473 | my ($key) = @_; |
d0b74c17 |
474 | |
a8fdabda |
475 | if ( !FileHandle::Fmode::is_W( $self->_fh ) ) { |
a86430bd |
476 | $self->_throw_error( 'Cannot write to a readonly filehandle' ); |
477 | } |
d0b74c17 |
478 | |
479 | ## |
480 | # Request exclusive lock for writing |
481 | ## |
482 | $self->lock( LOCK_EX ); |
483 | |
d0b74c17 |
484 | ## |
485 | # Delete bucket |
486 | ## |
7dd04e76 |
487 | my $value = $self->_engine->delete_key( $self, $key); |
a86430bd |
488 | |
83371fe3 |
489 | if (defined $value && !ref($value) && $self->_storage->{filter_fetch_value}) { |
490 | $value = $self->_storage->{filter_fetch_value}->($value); |
3b6a5056 |
491 | } |
492 | |
d0b74c17 |
493 | $self->unlock(); |
494 | |
495 | return $value; |
ffed8b01 |
496 | } |
497 | |
498 | sub EXISTS { |
d0b74c17 |
499 | ## |
500 | # Check if a single key or element exists given plain key or array index |
501 | ## |
a97c8f67 |
502 | my $self = shift->_get_self; |
503 | my ($key) = @_; |
d0b74c17 |
504 | |
d0b74c17 |
505 | ## |
506 | # Request shared lock for reading |
507 | ## |
508 | $self->lock( LOCK_SH ); |
509 | |
c9f02899 |
510 | my $result = $self->_engine->key_exists( $self, $key ); |
d0b74c17 |
511 | |
512 | $self->unlock(); |
513 | |
514 | return $result; |
ffed8b01 |
515 | } |
516 | |
517 | sub CLEAR { |
d0b74c17 |
518 | ## |
519 | # Clear all keys from hash, or all elements from array. |
520 | ## |
a97c8f67 |
521 | my $self = shift->_get_self; |
ffed8b01 |
522 | |
a8fdabda |
523 | if ( !FileHandle::Fmode::is_W( $self->_fh ) ) { |
a86430bd |
524 | $self->_throw_error( 'Cannot write to a readonly filehandle' ); |
525 | } |
526 | |
d0b74c17 |
527 | ## |
528 | # Request exclusive lock for writing |
529 | ## |
530 | $self->lock( LOCK_EX ); |
531 | |
f9a320bb |
532 | if ( $self->_type eq TYPE_HASH ) { |
533 | my $key = $self->first_key; |
534 | while ( $key ) { |
83c43bb5 |
535 | # Retrieve the key before deleting because we depend on next_key |
f9a320bb |
536 | my $next_key = $self->next_key( $key ); |
c9f02899 |
537 | $self->_engine->delete_key( $self, $key, $key ); |
f9a320bb |
538 | $key = $next_key; |
539 | } |
540 | } |
541 | else { |
542 | my $size = $self->FETCHSIZE; |
c3aafc14 |
543 | for my $key ( 0 .. $size - 1 ) { |
c9f02899 |
544 | $self->_engine->delete_key( $self, $key, $key ); |
f9a320bb |
545 | } |
546 | $self->STORESIZE( 0 ); |
547 | } |
f9c33187 |
548 | #XXX This needs updating to use _release_space |
f9a320bb |
549 | # $self->_engine->write_tag( |
550 | # $self->_base_offset, $self->_type, |
551 | # chr(0)x$self->_engine->{index_size}, |
552 | # ); |
d0b74c17 |
553 | |
554 | $self->unlock(); |
555 | |
556 | return 1; |
ffed8b01 |
557 | } |
558 | |
ffed8b01 |
559 | ## |
560 | # Public method aliases |
561 | ## |
7f441181 |
562 | sub put { (shift)->STORE( @_ ) } |
563 | sub store { (shift)->STORE( @_ ) } |
564 | sub get { (shift)->FETCH( @_ ) } |
565 | sub fetch { (shift)->FETCH( @_ ) } |
baa27ab6 |
566 | sub delete { (shift)->DELETE( @_ ) } |
567 | sub exists { (shift)->EXISTS( @_ ) } |
568 | sub clear { (shift)->CLEAR( @_ ) } |
ffed8b01 |
569 | |
570 | 1; |
ffed8b01 |
571 | __END__ |
572 | |
573 | =head1 NAME |
574 | |
fa944deb |
575 | DBM::Deep - A pure perl multi-level hash/array DBM that supports transactions |
ffed8b01 |
576 | |
577 | =head1 SYNOPSIS |
578 | |
579 | use DBM::Deep; |
580 | my $db = DBM::Deep->new( "foo.db" ); |
d0b74c17 |
581 | |
eff6a245 |
582 | $db->{key} = 'value'; |
ffed8b01 |
583 | print $db->{key}; |
d0b74c17 |
584 | |
eff6a245 |
585 | $db->put('key' => 'value'); |
ffed8b01 |
586 | print $db->get('key'); |
d0b74c17 |
587 | |
ffed8b01 |
588 | # true multi-level support |
589 | $db->{my_complex} = [ |
d0b74c17 |
590 | 'hello', { perl => 'rules' }, |
591 | 42, 99, |
90f93b43 |
592 | ]; |
ffed8b01 |
593 | |
fa944deb |
594 | $db->begin_work; |
595 | |
596 | # Do stuff here |
597 | |
598 | $db->rollback; |
599 | $db->commit; |
600 | |
eff6a245 |
601 | tie my %db, 'DBM::Deep', 'foo.db'; |
602 | $db{key} = 'value'; |
603 | print $db{key}; |
ffed8b01 |
604 | |
eff6a245 |
605 | tied(%db)->put('key' => 'value'); |
606 | print tied(%db)->get('key'); |
8db25060 |
607 | |
eff6a245 |
608 | =head1 DESCRIPTION |
8db25060 |
609 | |
eff6a245 |
610 | A unique flat-file database module, written in pure perl. True multi-level |
611 | hash/array support (unlike MLDBM, which is faked), hybrid OO / tie() |
612 | interface, cross-platform FTPable files, ACID transactions, and is quite fast. |
613 | Can handle millions of keys and unlimited levels without significant |
614 | slow-down. Written from the ground-up in pure perl -- this is NOT a wrapper |
615 | around a C-based DBM. Out-of-the-box compatibility with Unix, Mac OS X and |
616 | Windows. |
ffed8b01 |
617 | |
eff6a245 |
618 | =head1 VERSION DIFFERENCES |
ffed8b01 |
619 | |
fa944deb |
620 | B<NOTE>: 0.99_03 has significant file format differences from prior versions. |
621 | THere will be a backwards-compatibility layer in 1.00, but that is slated for |
622 | a later 0.99_x release. This version is B<NOT> backwards compatible with any |
623 | other release of DBM::Deep. |
624 | |
eff6a245 |
625 | B<NOTE>: 0.99_01 and above have significant file format differences from 0.983 and |
626 | before. There will be a backwards-compatibility layer in 1.00, but that is |
627 | slated for a later 0.99_x release. This version is B<NOT> backwards compatible |
628 | with 0.983 and before. |
ffed8b01 |
629 | |
630 | =head1 SETUP |
631 | |
d0b74c17 |
632 | Construction can be done OO-style (which is the recommended way), or using |
ffed8b01 |
633 | Perl's tie() function. Both are examined here. |
634 | |
635 | =head2 OO CONSTRUCTION |
636 | |
637 | The recommended way to construct a DBM::Deep object is to use the new() |
eff6a245 |
638 | method, which gets you a blessed I<and> tied hash (or array) reference. |
ffed8b01 |
639 | |
a8fdabda |
640 | my $db = DBM::Deep->new( "foo.db" ); |
ffed8b01 |
641 | |
642 | This opens a new database handle, mapped to the file "foo.db". If this |
d0b74c17 |
643 | file does not exist, it will automatically be created. DB files are |
ffed8b01 |
644 | opened in "r+" (read/write) mode, and the type of object returned is a |
645 | hash, unless otherwise specified (see L<OPTIONS> below). |
646 | |
ffed8b01 |
647 | You can pass a number of options to the constructor to specify things like |
eff6a245 |
648 | locking, autoflush, etc. This is done by passing an inline hash (or hashref): |
ffed8b01 |
649 | |
a8fdabda |
650 | my $db = DBM::Deep->new( |
651 | file => "foo.db", |
652 | locking => 1, |
653 | autoflush => 1 |
654 | ); |
ffed8b01 |
655 | |
656 | Notice that the filename is now specified I<inside> the hash with |
d0b74c17 |
657 | the "file" parameter, as opposed to being the sole argument to the |
ffed8b01 |
658 | constructor. This is required if any options are specified. |
659 | See L<OPTIONS> below for the complete list. |
660 | |
ffed8b01 |
661 | You can also start with an array instead of a hash. For this, you must |
662 | specify the C<type> parameter: |
663 | |
a8fdabda |
664 | my $db = DBM::Deep->new( |
665 | file => "foo.db", |
666 | type => DBM::Deep->TYPE_ARRAY |
667 | ); |
ffed8b01 |
668 | |
669 | B<Note:> Specifing the C<type> parameter only takes effect when beginning |
670 | a new DB file. If you create a DBM::Deep object with an existing file, the |
90f93b43 |
671 | C<type> will be loaded from the file header, and an error will be thrown if |
672 | the wrong type is passed in. |
ffed8b01 |
673 | |
674 | =head2 TIE CONSTRUCTION |
675 | |
90f93b43 |
676 | Alternately, you can create a DBM::Deep handle by using Perl's built-in |
677 | tie() function. The object returned from tie() can be used to call methods, |
eff6a245 |
678 | such as lock() and unlock(). (That object can be retrieved from the tied |
679 | variable at any time using tied() - please see L<perltie/> for more info. |
ffed8b01 |
680 | |
a8fdabda |
681 | my %hash; |
682 | my $db = tie %hash, "DBM::Deep", "foo.db"; |
d0b74c17 |
683 | |
a8fdabda |
684 | my @array; |
685 | my $db = tie @array, "DBM::Deep", "bar.db"; |
ffed8b01 |
686 | |
687 | As with the OO constructor, you can replace the DB filename parameter with |
688 | a hash containing one or more options (see L<OPTIONS> just below for the |
689 | complete list). |
690 | |
a8fdabda |
691 | tie %hash, "DBM::Deep", { |
692 | file => "foo.db", |
693 | locking => 1, |
694 | autoflush => 1 |
695 | }; |
ffed8b01 |
696 | |
697 | =head2 OPTIONS |
698 | |
699 | There are a number of options that can be passed in when constructing your |
700 | DBM::Deep objects. These apply to both the OO- and tie- based approaches. |
701 | |
702 | =over |
703 | |
704 | =item * file |
705 | |
706 | Filename of the DB file to link the handle to. You can pass a full absolute |
d0b74c17 |
707 | filesystem path, partial path, or a plain filename if the file is in the |
714618f0 |
708 | current working directory. This is a required parameter (though q.v. fh). |
709 | |
710 | =item * fh |
711 | |
712 | If you want, you can pass in the fh instead of the file. This is most useful for doing |
713 | something like: |
714 | |
715 | my $db = DBM::Deep->new( { fh => \*DATA } ); |
716 | |
717 | You are responsible for making sure that the fh has been opened appropriately for your |
718 | needs. If you open it read-only and attempt to write, an exception will be thrown. If you |
719 | open it write-only or append-only, an exception will be thrown immediately as DBM::Deep |
720 | needs to read from the fh. |
721 | |
722 | =item * file_offset |
723 | |
724 | This is the offset within the file that the DBM::Deep db starts. Most of the time, you will |
725 | not need to set this. However, it's there if you want it. |
726 | |
727 | If you pass in fh and do not set this, it will be set appropriately. |
ffed8b01 |
728 | |
ffed8b01 |
729 | =item * type |
730 | |
731 | This parameter specifies what type of object to create, a hash or array. Use |
359a01ac |
732 | one of these two constants: |
733 | |
734 | =over 4 |
735 | |
736 | =item * C<DBM::Deep-E<gt>TYPE_HASH> |
737 | |
738 | =item * C<DBM::Deep-E<gt>TYPE_ARRAY>. |
739 | |
740 | =back |
741 | |
d0b74c17 |
742 | This only takes effect when beginning a new file. This is an optional |
ffed8b01 |
743 | parameter, and defaults to C<DBM::Deep-E<gt>TYPE_HASH>. |
744 | |
745 | =item * locking |
746 | |
eff6a245 |
747 | Specifies whether locking is to be enabled. DBM::Deep uses Perl's flock() |
748 | function to lock the database in exclusive mode for writes, and shared mode |
749 | for reads. Pass any true value to enable. This affects the base DB handle |
750 | I<and any child hashes or arrays> that use the same DB file. This is an |
751 | optional parameter, and defaults to 0 (disabled). See L<LOCKING> below for |
752 | more. |
ffed8b01 |
753 | |
754 | =item * autoflush |
755 | |
d0b74c17 |
756 | Specifies whether autoflush is to be enabled on the underlying filehandle. |
757 | This obviously slows down write operations, but is required if you may have |
758 | multiple processes accessing the same DB file (also consider enable I<locking>). |
759 | Pass any true value to enable. This is an optional parameter, and defaults to 0 |
ffed8b01 |
760 | (disabled). |
761 | |
ffed8b01 |
762 | =item * filter_* |
763 | |
359a01ac |
764 | See L</FILTERS> below. |
ffed8b01 |
765 | |
ffed8b01 |
766 | =back |
767 | |
768 | =head1 TIE INTERFACE |
769 | |
770 | With DBM::Deep you can access your databases using Perl's standard hash/array |
90f93b43 |
771 | syntax. Because all DBM::Deep objects are I<tied> to hashes or arrays, you can |
772 | treat them as such. DBM::Deep will intercept all reads/writes and direct them |
773 | to the right place -- the DB file. This has nothing to do with the |
774 | L<TIE CONSTRUCTION> section above. This simply tells you how to use DBM::Deep |
775 | using regular hashes and arrays, rather than calling functions like C<get()> |
776 | and C<put()> (although those work too). It is entirely up to you how to want |
777 | to access your databases. |
ffed8b01 |
778 | |
779 | =head2 HASHES |
780 | |
781 | You can treat any DBM::Deep object like a normal Perl hash reference. Add keys, |
782 | or even nested hashes (or arrays) using standard Perl syntax: |
783 | |
a8fdabda |
784 | my $db = DBM::Deep->new( "foo.db" ); |
d0b74c17 |
785 | |
a8fdabda |
786 | $db->{mykey} = "myvalue"; |
787 | $db->{myhash} = {}; |
788 | $db->{myhash}->{subkey} = "subvalue"; |
ffed8b01 |
789 | |
a8fdabda |
790 | print $db->{myhash}->{subkey} . "\n"; |
ffed8b01 |
791 | |
792 | You can even step through hash keys using the normal Perl C<keys()> function: |
793 | |
a8fdabda |
794 | foreach my $key (keys %$db) { |
795 | print "$key: " . $db->{$key} . "\n"; |
796 | } |
ffed8b01 |
797 | |
798 | Remember that Perl's C<keys()> function extracts I<every> key from the hash and |
d0b74c17 |
799 | pushes them onto an array, all before the loop even begins. If you have an |
eff6a245 |
800 | extremely large hash, this may exhaust Perl's memory. Instead, consider using |
d0b74c17 |
801 | Perl's C<each()> function, which pulls keys/values one at a time, using very |
ffed8b01 |
802 | little memory: |
803 | |
a8fdabda |
804 | while (my ($key, $value) = each %$db) { |
805 | print "$key: $value\n"; |
806 | } |
ffed8b01 |
807 | |
808 | Please note that when using C<each()>, you should always pass a direct |
809 | hash reference, not a lookup. Meaning, you should B<never> do this: |
810 | |
a8fdabda |
811 | # NEVER DO THIS |
812 | while (my ($key, $value) = each %{$db->{foo}}) { # BAD |
ffed8b01 |
813 | |
814 | This causes an infinite loop, because for each iteration, Perl is calling |
815 | FETCH() on the $db handle, resulting in a "new" hash for foo every time, so |
d0b74c17 |
816 | it effectively keeps returning the first key over and over again. Instead, |
ffed8b01 |
817 | assign a temporary variable to C<$db->{foo}>, then pass that to each(). |
818 | |
819 | =head2 ARRAYS |
820 | |
821 | As with hashes, you can treat any DBM::Deep object like a normal Perl array |
d0b74c17 |
822 | reference. This includes inserting, removing and manipulating elements, |
ffed8b01 |
823 | and the C<push()>, C<pop()>, C<shift()>, C<unshift()> and C<splice()> functions. |
d0b74c17 |
824 | The object must have first been created using type C<DBM::Deep-E<gt>TYPE_ARRAY>, |
ffed8b01 |
825 | or simply be a nested array reference inside a hash. Example: |
826 | |
a8fdabda |
827 | my $db = DBM::Deep->new( |
828 | file => "foo-array.db", |
829 | type => DBM::Deep->TYPE_ARRAY |
830 | ); |
d0b74c17 |
831 | |
a8fdabda |
832 | $db->[0] = "foo"; |
833 | push @$db, "bar", "baz"; |
834 | unshift @$db, "bah"; |
d0b74c17 |
835 | |
a8fdabda |
836 | my $last_elem = pop @$db; # baz |
837 | my $first_elem = shift @$db; # bah |
838 | my $second_elem = $db->[1]; # bar |
d0b74c17 |
839 | |
a8fdabda |
840 | my $num_elements = scalar @$db; |
ffed8b01 |
841 | |
842 | =head1 OO INTERFACE |
843 | |
844 | In addition to the I<tie()> interface, you can also use a standard OO interface |
845 | to manipulate all aspects of DBM::Deep databases. Each type of object (hash or |
d0b74c17 |
846 | array) has its own methods, but both types share the following common methods: |
eff6a245 |
847 | C<put()>, C<get()>, C<exists()>, C<delete()> and C<clear()>. C<fetch()> and |
848 | C<store(> are aliases to C<put()> and C<get()>, respectively. |
ffed8b01 |
849 | |
850 | =over |
851 | |
4d35d856 |
852 | =item * new() / clone() |
853 | |
854 | These are the constructor and copy-functions. |
855 | |
90f93b43 |
856 | =item * put() / store() |
ffed8b01 |
857 | |
858 | Stores a new hash key/value pair, or sets an array element value. Takes two |
859 | arguments, the hash key or array index, and the new value. The value can be |
860 | a scalar, hash ref or array ref. Returns true on success, false on failure. |
861 | |
a8fdabda |
862 | $db->put("foo", "bar"); # for hashes |
863 | $db->put(1, "bar"); # for arrays |
ffed8b01 |
864 | |
90f93b43 |
865 | =item * get() / fetch() |
ffed8b01 |
866 | |
867 | Fetches the value of a hash key or array element. Takes one argument: the hash |
d0b74c17 |
868 | key or array index. Returns a scalar, hash ref or array ref, depending on the |
ffed8b01 |
869 | data type stored. |
870 | |
a8fdabda |
871 | my $value = $db->get("foo"); # for hashes |
872 | my $value = $db->get(1); # for arrays |
ffed8b01 |
873 | |
874 | =item * exists() |
875 | |
d0b74c17 |
876 | Checks if a hash key or array index exists. Takes one argument: the hash key |
ffed8b01 |
877 | or array index. Returns true if it exists, false if not. |
878 | |
a8fdabda |
879 | if ($db->exists("foo")) { print "yay!\n"; } # for hashes |
880 | if ($db->exists(1)) { print "yay!\n"; } # for arrays |
ffed8b01 |
881 | |
882 | =item * delete() |
883 | |
884 | Deletes one hash key/value pair or array element. Takes one argument: the hash |
885 | key or array index. Returns true on success, false if not found. For arrays, |
886 | the remaining elements located after the deleted element are NOT moved over. |
887 | The deleted element is essentially just undefined, which is exactly how Perl's |
d0b74c17 |
888 | internal arrays work. Please note that the space occupied by the deleted |
889 | key/value or element is B<not> reused again -- see L<UNUSED SPACE RECOVERY> |
ffed8b01 |
890 | below for details and workarounds. |
891 | |
a8fdabda |
892 | $db->delete("foo"); # for hashes |
893 | $db->delete(1); # for arrays |
ffed8b01 |
894 | |
895 | =item * clear() |
896 | |
d0b74c17 |
897 | Deletes B<all> hash keys or array elements. Takes no arguments. No return |
898 | value. Please note that the space occupied by the deleted keys/values or |
899 | elements is B<not> reused again -- see L<UNUSED SPACE RECOVERY> below for |
ffed8b01 |
900 | details and workarounds. |
901 | |
a8fdabda |
902 | $db->clear(); # hashes or arrays |
ffed8b01 |
903 | |
4d35d856 |
904 | =item * lock() / unlock() |
905 | |
906 | q.v. Locking. |
907 | |
908 | =item * optimize() |
909 | |
eff6a245 |
910 | Recover lost disk space. This is important to do, especially if you use |
911 | transactions. |
4d35d856 |
912 | |
913 | =item * import() / export() |
914 | |
915 | Data going in and out. |
916 | |
ffed8b01 |
917 | =back |
918 | |
919 | =head2 HASHES |
920 | |
d0b74c17 |
921 | For hashes, DBM::Deep supports all the common methods described above, and the |
ffed8b01 |
922 | following additional methods: C<first_key()> and C<next_key()>. |
923 | |
924 | =over |
925 | |
926 | =item * first_key() |
927 | |
d0b74c17 |
928 | Returns the "first" key in the hash. As with built-in Perl hashes, keys are |
929 | fetched in an undefined order (which appears random). Takes no arguments, |
ffed8b01 |
930 | returns the key as a scalar value. |
931 | |
a8fdabda |
932 | my $key = $db->first_key(); |
ffed8b01 |
933 | |
934 | =item * next_key() |
935 | |
936 | Returns the "next" key in the hash, given the previous one as the sole argument. |
937 | Returns undef if there are no more keys to be fetched. |
938 | |
a8fdabda |
939 | $key = $db->next_key($key); |
ffed8b01 |
940 | |
941 | =back |
942 | |
943 | Here are some examples of using hashes: |
944 | |
a8fdabda |
945 | my $db = DBM::Deep->new( "foo.db" ); |
d0b74c17 |
946 | |
a8fdabda |
947 | $db->put("foo", "bar"); |
948 | print "foo: " . $db->get("foo") . "\n"; |
d0b74c17 |
949 | |
a8fdabda |
950 | $db->put("baz", {}); # new child hash ref |
951 | $db->get("baz")->put("buz", "biz"); |
952 | print "buz: " . $db->get("baz")->get("buz") . "\n"; |
d0b74c17 |
953 | |
a8fdabda |
954 | my $key = $db->first_key(); |
955 | while ($key) { |
956 | print "$key: " . $db->get($key) . "\n"; |
957 | $key = $db->next_key($key); |
958 | } |
d0b74c17 |
959 | |
a8fdabda |
960 | if ($db->exists("foo")) { $db->delete("foo"); } |
ffed8b01 |
961 | |
962 | =head2 ARRAYS |
963 | |
d0b74c17 |
964 | For arrays, DBM::Deep supports all the common methods described above, and the |
965 | following additional methods: C<length()>, C<push()>, C<pop()>, C<shift()>, |
ffed8b01 |
966 | C<unshift()> and C<splice()>. |
967 | |
968 | =over |
969 | |
970 | =item * length() |
971 | |
972 | Returns the number of elements in the array. Takes no arguments. |
973 | |
a8fdabda |
974 | my $len = $db->length(); |
ffed8b01 |
975 | |
976 | =item * push() |
977 | |
d0b74c17 |
978 | Adds one or more elements onto the end of the array. Accepts scalars, hash |
ffed8b01 |
979 | refs or array refs. No return value. |
980 | |
a8fdabda |
981 | $db->push("foo", "bar", {}); |
ffed8b01 |
982 | |
983 | =item * pop() |
984 | |
985 | Fetches the last element in the array, and deletes it. Takes no arguments. |
986 | Returns undef if array is empty. Returns the element value. |
987 | |
a8fdabda |
988 | my $elem = $db->pop(); |
ffed8b01 |
989 | |
990 | =item * shift() |
991 | |
d0b74c17 |
992 | Fetches the first element in the array, deletes it, then shifts all the |
993 | remaining elements over to take up the space. Returns the element value. This |
994 | method is not recommended with large arrays -- see L<LARGE ARRAYS> below for |
ffed8b01 |
995 | details. |
996 | |
a8fdabda |
997 | my $elem = $db->shift(); |
ffed8b01 |
998 | |
999 | =item * unshift() |
1000 | |
d0b74c17 |
1001 | Inserts one or more elements onto the beginning of the array, shifting all |
1002 | existing elements over to make room. Accepts scalars, hash refs or array refs. |
1003 | No return value. This method is not recommended with large arrays -- see |
ffed8b01 |
1004 | <LARGE ARRAYS> below for details. |
1005 | |
a8fdabda |
1006 | $db->unshift("foo", "bar", {}); |
ffed8b01 |
1007 | |
1008 | =item * splice() |
1009 | |
d0b74c17 |
1010 | Performs exactly like Perl's built-in function of the same name. See L<perldoc |
ffed8b01 |
1011 | -f splice> for usage -- it is too complicated to document here. This method is |
1012 | not recommended with large arrays -- see L<LARGE ARRAYS> below for details. |
1013 | |
1014 | =back |
1015 | |
1016 | Here are some examples of using arrays: |
1017 | |
a8fdabda |
1018 | my $db = DBM::Deep->new( |
1019 | file => "foo.db", |
1020 | type => DBM::Deep->TYPE_ARRAY |
1021 | ); |
d0b74c17 |
1022 | |
a8fdabda |
1023 | $db->push("bar", "baz"); |
1024 | $db->unshift("foo"); |
1025 | $db->put(3, "buz"); |
d0b74c17 |
1026 | |
a8fdabda |
1027 | my $len = $db->length(); |
1028 | print "length: $len\n"; # 4 |
d0b74c17 |
1029 | |
a8fdabda |
1030 | for (my $k=0; $k<$len; $k++) { |
1031 | print "$k: " . $db->get($k) . "\n"; |
1032 | } |
d0b74c17 |
1033 | |
a8fdabda |
1034 | $db->splice(1, 2, "biz", "baf"); |
d0b74c17 |
1035 | |
a8fdabda |
1036 | while (my $elem = shift @$db) { |
1037 | print "shifted: $elem\n"; |
1038 | } |
ffed8b01 |
1039 | |
1040 | =head1 LOCKING |
1041 | |
d0b74c17 |
1042 | Enable automatic file locking by passing a true value to the C<locking> |
ffed8b01 |
1043 | parameter when constructing your DBM::Deep object (see L<SETUP> above). |
1044 | |
a8fdabda |
1045 | my $db = DBM::Deep->new( |
1046 | file => "foo.db", |
1047 | locking => 1 |
1048 | ); |
ffed8b01 |
1049 | |
d0b74c17 |
1050 | This causes DBM::Deep to C<flock()> the underlying filehandle with exclusive |
1051 | mode for writes, and shared mode for reads. This is required if you have |
1052 | multiple processes accessing the same database file, to avoid file corruption. |
1053 | Please note that C<flock()> does NOT work for files over NFS. See L<DB OVER |
ffed8b01 |
1054 | NFS> below for more. |
1055 | |
1056 | =head2 EXPLICIT LOCKING |
1057 | |
d0b74c17 |
1058 | You can explicitly lock a database, so it remains locked for multiple |
fa944deb |
1059 | actions. This is done by calling the C<lock()> method, and passing an |
90f93b43 |
1060 | optional lock mode argument (defaults to exclusive mode). This is particularly |
d0b74c17 |
1061 | useful for things like counters, where the current value needs to be fetched, |
ffed8b01 |
1062 | then incremented, then stored again. |
1063 | |
a8fdabda |
1064 | $db->lock(); |
1065 | my $counter = $db->get("counter"); |
1066 | $counter++; |
1067 | $db->put("counter", $counter); |
1068 | $db->unlock(); |
d0b74c17 |
1069 | |
a8fdabda |
1070 | # or... |
ffed8b01 |
1071 | |
a8fdabda |
1072 | $db->lock(); |
1073 | $db->{counter}++; |
1074 | $db->unlock(); |
ffed8b01 |
1075 | |
1076 | You can pass C<lock()> an optional argument, which specifies which mode to use |
68f943b3 |
1077 | (exclusive or shared). Use one of these two constants: |
1078 | C<DBM::Deep-E<gt>LOCK_EX> or C<DBM::Deep-E<gt>LOCK_SH>. These are passed |
1079 | directly to C<flock()>, and are the same as the constants defined in Perl's |
1080 | L<Fcntl/> module. |
ffed8b01 |
1081 | |
a8fdabda |
1082 | $db->lock( $db->LOCK_SH ); |
1083 | # something here |
1084 | $db->unlock(); |
ffed8b01 |
1085 | |
ffed8b01 |
1086 | =head1 IMPORTING/EXPORTING |
1087 | |
1088 | You can import existing complex structures by calling the C<import()> method, |
1089 | and export an entire database into an in-memory structure using the C<export()> |
1090 | method. Both are examined here. |
1091 | |
1092 | =head2 IMPORTING |
1093 | |
1094 | Say you have an existing hash with nested hashes/arrays inside it. Instead of |
d0b74c17 |
1095 | walking the structure and adding keys/elements to the database as you go, |
1096 | simply pass a reference to the C<import()> method. This recursively adds |
ffed8b01 |
1097 | everything to an existing DBM::Deep object for you. Here is an example: |
1098 | |
a8fdabda |
1099 | my $struct = { |
1100 | key1 => "value1", |
1101 | key2 => "value2", |
1102 | array1 => [ "elem0", "elem1", "elem2" ], |
1103 | hash1 => { |
1104 | subkey1 => "subvalue1", |
1105 | subkey2 => "subvalue2" |
1106 | } |
1107 | }; |
d0b74c17 |
1108 | |
a8fdabda |
1109 | my $db = DBM::Deep->new( "foo.db" ); |
1110 | $db->import( $struct ); |
d0b74c17 |
1111 | |
a8fdabda |
1112 | print $db->{key1} . "\n"; # prints "value1" |
d0b74c17 |
1113 | |
1114 | This recursively imports the entire C<$struct> object into C<$db>, including |
ffed8b01 |
1115 | all nested hashes and arrays. If the DBM::Deep object contains exsiting data, |
d0b74c17 |
1116 | keys are merged with the existing ones, replacing if they already exist. |
1117 | The C<import()> method can be called on any database level (not just the base |
ffed8b01 |
1118 | level), and works with both hash and array DB types. |
1119 | |
ffed8b01 |
1120 | B<Note:> Make sure your existing structure has no circular references in it. |
eff6a245 |
1121 | These will cause an infinite loop when importing. There are plans to fix this |
1122 | in a later release. |
ffed8b01 |
1123 | |
1124 | =head2 EXPORTING |
1125 | |
d0b74c17 |
1126 | Calling the C<export()> method on an existing DBM::Deep object will return |
1127 | a reference to a new in-memory copy of the database. The export is done |
ffed8b01 |
1128 | recursively, so all nested hashes/arrays are all exported to standard Perl |
1129 | objects. Here is an example: |
1130 | |
a8fdabda |
1131 | my $db = DBM::Deep->new( "foo.db" ); |
d0b74c17 |
1132 | |
a8fdabda |
1133 | $db->{key1} = "value1"; |
1134 | $db->{key2} = "value2"; |
1135 | $db->{hash1} = {}; |
1136 | $db->{hash1}->{subkey1} = "subvalue1"; |
1137 | $db->{hash1}->{subkey2} = "subvalue2"; |
d0b74c17 |
1138 | |
a8fdabda |
1139 | my $struct = $db->export(); |
d0b74c17 |
1140 | |
a8fdabda |
1141 | print $struct->{key1} . "\n"; # prints "value1" |
ffed8b01 |
1142 | |
1143 | This makes a complete copy of the database in memory, and returns a reference |
d0b74c17 |
1144 | to it. The C<export()> method can be called on any database level (not just |
1145 | the base level), and works with both hash and array DB types. Be careful of |
1146 | large databases -- you can store a lot more data in a DBM::Deep object than an |
ffed8b01 |
1147 | in-memory Perl structure. |
1148 | |
ffed8b01 |
1149 | B<Note:> Make sure your database has no circular references in it. |
eff6a245 |
1150 | These will cause an infinite loop when exporting. There are plans to fix this |
1151 | in a later release. |
ffed8b01 |
1152 | |
1153 | =head1 FILTERS |
1154 | |
1155 | DBM::Deep has a number of hooks where you can specify your own Perl function |
1156 | to perform filtering on incoming or outgoing data. This is a perfect |
1157 | way to extend the engine, and implement things like real-time compression or |
d0b74c17 |
1158 | encryption. Filtering applies to the base DB level, and all child hashes / |
1159 | arrays. Filter hooks can be specified when your DBM::Deep object is first |
1160 | constructed, or by calling the C<set_filter()> method at any time. There are |
ffed8b01 |
1161 | four available filter hooks, described below: |
1162 | |
1163 | =over |
1164 | |
1165 | =item * filter_store_key |
1166 | |
d0b74c17 |
1167 | This filter is called whenever a hash key is stored. It |
ffed8b01 |
1168 | is passed the incoming key, and expected to return a transformed key. |
1169 | |
1170 | =item * filter_store_value |
1171 | |
d0b74c17 |
1172 | This filter is called whenever a hash key or array element is stored. It |
ffed8b01 |
1173 | is passed the incoming value, and expected to return a transformed value. |
1174 | |
1175 | =item * filter_fetch_key |
1176 | |
d0b74c17 |
1177 | This filter is called whenever a hash key is fetched (i.e. via |
ffed8b01 |
1178 | C<first_key()> or C<next_key()>). It is passed the transformed key, |
1179 | and expected to return the plain key. |
1180 | |
1181 | =item * filter_fetch_value |
1182 | |
d0b74c17 |
1183 | This filter is called whenever a hash key or array element is fetched. |
ffed8b01 |
1184 | It is passed the transformed value, and expected to return the plain value. |
1185 | |
1186 | =back |
1187 | |
1188 | Here are the two ways to setup a filter hook: |
1189 | |
a8fdabda |
1190 | my $db = DBM::Deep->new( |
1191 | file => "foo.db", |
1192 | filter_store_value => \&my_filter_store, |
1193 | filter_fetch_value => \&my_filter_fetch |
1194 | ); |
d0b74c17 |
1195 | |
a8fdabda |
1196 | # or... |
d0b74c17 |
1197 | |
a8fdabda |
1198 | $db->set_filter( "filter_store_value", \&my_filter_store ); |
1199 | $db->set_filter( "filter_fetch_value", \&my_filter_fetch ); |
ffed8b01 |
1200 | |
1201 | Your filter function will be called only when dealing with SCALAR keys or |
1202 | values. When nested hashes and arrays are being stored/fetched, filtering |
d0b74c17 |
1203 | is bypassed. Filters are called as static functions, passed a single SCALAR |
ffed8b01 |
1204 | argument, and expected to return a single SCALAR value. If you want to |
1205 | remove a filter, set the function reference to C<undef>: |
1206 | |
a8fdabda |
1207 | $db->set_filter( "filter_store_value", undef ); |
ffed8b01 |
1208 | |
1209 | =head2 REAL-TIME ENCRYPTION EXAMPLE |
1210 | |
d0b74c17 |
1211 | Here is a working example that uses the I<Crypt::Blowfish> module to |
ffed8b01 |
1212 | do real-time encryption / decryption of keys & values with DBM::Deep Filters. |
d0b74c17 |
1213 | Please visit L<http://search.cpan.org/search?module=Crypt::Blowfish> for more |
ffed8b01 |
1214 | on I<Crypt::Blowfish>. You'll also need the I<Crypt::CBC> module. |
1215 | |
a8fdabda |
1216 | use DBM::Deep; |
1217 | use Crypt::Blowfish; |
1218 | use Crypt::CBC; |
1219 | |
1220 | my $cipher = Crypt::CBC->new({ |
1221 | 'key' => 'my secret key', |
1222 | 'cipher' => 'Blowfish', |
1223 | 'iv' => '$KJh#(}q', |
1224 | 'regenerate_key' => 0, |
1225 | 'padding' => 'space', |
1226 | 'prepend_iv' => 0 |
1227 | }); |
1228 | |
1229 | my $db = DBM::Deep->new( |
1230 | file => "foo-encrypt.db", |
1231 | filter_store_key => \&my_encrypt, |
1232 | filter_store_value => \&my_encrypt, |
1233 | filter_fetch_key => \&my_decrypt, |
1234 | filter_fetch_value => \&my_decrypt, |
1235 | ); |
1236 | |
1237 | $db->{key1} = "value1"; |
1238 | $db->{key2} = "value2"; |
1239 | print "key1: " . $db->{key1} . "\n"; |
1240 | print "key2: " . $db->{key2} . "\n"; |
1241 | |
1242 | undef $db; |
1243 | exit; |
1244 | |
1245 | sub my_encrypt { |
1246 | return $cipher->encrypt( $_[0] ); |
1247 | } |
1248 | sub my_decrypt { |
1249 | return $cipher->decrypt( $_[0] ); |
1250 | } |
ffed8b01 |
1251 | |
1252 | =head2 REAL-TIME COMPRESSION EXAMPLE |
1253 | |
1254 | Here is a working example that uses the I<Compress::Zlib> module to do real-time |
1255 | compression / decompression of keys & values with DBM::Deep Filters. |
d0b74c17 |
1256 | Please visit L<http://search.cpan.org/search?module=Compress::Zlib> for |
ffed8b01 |
1257 | more on I<Compress::Zlib>. |
1258 | |
a8fdabda |
1259 | use DBM::Deep; |
1260 | use Compress::Zlib; |
1261 | |
1262 | my $db = DBM::Deep->new( |
1263 | file => "foo-compress.db", |
1264 | filter_store_key => \&my_compress, |
1265 | filter_store_value => \&my_compress, |
1266 | filter_fetch_key => \&my_decompress, |
1267 | filter_fetch_value => \&my_decompress, |
1268 | ); |
1269 | |
1270 | $db->{key1} = "value1"; |
1271 | $db->{key2} = "value2"; |
1272 | print "key1: " . $db->{key1} . "\n"; |
1273 | print "key2: " . $db->{key2} . "\n"; |
1274 | |
1275 | undef $db; |
1276 | exit; |
1277 | |
1278 | sub my_compress { |
1279 | return Compress::Zlib::memGzip( $_[0] ) ; |
1280 | } |
1281 | sub my_decompress { |
1282 | return Compress::Zlib::memGunzip( $_[0] ) ; |
1283 | } |
ffed8b01 |
1284 | |
1285 | B<Note:> Filtering of keys only applies to hashes. Array "keys" are |
1286 | actually numerical index numbers, and are not filtered. |
1287 | |
1288 | =head1 ERROR HANDLING |
1289 | |
1290 | Most DBM::Deep methods return a true value for success, and call die() on |
95967a5e |
1291 | failure. You can wrap calls in an eval block to catch the die. |
ffed8b01 |
1292 | |
a8fdabda |
1293 | my $db = DBM::Deep->new( "foo.db" ); # create hash |
1294 | eval { $db->push("foo"); }; # ILLEGAL -- push is array-only call |
d0b74c17 |
1295 | |
a8fdabda |
1296 | print $@; # prints error message |
429e4192 |
1297 | |
ffed8b01 |
1298 | =head1 LARGEFILE SUPPORT |
1299 | |
1300 | If you have a 64-bit system, and your Perl is compiled with both LARGEFILE |
1301 | and 64-bit support, you I<may> be able to create databases larger than 2 GB. |
1302 | DBM::Deep by default uses 32-bit file offset tags, but these can be changed |
044e6288 |
1303 | by specifying the 'pack_size' parameter when constructing the file. |
ffed8b01 |
1304 | |
a8fdabda |
1305 | DBM::Deep->new( |
1306 | filename => $filename, |
1307 | pack_size => 'large', |
1308 | ); |
ffed8b01 |
1309 | |
d0b74c17 |
1310 | This tells DBM::Deep to pack all file offsets with 8-byte (64-bit) quad words |
1311 | instead of 32-bit longs. After setting these values your DB files have a |
ffed8b01 |
1312 | theoretical maximum size of 16 XB (exabytes). |
1313 | |
044e6288 |
1314 | You can also use C<pack_size =E<gt> 'small'> in order to use 16-bit file |
1315 | offsets. |
1316 | |
ffed8b01 |
1317 | B<Note:> Changing these values will B<NOT> work for existing database files. |
044e6288 |
1318 | Only change this for new files. Once the value has been set, it is stored in |
1319 | the file's header and cannot be changed for the life of the file. These |
1320 | parameters are per-file, meaning you can access 32-bit and 64-bit files, as |
fa944deb |
1321 | you choose. |
ffed8b01 |
1322 | |
044e6288 |
1323 | B<Note:> We have not personally tested files larger than 2 GB -- all my |
1324 | systems have only a 32-bit Perl. However, I have received user reports that |
1325 | this does indeed work! |
ffed8b01 |
1326 | |
1327 | =head1 LOW-LEVEL ACCESS |
1328 | |
90f93b43 |
1329 | If you require low-level access to the underlying filehandle that DBM::Deep uses, |
4d35d856 |
1330 | you can call the C<_fh()> method, which returns the handle: |
ffed8b01 |
1331 | |
a8fdabda |
1332 | my $fh = $db->_fh(); |
ffed8b01 |
1333 | |
1334 | This method can be called on the root level of the datbase, or any child |
1335 | hashes or arrays. All levels share a I<root> structure, which contains things |
90f93b43 |
1336 | like the filehandle, a reference counter, and all the options specified |
460b1067 |
1337 | when you created the object. You can get access to this file object by |
83371fe3 |
1338 | calling the C<_storage()> method. |
ffed8b01 |
1339 | |
83371fe3 |
1340 | my $file_obj = $db->_storage(); |
ffed8b01 |
1341 | |
1342 | This is useful for changing options after the object has already been created, |
f5be9b03 |
1343 | such as enabling/disabling locking. You can also store your own temporary user |
1344 | data in this structure (be wary of name collision), which is then accessible from |
1345 | any child hash or array. |
ffed8b01 |
1346 | |
1347 | =head1 CUSTOM DIGEST ALGORITHM |
1348 | |
1349 | DBM::Deep by default uses the I<Message Digest 5> (MD5) algorithm for hashing |
1350 | keys. However you can override this, and use another algorithm (such as SHA-256) |
d0b74c17 |
1351 | or even write your own. But please note that DBM::Deep currently expects zero |
044e6288 |
1352 | collisions, so your algorithm has to be I<perfect>, so to speak. Collision |
1353 | detection may be introduced in a later version. |
ffed8b01 |
1354 | |
044e6288 |
1355 | You can specify a custom digest algorithm by passing it into the parameter |
1356 | list for new(), passing a reference to a subroutine as the 'digest' parameter, |
1357 | and the length of the algorithm's hashes (in bytes) as the 'hash_size' |
1358 | parameter. Here is a working example that uses a 256-bit hash from the |
d0b74c17 |
1359 | I<Digest::SHA256> module. Please see |
044e6288 |
1360 | L<http://search.cpan.org/search?module=Digest::SHA256> for more information. |
ffed8b01 |
1361 | |
a8fdabda |
1362 | use DBM::Deep; |
1363 | use Digest::SHA256; |
d0b74c17 |
1364 | |
a8fdabda |
1365 | my $context = Digest::SHA256::new(256); |
d0b74c17 |
1366 | |
a8fdabda |
1367 | my $db = DBM::Deep->new( |
1368 | filename => "foo-sha.db", |
1369 | digest => \&my_digest, |
1370 | hash_size => 32, |
1371 | ); |
d0b74c17 |
1372 | |
a8fdabda |
1373 | $db->{key1} = "value1"; |
1374 | $db->{key2} = "value2"; |
1375 | print "key1: " . $db->{key1} . "\n"; |
1376 | print "key2: " . $db->{key2} . "\n"; |
d0b74c17 |
1377 | |
a8fdabda |
1378 | undef $db; |
1379 | exit; |
d0b74c17 |
1380 | |
a8fdabda |
1381 | sub my_digest { |
1382 | return substr( $context->hash($_[0]), 0, 32 ); |
1383 | } |
ffed8b01 |
1384 | |
1385 | B<Note:> Your returned digest strings must be B<EXACTLY> the number |
044e6288 |
1386 | of bytes you specify in the hash_size parameter (in this case 32). |
ffed8b01 |
1387 | |
260a80b4 |
1388 | B<Note:> If you do choose to use a custom digest algorithm, you must set it |
1389 | every time you access this file. Otherwise, the default (MD5) will be used. |
1390 | |
ffed8b01 |
1391 | =head1 CIRCULAR REFERENCES |
1392 | |
fa944deb |
1393 | B<NOTE>: DBM::Deep 0.99_03 has turned off circular references pending |
1394 | evaluation of some edge cases. I hope to be able to re-enable circular |
1395 | references in a future version prior to 1.00. |
1396 | |
ffed8b01 |
1397 | DBM::Deep has B<experimental> support for circular references. Meaning you |
1398 | can have a nested hash key or array element that points to a parent object. |
1399 | This relationship is stored in the DB file, and is preserved between sessions. |
1400 | Here is an example: |
1401 | |
a8fdabda |
1402 | my $db = DBM::Deep->new( "foo.db" ); |
d0b74c17 |
1403 | |
a8fdabda |
1404 | $db->{foo} = "bar"; |
1405 | $db->{circle} = $db; # ref to self |
d0b74c17 |
1406 | |
a8fdabda |
1407 | print $db->{foo} . "\n"; # prints "bar" |
1408 | print $db->{circle}->{foo} . "\n"; # prints "bar" again |
ffed8b01 |
1409 | |
69c94980 |
1410 | B<Note>: Passing the object to a function that recursively walks the |
ffed8b01 |
1411 | object tree (such as I<Data::Dumper> or even the built-in C<optimize()> or |
69c94980 |
1412 | C<export()> methods) will result in an infinite loop. This will be fixed in |
1413 | a future release. |
ffed8b01 |
1414 | |
eff6a245 |
1415 | =head1 TRANSACTIONS |
1416 | |
1417 | New in 0.99_01 is ACID transactions. Every DBM::Deep object is completely |
1418 | transaction-ready - it is not an option you have to turn on. Three new methods |
1419 | have been added to support them. They are: |
1420 | |
1421 | =over 4 |
1422 | |
1423 | =item * begin_work() |
1424 | |
1425 | This starts a transaction. |
1426 | |
1427 | =item * commit() |
1428 | |
1429 | This applies the changes done within the transaction to the mainline and ends |
1430 | the transaction. |
1431 | |
1432 | =item * rollback() |
1433 | |
1434 | This discards the changes done within the transaction to the mainline and ends |
1435 | the transaction. |
1436 | |
1437 | =back |
1438 | |
1439 | Transactions in DBM::Deep are done using the MVCC method, the same method used |
1440 | by the InnoDB MySQL table type. |
1441 | |
ffed8b01 |
1442 | =head1 CAVEATS / ISSUES / BUGS |
1443 | |
1444 | This section describes all the known issues with DBM::Deep. It you have found |
1445 | something that is not listed here, please send e-mail to L<jhuckaby@cpan.org>. |
1446 | |
eea0d863 |
1447 | =head2 REFERENCES |
1448 | |
1449 | (The reasons given assume a high level of Perl understanding, specifically of |
1450 | references. You can safely skip this section.) |
1451 | |
1452 | Currently, the only references supported are HASH and ARRAY. The other reference |
1453 | types (SCALAR, CODE, GLOB, and REF) cannot be supported for various reasons. |
1454 | |
1455 | =over 4 |
1456 | |
1457 | =item * GLOB |
1458 | |
1459 | These are things like filehandles and other sockets. They can't be supported |
1460 | because it's completely unclear how DBM::Deep should serialize them. |
1461 | |
1462 | =item * SCALAR / REF |
1463 | |
1464 | The discussion here refers to the following type of example: |
1465 | |
1466 | my $x = 25; |
1467 | $db->{key1} = \$x; |
1468 | |
1469 | $x = 50; |
1470 | |
1471 | # In some other process ... |
1472 | |
1473 | my $val = ${ $db->{key1} }; |
1474 | |
1475 | is( $val, 50, "What actually gets stored in the DB file?" ); |
1476 | |
1477 | The problem is one of synchronization. When the variable being referred to |
1478 | changes value, the reference isn't notified. This means that the new value won't |
1479 | be stored in the datafile for other processes to read. There is no TIEREF. |
1480 | |
1481 | It is theoretically possible to store references to values already within a |
1482 | DBM::Deep object because everything already is synchronized, but the change to |
1483 | the internals would be quite large. Specifically, DBM::Deep would have to tie |
1484 | every single value that is stored. This would bloat the RAM footprint of |
1485 | DBM::Deep at least twofold (if not more) and be a significant performance drain, |
1486 | all to support a feature that has never been requested. |
1487 | |
1488 | =item * CODE |
1489 | |
1990c72d |
1490 | L<Data::Dump::Streamer/> provides a mechanism for serializing coderefs, |
1491 | including saving off all closure state. However, just as for SCALAR and REF, |
1492 | that closure state may change without notifying the DBM::Deep object storing |
1493 | the reference. |
eea0d863 |
1494 | |
1495 | =back |
1496 | |
ffed8b01 |
1497 | =head2 FILE CORRUPTION |
1498 | |
14a3acb6 |
1499 | The current level of error handling in DBM::Deep is minimal. Files I<are> checked |
1500 | for a 32-bit signature when opened, but other corruption in files can cause |
1501 | segmentation faults. DBM::Deep may try to seek() past the end of a file, or get |
ffed8b01 |
1502 | stuck in an infinite loop depending on the level of corruption. File write |
1503 | operations are not checked for failure (for speed), so if you happen to run |
d0b74c17 |
1504 | out of disk space, DBM::Deep will probably fail in a bad way. These things will |
ffed8b01 |
1505 | be addressed in a later version of DBM::Deep. |
1506 | |
1507 | =head2 DB OVER NFS |
1508 | |
d8db2929 |
1509 | Beware of using DBM::Deep files over NFS. DBM::Deep uses flock(), which works |
1510 | well on local filesystems, but will NOT protect you from file corruption over |
1511 | NFS. I've heard about setting up your NFS server with a locking daemon, then |
1512 | using lockf() to lock your files, but your mileage may vary there as well. |
1513 | From what I understand, there is no real way to do it. However, if you need |
1514 | access to the underlying filehandle in DBM::Deep for using some other kind of |
1515 | locking scheme like lockf(), see the L<LOW-LEVEL ACCESS> section above. |
ffed8b01 |
1516 | |
1517 | =head2 COPYING OBJECTS |
1518 | |
d0b74c17 |
1519 | Beware of copying tied objects in Perl. Very strange things can happen. |
1520 | Instead, use DBM::Deep's C<clone()> method which safely copies the object and |
ffed8b01 |
1521 | returns a new, blessed, tied hash or array to the same level in the DB. |
1522 | |
a8fdabda |
1523 | my $copy = $db->clone(); |
ffed8b01 |
1524 | |
90f93b43 |
1525 | B<Note>: Since clone() here is cloning the object, not the database location, any |
d8db2929 |
1526 | modifications to either $db or $copy will be visible to both. |
90f93b43 |
1527 | |
ffed8b01 |
1528 | =head2 LARGE ARRAYS |
1529 | |
1530 | Beware of using C<shift()>, C<unshift()> or C<splice()> with large arrays. |
1531 | These functions cause every element in the array to move, which can be murder |
1532 | on DBM::Deep, as every element has to be fetched from disk, then stored again in |
fa944deb |
1533 | a different location. This will be addressed in a future version. |
ffed8b01 |
1534 | |
9be51a89 |
1535 | =head2 WRITEONLY FILES |
1536 | |
1537 | If you pass in a filehandle to new(), you may have opened it in either a readonly or |
1538 | writeonly mode. STORE will verify that the filehandle is writable. However, there |
1539 | doesn't seem to be a good way to determine if a filehandle is readable. And, if the |
1540 | filehandle isn't readable, it's not clear what will happen. So, don't do that. |
1541 | |
261d1296 |
1542 | =head1 CODE COVERAGE |
1543 | |
eff6a245 |
1544 | B<Devel::Cover> is used to test the code coverage of the tests. Below is the |
1545 | B<Devel::Cover> report on this distribution's test suite. |
7910cf68 |
1546 | |
eff6a245 |
1547 | ---------------------------- ------ ------ ------ ------ ------ ------ ------ |
1548 | File stmt bran cond sub pod time total |
1549 | ---------------------------- ------ ------ ------ ------ ------ ------ ------ |
fa944deb |
1550 | blib/lib/DBM/Deep.pm 87.7 81.0 81.0 93.9 89.5 4.2 87.2 |
1551 | blib/lib/DBM/Deep/Array.pm 95.9 88.3 100.0 96.4 100.0 4.9 94.5 |
1552 | blib/lib/DBM/Deep/Engine.pm 94.3 83.9 78.0 94.6 0.0 60.0 87.9 |
1553 | blib/lib/DBM/Deep/File.pm 88.5 76.2 45.5 93.8 0.0 28.9 78.8 |
1554 | blib/lib/DBM/Deep/Hash.pm 98.5 83.3 100.0 100.0 100.0 2.1 96.3 |
1555 | Total 93.0 83.4 77.5 95.0 31.6 100.0 88.3 |
eff6a245 |
1556 | ---------------------------- ------ ------ ------ ------ ------ ------ ------ |
37c5bcf0 |
1557 | =head1 MORE INFORMATION |
1558 | |
1559 | Check out the DBM::Deep Google Group at L<http://groups.google.com/group/DBM-Deep> |
eff6a245 |
1560 | or send email to L<DBM-Deep@googlegroups.com>. You can also visit #dbm-deep on |
1561 | irc.perl.org |
ffed8b01 |
1562 | |
d8db2929 |
1563 | The source code repository is at L<http://svn.perl.org/modules/DBM-Deep> |
1564 | |
fa944deb |
1565 | =head1 MAINTAINER(S) |
37c5bcf0 |
1566 | |
aeeb5497 |
1567 | Rob Kinyon, L<rkinyon@cpan.org> |
ffed8b01 |
1568 | |
eff6a245 |
1569 | Originally written by Joseph Huckaby, L<jhuckaby@cpan.org> |
1570 | |
ffed8b01 |
1571 | Special thanks to Adam Sah and Rich Gaushell! You know why :-) |
1572 | |
fa944deb |
1573 | Additional thanks go out to Stonehenge who have sponsored the 1.00 release. |
1574 | |
ffed8b01 |
1575 | =head1 SEE ALSO |
1576 | |
1577 | perltie(1), Tie::Hash(3), Digest::MD5(3), Fcntl(3), flock(2), lockf(3), nfs(5), |
1578 | Digest::SHA256(3), Crypt::Blowfish(3), Compress::Zlib(3) |
1579 | |
1580 | =head1 LICENSE |
1581 | |
fa944deb |
1582 | Copyright (c) 2007 Rob Kinyon. All Rights Reserved. |
ffed8b01 |
1583 | This is free software, you may use it and distribute it under the |
1584 | same terms as Perl itself. |
1585 | |
1586 | =cut |