releasing/cbrtools/perl/MLDBM.pm
author lorewang
Mon, 22 Nov 2010 10:56:31 +0800
changeset 700 c22eff170fac
parent 602 3145852acc89
permissions -rw-r--r--
update from trunk
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
602
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
     1
# Copyright (c) 1995-98 Gurusamy Sarathy.  All rights reserved.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
     2
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
     3
# Copyright (c) 1998 Raphael Manfredi.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
     4
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
     5
# This program is free software; you can redistribute it and/or
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
     6
# modify it under the same terms as Perl itself.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
     7
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
     8
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
     9
# MLDBM.pm
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    10
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    11
# store multi-level hash structure in single level tied hash (read DBM)
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    12
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    13
# Documentation at the __END__
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    14
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    15
# Gurusamy Sarathy <gsar@umich.edu>
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    16
# Raphael Manfredi <Raphael_Manfredi@grenoble.hp.com>
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    17
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    18
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    19
require 5.004;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    20
use strict;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    21
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    22
####################################################################
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    23
package MLDBM::Serializer;	## deferred
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    24
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    25
use Carp;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    26
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    27
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    28
# The serialization interface comprises of just three methods:
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    29
# new(), serialize() and deserialize().  Only the last two are
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    30
# _required_ to be implemented by any MLDBM serialization wrapper.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    31
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    32
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    33
sub new { bless {}, shift };
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    34
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    35
sub serialize { confess "deferred" };
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    36
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    37
sub deserialize { confess "deferred" };
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    38
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    39
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    40
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    41
# Attributes:
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    42
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    43
#    dumpmeth:
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    44
#	the preferred dumping method.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    45
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    46
#    removetaint:
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    47
#	untainting flag; when true, data will be untainted after
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    48
#	extraction from the database.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    49
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    50
#    key:
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    51
#	the magic string used to recognize non-natively stored data.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    52
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    53
# Attribute access methods:
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    54
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    55
#	These defaults allow readonly access. Sub-class may override
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    56
#	them to allow write access if any of these attributes
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    57
#	makes sense for it.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    58
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    59
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    60
sub DumpMeth	{
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    61
    my $s = shift;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    62
    confess "can't set dumpmeth with " . ref($s) if @_;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    63
    $s->_attrib('dumpmeth');
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    64
}
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    65
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    66
sub RemoveTaint	{
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    67
    my $s = shift;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    68
    confess "can't set untaint with " . ref($s) if @_;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    69
    $s->_attrib('removetaint');
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    70
}
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    71
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    72
sub Key	{
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    73
    my $s = shift;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    74
    confess "can't set key with " . ref($s) if @_;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    75
    $s->_attrib('key');
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    76
}
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    77
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    78
sub _attrib {
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    79
    my ($s, $a, $v) = @_;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    80
    if (ref $s and @_ > 2) {
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    81
	$s->{$a} = $v;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    82
	return $s;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    83
    }
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    84
    $s->{$a};
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    85
}
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    86
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    87
####################################################################
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    88
package MLDBM;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    89
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    90
$MLDBM::VERSION = $MLDBM::VERSION = '2.00';
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    91
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    92
require Tie::Hash;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    93
@MLDBM::ISA = 'Tie::Hash';
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    94
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    95
use Carp;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    96
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    97
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    98
# the DB package to use (we default to SDBM since it comes with perl)
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
    99
# you might want to change this default to something more efficient
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   100
# like DB_File (you can always override it in the use list)
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   101
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   102
$MLDBM::UseDB		= "SDBM_File"		unless $MLDBM::UseDB;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   103
$MLDBM::Serializer	= 'Data::Dumper'	unless $MLDBM::Serializer;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   104
$MLDBM::Key		= '$MlDbM'		unless $MLDBM::Key;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   105
$MLDBM::DumpMeth	= ""			unless $MLDBM::DumpMeth;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   106
$MLDBM::RemoveTaint	= 0			unless $MLDBM::RemoveTaint;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   107
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   108
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   109
# A private way to load packages at runtime.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   110
my $loadpack = sub {
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   111
    my $pack = shift;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   112
    $pack =~ s|::|/|g;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   113
    $pack .= ".pm";
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   114
    eval { require $pack };
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   115
    if ($@) {
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   116
	carp "MLDBM error: " . 
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   117
	  "Please make sure $pack is a properly installed package.\n" .
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   118
	    "\tPerl says: \"$@\"";
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   119
	return undef;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   120
    }
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   121
    1;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   122
};
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   123
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   124
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   125
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   126
# TIEHASH interface methods
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   127
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   128
sub TIEHASH {
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   129
    my $c = shift;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   130
    my $s = bless {}, $c;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   131
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   132
    #
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   133
    # Create the right serializer object.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   134
    my $szr = $MLDBM::Serializer;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   135
    unless (ref $szr) {
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   136
	$szr = "MLDBM::Serializer::$szr"	# allow convenient short names
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   137
	  unless $szr =~ /^MLDBM::Serializer::/;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   138
	&$loadpack($szr) or return undef;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   139
	$szr = $szr->new($MLDBM::DumpMeth,
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   140
			 $MLDBM::RemoveTaint,
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   141
			 $MLDBM::Key);
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   142
    }
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   143
    $s->Serializer($szr);
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   144
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   145
    #
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   146
    # Create the right TIEHASH  object.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   147
    my $db = $MLDBM::UseDB;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   148
    unless (ref $db) {
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   149
	&$loadpack($db) or return undef;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   150
	$db = $db->TIEHASH(@_)
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   151
	  or carp "MLDBM error: Second level tie failed, \"$!\""
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   152
	    and return undef;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   153
    }
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   154
    $s->UseDB($db);
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   155
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   156
    return $s;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   157
}
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   158
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   159
sub FETCH {
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   160
    my ($s, $k) = @_;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   161
    my $ret = $s->{DB}->FETCH($k);
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   162
    $s->{SR}->deserialize($ret);
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   163
}
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   164
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   165
sub STORE {
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   166
    my ($s, $k, $v) = @_;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   167
    $v = $s->{SR}->serialize($v);
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   168
    $s->{DB}->STORE($k, $v);
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   169
}
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   170
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   171
sub DELETE	{ my $s = shift; $s->{DB}->DELETE(@_); }
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   172
sub FIRSTKEY	{ my $s = shift; $s->{DB}->FIRSTKEY(@_); }
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   173
sub NEXTKEY	{ my $s = shift; $s->{DB}->NEXTKEY(@_); }
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   174
sub EXISTS	{ my $s = shift; $s->{DB}->EXISTS(@_); }
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   175
sub CLEAR	{ my $s = shift; $s->{DB}->CLEAR(@_); }
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   176
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   177
sub new		{ &TIEHASH }
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   178
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   179
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   180
# delegate messages to the underlying DBM
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   181
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   182
sub AUTOLOAD {
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   183
    return if $MLDBM::AUTOLOAD =~ /::DESTROY$/;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   184
    my $s = shift;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   185
    if (ref $s) {			# twas a method call
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   186
	my $dbname = ref($s->{DB});
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   187
	# permit inheritance
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   188
	$MLDBM::AUTOLOAD =~ s/^.*::([^:]+)$/$dbname\:\:$1/;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   189
	$s->{DB}->$MLDBM::AUTOLOAD(@_);
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   190
    }
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   191
}
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   192
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   193
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   194
# delegate messages to the underlying Serializer
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   195
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   196
sub DumpMeth	{ my $s = shift; $s->{SR}->DumpMeth(@_); }
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   197
sub RemoveTaint	{ my $s = shift; $s->{SR}->RemoveTaint(@_); }
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   198
sub Key		{ my $s = shift; $s->{SR}->Key(@_); }
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   199
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   200
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   201
# get/set the DB object
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   202
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   203
sub UseDB 	{ my $s = shift; @_ ? ($s->{DB} = shift) : $s->{DB}; }
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   204
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   205
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   206
# get/set the Serializer object
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   207
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   208
sub Serializer	{ my $s = shift; @_ ? ($s->{SR} = shift) : $s->{SR}; }
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   209
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   210
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   211
# stuff to do at 'use' time
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   212
#
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   213
sub import {
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   214
    my ($pack, $dbpack, $szr, $dumpmeth, $removetaint, $key) = @_;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   215
    $MLDBM::UseDB = $dbpack if defined $dbpack and $dbpack;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   216
    $MLDBM::Serializer = $szr if defined $szr and $szr;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   217
    # undocumented, may change!
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   218
    $MLDBM::DumpMeth = $dumpmeth if defined $dumpmeth;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   219
    $MLDBM::RemoveTaint = $removetaint if defined $removetaint;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   220
    $MLDBM::Key = $key if defined $key and $key;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   221
}
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   222
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   223
1;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   224
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   225
__END__
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   226
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   227
=head1 NAME
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   228
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   229
MLDBM - store multi-level hash structure in single level tied hash
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   230
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   231
=head1 SYNOPSIS
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   232
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   233
    use MLDBM;				# this gets the default, SDBM
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   234
    #use MLDBM qw(DB_File FreezeThaw);	# use FreezeThaw for serializing
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   235
    #use MLDBM qw(DB_File Storable);	# use Storable for serializing
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   236
    
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   237
    $dbm = tie %o, 'MLDBM' [..other DBM args..] or die $!;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   238
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   239
=head1 DESCRIPTION
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   240
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   241
This module can serve as a transparent interface to any TIEHASH package
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   242
that is required to store arbitrary perl data, including nested references.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   243
Thus, this module can be used for storing references and other arbitrary data
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   244
within DBM databases.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   245
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   246
It works by serializing the references in the hash into a single string. In the
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   247
underlying TIEHASH package (usually a DBM database), it is this string that
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   248
gets stored.  When the value is fetched again, the string is deserialized to
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   249
reconstruct the data structure into memory.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   250
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   251
For historical and practical reasons, it requires the B<Data::Dumper> package,
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   252
available at any CPAN site. B<Data::Dumper> gives you really nice-looking dumps of
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   253
your data structures, in case you wish to look at them on the screen, and
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   254
it was the only serializing engine before version 2.00.  However, as of version
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   255
2.00, you can use any of B<Data::Dumper>, B<FreezeThaw> or B<Storable> to
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   256
perform the underlying serialization, as hinted at by the L<SYNOPSIS> overview
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   257
above.  Using B<Storable> is usually much faster than the other methods.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   258
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   259
See the L<BUGS> section for important limitations.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   260
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   261
=head2 Changing the Defaults
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   262
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   263
B<MLDBM> relies on an underlying TIEHASH implementation (usually a
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   264
DBM package), and an underlying serialization package.  The respective
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   265
defaults are B<SDBM_File> and D<Data::Dumper>.  Both of these defaults
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   266
can be changed.  Changing the B<SDBM_File> default is strongly recommended.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   267
See L<WARNINGS> below.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   268
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   269
Three serialization wrappers are currently supported: B<Data::Dumper>,
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   270
B<Storable>, and B<FreezeThaw>.  Additional serializers can be
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   271
supported by writing a wrapper that implements the interface required by
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   272
B<MLDBM::Serializer>.  See the supported wrappers and the B<MLDBM::Serializer>
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   273
source for details.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   274
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   275
In the following, I<$OBJ> stands for the tied object, as in:
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   276
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   277
	$obj = tie %o, ....
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   278
	$obj = tied %o;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   279
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   280
=over 4
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   281
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   282
=item $MLDBM::UseDB	I<or>	I<$OBJ>->UseDB(I<[TIEDOBJECT]>)
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   283
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   284
The global C<$MLDBM::UseDB> can be set to default to something other than
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   285
C<SDBM_File>, in case you have a more efficient DBM, or if you want to use
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   286
this with some other TIEHASH implementation.  Alternatively, you can specify
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   287
the name of the package at C<use> time, as the first "parameter".
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   288
Nested module names can be specified as "Foo::Bar".
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   289
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   290
The corresponding method call returns the underlying TIEHASH object when
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   291
called without arguments.  It can be called with any object that
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   292
implements Perl's TIEHASH interface, to set that value.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   293
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   294
=item $MLDBM::Serializer	I<or>	I<$OBJ>->Serializer(I<[SZROBJECT]>)
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   295
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   296
The global C<$MLDBM::Serializer> can be set to the name of the serializing
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   297
package to be used. Currently can be set to one of C<Data::Dumper>,
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   298
C<Storable>, or C<FreezeThaw>. Defaults to C<Data::Dumper>.  Alternatively,
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   299
you can specify the name of the serializer package at C<use> time, as the
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   300
second "parameter".
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   301
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   302
The corresponding method call returns the underlying MLDBM serializer object
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   303
when called without arguments.  It can be called with an object that
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   304
implements the MLDBM serializer interface, to set that value.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   305
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   306
=back
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   307
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   308
=head2 Controlling Serializer Properties
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   309
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   310
These methods are meant to supply an interface to the properties of the
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   311
underlying serializer used.  Do B<not> call or set them without
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   312
understanding the consequences in full.  The defaults are usually sensible.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   313
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   314
Not all of these necessarily apply to all the supplied serializers, so we
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   315
specify when to apply them.  Failure to respect this will usually lead to
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   316
an exception.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   317
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   318
=over 4
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   319
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   320
=item $MLDBM::DumpMeth	I<or>  I<$OBJ>->DumpMeth(I<[METHNAME]>)
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   321
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   322
If the serializer provides alternative serialization methods, this
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   323
can be used to set them.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   324
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   325
With B<Data::Dumper> (which offers a pure Perl and an XS verion
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   326
of its serializing routine), this is set to C<Dumpxs> by default if that
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   327
is supported in your installation.  Otherwise, defaults to the slower
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   328
C<Dump> method.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   329
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   330
With B<Storable>, a value of C<portable> requests that serialization be
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   331
architecture neutral, i.e. the deserialization can later occur on another
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   332
platform. Of course, this only makes sense if your database files are
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   333
themselves architecture neutral.  By default, native format is used for
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   334
greater serializing speed in B<Storable>.  Both B<Data::Dumper> and
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   335
B<FreezeThaw> are always architecture neutral.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   336
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   337
B<FreezeThaw> does not honor this attribute.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   338
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   339
=item $MLDBM::Key  I<or>  I<$OBJ>->Key(I<[KEYSTRING]>)
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   340
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   341
If the serializer only deals with part of the data (perhaps because
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   342
the TIEHASH object can natively store some types of data), it may need
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   343
a unique key string to recognize the data it handles.  This can be used
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   344
to set that string.  Best left alone.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   345
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   346
Defaults to the magic string used to recognize MLDBM data. It is a six
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   347
character wide, unique string. This is best left alone, unless you know
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   348
what you are doing. 
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   349
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   350
B<Storable> and B<FreezeThaw> do not honor this attribute.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   351
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   352
=item $MLDBM::RemoveTaint  I<or>  I<$OBJ>->RemoveTaint(I<[BOOL]>)
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   353
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   354
If the serializer can optionally untaint any retrieved data subject to
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   355
taint checks in Perl, this can be used to request that feature.  Data
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   356
that comes from external sources (like disk-files) must always be
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   357
viewed with caution, so use this only when you are sure that that is
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   358
not an issue.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   359
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   360
B<Data::Dumper> uses C<eval()> to deserialize and is therefore subject to
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   361
taint checks.  Can be set to a true value to make the B<Data::Dumper>
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   362
serializer untaint the data retrieved. It is not enabled by default.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   363
Use with care.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   364
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   365
B<Storable> and B<FreezeThaw> do not honor this attribute.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   366
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   367
=back
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   368
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   369
=head1 EXAMPLES
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   370
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   371
Here is a simple example.  Note that does not depend upon the underlying
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   372
serializing package--most real life examples should not, usually.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   373
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   374
    use MLDBM;				# this gets SDBM and Data::Dumper
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   375
    #use MLDBM qw(SDBM_File Storable);	# SDBM and Storable
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   376
    use Fcntl;				# to get 'em constants
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   377
     
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   378
    $dbm = tie %o, 'MLDBM', 'testmldbm', O_CREAT|O_RDWR, 0640 or die $!;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   379
    
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   380
    $c = [\ 'c'];
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   381
    $b = {};
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   382
    $a = [1, $b, $c];
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   383
    $b->{a} = $a;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   384
    $b->{b} = $a->[1];
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   385
    $b->{c} = $a->[2];
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   386
    @o{qw(a b c)} = ($a, $b, $c);
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   387
    
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   388
    #
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   389
    # to see what was stored
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   390
    #
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   391
    use Data::Dumper;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   392
    print Data::Dumper->Dump([@o{qw(a b c)}], [qw(a b c)]);
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   393
    
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   394
    #
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   395
    # to modify data in a substructure
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   396
    #
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   397
    $tmp = $o{a};
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   398
    $tmp->[0] = 'foo';
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   399
    $o{a} = $tmp;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   400
    
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   401
    #
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   402
    # can access the underlying DBM methods transparently
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   403
    #
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   404
    #print $dbm->fd, "\n";		# DB_File method
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   405
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   406
Here is another small example using Storable, in a portable format:
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   407
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   408
    use MLDBM qw(DB_File Storable);	# DB_File and Storable
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   409
    
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   410
    tie %o, 'MLDBM', 'testmldbm', O_CREAT|O_RDWR, 0640 or die $!;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   411
    
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   412
    (tied %o)->DumpMeth('portable');	# Ask for portable binary
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   413
    $o{'ENV'} = \%ENV;			# Stores the whole environment
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   414
    
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   415
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   416
=head1 BUGS
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   417
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   418
=over 4
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   419
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   420
=item 1.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   421
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   422
Adding or altering substructures to a hash value is not entirely transparent
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   423
in current perl.  If you want to store a reference or modify an existing
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   424
reference value in the DBM, it must first be retrieved and stored in a
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   425
temporary variable for further modifications.  In particular, something like
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   426
this will NOT work properly:
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   427
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   428
	$mldb{key}{subkey}[3] = 'stuff';	# won't work
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   429
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   430
Instead, that must be written as:
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   431
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   432
	$tmp = $mldb{key};			# retrieve value
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   433
	$tmp->{subkey}[3] = 'stuff';
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   434
	$mldb{key} = $tmp;			# store value
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   435
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   436
This limitation exists because the perl TIEHASH interface currently has no
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   437
support for multidimensional ties.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   438
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   439
=item 2.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   440
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   441
The B<Data::Dumper> serializer uses eval().  A lot.  Try the B<Storable>
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   442
serializer, which is generally the most efficient.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   443
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   444
=back
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   445
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   446
=head1 WARNINGS
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   447
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   448
=over 4
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   449
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   450
=item 1.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   451
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   452
Many DBM implementations have arbitrary limits on the size of records
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   453
that can be stored.  For example, SDBM and many ODBM or NDBM
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   454
implementations have a default limit of 1024 bytes for the size of a
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   455
record.  MLDBM can easily exceed these limits when storing large data
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   456
structures, leading to mysterious failures.  Although SDBM_File is
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   457
used by MLDBM by default, it is not a good choice if you're storing
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   458
large data structures.  Berkeley DB and GDBM both do not have these
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   459
limits, so I recommend using either of those instead.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   460
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   461
=item 2.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   462
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   463
MLDBM does well with data structures that are not too deep and not
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   464
too wide.  You also need to be careful about how many C<FETCH>es your
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   465
code actually ends up doing.  Meaning, you should get the most mileage
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   466
out of a C<FETCH> by holding on to the highest level value for as long
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   467
as you need it.  Remember that every toplevel access of the tied hash,
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   468
for example C<$mldb{foo}>, translates to a MLDBM C<FETCH()> call.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   469
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   470
Too often, people end up writing something like this:
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   471
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   472
        tie %h, 'MLDBM', ...;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   473
        for my $k (keys %{$h{something}}) {
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   474
            print $h{something}{$k}[0]{foo}{bar};  # FETCH _every_ time!
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   475
        }
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   476
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   477
when it should be written this for efficiency:
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   478
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   479
        tie %h, 'MLDBM', ...;
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   480
        my $root = $h{something};                  # FETCH _once_
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   481
        for my $k (keys %$root) {
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   482
            print $k->[0]{foo}{bar};
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   483
        }
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   484
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   485
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   486
=back
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   487
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   488
=head1 AUTHORS
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   489
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   490
Gurusamy Sarathy <F<gsar@umich.edu>>.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   491
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   492
Support for multiple serializing packages by
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   493
Raphael Manfredi <F<Raphael_Manfredi@grenoble.hp.com>>.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   494
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   495
Copyright (c) 1995-98 Gurusamy Sarathy.  All rights reserved.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   496
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   497
Copyright (c) 1998 Raphael Manfredi.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   498
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   499
This program is free software; you can redistribute it and/or
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   500
modify it under the same terms as Perl itself.
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   501
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   502
=head1 VERSION
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   503
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   504
Version 2.00	10 May 1998
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   505
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   506
=head1 SEE ALSO
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   507
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   508
perl(1), perltie(1), perlfunc(1), Data::Dumper(3), FreezeThaw(3), Storable(3).
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   509
3145852acc89 add releasing to new structure
jjkang
parents:
diff changeset
   510
=cut