NAME
SQLite_File - Tie to SQLite, with DB_File emulation
SYNOPSIS
# tie a simple hash to a SQLite DB file
my %db;
tie(%db, 'SQLite_File', 'my.db');
# tie an array
my @db;
tie(@db, 'SQLite_File', 'my.db');
# tie to a tempfile
tie(%db, 'SQLite_File', undef);
# get attributes of the tied object
$SQLite_handle = (tied %db)->dbh;
$db_file = (tied %db)->file;
# use as an option in AnyDBM_File
@AnyDBM_File::ISA = qw( DB_File SQLite_File SDBM );
my %db;
tie(%db, 'AnyDBM_File', 'my.db', @dbmargs)DESCRIPTION
This module allows a hash or an array to be tied to a SQLite DB via DBI plus DBD::SQLite, in a way that emulates many features of Berkeley-DB-based DB_File. In particular, this module offers another choice for ActiveState users, who may find it difficult to get a working DB_File installed, but can't failover to SDBM due to its record length restrictions. SQLite_File requires DBD::SQLite, which has SQLite built-in -- no external application install required.
Key/Value filters
The filter hooks fetch_key_filter, fetch_value_filter, store_key_filter, and store_value_filter are honored.
DB_File Emulation
The intention was to create a DBM that could almost completely substitute for DB_File, so that DB_File could be replaced everywhere in code by AnyDBM_File, and things would just work. Currently, it is slightly more complicated than that, but not too much more.
Versions of $DB_HASH, $DB_BTREE, and $DB_RECNO, as well as the necessary flags (R_DUP, R_FIRST, R_NEXT, etc.) are imported by using the AnyDBM_File::Importer module. The desired constants need to be declared global in the calling program, as well as imported, to avoid compilation errors (at this point). See "Converting from DB_File" below.
Arguments to the tie function mirror those of DB_File, and all should work the same way. See "Converting from DB_File".
All of DB_File's random and sequential access functions work:
get()
put()
del()
seq()as well as the duplicate key handlers
get_dup()
del_dup()
find_dup()seq() works by finding partial matches, like DB_File::seq(). The extra array functions ( shift(), pop(), etc. ) are not yet implemented as method calls, though all these functions (including splice are available on the tied arrays.
Some HASHINFO fields are functional:
$DB_BTREE->{'compare'} = sub { - shift cmp shift };will provide sequential access in reverse lexographic order, for example.
$DB_HASH->{'cachesize'} = 20000;will enforce PRAGMA cache_size = 20000.
Converting from DB_File
To failover to SQLite_File from DB_File, go from this:
use DB_File;
# ...
$DB_BTREE->{cachesize} = 100000;
$DB_BTREE->{flags} = R_DUP;
my %db;
my $obj = tie( %db, 'DB_File', 'my.db', $flags, 0666, $DB_BTREE);to this:
use vars qw( $DB_HASH &R_DUP );
BEGIN {
@AnyDBM_File::ISA = qw( DB_File SQLite_File )
unless @AnyDBM_File::ISA == 1; #
}
use AnyDBM_File;
use AnyDBMImporter qw(:bdb);
# ...
$DB_BTREE->{cachesize} = 100000;
$DB_BTREE->{flags} = R_DUP;
my %db;
my $obj = tie( %db, 'AnyDBM_File', 'my.db', $flags, 0666, $DB_BTREE);SEE ALSO
AnyDBMImporter, DBD::SQLite, DB_File, AnyDBM_File
AUTHOR - Mark A. Jensen
Email jensen -at- fortinbras -dot- us http://fortinbras.us http://www.bioperl.org/wiki/Mark_Jensen
CONTRIBUTORS
This code owes an intellectual debt to Lincoln Stein. Inelegancies and bugs are mine.
COPYRIGHT
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
Attribute accessors
file
Title : file
Usage : $obj->file($newval)
Function: filename for the SQLite db
Example :
Returns : value of file (a scalar)
Args : on set, new value (a scalar or undef, optional)_fh
Title : _fh
Usage : $obj->_fh($newval)
Function: holds the temp file handle
Example :
Returns : value of _fh (a scalar)
Args : on set, new value (a scalar or undef, optional)keep
Title : keep
Usage : $obj->keep($newval)
Function: flag allows preservation of db file when set
Example :
Returns : value of keep (a scalar)
Args : on set, new value (a scalar or undef, optional)ref()
Title : ref
Usage : $obj->ref
Function: HASH or ARRAY? Find out.
Returns : scalar string : 'HASH' or 'ARRAY'
Args : noneindex
Title : index
Usage : $obj->index($newval)
Function: access the index type structure ($DB_BTREE, $DB_HASH, $DB_RECNO)
that initialized this instance
Example :
Returns : value of index (a hashref)
Args : _keys
Title : _keys
Usage : internal
Function: points to a hash to make iterating easy and fun
Example :
Returns : value of _keys (a hashref)
Args : on set, an arrayref of scalar keysBDB API Emulation: random access
get()
Title : get
Usage : $X->get($key, $value, $flags)
Function: as in DB_File
Returns :
Args : put()
Title : put
Usage : $X->put($key, $value, $flags)
Function: as in DB_File
Returns :
Args : del()
Title : del
Usage :
Function: as in DB_file
Returns :
Args : BDB API Emulation : sequential access
seq()
Title : seq
Usage :
Function: as in DB_File
Returns :
Args : sync()
Title : sync
Usage :
Function: stub for BDB sync
Returns : 0
Args : BDB API Emulation: dup
dup
Title : dup
Usage : $obj->dup($newval)
Function: flag to indicate whether duplicate keys are handled
(compare R_DUP of DB_File)
Example :
Returns : value of dup (a scalar)
Args : on set, new value (a scalar or undef, optional)get_dup()
Title : get_dup
Usage :
Function: as in DB_File
Returns :
Args : find_dup()
Title : find_dup
Usage :
Function: as in DB_File
Returns :
Args :
Note : no cursor functionalitydel_dup()
Title : del_dup
Usage :
Function: as in DB_File
Returns :
Args : BDB API Emulation : internals
partial_match()
Title : partial_match
Usage :
Function: emulate the partial matching of DB_File::seq() with
R_CURSOR flag
Returns :
Args : $keySQL interface : internal
dbh
Title : dbh
Usage : $obj->dbh($newval)
Function: database handle
Example :
Returns : value of dbh (a scalar)
Args : on set, new value (a scalar or undef, optional)sth()
Title : sth
Usage : $obj->sth($stmt_descriptor)
Function: statement handle generator
Returns : a prepared DBI statement handle
Args : scalar string (statement descriptor)
Note : calls such as $obj->put_sth are autoloaded through
this methodcommit()
Title : commit
Usage :
Function: commit transactions
Returns :
Args : commit(1) forces, commit() commits when
number of pending transactions > $MAXPENDpending()
Title : pending
Usage : $obj->pending
Function: count of pending (uncommitted) transactions
Returns : scalar int
Args : none (rdonly)trace()
Title : trace
Usage :
Function: invoke the DBI trace logging service
Returns :
Args : scalar int trace levelPrivate index methods : Internal
_index_is_stale()
Title : _index_is_stale
Usage :
Function: predicate indicating whether a _reindex has been
performed since adding or updating the db
Returns :
Args : none_index()
Title : _index
Usage :
Function: initial the internal index array (maps sequential
coordinates to db primary key integers)
Returns : 1 on success
Args : none_reindex()
Title : _reindex
Usage :
Function: reorder SEQIDX to reflect BTREE ordering,
preserving cursor
Returns : true on success
Args : none_find_idx()
Title : _find_idx
Usage :
Function: search of array for index corresponding
to a given value
Returns : scalar int (target array index)
Args : scalar int (target value), array ref (index array)_wring_SEQIDX()
Title : _wring_SEQIDX
Usage :
Function: remove undef'ed values from SEQIDX,
preserving cursor
Returns :
Args : none_get_pk()
Title : _get_pk
Usage :
Function: provide an unused primary key integer for seq access
Returns : scalar int
Args : none_last_pk
Title : _last_pk
Usage : $obj->_last_pk($newval)
Function: the primary key integer returned on the last FETCH
Example :
Returns : value of _last_pk (a scalar)
Args : on set, new value (a scalar or undef, optional)