MLDBM(3) | User Contributed Perl Documentation | MLDBM(3) |
MLDBM - store multi-level Perl hash structure in single level tied hash
use MLDBM; # this gets the default, SDBM #use MLDBM qw(DB_File FreezeThaw); # use FreezeThaw for serializing #use MLDBM qw(DB_File Storable); # use Storable for serializing $dbm = tie %o, 'MLDBM' [..other DBM args..] or die $!;
This module can serve as a transparent interface to any TIEHASH package that is required to store arbitrary perl data, including nested references. Thus, this module can be used for storing references and other arbitrary data within DBM databases.
It works by serializing the references in the hash into a single string. In the underlying TIEHASH package (usually a DBM database), it is this string that gets stored. When the value is fetched again, the string is deserialized to reconstruct the data structure into memory.
For historical and practical reasons, it requires the Data::Dumper package, available at any CPAN site. Data::Dumper gives you really nice-looking dumps of your data structures, in case you wish to look at them on the screen, and it was the only serializing engine before version 2.00. However, as of version 2.00, you can use any of Data::Dumper, FreezeThaw or Storable to perform the underlying serialization, as hinted at by the SYNOPSIS overview above. Using Storable is usually much faster than the other methods.
See the BUGS section for important limitations.
MLDBM relies on an underlying TIEHASH implementation (usually a DBM package), and an underlying serialization package. The respective defaults are SDBM_File and Data::Dumper. Both of these defaults can be changed. Changing the SDBM_File default is strongly recommended. See WARNINGS below.
Three serialization wrappers are currently supported: Data::Dumper, Storable, and FreezeThaw. Additional serializers can be supported by writing a wrapper that implements the interface required by MLDBM::Serializer. See the supported wrappers and the MLDBM::Serializer source for details.
In the following, $OBJ stands for the tied object, as in:
$obj = tie %o, .... $obj = tied %o;
The corresponding method call returns the underlying TIEHASH object when called without arguments. It can be called with any object that implements Perl's TIEHASH interface, to set that value.
The corresponding method call returns the underlying MLDBM serializer object when called without arguments. It can be called with an object that implements the MLDBM serializer interface, to set that value.
These methods are meant to supply an interface to the properties of the underlying serializer used. Do not call or set them without understanding the consequences in full. The defaults are usually sensible.
Not all of these necessarily apply to all the supplied serializers, so we specify when to apply them. Failure to respect this will usually lead to an exception.
With Data::Dumper (which offers a pure Perl and an XS verion of its serializing routine), this is set to "Dumpxs" by default if that is supported in your installation. Otherwise, defaults to the slower "Dump" method.
With Storable, a value of "portable" requests that serialization be architecture neutral, i.e. the deserialization can later occur on another platform. Of course, this only makes sense if your database files are themselves architecture neutral. By default, native format is used for greater serializing speed in Storable. Both Data::Dumper and FreezeThaw are always architecture neutral.
FreezeThaw does not honor this attribute.
Defaults to the magic string used to recognize MLDBM data. It is a six character wide, unique string. This is best left alone, unless you know what you are doing.
Storable and FreezeThaw do not honor this attribute.
Data::Dumper uses "eval()" to deserialize and is therefore subject to taint checks. Can be set to a true value to make the Data::Dumper serializer untaint the data retrieved. It is not enabled by default. Use with care.
Storable and FreezeThaw do not honor this attribute.
Here is a simple example. Note that does not depend upon the underlying serializing package--most real life examples should not, usually.
use MLDBM; # this gets SDBM and Data::Dumper #use MLDBM qw(SDBM_File Storable); # SDBM and Storable use Fcntl; # to get 'em constants $dbm = tie %o, 'MLDBM', 'testmldbm', O_CREAT|O_RDWR, 0640 or die $!; $c = [\ 'c']; $b = {}; $a = [1, $b, $c]; $b->{a} = $a; $b->{b} = $a->[1]; $b->{c} = $a->[2]; @o{qw(a b c)} = ($a, $b, $c); # # to see what was stored # use Data::Dumper; print Data::Dumper->Dump([@o{qw(a b c)}], [qw(a b c)]); # # to modify data in a substructure # $tmp = $o{a}; $tmp->[0] = 'foo'; $o{a} = $tmp; # # can access the underlying DBM methods transparently # #print $dbm->fd, "\n"; # DB_File method
Here is another small example using Storable, in a portable format:
use MLDBM qw(DB_File Storable); # DB_File and Storable tie %o, 'MLDBM', 'testmldbm', O_CREAT|O_RDWR, 0640 or die $!; (tied %o)->DumpMeth('portable'); # Ask for portable binary $o{'ENV'} = \%ENV; # Stores the whole environment
$mldb{key}{subkey}[3] = 'stuff'; # won't work
Instead, that must be written as:
$tmp = $mldb{key}; # retrieve value $tmp->{subkey}[3] = 'stuff'; $mldb{key} = $tmp; # store value
This limitation exists because the perl TIEHASH interface currently has no support for multidimensional ties.
Too often, people end up writing something like this:
tie %h, 'MLDBM', ...; for my $k (keys %{$h{something}}) { print $h{something}{$k}[0]{foo}{bar}; # FETCH _every_ time! }
when it should be written this for efficiency:
tie %h, 'MLDBM', ...; my $root = $h{something}; # FETCH _once_ for my $k (keys %$root) { print $k->[0]{foo}{bar}; }
Gurusamy Sarathy <gsar@umich.edu>.
Support for multiple serializing packages by Raphael Manfredi <Raphael_Manfredi@grenoble.hp.com>.
Test suite fixes for perl 5.8.0 done by Josh Chamas.
Copyright (c) 1995-98 Gurusamy Sarathy. All rights reserved.
Copyright (c) 1998 Raphael Manfredi.
Copyright (c) 2002 Josh Chamas, Chamas Enterprises Inc.
Copyright (c) 2010-2013 Alexandr Ciornii (alexchorny@gmail.com).
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Version 2.05
perl(1), perltie(1), perlfunc(1), Data::Dumper, FreezeThaw, Storable, DBM::Deep, MLDBM::Serializer::JSON.
2024-04-13 | perl v5.34.0 |