DBM - DBM interface for STk

version 0.2

1. Overview

DBM-like libraries provides an easy way to store values to a file, indexed by keys. You can think it as a persistent associative memory. This package provides a generic interface to the various dbm-like libraries. Current version hass bridges to gdbm, ndbm and legacy dbm libraries.

1.1 Requirements

You need STk version 4.0.1 or later. STk is available at http://kaolin.unice.fr/stk/. Also a generic serializer package for STk (after 0.3) is required. It is available at http://pracitcal-scheme.net/.

You should have at least one of dbm, ndbm or gdbm library. Gdbm is available at http://www.gnu.org/software/gdbm/gdbm.html.

1.2 Installation

The most recent version of the document and the package is available at the following URLs. (The package tarball includes the html document).

Document: http://practical-scheme.net/vault/dbm.html
Package: http://practical-scheme.net/vault/dbm-0.2.tar.gz

After ungzip and untar the package, you'll find a directory dbm. Just type

./configure

to create a Makefile. Then

make

compiles necessary files. If you like to confirm everything is OK, type

make test

to do some test. You can install the package to the site-scheme location by

make install

2. Common Interface

The <dbm> abstract class defines a common interface to use various DBM-type database packages.

Just to operate on the already created and opened database, require "dbm" module.

(require "dbm")

To create or open a database, you need to load at lease one of the following modules. Each module defines its own low-level accessing functions as well as the common interface.

gdbm: GDBM library. Besides the common interface, all of the options GDBM provides are available. See section 3. GDBM bridge for details.
ndbm: NDBM library. See section 4. NDBM bridge for details.
odbm: DBM library. See section 5. Original DBM bridge for details.

By default, only strings are allowed to keys and values. You can use other Scheme types for keys and values, however, by specifying a serializer class upon the creation of the <dbm> instance. See section 2.5 Object serialization for details.

2.1 Opening a database

By instantiating a subclass of the <dbm> class, you can either open an existing database or create a new database.

Generic method: make class &key :path :rw-mode :file-mode :serializer

Create a new dbm object associated to the database file path if class is one of subclasses of the class <dbm>.

Depending on the actual implementation, path may be used literally as a database filename (gdbm) or some suffixes are added (odbm, ndbm).

The keyword argument rw-mode takes one of the following values:

:read: Opens a database for read-only. If the specified database file does not exist, an error is signalled.
:write: Opens a database for read and write. If the specified database file does not exist, a new empty database is created. This is the default.
:create: Creates a database for read and write. If the specified database file already exists, its content is cleared.

The keyword argument file-mode takes a number representing unix file mode to be used when make needs to create a new database. The default is #o664. This value may be masked by the user's umask setting.

DBM interface only takes strings for keys and values by default. If you need to store other types of objects to the database, you need to tell the DBM instance how to convert those objects by serializer keyword argument. It may take a class object which is a subclass of <serializer>, or a value #t. If it is a subclass of <serializer>, a serializer instance of the class is used to convert Scheme objects. If it is #t, the standard external representation is used. See section 2.5 Object serialization for details how this mechanism works.

2.2 Accessing a database

Once a database object is created, you can use the following methods to access individual key/value pairs. Note that, unless you specify serializer argument when you create the dbm object, keys and values must be strings. See section 2.5 Object serialization for details.

Generic method: dbm-put! (dbm <dbm>) key value: Put a value with key.

Generic method: dbm-get (dbm <dbm>) key &optional default: Get a value associated with key. If no value exists for key and default is specified, it is returned. If no value exists for key and default is not specified, an error is signalled.

Generic method: dbm-exists? (dbm <dbm>) key: Return true if a value exists for key, false otherwise.

Generic method: dbm-delete! (dbm <dbm>) key: Delete a value associated with key.

2.3 Iterating on a database

To walk over the entire database, following methos are provided.

Generic method: dbm-for-each (dbm <dbm>) procedure: For each key/value pair in the database dbm, procedure is called. Two arguments are passed to procedure---a key and a value. The result of procedure is discarded.

Generic method: dbm-map (dbm <dbm>) procedure: For each key/value pair in the database dbm, procedure is called. Two arguments are passed to procedure---a key and a value. The result of procedure is accumulated to a list which is returned as a result of dbm-map.

2.4 To close a database

Database file is closed when it is garbage collected. However, to ensure the modification is properly synchornized, you may want to close the database explicitly

Generic method: dbm-close (dbm <dbm>): Closes a database dbm. Once the database is closed, any operation to access the database content raises an error.

Generic method: dbm-closed? (dbm <dbm>): Returns true if a database dbm is already closed, false otherwise.

2.5 Object serialization

The low-level interface to the dbm libraries only deals with strings. If you want to store general Scheme objects, you need to specify how to convert back and forth between objects and strings. Different applications need different requirements, so it's not good to implement one specific way in this library.

With :serializer parameter in the constructor of dbm class, you can specify your serialization scheme.

#f

No conversion is done. You must pass a string as a key or a value. Keys are effectively compared by string=?.

#t

DBM interface applies write* to get a string representation of the object, and read to get the original object back. This means:

You can use only use primitive Scheme types, such as numbers, booleans, characters, symbols, strings, and lists and vectors of those types.
No check is done if the object is representable by string. If you pass the object whose external representation can't be read back, no error is signalled in dbm-put!, but you'll have a trouble when you try to retrieve the data later.
Keys are effectively compared by equal?

a class derived from <serializer>

An abstract base class <serializer> defines a common interface for object serialization. You can pass a serializer implemenation of your choice. See http://practical-scheme.net/vault/serializer.html about the details of serializer.