/ 
CDB_File-0.5
River stage two • 6 direct dependents • 11 total dependents
/ CDB_File

NAME

CDB_File - Perl extension for access to CDB

SYNOPSIS

use CDB_File;
tie %h, 'CDB_File', 'file.cdb' or die "tie failed: $!\n";

CDB_File::create %t, 't.cdb', 't.tmp';

DESCRIPTION

CDB_File is a module which provides a Perl interface to Dan Berstein's cdb package:

cdb is a fast, reliable, lightweight package for creating and
reading constant databases.

After the tie shown above, accesses to %h will refer to the cdb file file.cdb, as described in "tie" in perlfunc.

CDB_File::create %t, $file, $tmp creates a cdb file named $file containing the contents of %t. $tmp must refer to a temporary file which can be atomically renamed to $file. CDB_File::create may be imported.

EXAMPLES

1. Convert a Berkeley DB (B-tree) database to CDB format.

use CDB_File;
use DB_File;

tie %h, DB_File, $ARGV[0], O_RDONLY, undef, $DB_BTREE or
        die "$0: can't tie to $ARGV[0]: $!\n";

CDB_File::create %h, $ARGV[1], "$ARGV[1].tmp" or
        die "$0: can't create cdb: $!\n";

2. Convert a flat file to CDB format. In this example, the flat file consists of one key per line, separated by a colon from the value. Blank lines and lines beginning with # are skipped. The flat file may contain repeated keys: in this case the different values are joined with $;.

use CDB_File;
while (<>) {
        next if /^$/ or /^#/;
        chop;
        ($k, $v) = split /:/, $_, 2;
        if ($data{$k}) {
                $data{$k} .= "$;$v";
        } else {
                $data{$k} = "$v";
        }
}
CDB_File::create %data, 'data.cdb', 'data.tmp' or
        die "$0: cdb create failed\n";

3. Use the CDB file created in example 2.

tie %data, 'CDB_File', 'data.cdb' or
        die "$0: can't tie to data.cdb: $!\n";
my $values = $data{$key};
if (defined $values) {
        foreach (split /$;/, $values) {
                # Do that funky thang...
        }
} else {
        warn "$0: can't find `$key'\n";
}

4. Perl version of cdbdump.

tie %data, 'CDB_File', $ARGV[0] or
        die "$0: can't tie to $ARGV[0]: $!\n";
while (($k, $v) = each %data) {
        print '+', length $k, ',', length $v, ":$k->$v\n";
}
print "\n";

5. Although CDB files are constant, it's easy to update them in Perl, at least if you've got enough memory! You could tie %out to a DB_File (or a GDBM_File, etc.) before the assignment in order to reduce the memory requirement. This sounds a bit convoluted, but it might be worth doing if you have a database which is read from many more times than it is written to.

use CDB_File 'create';

tie %in, 'CDB_File', 'dict.cdb' or
        die "$0: can't tie to dict.cdb: $!\n";
%out = %in;
untie %in;

while (<>) {
        chop;
        ($k, $v) = split;
        $out{$k} = $v;
}

create %out, 'dict.cdb', 'dict.tmp' or
        die "$0: can't create dict.cdb: $!\n";

DIAGNOSTICS

Modification of a CDB_File attempted

This fatal error will result from any attempt to modify a hash tied to a CDB_File.

BUGS

It ain't lightweight after you've plumbed Perl into it.

The Perl interface to cdb imposes the restriction that data must fit into memory.

SEE ALSO

cdb(3).

AUTHOR

Tim Goodwin, <tim@uunet.pipex.com>, 1997-01-08.