QDBM provides API for Ruby. This encapsulates the basic API and the extended API of QDBM. These APIs are safe on multi thread environment of Ruby.
You call the constructor `new' of the class `Depot' or `Curia' to open a database file or directory and get the handle. The method `close' is used in order to close the database. Although a finalizer is not used, an iterator of `new' method save you from neglecting to call `close'. The method `put' is used in order to store a record. The method `out' is used in order to delete a record. The method `get' is used in order to retrieve a record. Besides, most operations like ones of the basic API and the extended API for C is available.
Although keys and values of storing records are treated as strings, binary data can be stored as they are. `Depot' realizes a database with a file. `Curia' realizes a database with a directory and multiple files. Although the formar is faster, the latter is more scalable.
Because `Depot' and `Curia' perform Mix-in of the module `Enumerable', you can use such methods as `find', `sort' and so on. Moreover, they implements such methods: `[]=', `[]' and so on like the class `Hash', you can use a database like a usual hash.
For more information about the APIs, read documents in the sub directory `rapidoc'.
Make sure that Ruby 1.6.5 or later version is installed and make sure that QDBM is installed under `/usr/local'.
Change the current working directory to the subdirectory named `ruby'.
cd ruby
Run the configuration script.
./configure
Build programs.
make
Perform self-diagnostic test.
make check
Install programs. This operation must be carried out by the root user.
make install
When a series of work finishes, `depot.rb', `mod_depot.so', `curia.rb', `mod_curia.so' and so on are installed under an appropriate directory according to the install directory of Ruby. Executable commands `rdptest' and `rcrtest' will be installed in `/usr/local/bin'.
The following example stores and retrieves a phone number, using the name as the key.
require 'depot' NAME = "mikio" NUMBER = "000-1234-5678" DBNAME = "book" def main depot = nil begin # open the database depot = Depot::new(DBNAME, Depot::OWRITER | Depot::OCREAT) # store the record depot.put(NAME, NUMBER) # retrieve the record printf("Name: %s\n", NAME) printf("Number: %s\n", depot.get(NAME)) rescue printf("%s\n", $!) return 1 ensure # close the database if(depot) begin depot.close() rescue printf("%s\n", $!) end end end return 0 end exit(main());
The following example is a transcription of the one above, using hash-like interface and iterator.
require 'depot' NAME = "mikio" NUMBER = "000-1234-5678" DBNAME = "book" def main begin # open the database and close it automatically Depot::new(DBNAME, Depot::OWRITER | Depot::OCREAT) do |depot| # store the record depot[NAME] = NUMBER # retrieve the record printf("Name: %s\n", NAME) printf("Number: %s\n", depot[NAME]) end rescue printf("%s\n", $!) return 1 end return 0 end exit(main());
This API are subtly different from the interface of standard library `DBM'.
This API can be implemented more effectively by Ruby hackers.
For the sake of simplicity of interface, Curia for Ruby does not feature handling large objects.