.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "MLDBM 3"
.TH MLDBM 3 "2016-08-24" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MLDBM \- store multi\-level Perl hash structure in single level tied hash
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    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, \*(AqMLDBM\*(Aq [..other DBM args..] or die $!;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module can serve as a transparent interface to any \s-1TIEHASH\s0 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 \s-1DBM\s0 databases.
.PP
It works by serializing the references in the hash into a single string. In the
underlying \s-1TIEHASH\s0 package (usually a \s-1DBM\s0 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.
.PP
For historical and practical reasons, it requires the \fBData::Dumper\fR package,
available at any \s-1CPAN\s0 site. \fBData::Dumper\fR 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 \fBData::Dumper\fR, \fBFreezeThaw\fR or \fBStorable\fR to
perform the underlying serialization, as hinted at by the \s-1SYNOPSIS\s0 overview
above.  Using \fBStorable\fR is usually much faster than the other methods.
.PP
See the \s-1BUGS\s0 section for important limitations.
.SS "Changing the Defaults"
.IX Subsection "Changing the Defaults"
\&\fB\s-1MLDBM\s0\fR relies on an underlying \s-1TIEHASH\s0 implementation (usually a
\&\s-1DBM\s0 package), and an underlying serialization package.  The respective
defaults are \fBSDBM_File\fR and \fBData::Dumper\fR.  Both of these defaults
can be changed.  Changing the \fBSDBM_File\fR default is strongly recommended.
See \s-1WARNINGS\s0 below.
.PP
Three serialization wrappers are currently supported: \fBData::Dumper\fR,
\&\fBStorable\fR, and \fBFreezeThaw\fR.  Additional serializers can be
supported by writing a wrapper that implements the interface required by
\&\fBMLDBM::Serializer\fR.  See the supported wrappers and the \fBMLDBM::Serializer\fR
source for details.
.PP
In the following, \fI\f(CI$OBJ\fI\fR stands for the tied object, as in:
.PP
.Vb 2
\&        $obj = tie %o, ....
\&        $obj = tied %o;
.Ve
.ie n .IP "$MLDBM::UseDB	\fIor\fR	\fI\fI$OBJ\fI\fR\->UseDB(\fI[\s-1TIEDOBJECT\s0]\fR)" 4
.el .IP "\f(CW$MLDBM::UseDB\fR	\fIor\fR	\fI\f(CI$OBJ\fI\fR\->UseDB(\fI[\s-1TIEDOBJECT\s0]\fR)" 4
.IX Item "$MLDBM::UseDB or $OBJ->UseDB([TIEDOBJECT])"
The global \f(CW$MLDBM::UseDB\fR can be set to default to something other than
\&\f(CW\*(C`SDBM_File\*(C'\fR, in case you have a more efficient \s-1DBM,\s0 or if you want to use
this with some other \s-1TIEHASH\s0 implementation.  Alternatively, you can specify
the name of the package at \f(CW\*(C`use\*(C'\fR time, as the first \*(L"parameter\*(R".
Nested module names can be specified as \*(L"Foo::Bar\*(R".
.Sp
The corresponding method call returns the underlying \s-1TIEHASH\s0 object when
called without arguments.  It can be called with any object that
implements Perl's \s-1TIEHASH\s0 interface, to set that value.
.ie n .IP "$MLDBM::Serializer	\fIor\fR	\fI\fI$OBJ\fI\fR\->Serializer(\fI[\s-1SZROBJECT\s0]\fR)" 4
.el .IP "\f(CW$MLDBM::Serializer\fR	\fIor\fR	\fI\f(CI$OBJ\fI\fR\->Serializer(\fI[\s-1SZROBJECT\s0]\fR)" 4
.IX Item "$MLDBM::Serializer or $OBJ->Serializer([SZROBJECT])"
The global \f(CW$MLDBM::Serializer\fR can be set to the name of the serializing
package to be used. Currently can be set to one of \f(CW\*(C`Data::Dumper\*(C'\fR,
\&\f(CW\*(C`Storable\*(C'\fR, or \f(CW\*(C`FreezeThaw\*(C'\fR. Defaults to \f(CW\*(C`Data::Dumper\*(C'\fR.  Alternatively,
you can specify the name of the serializer package at \f(CW\*(C`use\*(C'\fR time, as the
second \*(L"parameter\*(R".
.Sp
The corresponding method call returns the underlying \s-1MLDBM\s0 serializer object
when called without arguments.  It can be called with an object that
implements the \s-1MLDBM\s0 serializer interface, to set that value.
.SS "Controlling Serializer Properties"
.IX Subsection "Controlling Serializer Properties"
These methods are meant to supply an interface to the properties of the
underlying serializer used.  Do \fBnot\fR call or set them without
understanding the consequences in full.  The defaults are usually sensible.
.PP
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.
.ie n .IP "$MLDBM::DumpMeth	\fIor\fR  \fI\fI$OBJ\fI\fR\->DumpMeth(\fI[\s-1METHNAME\s0]\fR)" 4
.el .IP "\f(CW$MLDBM::DumpMeth\fR	\fIor\fR  \fI\f(CI$OBJ\fI\fR\->DumpMeth(\fI[\s-1METHNAME\s0]\fR)" 4
.IX Item "$MLDBM::DumpMeth or $OBJ->DumpMeth([METHNAME])"
If the serializer provides alternative serialization methods, this
can be used to set them.
.Sp
With \fBData::Dumper\fR (which offers a pure Perl and an \s-1XS\s0 verion
of its serializing routine), this is set to \f(CW\*(C`Dumpxs\*(C'\fR by default if that
is supported in your installation.  Otherwise, defaults to the slower
\&\f(CW\*(C`Dump\*(C'\fR method.
.Sp
With \fBStorable\fR, a value of \f(CW\*(C`portable\*(C'\fR 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 \fBStorable\fR.  Both \fBData::Dumper\fR and
\&\fBFreezeThaw\fR are always architecture neutral.
.Sp
\&\fBFreezeThaw\fR does not honor this attribute.
.ie n .IP "$MLDBM::Key  \fIor\fR  \fI\fI$OBJ\fI\fR\->Key(\fI[\s-1KEYSTRING\s0]\fR)" 4
.el .IP "\f(CW$MLDBM::Key\fR  \fIor\fR  \fI\f(CI$OBJ\fI\fR\->Key(\fI[\s-1KEYSTRING\s0]\fR)" 4
.IX Item "$MLDBM::Key or $OBJ->Key([KEYSTRING])"
If the serializer only deals with part of the data (perhaps because
the \s-1TIEHASH\s0 object can natively store some types of data), it may need
a unique key string to recognize the data it handles.  This can be used
to set that string.  Best left alone.
.Sp
Defaults to the magic string used to recognize \s-1MLDBM\s0 data. It is a six
character wide, unique string. This is best left alone, unless you know
what you are doing.
.Sp
\&\fBStorable\fR and \fBFreezeThaw\fR do not honor this attribute.
.ie n .IP "$MLDBM::RemoveTaint  \fIor\fR  \fI\fI$OBJ\fI\fR\->RemoveTaint(\fI[\s-1BOOL\s0]\fR)" 4
.el .IP "\f(CW$MLDBM::RemoveTaint\fR  \fIor\fR  \fI\f(CI$OBJ\fI\fR\->RemoveTaint(\fI[\s-1BOOL\s0]\fR)" 4
.IX Item "$MLDBM::RemoveTaint or $OBJ->RemoveTaint([BOOL])"
If the serializer can optionally untaint any retrieved data subject to
taint checks in Perl, this can be used to request that feature.  Data
that comes from external sources (like disk-files) must always be
viewed with caution, so use this only when you are sure that that is
not an issue.
.Sp
\&\fBData::Dumper\fR uses \f(CW\*(C`eval()\*(C'\fR to deserialize and is therefore subject to
taint checks.  Can be set to a true value to make the \fBData::Dumper\fR
serializer untaint the data retrieved. It is not enabled by default.
Use with care.
.Sp
\&\fBStorable\fR and \fBFreezeThaw\fR do not honor this attribute.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Here is a simple example.  Note that does not depend upon the underlying
serializing package\*(--most real life examples should not, usually.
.PP
.Vb 3
\&    use MLDBM;                          # this gets SDBM and Data::Dumper
\&    #use MLDBM qw(SDBM_File Storable);  # SDBM and Storable
\&    use Fcntl;                          # to get \*(Aqem constants
\&
\&    $dbm = tie %o, \*(AqMLDBM\*(Aq, \*(Aqtestmldbm\*(Aq, O_CREAT|O_RDWR, 0640 or die $!;
\&
\&    $c = [\e \*(Aqc\*(Aq];
\&    $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] = \*(Aqfoo\*(Aq;
\&    $o{a} = $tmp;
\&
\&    #
\&    # can access the underlying DBM methods transparently
\&    #
\&    #print $dbm\->fd, "\en";              # DB_File method
.Ve
.PP
Here is another small example using Storable, in a portable format:
.PP
.Vb 1
\&    use MLDBM qw(DB_File Storable);     # DB_File and Storable
\&
\&    tie %o, \*(AqMLDBM\*(Aq, \*(Aqtestmldbm\*(Aq, O_CREAT|O_RDWR, 0640 or die $!;
\&
\&    (tied %o)\->DumpMeth(\*(Aqportable\*(Aq);    # Ask for portable binary
\&    $o{\*(AqENV\*(Aq} = \e%ENV;                  # Stores the whole environment
.Ve
.SH "BUGS"
.IX Header "BUGS"
.IP "1." 4
Adding or altering substructures to a hash value is not entirely transparent
in current perl.  If you want to store a reference or modify an existing
reference value in the \s-1DBM,\s0 it must first be retrieved and stored in a
temporary variable for further modifications.  In particular, something like
this will \s-1NOT\s0 work properly:
.Sp
.Vb 1
\&        $mldb{key}{subkey}[3] = \*(Aqstuff\*(Aq;        # won\*(Aqt work
.Ve
.Sp
Instead, that must be written as:
.Sp
.Vb 3
\&        $tmp = $mldb{key};                      # retrieve value
\&        $tmp\->{subkey}[3] = \*(Aqstuff\*(Aq;
\&        $mldb{key} = $tmp;                      # store value
.Ve
.Sp
This limitation exists because the perl \s-1TIEHASH\s0 interface currently has no
support for multidimensional ties.
.IP "2." 4
The \fBData::Dumper\fR serializer uses \fIeval()\fR.  A lot.  Try the \fBStorable\fR
serializer, which is generally the most efficient.
.SH "WARNINGS"
.IX Header "WARNINGS"
.IP "1." 4
Many \s-1DBM\s0 implementations have arbitrary limits on the size of records
that can be stored.  For example, \s-1SDBM\s0 and many \s-1ODBM\s0 or \s-1NDBM\s0
implementations have a default limit of 1024 bytes for the size of a
record.  \s-1MLDBM\s0 can easily exceed these limits when storing large data
structures, leading to mysterious failures.  Although SDBM_File is
used by \s-1MLDBM\s0 by default, it is not a good choice if you're storing
large data structures.  Berkeley \s-1DB\s0 and \s-1GDBM\s0 both do not have these
limits, so I recommend using either of those instead.
.IP "2." 4
\&\s-1MLDBM\s0 does well with data structures that are not too deep and not
too wide.  You also need to be careful about how many \f(CW\*(C`FETCH\*(C'\fRes your
code actually ends up doing.  Meaning, you should get the most mileage
out of a \f(CW\*(C`FETCH\*(C'\fR by holding on to the highest level value for as long
as you need it.  Remember that every toplevel access of the tied hash,
for example \f(CW$mldb{foo}\fR, translates to a \s-1MLDBM \s0\f(CW\*(C`FETCH()\*(C'\fR call.
.Sp
Too often, people end up writing something like this:
.Sp
.Vb 4
\&        tie %h, \*(AqMLDBM\*(Aq, ...;
\&        for my $k (keys %{$h{something}}) {
\&            print $h{something}{$k}[0]{foo}{bar};  # FETCH _every_ time!
\&        }
.Ve
.Sp
when it should be written this for efficiency:
.Sp
.Vb 5
\&        tie %h, \*(AqMLDBM\*(Aq, ...;
\&        my $root = $h{something};                  # FETCH _once_
\&        for my $k (keys %$root) {
\&            print $k\->[0]{foo}{bar};
\&        }
.Ve
.SH "AUTHORS"
.IX Header "AUTHORS"
Gurusamy Sarathy <\fIgsar@umich.edu\fR>.
.PP
Support for multiple serializing packages by
Raphael Manfredi <\fIRaphael_Manfredi@grenoble.hp.com\fR>.
.PP
Test suite fixes for perl 5.8.0 done by Josh Chamas.
.PP
Copyright (c) 1995\-98 Gurusamy Sarathy.  All rights reserved.
.PP
Copyright (c) 1998 Raphael Manfredi.
.PP
Copyright (c) 2002 Josh Chamas, Chamas Enterprises Inc.
.PP
Copyright (c) 2010\-2013 Alexandr Ciornii (alexchorny@gmail.com).
.PP
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "VERSION"
.IX Header "VERSION"
Version 2.05
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1), \fIperltie\fR\|(1), \fIperlfunc\fR\|(1), Data::Dumper, FreezeThaw, Storable, DBM::Deep, MLDBM::Serializer::JSON.