view release on metacpan or  search on metacpan

MCDB_File.pm  view on Meta::CPAN

package MCDB_File;

use strict;
use warnings;
use Carp;
use vars qw($VERSION @ISA);

use DynaLoader ();
use Exporter ();

@ISA = qw(Exporter DynaLoader);

$VERSION = '0.0108';

=head1 NAME

MCDB_File - Perl extension for access to mcdb constant databases 

=head1 SYNOPSIS

    use MCDB_File ();
    tie %mcdb, 'MCDB_File', 'file.mcdb' or die "tie failed: $!\n";
    $value = $mcdb{$key};
    $num_records = scalar $mcdb;
    untie %mcdb;

    use MCDB_File ();
    eval {
      my $mcdb_make = new MCDB_File::Make('t.mcdb')
        or die "create t.mcdb failed: $!\n";
      $mcdb_make->insert('key1', 'value1');
      $mcdb_make->insert('key2' => 'value2', 'key3' => 'value3');
      $mcdb_make->insert(%t);
      $mcdb_make->finish;
    } or ($@ ne "" and warn "$@");

    use MCDB_File ();
    eval { MCDB_File::Make::create $file, %t; }
      or ($@ ne "" and warn "$@");

=head1 DESCRIPTION

B<MCDB_File> is a module which provides a Perl interface to B<mcdb>.
mcdb is originally based on Dan Bernstein's B<cdb> package.

    mcdb - fast, reliable, simple code to create, read constant databases

=head2 Reading from an mcdb constant database

After the C<tie> shown above, accesses to C<%h> will refer
to the B<mcdb> file C<file.mcdb>, as described in L<perlfunc/tie>.

C<keys>, C<values>, and C<each> can be used to iterate through records.
Note that only one iteration loop can be in progress at any one time.
Performing multiple iterations at the same time (i.e. in nested loops)
will not have independent iterators and therefore should be avoided.
Note that it is safe to use the find('key') method while iterating.
See PERFORMANCE section below for sample usage.

=head2 Creating an mcdb constant database

An B<mcdb> file is created in three steps.  First call
C<new MCDB_File::Make($fname)>, where C<$fname> is the name of the
database file to be created.  Secondly, call the C<insert> method
once for each (I<key>, I<value>) pair.  Finally, call the C<finish>
method to complete the creation.  A temporary file is used during
mcdb creation and atomically renamed to C<$fname> when C<finish>
method is successful.

Alternatively, call the C<insert()> method with multiple key/value
pairs. This can be significantly faster because there is less crossing
over the bridge from perl to C code. One simple way to do this is to pass
in an entire hash, as in: C<< $mcdb_make->insert(%hash); >>.

A simpler interface to B<mcdb> file creation is provided by
C<MCDB_File::Make::create $fname, %t>.  This creates an B<mcdb> file named
C<$fname> containing the contents of C<%t>.

=head1 EXAMPLES

These are all complete programs.

1. Use $mcdb->find('key') method to look up a 'key' in an mcdb.

    use MCDB_File ();
    $mcdb = tie %h, MCDB_File, "$file.mcdb" or die ...;
    $value = $mcdb->find('key'); # slightly faster than $value = $h{key};
    undef $mcdb;
    untie %h;

2. Convert a Berkeley DB (B-tree) database to B<mcdb> format.

    use MCDB_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";

    MCDB_File::Make::create $ARGV[1], %h;  # croak()s if error

3. Convert a flat file to B<mcdb> 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 B<#> are skipped.

    use MCDB_File;

    eval {
        my $mcdb = new MCDB_File::Make("data.mcdb")
          or die "$0: new MCDB_File::Make failed: $!\n";
        while (<>) {
            next if /^$/ or /^#/;
            chomp;
            ($k, $v) = split /:/, $_, 2;
            if (defined $v) {
                $mcdb->insert($k, $v);