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

ruby-qdbm 0.1

Files changed (27) hide show

data/rbspex-ja.html ADDED Viewed

@@ -0,0 +1,284 @@
+<?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" xml:lang="ja" lang="ja">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta http-equiv="Content-Style-Type" content="text/css" />
+<meta name="author" content="Mikio Hirabayashi" />
+<meta name="keywords" content="QDBM, Ruby, Depot, Curia, Villa" />
+<meta name="description" content="specifications of Ruby API of QDBM" />
+<link rel="contents" href="./" />
+<link rel="alternate" href="rbspex.html" hreflang="en" title="the English version" />
+<link rev="made" href="mailto:mikio@fallabs.com" />
+<title>Specifications of QDBM for Ruby (Japanese)</title>
+<style type="text/css">html { margin: 0em 0em; padding: 0em 0em; background: #eeeeee none; }
+body { margin: 2em 2em; padding: 0em 0em;
+  background: #eeeeee none; color: #111111;
+  font-style: normal; font-weight: normal; }
+h1 { margin-top: 1.8em; margin-bottom: 1.3em; font-weight: bold; }
+h2 { margin-top: 1.8em; margin-bottom: 1.1em; font-weight: bold;
+  border-left: solid 0.6em #445555; border-bottom: solid 1pt #bbbbbb;
+  padding: 0.5em 0.5em; width: 60%; }
+h3 { margin-top: 1.8em; margin-bottom: 0.8em; font-weight: bold; }
+hr { margin-top: 2.5em; margin-bottom: 1.5em; height: 1pt;
+  color: #999999; background-color: #999999; border: none; }
+div.note,div.navi { text-align: right; }
+div.logo { text-align: center; margin: 3em 0em; }
+div.logo img { border: inset 2pt #ccccdd; }
+p { margin: 0.8em 0em; line-height: 140%; }
+p,dd { text-indent: 0.8em; }
+div,pre { margin-left: 1.7em; margin-right: 1.7em; }
+pre { background-color: #ddddee; padding: 0.2em; border: 1pt solid #bbbbcc; font-size: smaller; }
+kbd { color: #111111; font-style: normal; font-weight: bold; }
+a { color: #0022aa; text-decoration: none; }
+a:hover,a:focus { color: #0033ee; text-decoration: underline; }
+a.head { color: #111111; text-decoration: none; }
+table { padding: 1pt 2pt 1pt 2pt; border: none; margin-left: 1.7em; border-collapse: collapse; }
+th { padding: 1pt 4pt 1pt 4pt; border-style: none;
+  text-align: left; vertical-align: bottom; }
+td { padding: 1pt 4pt 1pt 4pt; border: 1pt solid #333333;
+  text-align: left; vertical-align: top; }
+ul,ol,dl { line-height: 140%; }
+dt { margin-left: 1.2em; }
+dd { margin-left: 2.0em; }
+ul.lines { list-style-type: none; }
+@media print {
+  html,body { margin: 0em 0em; background-color: #ffffff; color: #000000; }
+  h1 { padding: 8em 0em 0.5em 0em; text-align: center; }
+  h2 { page-break-before: always; }
+  div.note { text-align: center; }
+  div.navi,div.logo { display: none }
+  hr { display: none; }
+  pre { margin: 0.8em 0.8em; background-color: #ffffff;
+    border: 1pt solid #aaaaaa; font-size: smaller; }
+  a,kbd { color: #000000; text-decoration: none; }
+  h1,h2,h3 { font-family: sans-serif; }
+  p,div,li,dt,dd { font-family: serif; }
+  pre,kbd { font-family: monospace; }
+  dd { font-size: smaller; }
+}
+</style>
+</head>
+<body>
+<h1>QDBM付属Ruby用API仕様書</h1>
+<div class="note">Copyright (C) 2000-2006 Mikio Hirabayashi</div>
+<div class="note">Last Update: Thu, 26 Oct 2006 15:00:20 +0900</div>
+<div class="navi">[<a href="rbapidoc/index.html">API</a>] [<a href="rbspex.html" hreflang="en">English</a>]</div>
+<hr />
+<h2>目次</h2>
+<ol>
+<li><a href="#overview">概要</a></li>
+<li><a href="#installation">インストール</a></li>
+<li><a href="#examples">サンプルコード</a></li>
+<li><a href="#bugs">バグ</a></li>
+</ol>
+<hr />
+<h2><a name="overview" id="overview" class="head">概要</a></h2>
+<p>QDBMにはRuby言語用のAPIがある。QDBMの基本APIと拡張APIと上級APIの関数群をRubyのクラス機構を用いてカプセル化したものである。また、Rubyのマルチスレッド機能においてスレッドセーフである。</p>
+<p>クラス `Depot' か `Curia' か `Villa' のコンストラクタ `new' を呼び出してデータベースを開き、その戻り値のオブジェクトをハンドルにする。データベースを閉じるにはメソッド `close' を呼ぶ。ファイナライザは利用されないが、`new' のイテレータを用いることでデータベースの閉じ忘れを防ぐことができる。メソッド `put' はレコードを追加するために用いる。メソッド `out' はレコードを削除するために用いる。メソッド `get' はレコードを検索するために用いる。その他にも、C言語のAPIとほぼ同じ操作を利用することができる。各クラスは例外クラス `EANY' およびそのサブクラスを定数として持つ。それらは各メソッドが失敗した際に投げられる。</p>
+<p>これらのクラスは `Enumerable' モジュールをMix-inしているので、`find' や `sort' といったメソッドが利用できる。また、`Hash' クラスに似せて '[]=' や '[]' 等のメソッドを定義しているので、普通のハッシュのように利用することができる。</p>
+<p>データベースに格納するレコードのキーと値は文字列として扱われるが、バイナリデータをそのまま格納することも可能である。ただし、`Villa' は直列化可能かつ比較可能な任意のオブジェクトを格納することができる。`Depot' はファイルを用いてハッシュデータベースを実現し、`Curia' はディレクトリと複数のファイルを用いてハッシュデータベースを実現し、`Villa' はファイルを用いてB+木データベースを実現する。`Depot' は最も高速である。`Curia' は最もスケーラブルである。`Villa' はカーソルによって順序に基づく参照を可能にする。</p>
+<p>`put' で既存のレコードの上書きがキャンセルされた際や `get' で存在しないレコードが検索された際には例外によって操作の失敗が通知されるが、それが鬱陶しい場合は `silent' フラグを真にするとよい。その場合は失敗が戻り値によって通知される。</p>
+<p>APIの詳細に関しては、サブディレクトリ `<a href="rbapidoc/">rbapidoc</a>' の文書を参照すること。</p>
+<hr />
+<h2><a name="installation" id="installation" class="head">インストール</a></h2>
+<p>Rubyの1.6.5以降のバージョンがインストールされ、QDBMが `/usr/local' 以下にインストールされていることが必要である。</p>
+<p>インストール作業は、サブディレクトリ `ruby' をカレントディレクトリにして行う。</p>
+<pre>cd ruby
+</pre>
+<p>ビルド環境を設定する。</p>
+<pre>./configure
+</pre>
+<p>プログラムをビルドする。</p>
+<pre>make
+</pre>
+<p>プログラムの自己診断テストを行う。</p>
+<pre>make check
+</pre>
+<p>プログラムをインストールする。作業は `root' ユーザで行う。</p>
+<pre>make install
+</pre>
+<p>一連の作業が終ると、Rubyのインストールディレクトリに応じた適当な場所に `depot.rb'、`mod_depot.so' 、`curia.rb' 、`mod_curia.so' 、`villa.rb' 、`mod_villa.so' 等のライブラリがインストールされ、コマンド `rbdptest' と `rbcrtest' と `rbvltest' が `/usr/local/bin' にインストールされる。</p>
+<p>アンインストールするには、`./configure' をした後の状態で以下のコマンドを実行する。作業は `root' ユーザで行う。</p>
+<pre>make uninstall
+</pre>
+<hr />
+<h2><a name="examples" id="examples" class="head">サンプルコード</a></h2>
+<p>名前と対応させて電話番号を格納し、それを検索するアプリケーションのサンプルコードを以下に示す。</p>
+<pre>require 'depot'
+NAME = "mikio"
+NUMBER = "000-1234-5678"
+DBNAME = "book"
+def main
+  depot = nil
+  begin
+    # データベースを開く
+    depot = Depot::new(DBNAME, Depot::OWRITER | Depot::OCREAT)
+    # レコードを格納する
+    depot.put(NAME, NUMBER)
+    # レコードを取得する
+    printf("Name: %s\n", NAME)
+    printf("Number: %s\n", depot.get(NAME))
+  rescue Depot::EANY
+    printf("%s\n", $!)
+    return 1
+  ensure
+    # データベースを閉じる
+    if(depot)
+      begin
+        depot.close()
+      rescue Depot::EANY
+        printf("%s\n", $!)
+      end
+    end
+  end
+  return 0
+end
+exit(main());
+</pre>
+<p>上記の例を `Hash' クラスに似せたインタフェースとイテレータを用いて書き直した例を以下に示す。</p>
+<pre>require 'depot'
+NAME = "mikio"
+NUMBER = "000-1234-5678"
+DBNAME = "book"
+def main
+  begin
+    # データベースを開いて自動的に閉じる
+    Depot::new(DBNAME, Depot::OWRITER | Depot::OCREAT) do |depot|
+      # レコードを格納する
+      depot[NAME] = NUMBER
+      # レコードを取得する
+      printf("Name: %s\n", NAME)
+      printf("Number: %s\n", depot[NAME])
+    end
+  rescue Depot::EANY
+    printf("%s\n", $!)
+    return 1
+  end
+  return 0
+end
+exit(main());
+</pre>
+<p>`Villa' クラスを用いて文字列の前方一致検索を行う例を以下に示す。</p>
+<pre>require 'villa'
+DBNAME = "words"
+PREFIX = "apple"
+def main
+  begin
+    # データベースを開いて自動的に閉じる
+    Villa::new(DBNAME, Villa::OWRITER | Villa::OCREAT) do |villa|
+      # レコードを格納する
+      villa.put("applet", "little application", Villa::DDUP)
+      villa.put("aurora", "polar wonderwork", Villa::DDUP)
+      villa.put("apple", "delicious fruit", Villa::DDUP)
+      villa.put("amigo", "good friend", Villa::DDUP)
+      villa.put("apple", "big city", Villa::DDUP)
+      begin
+        # カーソルを候補の先頭に置く
+        villa.curjump(PREFIX)
+        # カーソルを走査する
+        while(true)
+          key = villa.curkey()
+          (key.index(PREFIX) == 0) || break
+          val = villa.curval()
+          printf("%s: %s\n", key, val)
+          villa.curnext()
+        end
+      rescue Villa::ENOITEM
+      end
+    end
+  rescue Villa::EANY
+    printf("%s\n", $!)
+    return 1
+  end
+  return 0
+end
+exit(main());
+</pre>
+<hr />
+<h2><a name="bugs" id="bugs" class="head">バグ</a></h2>
+<p>標準添付ライブラリの `DBM' クラスのインタフェースと微妙に違うところがある。</p>
+<p>もしもRubyハッカー達の手にかかれば、より効率的な実装がなされるだろう。</p>
+<p>インタフェースを簡潔にするため、Ruby用のCuriaにはラージオブジェクトを扱う機能はない。</p>
+<hr />
+</body>
+</html>
+<!-- END OF FILE -->

data/rbspex.html ADDED Viewed

@@ -0,0 +1,284 @@
+<?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" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta http-equiv="Content-Style-Type" content="text/css" />
+<meta name="author" content="Mikio Hirabayashi" />
+<meta name="keywords" content="QDBM, Ruby, Depot, Curia, Villa" />
+<meta name="description" content="specifications of Ruby API of QDBM" />
+<link rel="contents" href="./" />
+<link rel="alternate" href="rbspex-ja.html" hreflang="ja" title="the Japanese version" />
+<link rev="made" href="mailto:mikio@fallabs.com" />
+<title>Specifications of QDBM for Ruby</title>
+<style type="text/css">html { margin: 0em 0em; padding: 0em 0em; background: #eeeeee none; }
+body { margin: 2em 2em; padding: 0em 0em;
+  background: #eeeeee none; color: #111111;
+  font-style: normal; font-weight: normal; }
+h1 { margin-top: 1.8em; margin-bottom: 1.3em; font-weight: bold; }
+h2 { margin-top: 1.8em; margin-bottom: 1.1em; font-weight: bold;
+  border-left: solid 0.6em #445555; border-bottom: solid 1pt #bbbbbb;
+  padding: 0.5em 0.5em; width: 60%; }
+h3 { margin-top: 1.8em; margin-bottom: 0.8em; font-weight: bold; }
+hr { margin-top: 2.5em; margin-bottom: 1.5em; height: 1pt;
+  color: #999999; background-color: #999999; border: none; }
+div.note,div.navi { text-align: right; }
+div.logo { text-align: center; margin: 3em 0em; }
+div.logo img { border: inset 2pt #ccccdd; }
+p { margin: 0.8em 0em; line-height: 140%; }
+p,dd { text-indent: 0.8em; }
+div,pre { margin-left: 1.7em; margin-right: 1.7em; }
+pre { background-color: #ddddee; padding: 0.2em; border: 1pt solid #bbbbcc; font-size: smaller; }
+kbd { color: #111111; font-style: normal; font-weight: bold; }
+a { color: #0022aa; text-decoration: none; }
+a:hover,a:focus { color: #0033ee; text-decoration: underline; }
+a.head { color: #111111; text-decoration: none; }
+table { padding: 1pt 2pt 1pt 2pt; border: none; margin-left: 1.7em; border-collapse: collapse; }
+th { padding: 1pt 4pt 1pt 4pt; border-style: none;
+  text-align: left; vertical-align: bottom; }
+td { padding: 1pt 4pt 1pt 4pt; border: 1pt solid #333333;
+  text-align: left; vertical-align: top; }
+ul,ol,dl { line-height: 140%; }
+dt { margin-left: 1.2em; }
+dd { margin-left: 2.0em; }
+ul.lines { list-style-type: none; }
+@media print {
+  html,body { margin: 0em 0em; background-color: #ffffff; color: #000000; }
+  h1 { padding: 8em 0em 0.5em 0em; text-align: center; }
+  h2 { page-break-before: always; }
+  div.note { text-align: center; }
+  div.navi,div.logo { display: none }
+  hr { display: none; }
+  pre { margin: 0.8em 0.8em; background-color: #ffffff;
+    border: 1pt solid #aaaaaa; font-size: smaller; }
+  a,kbd { color: #000000; text-decoration: none; }
+  h1,h2,h3 { font-family: sans-serif; }
+  p,div,li,dt,dd { font-family: serif; }
+  pre,kbd { font-family: monospace; }
+  dd { font-size: smaller; }
+}
+</style>
+</head>
+<body>
+<h1>Specifications of QDBM for Ruby</h1>
+<div class="note">Copyright (C) 2000-2006 Mikio Hirabayashi</div>
+<div class="note">Last Update: Thu, 26 Oct 2006 15:00:20 +0900</div>
+<div class="navi">[<a href="rbapidoc/index.html">API</a>] [<a href="rbspex-ja.html" hreflang="ja">Japanese</a>]</div>
+<hr />
+<h2>Table of Contents</h2>
+<ol>
+<li><a href="#overview">Overview</a></li>
+<li><a href="#installation">Installation</a></li>
+<li><a href="#examples">Examples</a></li>
+<li><a href="#bugs">Bugs</a></li>
+</ol>
+<hr />
+<h2><a name="overview" id="overview" class="head">Overview</a></h2>
+<p>QDBM provides API for Ruby.  This encapsulates the basic API, the extended API and the advanced API of QDBM.  These APIs are safe on multi thread environment of Ruby.</p>
+<p>You call the constructor `new' of the class `Depot', `Curia' or `Villa' 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 APIs for C are available.  Each class has class constants which are `EANY' and its sub classes.  They are thrown when each method fails.</p>
+<p>Because these classes 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.</p>
+<p>Although keys and values of storing records are treated as strings, binary data can be stored as they are.  But, `Villa' can store any serializable and comparable objects.  `Depot' realizes a hash database with a file.  `Curia' realizes a hash database with a directory and multiple files.  `Villa' realizes a B+ tree database with a file.  `Depot' is fastest.  `Curia' is most scalable.  `Villa' provides cursor supporting ordering access.</p>
+<p>When `put' overwriting an existing record is cancelled or `get' retrieving a missing record, failure of the operation is noticed by exception.  If you dislike such behavior, set the `silent' flag to be true.  Then, failure of the operation is noticed by the return value.</p>
+<p>For more information about the APIs, read documents in the sub directory `<a href="rbapidoc/">rbapidoc</a>'.</p>
+<hr />
+<h2><a name="installation" id="installation" class="head">Installation</a></h2>
+<p>Make sure that Ruby 1.6.5 or later version is installed and make sure that QDBM is installed under `/usr/local'.</p>
+<p>Change the current working directory to the sub directory named `ruby'.</p>
+<pre>cd ruby
+</pre>
+<p>Run the configuration script.</p>
+<pre>./configure
+</pre>
+<p>Build programs.</p>
+<pre>make
+</pre>
+<p>Perform self-diagnostic test.</p>
+<pre>make check
+</pre>
+<p>Install programs.  This operation must be carried out by the root user.</p>
+<pre>make install
+</pre>
+<p>When a series of work finishes, `depot.rb', `mod_depot.so', `curia.rb', `mod_curia.so', `villa.rb', `mod_villa.so', and so on are installed under an appropriate directory according to the install directory of Ruby.  Executable commands `rbdptest', `rbcrtest', and `rbvltest' will be installed in `/usr/local/bin'.</p>
+<p>To uninstall them, execute the following command after `./configure'.  This operation must be carried out by the root user.</p>
+<pre>make uninstall
+</pre>
+<hr />
+<h2><a name="examples" id="examples" class="head">Examples</a></h2>
+<p>The following example stores and retrieves a phone number, using the name as the key.</p>
+<pre>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 Depot::EANY
+    printf("%s\n", $!)
+    return 1
+  ensure
+    # close the database
+    if(depot)
+      begin
+        depot.close()
+      rescue Depot::EANY
+        printf("%s\n", $!)
+      end
+    end
+  end
+  return 0
+end
+exit(main());
+</pre>
+<p>The following example is a transcription of the one above, using hash-like interface and iterator.</p>
+<pre>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 Depot::EANY
+    printf("%s\n", $!)
+    return 1
+  end
+  return 0
+end
+exit(main());
+</pre>
+<p>The following example performs forward matching search for strings, using the class `Villa'.</p>
+<pre>require 'villa'
+DBNAME = "words"
+PREFIX = "apple"
+def main
+  begin
+    # open the database and close it automatically
+    Villa::new(DBNAME, Villa::OWRITER | Villa::OCREAT) do |villa|
+      # store records
+      villa.put("applet", "little application", Villa::DDUP)
+      villa.put("aurora", "polar wonderwork", Villa::DDUP)
+      villa.put("apple", "delicious fruit", Villa::DDUP)
+      villa.put("amigo", "good friend", Villa::DDUP)
+      villa.put("apple", "big city", Villa::DDUP)
+      begin
+        # set the cursor at the top of candidates
+        villa.curjump(PREFIX)
+        # scan with the cursor
+        while(true)
+          key = villa.curkey()
+          (key.index(PREFIX) == 0) || break
+          val = villa.curval()
+          printf("%s: %s\n", key, val)
+          villa.curnext()
+        end
+      rescue Villa::ENOITEM
+      end
+    end
+  rescue Villa::EANY
+    printf("%s\n", $!)
+    return 1
+  end
+  return 0
+end
+exit(main());
+</pre>
+<hr />
+<h2><a name="bugs" id="bugs" class="head">Bugs</a></h2>
+<p>This API are subtly different from the interface of standard library `DBM'.</p>
+<p>This API can be implemented more effectively by Ruby hackers.</p>
+<p>For the sake of simplicity of interface, Curia for Ruby does not feature handling large objects.</p>
+<hr />
+</body>
+</html>
+<!-- END OF FILE -->