1MLDBM(3)              User Contributed Perl Documentation             MLDBM(3)
2
3
4

NAME

6       MLDBM - store multi-level Perl hash structure in single level tied hash
7

SYNOPSIS

9           use MLDBM;                          # this gets the default, SDBM
10           #use MLDBM qw(DB_File FreezeThaw);  # use FreezeThaw for serializing
11           #use MLDBM qw(DB_File Storable);    # use Storable for serializing
12
13           $dbm = tie %o, 'MLDBM' [..other DBM args..] or die $!;
14

DESCRIPTION

16       This module can serve as a transparent interface to any TIEHASH package
17       that is required to store arbitrary perl data, including nested
18       references.  Thus, this module can be used for storing references and
19       other arbitrary data within DBM databases.
20
21       It works by serializing the references in the hash into a single
22       string. In the underlying TIEHASH package (usually a DBM database), it
23       is this string that gets stored.  When the value is fetched again, the
24       string is deserialized to reconstruct the data structure into memory.
25
26       For historical and practical reasons, it requires the Data::Dumper
27       package, available at any CPAN site. Data::Dumper gives you really
28       nice-looking dumps of your data structures, in case you wish to look at
29       them on the screen, and it was the only serializing engine before
30       version 2.00.  However, as of version 2.00, you can use any of
31       Data::Dumper, FreezeThaw or Storable to perform the underlying
32       serialization, as hinted at by the SYNOPSIS overview above.  Using
33       Storable is usually much faster than the other methods.
34
35       See the BUGS section for important limitations.
36
37   Changing the Defaults
38       MLDBM relies on an underlying TIEHASH implementation (usually a DBM
39       package), and an underlying serialization package.  The respective
40       defaults are SDBM_File and Data::Dumper.  Both of these defaults can be
41       changed.  Changing the SDBM_File default is strongly recommended.  See
42       WARNINGS below.
43
44       Three serialization wrappers are currently supported: Data::Dumper,
45       Storable, and FreezeThaw.  Additional serializers can be supported by
46       writing a wrapper that implements the interface required by
47       MLDBM::Serializer.  See the supported wrappers and the
48       MLDBM::Serializer source for details.
49
50       In the following, $OBJ stands for the tied object, as in:
51
52               $obj = tie %o, ....
53               $obj = tied %o;
54
55       $MLDBM::UseDB  or   $OBJ->UseDB([TIEDOBJECT])
56           The global $MLDBM::UseDB can be set to default to something other
57           than "SDBM_File", in case you have a more efficient DBM, or if you
58           want to use this with some other TIEHASH implementation.
59           Alternatively, you can specify the name of the package at "use"
60           time, as the first "parameter".  Nested module names can be
61           specified as "Foo::Bar".
62
63           The corresponding method call returns the underlying TIEHASH object
64           when called without arguments.  It can be called with any object
65           that implements Perl's TIEHASH interface, to set that value.
66
67       $MLDBM::Serializer  or   $OBJ->Serializer([SZROBJECT])
68           The global $MLDBM::Serializer can be set to the name of the
69           serializing package to be used. Currently can be set to one of
70           "Data::Dumper", "Storable", or "FreezeThaw". Defaults to
71           "Data::Dumper".  Alternatively, you can specify the name of the
72           serializer package at "use" time, as the second "parameter".
73
74           The corresponding method call returns the underlying MLDBM
75           serializer object when called without arguments.  It can be called
76           with an object that implements the MLDBM serializer interface, to
77           set that value.
78
79   Controlling Serializer Properties
80       These methods are meant to supply an interface to the properties of the
81       underlying serializer used.  Do not call or set them without
82       understanding the consequences in full.  The defaults are usually
83       sensible.
84
85       Not all of these necessarily apply to all the supplied serializers, so
86       we specify when to apply them.  Failure to respect this will usually
87       lead to an exception.
88
89       $MLDBM::DumpMeth    or  $OBJ->DumpMeth([METHNAME])
90           If the serializer provides alternative serialization methods, this
91           can be used to set them.
92
93           With Data::Dumper (which offers a pure Perl and an XS verion of its
94           serializing routine), this is set to "Dumpxs" by default if that is
95           supported in your installation.  Otherwise, defaults to the slower
96           "Dump" method.
97
98           With Storable, a value of "portable" requests that serialization be
99           architecture neutral, i.e. the deserialization can later occur on
100           another platform. Of course, this only makes sense if your database
101           files are themselves architecture neutral.  By default, native
102           format is used for greater serializing speed in Storable.  Both
103           Data::Dumper and FreezeThaw are always architecture neutral.
104
105           FreezeThaw does not honor this attribute.
106
107       $MLDBM::Key  or  $OBJ->Key([KEYSTRING])
108           If the serializer only deals with part of the data (perhaps because
109           the TIEHASH object can natively store some types of data), it may
110           need a unique key string to recognize the data it handles.  This
111           can be used to set that string.  Best left alone.
112
113           Defaults to the magic string used to recognize MLDBM data. It is a
114           six character wide, unique string. This is best left alone, unless
115           you know what you are doing.
116
117           Storable and FreezeThaw do not honor this attribute.
118
119       $MLDBM::RemoveTaint  or  $OBJ->RemoveTaint([BOOL])
120           If the serializer can optionally untaint any retrieved data subject
121           to taint checks in Perl, this can be used to request that feature.
122           Data that comes from external sources (like disk-files) must always
123           be viewed with caution, so use this only when you are sure that
124           that is not an issue.
125
126           Data::Dumper uses "eval()" to deserialize and is therefore subject
127           to taint checks.  Can be set to a true value to make the
128           Data::Dumper serializer untaint the data retrieved. It is not
129           enabled by default.  Use with care.
130
131           Storable and FreezeThaw do not honor this attribute.
132

EXAMPLES

134       Here is a simple example.  Note that does not depend upon the
135       underlying serializing package--most real life examples should not,
136       usually.
137
138           use MLDBM;                          # this gets SDBM and Data::Dumper
139           #use MLDBM qw(SDBM_File Storable);  # SDBM and Storable
140           use Fcntl;                          # to get 'em constants
141
142           $dbm = tie %o, 'MLDBM', 'testmldbm', O_CREAT|O_RDWR, 0640 or die $!;
143
144           $c = [\ 'c'];
145           $b = {};
146           $a = [1, $b, $c];
147           $b->{a} = $a;
148           $b->{b} = $a->[1];
149           $b->{c} = $a->[2];
150           @o{qw(a b c)} = ($a, $b, $c);
151
152           #
153           # to see what was stored
154           #
155           use Data::Dumper;
156           print Data::Dumper->Dump([@o{qw(a b c)}], [qw(a b c)]);
157
158           #
159           # to modify data in a substructure
160           #
161           $tmp = $o{a};
162           $tmp->[0] = 'foo';
163           $o{a} = $tmp;
164
165           #
166           # can access the underlying DBM methods transparently
167           #
168           #print $dbm->fd, "\n";              # DB_File method
169
170       Here is another small example using Storable, in a portable format:
171
172           use MLDBM qw(DB_File Storable);     # DB_File and Storable
173
174           tie %o, 'MLDBM', 'testmldbm', O_CREAT|O_RDWR, 0640 or die $!;
175
176           (tied %o)->DumpMeth('portable');    # Ask for portable binary
177           $o{'ENV'} = \%ENV;                  # Stores the whole environment
178

BUGS

180       1.  Adding or altering substructures to a hash value is not entirely
181           transparent in current perl.  If you want to store a reference or
182           modify an existing reference value in the DBM, it must first be
183           retrieved and stored in a temporary variable for further
184           modifications.  In particular, something like this will NOT work
185           properly:
186
187                   $mldb{key}{subkey}[3] = 'stuff';        # won't work
188
189           Instead, that must be written as:
190
191                   $tmp = $mldb{key};                      # retrieve value
192                   $tmp->{subkey}[3] = 'stuff';
193                   $mldb{key} = $tmp;                      # store value
194
195           This limitation exists because the perl TIEHASH interface currently
196           has no support for multidimensional ties.
197
198       2.  The Data::Dumper serializer uses eval().  A lot.  Try the Storable
199           serializer, which is generally the most efficient.
200

WARNINGS

202       1.  Many DBM implementations have arbitrary limits on the size of
203           records that can be stored.  For example, SDBM and many ODBM or
204           NDBM implementations have a default limit of 1024 bytes for the
205           size of a record.  MLDBM can easily exceed these limits when
206           storing large data structures, leading to mysterious failures.
207           Although SDBM_File is used by MLDBM by default, it is not a good
208           choice if you're storing large data structures.  Berkeley DB and
209           GDBM both do not have these limits, so I recommend using either of
210           those instead.
211
212       2.  MLDBM does well with data structures that are not too deep and not
213           too wide.  You also need to be careful about how many "FETCH"es
214           your code actually ends up doing.  Meaning, you should get the most
215           mileage out of a "FETCH" by holding on to the highest level value
216           for as long as you need it.  Remember that every toplevel access of
217           the tied hash, for example $mldb{foo}, translates to a MLDBM
218           "FETCH()" call.
219
220           Too often, people end up writing something like this:
221
222                   tie %h, 'MLDBM', ...;
223                   for my $k (keys %{$h{something}}) {
224                       print $h{something}{$k}[0]{foo}{bar};  # FETCH _every_ time!
225                   }
226
227           when it should be written this for efficiency:
228
229                   tie %h, 'MLDBM', ...;
230                   my $root = $h{something};                  # FETCH _once_
231                   for my $k (keys %$root) {
232                       print $k->[0]{foo}{bar};
233                   }
234

AUTHORS

236       Gurusamy Sarathy <gsar@umich.edu>.
237
238       Support for multiple serializing packages by Raphael Manfredi
239       <Raphael_Manfredi@grenoble.hp.com>.
240
241       Test suite fixes for perl 5.8.0 done by Josh Chamas.
242
243       Copyright (c) 1995-98 Gurusamy Sarathy.  All rights reserved.
244
245       Copyright (c) 1998 Raphael Manfredi.
246
247       Copyright (c) 2002 Josh Chamas, Chamas Enterprises Inc.
248
249       Copyright (c) 2010-2013 Alexandr Ciornii (alexchorny@gmail.com).
250
251       This program is free software; you can redistribute it and/or modify it
252       under the same terms as Perl itself.
253

VERSION

255       Version 2.05
256

SEE ALSO

258       perl(1), perltie(1), perlfunc(1), Data::Dumper, FreezeThaw, Storable,
259       DBM::Deep, MLDBM::Serializer::JSON.
260
261
262
263perl v5.30.1                      2020-01-30                          MLDBM(3)
Impressum