$db = Class->new (%option)

[4] 級メソッド new は、新しいデータベースの実現値を生成します。

%option には、0個以上の引数を与えます。 データベースの種類によって、引数名、引数値の型、必須かどうか、既定値が決まります。 不適当な引数がある (あるいは必要な引数がない) ときには、例外を発生させて構いません。

[5] このメソッド内では必要な初期化を行います。 データベースを実際に開いても構いませんし、 その前に固定を行っても構いません。

$result = $db->open (%option)

[35] データベースを開きます。

この method は、 close との対称性のため予約していますが、現在のところ使われていません。

$result = $db->open_prop (%option)

特性を開きます。データベース内に複数の特性があって、別々に開いたり閉じたりできる場合のみ有効です。 そうでない場合は、何もせずに、 適当な結果を返します。

$result:

1

特性を開くのに成功した

0

特性を開くのに失敗した (適当な例外を発生させて構わない。その場合の $result は未定義)

"0 but true"

特性は既に開かれている

$result = $db->close_prop (%option)

[7] 特性を閉じます。指定された特性を閉じるためには他の開かれている特性も閉じなければならないときは、 "0 but true" を返します。

$db->close (%option)

[8] データベースを閉じます。 特性が開かれていれば、すべて閉じます。 固定されていれば、解除して構いません。

一度閉じたデータベースを再び開ける必要はありませんが、もしかしたら将来 open メソッドが定義されるかもしれません。

$db->DESTROY

[9] 必要な後始末をします。 データベースが閉じられていないのなら、閉じたほうがいいですが、 他で確実に閉じられる保証があるのならその限りではありません。 固定についても同様です。

この method は必要がなければ定義しなくて構いません。 この method は Perl が自動的に呼び出します。 利用者が直接呼び出すことは想定していません。

$value = $db->get ($prop, $key, %option)

[10] 値 v_$key,$prop を取得します。

データベースの制限または不測の事態により値を取得できないときは、例外を発生させます。

単に値が未定義の時は、 undef を返すのがいいですが、その辺はデータベースの性質によります。

$db->set ($prop, $key => $value, %option)

[11] 値 v_$key,$prop を設定します。

データベースの制限、不当な値、または不測の事態により値を設定できないときには、例外を発生させます。

undef が与えられたら値を削除しても構いませんが、その辺はデータベースの性質によります。

返される値は未定義です。

($key1, $key2, ...) = $db->keys ($prop, %option)

[29] すべての鍵を返します。

each 型の列挙方法も用意することを検討中です。。。

$result = $db->exist ($prop, $key, %option)

[13] 値 v_$key,$prop が存在するかを返します。

存在すれば真、しなければ偽とします。 データベースの性質上値が存在できない場合あるいは不定の場合は、 一般の偽とは異なる) undef を返しても構いません。

データベースの制限または不測の事態により存在するか調べられないときには、例外を発生させても構いません。

ハッシュの鍵の存在を検査する exists と綴りが違うことに注意。

$db->delete ($prop, $key, %option)

[14] 値 v_$key,$prop を削除します。

データベースの制限または不測の事態により削除できないときには、例外を発生させても構いません。

Perl 組込みの delete と同じ名前であることに注意。

_ で始まる名前のメソッド

[17] _ で始まる名前のメソッドは、 モジュール定義のメソッドとします。モジュールは必要に応じて適当な名前のメソッドを用意して構いません。また、モジュールの利用者は必要に応じてそのメソッドを呼んで構いません。

[18] __ で始まる名前のメソッドは、 モジュール定義の内部用メソッドとします。モジュールは必要に応じて適当な名前のメソッドを用意して構いません。モジュールの利用者はこのメソッドを利用するべきではありません。

[19] ___ で始まる名前のメソッドは、標準化された内部用メソッドとします。モジュールは必要に応じてそのメソッドを定義する必要があります。 モジュールの利用者は基本的にこのメソッドを利用してはいけませんし、 その必要もないはずです。

[20] 4文字以上の _ で始まる名前のメソッドは、将来の標準化のために予約します。モジュールはそのようなメソッドを定義するべきではありません。

SuikaWiki::DB::Util

[22] SuikaWiki::DB::Util <IW:SuikaCVS:"suikawiki/script/lib/SuikaWiki/DB/Util.pm"> は、 WikiDB 各モジュールが共通に使うであろう関数を用意しています。 このモジュールを使うモジュールは、冒頭で require SuikaWiki::DB::Util; してください。

このモジュールで実装されている SuikaWiki::DB::Util::template 名前空間は、 WikiDB モジュールの基底級とできます。 そうしたい場合は push our @ISA, 'SuikaWiki::DB::Util::template' とでもしてください。

このモジュールは、自動的に SuikaWiki::DB::Util::Error を読み込みます。

SuikaWiki::DB::Util::Error

[23] SuikaWiki::DB::Util::Error は、 WikiDB の共通の誤り定義です。この級は Message::Util::Error を継承しています。

WikiDB モジュール独自の誤りを定義したいときは、 この級を継承した誤り定義級を定義してください。

[24] WikiDB モジュール内で誤りを発生させたり、 情報・虫取用メッセージを出すときには、

  report SuikaWiki::DB::Util::Error
    -type => error-name,
    -object => $module, method => method-name,
    key => $key, prop => $prop, # あれば。
    param-name1 => param-value1,
    ...;

として下さい。 error-name は SuikaWiki::DB::Util::Error の誤り名です。 可能な引数は、誤り名によります。 (モジュール独自の誤り定義を使うときは、 SuikaWiki::DB::Util::Error を誤り定義級名に換えてください。)

(引数の最初の - の有無に注意。 - から始まるのは、 Message::Util::Error で定義された引数です。)

[25] SuikaWiki::DB::Util::Error::___error_def では、 Message::Util::Error の形式で誤りが定義されています。

たとえば、

    STOP_DB_PROP_CANT_OPEN => {
      level => 'stop',
      description => q(%t (name => method);: Sub-database "%t (name => prop);" cannot be opened%t (prefix => {: }, name => file);%t (prefix => {: }, name => msg);),
    },

の部分は、 STOP_DB_PROP_CANT_OPEN という名前の誤りを定義しています。 level 引数は、報告水準を指定します。 現在定義されているのは次の通りです。

'fatal'

致死誤り。深刻な誤りであって、 WikiDB をこのまま操作し続けられることを一切保証できません。この種の誤りに遭遇したら、普通は適当なメッセージを出してプログラム自体死ぬべきです。

'stop'

停止誤り。その特定の操作が失敗しました。 たとえば、読み取り専用のところに書き込もうとしたときは通常この種類になります。その操作自体は失敗しましたが、 WikiDB 全体としては処理を継続できます。

'warn'

警告。処理中に望ましからぬ状況に遭遇しました。 この状況をもって処理を中止できるかは、その状況に依存します。 普通は、適当に利用者に報告しつつ処理を継続するべきです。

'log'

記録しておくと有用かもしれない事象が発生しました。

'detaillog'

細かい記録を取っておきたいときに記録しておくと有用かもしれない事象が発生しました。 普通は、利用者が特に求めない限り、この種の報告は無視するべきです。

'debug'

虫取用のメッセージ。 普通は、利用者が特に求めない限り、この種の報告は無視するべきです。

誤り名の最初に水準が示されていることがありますが、 モジュールで使うときに分かりやすいようにそうしているだけであって、 名前自体は意味を持ちません。

[26] description は、誤り状況を報告するメッセージを自然言語 i-default の、 Message::Util::Formatter 形式で記述します。 このメッセージは簡易的な出力で利用することを想定したもので、多言語化は想定していません。各応用で別途誤り名と各言語化メッセージの対応を保持しておく必要があります。

ここでは、 Message::Util::Error の書式付け規則に加えて、 %key が使えます。 %key; は、与えられた鍵名に置き換えられます。 (Message::Util::Error が提供する書式付け規則 %t を使うと、配列への参照に対応していないので、 ARRAY(0xなんたら) に置き換えられてしまいます。)

SuikaWiki::DB::Util::Lock

[27] このモジュールは、 Yuki::YukiWikiDB2 で実装されている固定を移植したものです。 (実装符号自体は完全に書き換えてしまいましたし、 界面や作られる固定ファイルにも互換性はありませんが、 算法は基本的に同じものです。)

flock など他の固定方法の実装および共通化した界面は検討中です。