view release on metacpan or  search on metacpan

lib/BerkeleyDB/Easy.pm  view on Meta::CPAN

sub new {
    require BerkeleyDB;
    require BerkeleyDB::Easy::Handle;
    shift->SUPER::_new(@_, Type => BerkeleyDB::DB_RECNO());
}

# --------------------------------------------------------

package BerkeleyDB::Easy::Queue;
our @ISA = qw(BerkeleyDB::Easy::Handle);

sub new {
    require BerkeleyDB;
    require BerkeleyDB::Easy::Handle;
    shift->SUPER::_new(@_, Type => BerkeleyDB::DB_QUEUE());
}

# --------------------------------------------------------

package BerkeleyDB::Easy::Heap;
our @ISA = qw(BerkeleyDB::Easy::Handle);

sub new {
    require BerkeleyDB;
    require BerkeleyDB::Easy::Handle;
    shift->SUPER::_new(@_, Type => BerkeleyDB::DB_HEAP());
}

# --------------------------------------------------------

package BerkeleyDB::Easy::Unknown;
our @ISA = qw(BerkeleyDB::Easy::Handle);

sub new {
    require BerkeleyDB;
    require BerkeleyDB::Easy::Handle;
    shift->SUPER::_new(@_, Type => BerkeleyDB::DB_UNKNOWN());
}

# --------------------------------------------------------

1;

=encoding utf8

=head1 NAME

BerkeleyDB::Easy - BerkeleyDB wrapper with Perlish interface and error handling

=head1 SYNOPSIS

    my $db = BerkeleyDB::Easy::Btree->new(
        -Filename => 'test.db',
        -Flags    => DB_CREATE,
    );

    $db->put('foo', 'bar');

    my $foo = $db->get('foo');

    my $cur = $db->cursor;

    while (my ($key, $val) = $cur->next) {
        $db->del($key);
    }

    $db->sync;

=head1 DESCRIPTION

BerkeleyDB::Easy is a convenience wrapper around BerkeleyDB.pm. It will 
reduce the amount of boilerplate you have to write, with special focus
on comprehensive and customizable error handling and logging, with minimal
overhead.

=head1 ERRORS

When using BerkeleyDB, errors can be generated at many levels. The OS,
the Perl interpreter, the BDB C library, and the BerkeleyDB.pm module.
Each of these need to be handled via different mechanisms, which can be
quite a headache. This module attempts to consolidate and automate error
handling at all these levels, so you don't have to think about it.

Errors are thrown as a versatile structured exception object. It is overloaded
to stringify as a concise message, numberify into an error code, and has various
methods for detailed handling.

    use BerkeleyDB::Easy;

    my $db = BerkeleyDB::Easy::Btree->new();
    my $err;

    use Try::Tiny;
    try { $db->get('asdf', 666) } catch { $err = $_ };

    use feature 'say';
    say $err;

    # [BerkeleyDB::Easy::Handle::get] EINVAL (22): Invalid argument.
    #   DB_READ_COMMITTED, DB_READ_UNCOMMITTED and DB_RMW require locking
    #   at error.pl line 16.

    say 0 + $err;

    # 22

    use Data::Dump;
    dd $err;

    # bless({
    #   code    => 22,
    #   desc    => "Invalid argument",
    #   detail  => "DB_READ_COMMITTED, DB_READ_UNCOMMITTED and DB_RMW require locking",
    #   file    => "error.pl",
    #   level   => "BDB_ERROR",
    #   line    => 16,
    #   message => "Invalid argument. DB_READ_COMMITTED, DB_READ_UNCOMMITTED and "
    #            . "DB_RMW require locking",
    #   name    => "EINVAL",
    #   package => "main",
    #   string  => "[BerkeleyDB::Easy::Handle::get] EINVAL (22): Invalid argument. "