{ "content": [ { "type": "text", "text": "# MLDBM (man)\n\n## NAME\n\nMLDBM - store multi-level Perl hash structure in single level tied hash\n\n## SYNOPSIS\n\nuse MLDBM; # this gets the default, SDBM\n#use MLDBM qw(DBFile FreezeThaw); # use FreezeThaw for serializing\n#use MLDBM qw(DBFile Storable); # use Storable for serializing\n$dbm = tie %o, 'MLDBM' [..other DBM args..] or die $!;\n\n## DESCRIPTION\n\nThis module can serve as a transparent interface to any TIEHASH package that is required to\nstore arbitrary perl data, including nested references. Thus, this module can be used for\nstoring references and other arbitrary data within DBM databases.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (2 subsections)\n- **EXAMPLES**\n- **BUGS**\n- **WARNINGS**\n- **AUTHORS**\n- **VERSION**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "MLDBM", "section": "", "mode": "man", "summary": "MLDBM - store multi-level Perl hash structure in single level tied hash", "synopsis": "use MLDBM; # this gets the default, SDBM\n#use MLDBM qw(DBFile FreezeThaw); # use FreezeThaw for serializing\n#use MLDBM qw(DBFile Storable); # use Storable for serializing\n$dbm = tie %o, 'MLDBM' [..other DBM args..] or die $!;", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [ "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(SDBMFile Storable); # SDBM and Storable", "use Fcntl; # to get 'em constants", "$dbm = tie %o, 'MLDBM', 'testmldbm', OCREAT|ORDWR, 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\"; # DBFile method", "Here is another small example using Storable, in a portable format:", "use MLDBM qw(DBFile Storable); # DBFile and Storable", "tie %o, 'MLDBM', 'testmldbm', OCREAT|ORDWR, 0640 or die $!;", "(tied %o)->DumpMeth('portable'); # Ask for portable binary", "$o{'ENV'} = \\%ENV; # Stores the whole environment" ], "see_also": [ { "name": "perl", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/perl/1/json" }, { "name": "perltie", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/perltie/1/json" }, { "name": "perlfunc", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/perlfunc/1/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 6, "subsections": [] }, { "name": "DESCRIPTION", "lines": 17, "subsections": [ { "name": "Changing the Defaults", "lines": 35 }, { "name": "Controlling Serializer Properties", "lines": 45 } ] }, { "name": "EXAMPLES", "lines": 44, "subsections": [] }, { "name": "BUGS", "lines": 19, "subsections": [] }, { "name": "WARNINGS", "lines": 28, "subsections": [] }, { "name": "AUTHORS", "lines": 18, "subsections": [] }, { "name": "VERSION", "lines": 2, "subsections": [] }, { "name": "SEE ALSO", "lines": 4, "subsections": [] } ], "sections": { "NAME": { "content": "MLDBM - store multi-level Perl hash structure in single level tied hash\n", "subsections": [] }, "SYNOPSIS": { "content": "use MLDBM; # this gets the default, SDBM\n#use MLDBM qw(DBFile FreezeThaw); # use FreezeThaw for serializing\n#use MLDBM qw(DBFile Storable); # use Storable for serializing\n\n$dbm = tie %o, 'MLDBM' [..other DBM args..] or die $!;\n", "subsections": [] }, "DESCRIPTION": { "content": "This module can serve as a transparent interface to any TIEHASH package that is required to\nstore arbitrary perl data, including nested references. Thus, this module can be used for\nstoring references and other arbitrary data within DBM databases.\n\nIt works by serializing the references in the hash into a single string. In the underlying\nTIEHASH package (usually a DBM database), it is this string that gets stored. When the value\nis fetched again, the string is deserialized to reconstruct the data structure into memory.\n\nFor historical and practical reasons, it requires the Data::Dumper package, available at any\nCPAN site. Data::Dumper gives you really nice-looking dumps of your data structures, in case\nyou wish to look at them on the screen, and it was the only serializing engine before version\n2.00. However, as of version 2.00, you can use any of Data::Dumper, FreezeThaw or Storable\nto perform the underlying serialization, as hinted at by the SYNOPSIS overview above. Using\nStorable is usually much faster than the other methods.\n\nSee the BUGS section for important limitations.\n", "subsections": [ { "name": "Changing the Defaults", "content": "MLDBM relies on an underlying TIEHASH implementation (usually a DBM package), and an\nunderlying serialization package. The respective defaults are SDBMFile and Data::Dumper.\nBoth of these defaults can be changed. Changing the SDBMFile default is strongly\nrecommended. See WARNINGS below.\n\nThree serialization wrappers are currently supported: Data::Dumper, Storable, and FreezeThaw.\nAdditional serializers can be supported by writing a wrapper that implements the interface\nrequired by MLDBM::Serializer. See the supported wrappers and the MLDBM::Serializer source\nfor details.\n\nIn the following, $OBJ stands for the tied object, as in:\n\n$obj = tie %o, ....\n$obj = tied %o;\n\n$MLDBM::UseDB or $OBJ->UseDB([TIEDOBJECT])\nThe global $MLDBM::UseDB can be set to default to something other than \"SDBMFile\", in\ncase you have a more efficient DBM, or if you want to use this with some other TIEHASH\nimplementation. Alternatively, you can specify the name of the package at \"use\" time, as\nthe first \"parameter\". Nested module names can be specified as \"Foo::Bar\".\n\nThe corresponding method call returns the underlying TIEHASH object when called without\narguments. It can be called with any object that implements Perl's TIEHASH interface, to\nset that value.\n\n$MLDBM::Serializer or $OBJ->Serializer([SZROBJECT])\nThe global $MLDBM::Serializer can be set to the name of the serializing package to be\nused. Currently can be set to one of \"Data::Dumper\", \"Storable\", or \"FreezeThaw\".\nDefaults to \"Data::Dumper\". Alternatively, you can specify the name of the serializer\npackage at \"use\" time, as the second \"parameter\".\n\nThe corresponding method call returns the underlying MLDBM serializer object when called\nwithout arguments. It can be called with an object that implements the MLDBM serializer\ninterface, to set that value.\n" }, { "name": "Controlling Serializer Properties", "content": "These methods are meant to supply an interface to the properties of the underlying serializer\nused. Do not call or set them without understanding the consequences in full. The defaults\nare usually sensible.\n\nNot all of these necessarily apply to all the supplied serializers, so we specify when to\napply them. Failure to respect this will usually lead to an exception.\n\n$MLDBM::DumpMeth or $OBJ->DumpMeth([METHNAME])\nIf the serializer provides alternative serialization methods, this can be used to set\nthem.\n\nWith Data::Dumper (which offers a pure Perl and an XS verion of its serializing routine),\nthis is set to \"Dumpxs\" by default if that is supported in your installation. Otherwise,\ndefaults to the slower \"Dump\" method.\n\nWith Storable, a value of \"portable\" requests that serialization be architecture neutral,\ni.e. the deserialization can later occur on another platform. Of course, this only makes\nsense if your database files are themselves architecture neutral. By default, native\nformat is used for greater serializing speed in Storable. Both Data::Dumper and\nFreezeThaw are always architecture neutral.\n\nFreezeThaw does not honor this attribute.\n\n$MLDBM::Key or $OBJ->Key([KEYSTRING])\nIf the serializer only deals with part of the data (perhaps because the TIEHASH object\ncan natively store some types of data), it may need a unique key string to recognize the\ndata it handles. This can be used to set that string. Best left alone.\n\nDefaults to the magic string used to recognize MLDBM data. It is a six character wide,\nunique string. This is best left alone, unless you know what you are doing.\n\nStorable and FreezeThaw do not honor this attribute.\n\n$MLDBM::RemoveTaint or $OBJ->RemoveTaint([BOOL])\nIf the serializer can optionally untaint any retrieved data subject to taint checks in\nPerl, this can be used to request that feature. Data that comes from external sources\n(like disk-files) must always be viewed with caution, so use this only when you are sure\nthat that is not an issue.\n\nData::Dumper uses \"eval()\" to deserialize and is therefore subject to taint checks. Can\nbe set to a true value to make the Data::Dumper serializer untaint the data retrieved. It\nis not enabled by default. Use with care.\n\nStorable and FreezeThaw do not honor this attribute.\n" } ] }, "EXAMPLES": { "content": "Here is a simple example. Note that does not depend upon the underlying serializing\npackage--most real life examples should not, usually.\n\nuse MLDBM; # this gets SDBM and Data::Dumper\n#use MLDBM qw(SDBMFile Storable); # SDBM and Storable\nuse Fcntl; # to get 'em constants\n\n$dbm = tie %o, 'MLDBM', 'testmldbm', OCREAT|ORDWR, 0640 or die $!;\n\n$c = [\\ 'c'];\n$b = {};\n$a = [1, $b, $c];\n$b->{a} = $a;\n$b->{b} = $a->[1];\n$b->{c} = $a->[2];\n@o{qw(a b c)} = ($a, $b, $c);\n\n#\n# to see what was stored\n#\nuse Data::Dumper;\nprint Data::Dumper->Dump([@o{qw(a b c)}], [qw(a b c)]);\n\n#\n# to modify data in a substructure\n#\n$tmp = $o{a};\n$tmp->[0] = 'foo';\n$o{a} = $tmp;\n\n#\n# can access the underlying DBM methods transparently\n#\n#print $dbm->fd, \"\\n\"; # DBFile method\n\nHere is another small example using Storable, in a portable format:\n\nuse MLDBM qw(DBFile Storable); # DBFile and Storable\n\ntie %o, 'MLDBM', 'testmldbm', OCREAT|ORDWR, 0640 or die $!;\n\n(tied %o)->DumpMeth('portable'); # Ask for portable binary\n$o{'ENV'} = \\%ENV; # Stores the whole environment\n", "subsections": [] }, "BUGS": { "content": "1. Adding or altering substructures to a hash value is not entirely transparent in current\nperl. If you want to store a reference or modify an existing reference value in the DBM,\nit must first be retrieved and stored in a temporary variable for further modifications.\nIn particular, something like this will NOT work properly:\n\n$mldb{key}{subkey}[3] = 'stuff'; # won't work\n\nInstead, that must be written as:\n\n$tmp = $mldb{key}; # retrieve value\n$tmp->{subkey}[3] = 'stuff';\n$mldb{key} = $tmp; # store value\n\nThis limitation exists because the perl TIEHASH interface currently has no support for\nmultidimensional ties.\n\n2. The Data::Dumper serializer uses eval(). A lot. Try the Storable serializer, which is\ngenerally the most efficient.\n", "subsections": [] }, "WARNINGS": { "content": "1. Many DBM implementations have arbitrary limits on the size of records that can be stored.\nFor example, SDBM and many ODBM or NDBM implementations have a default limit of 1024\nbytes for the size of a record. MLDBM can easily exceed these limits when storing large\ndata structures, leading to mysterious failures. Although SDBMFile is used by MLDBM by\ndefault, it is not a good choice if you're storing large data structures. Berkeley DB\nand GDBM both do not have these limits, so I recommend using either of those instead.\n\n2. MLDBM does well with data structures that are not too deep and not too wide. You also\nneed to be careful about how many \"FETCH\"es your code actually ends up doing. Meaning,\nyou should get the most mileage out of a \"FETCH\" by holding on to the highest level value\nfor as long as you need it. Remember that every toplevel access of the tied hash, for\nexample $mldb{foo}, translates to a MLDBM \"FETCH()\" call.\n\nToo often, people end up writing something like this:\n\ntie %h, 'MLDBM', ...;\nfor my $k (keys %{$h{something}}) {\nprint $h{something}{$k}[0]{foo}{bar}; # FETCH every time!\n}\n\nwhen it should be written this for efficiency:\n\ntie %h, 'MLDBM', ...;\nmy $root = $h{something}; # FETCH once\nfor my $k (keys %$root) {\nprint $k->[0]{foo}{bar};\n}\n", "subsections": [] }, "AUTHORS": { "content": "Gurusamy Sarathy .\n\nSupport for multiple serializing packages by Raphael Manfredi\n.\n\nTest suite fixes for perl 5.8.0 done by Josh Chamas.\n\nCopyright (c) 1995-98 Gurusamy Sarathy. All rights reserved.\n\nCopyright (c) 1998 Raphael Manfredi.\n\nCopyright (c) 2002 Josh Chamas, Chamas Enterprises Inc.\n\nCopyright (c) 2010-2013 Alexandr Ciornii (alexchorny@gmail.com).\n\nThis program is free software; you can redistribute it and/or modify it under the same terms\nas Perl itself.\n", "subsections": [] }, "VERSION": { "content": "Version 2.05\n", "subsections": [] }, "SEE ALSO": { "content": "perl(1), perltie(1), perlfunc(1), Data::Dumper, FreezeThaw, Storable, DBM::Deep,\nMLDBM::Serializer::JSON.\n\nperl v5.36.0 2022-10-16 MLDBM(3pm)", "subsections": [] } } } }