RubyGems - ruby-qdbm - Versions diffs - 0.1 - Mend

ruby-qdbm 0.1

Files changed (27) hide show

data/rbapidoc/villa.rb.html ADDED Viewed

@@ -0,0 +1,551 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta http-equiv="Content-Style-Type" content="text/css" />
+<link rel="contents" href="./" />
+<link rev="made" href="mailto:mikio@fallabs.com" />
+<title>villa (QDBM for Ruby)</title>
+<style type="text/css">html { margin: 0em 0em; padding 0em 0em; background: #eeeeee none; }
+body { background-color: #eeeeee; color: #111111; padding: 1.5em 2em; margin: 0em 0em;
+  border-left: double 3.0em #eedddd; border-right: solid 1.0em #eedddd;
+  font-style: normal; font-weight: normal; font-family: serif; }
+h1 { margin-top: 0.8em; margin-bottom: 1.3em; font-weight: bold; font-family: sans-serif; }
+h2 { margin-top: 1.8em; margin-bottom: 1.1em; font-weight: bold; font-family: sans-serif; }
+h3 { margin-top: 1.8em; margin-bottom: 0.8em; font-weight: bold; font-family: sans-serif; }
+p,ul,ol,dl { line-height: 140%; }
+em { color: #111111; font-style: italic; font-weight: normal; font-family: serif; }
+kbd { color: #111111; font-style: normal; font-weight: bold; font-family: monospace; }
+a { color: #0022aa; text-decoration: none; }
+a:hover { color: #0033ee; text-decoration: underline; }
+a.head { color: #111111; text-decoration: none; }
+.note { text-align: right; }
+</style>
+</head>
+<body>
+<div class="note">[<a href="index.html">Back</a>]</div>
+<h1>API of villa</h1>
+<hr />
+<dl>
+<dt><kbd>require 'villa'</kbd></dt>
+<dd>
+The library `villa' should be included in application codes.
+An instance of the class `Villa' is used as a database handle.
+`Villa' performs Mix-in of `Enumerable'.
+Each method of `Villa' throws an exception of `Villa::EANY' or its sub classes when an error
+occurs: `Villa::ENOERR', `Villa::EFATAL', `Villa::EMODE', `Villa::EBROKEN', `Villa::EKEEP',
+`Villa::ENOITEM', `Villa::EALLOC', `Villa::EMAP', `Villa::EOPEN', `Villa::ECLOSE',
+`Villa::ETRUNC', `Villa::ESYNC', `Villa::ESTAT', `Villa::ESEEK', `Villa::EREAD',
+`Villa::EWRITE', `Villa::ELOCK', `Villa::EUNLINK', `Villa::EMKDIR', `Villa::ERMDIR' and
+`Villa::EMISC'.
+</dd>
+</dl>
+<dl>
+<dt><kbd>villa = Villa::new(name, omode, cmode)</kbd></dt>
+<dd>
+Constructor: Get a database handle.
+`name' specifies the name of a database file.
+`omode' specifies the connection mode: `Villa::OWRITER' as a writer, `Villa::OREADER' as a
+reader.  If the mode is `Villa::OWRITER', the following may be added by bitwise or:
+`Villa::OCREAT', which means it creates a new database if not exist, `Villa::OTRUNC', which
+means it creates a new database regardless if one exists, `Villa::OZCOMP', which means
+leaves in the database are compressed with ZLIB, `Villa::OYCOMP', which means leaves in the
+database are compressed with LZO, `Villa::OXCOMP', which means leaves in the database are
+compressed with BZIP2.  Both of `Villa::OREADER' and `Villa::OWRITER' can be added to by
+bitwise or: `Villa::ONOLCK', which means it opens a database file without file locking, or
+`Villa::OLCKNB', which means locking is performed without blocking.  If it is omitted,
+`Villa::OREADER' is specified.
+`cmode' specifies the comparing function: `Villa::CMPLEX' comparing keys in lexical order,
+`Villa::CMPDEC' comparing keys as decimal strings, `Villa::CMPOBJ' comparing keys as
+serialized objects implementing the method `&lt;=&gt;'.  The comparing function should be kept
+same in the life of a database.  If `Villa::CMPOBJ' is used, such methods as `put', `out',
+`get' and so on can treat not only instances of `String' but also any serializable and
+comparable object.
+If so, objects being stored are serialized and objects being retrieved are deserialized.
+The return value is the database handle.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs.
+If a block parameter is given, this method works as an iterator.  A database handle is
+opened and passed via the first argument of the block.  The database handle is surely
+closed when the block is over.
+While connecting as a writer, an exclusive lock is invoked to the database file.
+While connecting as a reader, a shared lock is invoked to the database file.  The thread
+blocks until the lock is achieved.  `Villa::OZCOMP', `Villa::OYCOMP', and `Villa::OXCOMP'
+are available only if QDBM was built each with ZLIB, LZO, and BZIP2 enabled.  If
+`Villa::ONOLCK' is used, the application is responsible for exclusion control.
+</dd>
+</dl>
+<dl>
+<dt><kbd>villa = Villa::open(name, omode, cmode)</kbd></dt>
+<dd>
+Constructor: An alias of `new'.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.close()</kbd></dt>
+<dd>
+Method: Close the database handle.
+The return value is always true.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs.
+Because the region of a closed handle is released, it becomes impossible to use the handle.
+Updating a database is assured to be written when the handle is closed.  If a writer opens
+a database but does not close it appropriately, the database will be broken.  If the
+transaction is activated and not committed, it is aborted.
+</dd>
+</dl>
+<dl>
+<dt><kbd>villa.silent = bool</kbd></dt>
+<dd>
+Method: Set the flag whether to repress frequent exceptions.
+The return value is the assigned value.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.put(key, val, dmode)</kbd></dt>
+<dd>
+Method: Store a record.
+`key' specifies a key.  Although it must be an instance of String, binary data is okey.
+`val' specifies a value.  Although it must be an instance of String, binary data is okey.
+`dmode' specifies behavior when the key overlaps, by the following values: `Villa::DOVER',
+which means the specified value overwrites the existing one, `Villa::DKEEP', which means the
+existing value is kept, `Villa::DCAT', which means the specified value is concatenated at the
+end of the existing value, `Villa::DDUP', which means duplication of keys is allowed and the
+specified value is added as the last one, `Villa::DDUPR', which means duplication of keys is
+allowed and the specified value is added as the first one.  If it is omitted, `Villa::DOVER'
+is specified.
+The return value is always true.  However, if the silent flag is true and replace is
+cancelled, false is returned instead of exception.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs or replace
+is cancelled.
+The cursor becomes unavailable due to updating database.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.store(key, val)</kbd></dt>
+<dd>
+Method: An alias of `put'.
+</dd>
+</dl>
+<dl>
+<dt><kbd>villa[key] = val</kbd></dt>
+<dd>
+Method: An alias of `put'.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.out(key)</kbd></dt>
+<dd>
+Method: Delete a record.
+`key' specifies a key.  Although it must be an instance of String, binary data is okey.
+The return value is always true.  However, if the silent flag is true and no record
+corresponds, false is returned instead of exception.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs or no record
+corresponds.
+When the key of duplicated records is specified, the value of the first record of the same
+key is selected.  The cursor becomes unavailable due to updating database.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.delete(key)</kbd></dt>
+<dd>
+Method: An alias of `out'.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.clear()</kbd></dt>
+<dd>
+Method: Delete all records.
+The return value is always true.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs.
+</dd>
+</dl>
+<dl>
+<dt><kbd>str = villa.get(key)</kbd></dt>
+<dd>
+Method: Retrieve a record.
+`key' specifies a key.  Although it must be an instance of String, binary data is okey.
+The return value is an instance of the value of the corresponding record.  If the silent flag
+is true and no record corresponds, nil is returned instead of exception.
+When the key of duplicated records is specified, the first record of the same key is
+deleted.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs or no record
+corresponds.
+</dd>
+</dl>
+<dl>
+<dt><kbd>str = villa.fetch(key, defval)</kbd></dt>
+<dd>
+Method: Retrieve a record.
+`key' specifies a key.  Although it must be an instance of String, binary data is okey.
+`defval' specifies the default value used when no record corresponds.  If it is omitted, nil
+is specified.
+The return value is an instance of the value of the corresponding record, or the default
+value if no record corresponds.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs.
+</dd>
+</dl>
+<dl>
+<dt><kbd>str = villa[key]</kbd></dt>
+<dd>
+Method: An alias of `fetch'.
+</dd>
+</dl>
+<dl>
+<dt><kbd>num = villa.vsiz(key)</kbd></dt>
+<dd>
+Method: Get the size of the value of a record.
+`key' specifies a key.  Although it must be an instance of String, binary data is okey.
+The return value is the size of the value of the corresponding record.  If the silent flag
+is true and no record corresponds, -1 is returned instead of exception.  If multiple records
+correspond, the size of the first is returned.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs.
+</dd>
+</dl>
+<dl>
+<dt><kbd>num = villa.vnum(key)</kbd></dt>
+<dd>
+Method: Get the number of records corresponding a key.
+`key' specifies a key.  Although it must be an instance of String, binary data is okey.
+The return value is the size of the value of the corresponding record.  If no record
+corresponds, 0 is returned.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.curfirst()</kbd></dt>
+<dd>
+Method: Move the cursor to the first record.
+The return value is always true.  However, if the silent flag is true and no record
+corresponds, false is returned instead of exception.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs or there is
+no record in the database.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.curlast()</kbd></dt>
+<dd>
+Method: Move the cursor to the last record.
+The return value is always true.  However, if the silent flag is true and no record
+corresponds, false is returned instead of exception.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs or there is
+no record in the database.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.curprev()</kbd></dt>
+<dd>
+Method: Move the cursor to the previous record.
+The return value is always true.  However, if the silent flag is true and no record
+corresponds, false is returned instead of exception.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs or there is
+no previous record.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.curnext()</kbd></dt>
+<dd>
+Method: Move the cursor to the next record.
+The return value is always true.  However, if the silent flag is true and no record
+corresponds, false is returned instead of exception.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs or there is
+no next record.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.curjump(key, jmode)</kbd></dt>
+<dd>
+Method: Move the cursor to a position around a record.
+`key' specifies a key.  Although it must be an instance of String, binary data is okey.
+`jmode' specifies detail adjustment: `Villa::JFORWARD', which means that the cursor is set
+to the first record of the same key and that the cursor is set to the next substitute if
+completely matching record does not exist, `Villa::JBACKWARD', which means that the cursor
+is set to the last record of the same key and that the cursor is set to the previous
+substitute if completely matching record does not exist.  If it is omitted, `Villa::JFORWARD'
+is specified.
+The return value is always true.  However, if the silent flag is true and no record
+corresponds, false is returned instead of exception.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs or there is
+no record corresponding the condition.
+</dd>
+</dl>
+<dl>
+<dt><kbd>str = villa.curkey()</kbd></dt>
+<dd>
+Method: Get the key of the record where the cursor is.
+The return value is the key of the corresponding record.  If the silent flag is true and no
+record corresponds, nil is returned instead of exception.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs or no record
+corresponds to the cursor.
+</dd>
+</dl>
+<dl>
+<dt><kbd>str = villa.curval()</kbd></dt>
+<dd>
+Method: Get the value of the record where the cursor is.
+The return value is the value of the corresponding record.  If the silent flag is true and no
+record corresponds, nil is returned instead of exception.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs or no record
+corresponds to the cursor.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.curput(val, cpmode);</kbd></dt>
+<dd>
+Method: Insert a record around the cursor.
+`val' specifies a value.  Although it must be an instance of String, binary data is okey.
+`cpmode' specifies detail adjustment: `Villa::CPCURRENT', which means that the value of the
+current record is overwritten, `Villa::CPBEFORE', which means that a new record is inserted
+before the current record, `Villa::CPAFTER', which means that a new record is inserted after
+the current record.  If it is omitted, `Villa::CPCURRENT' is specified.
+The return value is always true.  However, if the silent flag is true and no record
+corresponds to the cursor, false is returned instead of exception.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs or no record
+corresponds to the cursor.
+After insertion, the cursor is moved to the inserted record.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.curout();</kbd></dt>
+<dd>
+Method: Delete the record where the cursor is.
+The return value is always true.  However, if the silent flag is true and no record
+corresponds to the cursor, false is returned instead of exception.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs or no record
+corresponds to the cursor.
+After deletion, the cursor is moved to the next record if possible.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.settuning(lrecmax, nidxmax, lcnum, ncnum)</kbd></dt>
+<dd>
+Method: Set the tuning parameters for performance.
+`lrecmax' specifies the max number of records in a leaf node of B+ tree.  If it is not more
+than 0, the default value is specified.
+`nidxmax' specifies the max number of indexes in a non-leaf node of B+ tree.  If it is not
+more than 0, the default value is specified.
+`lcnum' specifies the max number of caching leaf nodes.  If it is not more than 0, the
+default value is specified.
+`ncnum' specifies the max number of caching non-leaf nodes.  If it is not more than 0, the
+default value is specified.
+The return value is always true.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs.
+The default setting is equivalent to `vlsettuning(49, 192, 1024, 512)'.  Because tuning
+parameters are not saved in a database, you should specify them every opening a database.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.sync()</kbd></dt>
+<dd>
+Method: Synchronize updating contents with the file and the device.
+The return value is always true.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs.
+This method is useful when another process uses the connected database file.  This method
+should not be used while the transaction is activated.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.optimize()</kbd></dt>
+<dd>
+Method: Optimize the database.
+The return value is always true.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs.
+In an alternating succession of deleting and storing with overwrite or concatenate,
+dispensable regions accumulate.  This method is useful to do away with them.  This method
+should not be used while the transaction is activated.
+</dd>
+</dl>
+<dl>
+<dt><kbd>num = villa.fsiz()</kbd></dt>
+<dd>
+Method: Get the size of the database file.
+The return value is the size of the database file.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs.
+Because of the I/O buffer, the return value may be less than the real size.
+</dd>
+</dl>
+<dl>
+<dt><kbd>num = villa.rnum()</kbd></dt>
+<dd>
+Method: Get the number of the records stored in the database.
+The return value is the number of the records stored in the database.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs.
+</dd>
+</dl>
+<dl>
+<dt><kbd>num = villa.length()</kbd></dt>
+<dd>
+Method: An alias of `rnum'.
+</dd>
+</dl>
+<dl>
+<dt><kbd>num = villa.size()</kbd></dt>
+<dd>
+Method: An alias of `rnum'.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.writable()</kbd></dt>
+<dd>
+Method: Check whether the database handle is a writer or not.
+The return value is true if the handle is a writer, false if not.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.fatalerror()</kbd></dt>
+<dd>
+Method: Check whether the database has a fatal error or not.
+The return value is true if the database has a fatal error, false if not.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.tranbegin()</kbd></dt>
+<dd>
+Method: Begin the transaction.
+The return value is always true.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs.
+If a thread is already in the transaction, the other threads block until the prius is out
+of the transaction.  Only one transaction can be activated with a database handle at the
+same time.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.trancommit()</kbd></dt>
+<dd>
+Method: Commit the transaction.
+The return value is always true.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs.
+Updating a database in the transaction is fixed when it is committed successfully.  Any
+other thread except for the one which began the transaction should not call this method.
+</dd>
+</dl>
+<dl>
+<dt><kbd>bool = villa.tranabort()</kbd></dt>
+<dd>
+Method: Abort the transaction.
+The return value is always true.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs.
+Updating a database in the transaction is discarded when it is aborted.  The state of the
+database is rollbacked to before transaction.  Any other thread except for the one which
+began the transaction should not call this method.
+</dd>
+</dl>
+<dl>
+<dt><kbd>villa.transaction() do ... end</kbd></dt>
+<dd>
+Iterator Method: Perform an iterator block in the transaction.
+The specified iterator block is performed in the transaction.  If the block returns true,
+the transaction is committed.  If the block returns false or raises any exception, the
+transaction is aborted.
+</dd>
+</dl>
+<dl>
+<dt><kbd>villa.each() do |key, val| ... end</kbd></dt>
+<dd>
+Iterator Method: Iterate a process with a pair of a key and a value of each record.
+</dd>
+</dl>
+<dl>
+<dt><kbd>villa.each_pair() do |key, val| ... end</kbd></dt>
+<dd>
+Iterator Method: An alias of `each'.
+</dd>
+</dl>
+<dl>
+<dt><kbd>villa.each_key() do |key| ... end</kbd></dt>
+<dd>
+Iterator Method: Iterate a process with a key of each record.
+</dd>
+</dl>
+<dl>
+<dt><kbd>villa.each_value() do |val| ... end</kbd></dt>
+<dd>
+Iterator Method: Iterate a process with a value of each record.
+</dd>
+</dl>
+<dl>
+<dt><kbd>ary = villa.keys()</kbd></dt>
+<dd>
+Method: Get an array of all keys.
+The return value is an array of all keys.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs.
+</dd>
+</dl>
+<dl>
+<dt><kbd>ary = villa.values()</kbd></dt>
+<dd>
+Method: Get an array of all values.
+The return value is an array of all values.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs.
+</dd>
+</dl>
+<dl>
+<dt><kbd>str = villa.index(val)</kbd></dt>
+<dd>
+Method: Retrieve a record with a value.
+`val' specifies a value.  Although it must be an instance of String, binary data is okey.
+The return value is the key of the record with the specified value.
+An exception of `Villa::EANY' or its sub classes is thrown if an error occurs or no record
+corresponds.
+If two or more records correspond, the first found record is selected.
+</dd>
+</dl>
+<dl>
+<dt><kbd>num = villa.to_int()</kbd></dt>
+<dd>
+Method: An alias of `rnum'.
+</dd>
+</dl>
+<dl>
+<dt><kbd>num = villa.to_i()</kbd></dt>
+<dd>
+Method: An alias of `to_int'.
+</dd>
+</dl>
+<dl>
+<dt><kbd>str = villa.to_str()</kbd></dt>
+<dd>
+Method: Get string standing for the instance.
+</dd>
+</dl>
+<dl>
+<dt><kbd>str = villa.to_s()</kbd></dt>
+<dd>
+Method: An alias of `to_str'.
+</dd>
+</dl>
+<dl>
+<dt><kbd>ary = villa.to_ary()</kbd></dt>
+<dd>
+Method: Get an array of alternation of each pair of a key and a value.
+</dd>
+</dl>
+<dl>
+<dt><kbd>ary = villa.to_a()</kbd></dt>
+<dd>
+Method: An alias of `to_ary'.
+</dd>
+</dl>
+<dl>
+<dt><kbd>hash = villa.to_hash()</kbd></dt>
+<dd>
+Method: Get a hash storing all records.
+</dd>
+</dl>
+<dl>
+<dt><kbd>hash = villa.to_h()</kbd></dt>
+<dd>
+Method: An alias of `to_hash'.
+</dd>
+</dl>
+<dl>
+<dt><kbd>str = villa.inspect()</kbd></dt>
+<dd>
+Method: An alias of `to_str'.
+</dd>
+</dl>
+<hr />
+<div class="note">Generated by ./myrbdoc, 2010/08/05.</div>
+</body>
+</html>