EB ライブラリ

テキストデータ

テキストデータの取得は、検索と並ぶ重要な機能です。

ここで言うテキストデータ (text data) は、本文 (text body) という意味ではありません。 CD-ROM 書籍には確かに本文も存在しますが、本文と同じデータ形式を用いて書かれたデータが数種類あります。本書では、これらのデータをまとめてテキストデータと呼んでいます。 EB ライブラリが扱えるテキストデータの種類には、次のものがあります。

見出し
本文
メニュー
著作権表示
複合検索の入力語の候補一覧

本章では、これらのテキストデータの取得と加工方法について説明します。

テキストデータのシークと読み込み

UNIX でプログラムを組んだ経験のある方には、ファイルからデータを読み込む際に用いる lseek(), read() というシステムコールをご存じの方も多いでしょう。

EB ライブラリでも、テキストデータの取得には、シーク (seek) と読み込み (read) という 2 つの操作で行います。ただし、EB ライブラリではファイルポインタやディスクリプタはなく、 EB_Book オブジェクトを通じてシークや読み込みの操作を行います。

また、シーク時に指定する位置も off_t 型ではなく、 EB_Position 型 (「[検索] データ型の詳細」を参照のこと) のオブジェクトを用います。たとえば、本文の先頭位置は、eb_text() という関数を使って次のように取得できますが、このときも位置データは EB_Position 型オブジェクトに書き込まれます。

EB_Position position;

/* 関数の処理が成功すると、position に本文の開始位置が
 * 書き込まれます。 */
if (eb_text(&book, &position) != EB_SUCCESS) {
    fprintf(stderr, "an error occurs.\n");
    return;
}

参考までに、EB_Position 型の内部構造は、次のようになっています。

typedef struct EB_Position_Struct EB_Position;

struct EB_Position_Struct {
    int page;     /* ページ番号 */
    int offset;   /* ページ内のオフセット */
};

検索して見つかった一致エントリの見出しや本文を読み込む際にも、位置情報の指定には EB_Position 型が使われます。一致したエントリの情報は、関数 eb_hit_list() によって EB_Hit という型のオブジェクトに書き込まれますが、 EB_Hit 型は次のように定義されています。 (詳しくは「[検索] データ型の詳細」を参照のこと。)

typedef struct {
    EB_Position heading;   /* 見出しの位置 */
    EB_Position text;      /* 本文の位置   */
} EB_Hit;

つまり、このときの見出しと本文の位置も、EB_Position 型で表現されているのです。

では、実際のプログラムを例にして、シークと読み込みを行ってみます。まずは、シークからです。これには関数 eb_seek_text() を用います。ここでもやはり、位置は EB_Position 型で渡します。

if (eb_seek_text(&book, &position) != EB_SUCCESS) {
    fprintf(stderr, "an error occurs.\n");
    return;
}

データの種類 (見出し、本文 ...) によらず、テキストデータのシークはすべて eb_seek_text() で行います。

ただし、EB_Book オブジェクトは、テキストデータの種類別に読み込み位置を覚えているわけではなく、全種類のテキストデータで共有する位置情報を一つ覚えているだけです。たとえば、本文を読み込んだ後で、別の位置にシークして見出しを読み込むと、 EB_Book は本文の読み込み位置のことは忘れてしまいます。

さて、シークが終わったら、データを読み込みます。読み込もうとするテキストデータの種類によって、使用する関数が異なります。見出しだけは eb_read_heading() を使いますが、それ以外では eb_read_text() を使います。

以下は、eb_read_text() の使用例です。

#define MAX_LENGTH 1000
char buffer[MAX_LENGTH + 1];
ssize_t text_length;

if (eb_read_text(&book, NULL, NULL, NULL, MAX_LENGTH,
    text, &text_length) != EB_SUCCESS) {
    fprintf(stderr, "an error occurs.\n");
    return;
}

成功すると、text にはテキストデータが、 text_length には実際に読み込んだバイト数が書き込まれます。テキストは最大で MAX_LENGTH バイト書き込まれます。テキストデータはさらにナル文字で終端されますので、buffer にはもう 1 バイト分の領域が必要になります。

eb_read_heading() の呼び出し方も、eb_read_text() とまったく変わりません。

if (eb_read_heading(&book, NULL, NULL, NULL, MAX_LENGTH,
    text, &text_length) != EB_SUCCESS) {
    fprintf(stderr, "an error occurs.\n");
    return;
}

eb_read_text() や eb_read_heading() で読み込んだテキストデータは平文のテキストになっていて、ナル文字で終端されています。

printf("%s\n", text);   /* 出力してみる */

読み込みたいテキストデータが長すぎて、eb_read_text() あるいは eb_read_heading() を一回呼び出しただけでは全部読み込めなかった場合は、再度呼び出すことで続きのデータを読み込むことができます。

テキストデータの内部形式

前節の例では、読み込んだテキストデータは、平文テキストになっていました。けれども、CD-ROM 書籍内に平文テキストのデータが、そのまま収録されているわけではありません。

実際のテキストデータの例を、以下に示します。左側のブロックは 16 進数でダンプした様子で、右側はそれを基に JIS X 0208 (日本語のかな漢字) の文字を表している部分を [　] という形に直したものです。

     (16進数によるダンプ)            (可能な部分をかな漢字に変換)
1f0900011f41010026321f611f042121   1f0900011f410100[Σ]1f611f04[　]
212721211f053e704a734a541f0a1f04   [：][　]1f05[情][報][編]1f0a1f04
214e1f0525372530255e1f04214f2121   [［]1f05[シ][グ][マ]1f04[］][　]
214a237323692367236d236121212370   [（][ｓ][ｉ][ｇ][ｍ][ａ][　][ｐ]
2372236f236a236523632374214b1f05   [ｒ][ｏ][ｊ][ｅ][ｃ][ｔ][）]1f05

右側のブロックを見ると、おおよそ平文に近い形でテキストデータが収められていることが分かりますが、ところどころに「文字」ではないデータも含まれています。

文字ではない部分は、すべて「エスケープシーケンス」と呼ばれるものです。エスケープシーケンスとは、テキストデータを出力する際に、改行の禁止や強調修飾といった制御情報を伝えるための仕組みです。 16 進数の 1f が、エスケープシーケンスの開始を意味します。

参考までに、上のテキストデータで使われているエスケープシーケンスをすべて列挙すると、次のようになります。

1f09 0001: 字下げ (インデント) の量を指定。 (引数が 0001 なので、字下げ量は 1。)
1f41 0100: 検索キーの開始。 (引数 0100 の意味については、JIS X 4081 に記述がないため不明。)
1f61: 検索キーの終了。
1f04: 半角表示の開始。
1f05: 半角表示の終了。
1f0a: 改行

前節のプログラムで、読み込んだデータが平文テキストになっていたのは、実は EB ライブラリが加工処理をしたからです。つまり、「改行」のように平文テキストでも表現可能なエスケープシーケンスについては処理し、「検索キーの開始」のように表現できないものについては無視するようにして、平文テキストになるように加工していたのです。

しかし、平文テキストは表現力が乏しいので、元のデータには含まれているエスケープシーケンスの多くを無視することになってしまいます。 HTML のように、もっと表現力のある形式で出力するなら、無視せずに済むシーケンスを増やせそうです。では、HTML 形式でテキストデータを取得する関数が EB ライブラリに用意されているかというと、残念ながらありません。

その代わりに、かなり手間はかかりますが、自由にテキストデータを加工できるための仕組みが用意されています。それが、次の節で説明するフック (hook) です。フックを使うことで、テキストデータを柔軟に加工することができます。

フック

特に何も指定しなければ、eb_read_text(), eb_read_heading() が返すテキストデータの加工は、あらかじめ決められた通りの方法で行われます。たとえば、「改行」のエスケープシーケンスに対しては、\n を書き込むようになっています。

フック (hook) を使うと、こうした加工方法を変えることができます。フックは、あらかじめ決められたフック設定位置に対して、フック関数を登録することで有効になります。フック関数が登録されていると、eb_read_text() や eb_read_heading() は、あらかじめ決まったやり方でデータを書き込む代わりに、フック関数を呼び出します。呼び出されたフック関数がデータの書き込み処理を行うことで、 eb_read_text() や eb_read_heading() から返るテキストデータが変化するというわけです。

EB ライブラリには、多数のフック設定位置が用意されています。各エスケープシーケンスには、それぞれ専用にフックが用意されており、それ以外にも文字のためのフックが存在します。 (どのようなフック設定位置があるか、詳しくは「フックコードの一覧」を参照のこと。)

それぞれのフック設定位置は、フックコード (hook code) と呼ばれるコード値で識別されます。たとえば、前述の「改行」のエスケープシーケンスに対応するフックコードは EB_HOOK_NEWLINE になります。

アプリケーションプログラムがフックを扱うには、フックの集合であるフックセット (hook set) を用意します。これは、EB ライブラリで利用可能なすべてのフック設定位置に対して、どのフック関数を使うのかを記録するためのオブジェクトです。

では、実際にどうやってフックセットを扱うのか、説明していきましょう。フックセットは EB_Hookset 型のオブジェクトで表しますので、まず EB_Hookset オブジェクトを用意します。

EB_Hookset hookset;

EB_Hookset オブジェクトは、EB_Book オブジェクトと同様に、使用前に必ず初期化する必要があります。

eb_initialize_hookset(&hookset);

実際のフック関数は、次のようなものになります。この例では、フック関数の中で eb_write_text_string() という関数を呼び出して、<br> という文字列をテキストデータとして書き込んでいます。

EB_Error_Code
hook_newline(EB_Book *book, EB_Appendix *appendix, void *container,
    EB_Hook_Code code, int argc, const unsigned int *argv) {
    eb_write_text_string(book, "<br>");
    return 0;
}

関数 eb_set_hook() を用いることで、このフック関数をフックセットに登録することができます。ただし、まず EB_Hook という型のオブジェクトにいったんフックコードとフック関数を設定し、それを eb_set_hook() を渡してやる必要があります。ここでは、「改行」を表すエスケープシーケンスに対して、上記のフック関数を登録してみます。

EB_Hook hook;

hook.code = EB_HOOK_NEWLINE;   # フックコードをセット
hook.function = hook_newline;  # フック関数をセット
eb_set_hook(&hookset, &hook);

なお、同じフック設定位置 (フックコード) に複数回フック関数を登録しても、有効になるのは最後に登録したものだけですので、注意して下さい。フック関数として NULL を指定すると、登録されているフックが解除されます。

関数 eb_set_hooks() (最後に s が付く) を使えば、複数のフック関数を一度に登録できます。

static const EB_Hook hooks[] = {
    {EB_HOOK_NEWLINE,        hook_newline},
    {EB_HOOK_SET_INDENT,     hook_set_indent},
    {EB_HOOK_WIDE_JISX0208,  hook_set_jisx0208},
    {EB_HOOK_NULL,           NULL}
};

eb_set_hooks(&hookset, &hooks);

配列の末尾を明示するために、EB_HOOK_NULL という特殊なフックコードを置きます。この点も注意して下さい。

こうしてフック関数を登録したフックセットを、eb_raed_text(), eb_raed_heading() への引数として渡します。前節までの例では、NULL を渡していましたが、代わりに &hookset を渡してみます。

if (eb_read_text(&book, NULL, &hookset, NULL, MAX_LENGTH,
    text, &text_length) != EB_SUCCESS) {
    fprintf(stderr, "an error occurs.\n");
    return;
}

これによって、テキストデータ中に改行を表すエスケープシーケンスがあると、 \n の代わりに <br> という文字列が書き込まれるようになります。

EB_Hookset オブジェクトを使い終わったら、 eb_finalize_hookset() を呼んで後始末をします。

eb_finalize_hookset(&hookset);

フックと文字コードの関係

前節では、エスケープシーケンスに対するフックを例にとりましたが、この他にも、EB ライブラリには文字に対するフックが用意されています。

EB_HOOK_ISO8859_1: ISO 8859-1 (ラテン文字 1) 文字へのフック。ただし制御文字を除きます。引数として、ISO 8859-1 の文字番号がフック関数に渡されます。
EB_HOOK_NARROW_JISX0208: 半角の JIS X 0208 (日本語のかな漢字) 文字へのフック。引数として、日本語 EUC で表現した場合の文字番号が、フック関数に渡されます。
EB_HOOK_WIDE_JISX0208: 全角の JIS X 0208 (日本語のかな漢字) 文字へのフック。引数として、日本語 EUC で表現した場合の文字番号が、フック関数に渡されます。
EB_HOOK_GB2312: GB 2312 (中国語の簡体字) 文字へのフック。引数として、中国語 EUC で表現した場合の文字番号が、フック関数に渡されます。
EB_HOOK_NARROW_FONT: 半角の外字へのフック。引数として、外字の文字番号が、フック関数に渡されます。
EB_HOOK_WIDE_FONT: 半角の外字へのフック。引数として、外字の文字番号が、フック関数に渡されます。

いずれも、その文字がテキストデータ中に現れる度に、フック関数が呼び出されます。

上の記述を見ても分かるように、フック関数に渡される文字番号は、書籍の文字コードに応じて、ISO 8859-1, 日本語 EUC、中国語 EUC のいずれかの文字コードで表現されたものになります。

フック関数を登録しなければ、その文字番号がテキストデータとしてそのまま書き込まれます。

もし、アプリケーションプログラムが、EB ライブラリの内部コードとは異なる文字コードを使用したい場合は、これらのフックのフック関数を登録して、コード変換処理をするのも手です。ただし、一文字毎にフック関数が呼び出されるので、相応の負荷がかかります。

また、EBXA-C を扱うには、特別な処理が必要です。 EBXA-C では、文字コードとして GB 2312 と JIS X 0208 が使われますが (「文字コード」を参照のこと)、EB ライブラリによる標準の処理では、どちらも 0xa1a1 〜 0xfefe にマッピングされて衝突するため、最低でもどちらか一方をフックして文字の表現方法を変えないと、正しく出力できません。

クロス検索の検索結果

すでに「検索」の章で述べたように、CD-ROM 書籍には前方一致検索、後方一致検索といった複数の検索メソッドがあります。 EB ライブラリで検索を行うと、どの検索メソッドでも、一致したエントリの情報は、以下のような EB_Hit 型のオブジェクトとして受け取ります。

typedef struct {
    EB_Position heading;   /* 見出しの位置 */
    EB_Position text;      /* 本文の位置   */
} EB_Hit;

しかしクロス検索では、EB_Hit の見出しと本文の位置はまったく同じになります。したがって、見出しと本文のテキストデータを読み込むには、他の検索メソッドのようにそれぞれの位置にシークして読み込むというやり方ではうまくいきません。

以下に、クロス検索の見出しと本文を読み込むプログラム例を示します。

/* 見出し位置へのシークを行う */
if (eb_seek_text(&book, &hits[0].heading) != EB_SUCCESS) {
    fprintf(stderr, "an error occurs.\n");
    return;
}
/* 見出しの読み込みを行う */
if (eb_read_heading(&book, NULL, NULL, NULL, MAX_LENGTH,
    heading, &heading_length) != EB_SUCCESS) {
    fprintf(stderr, "an error occurs.\n");
    return;
}
/* 先ほど読み込んだ見出しの、次の部分へ飛ぶ */
if (eb_forward_heading(&book) != EB_SUCCESS) {
    fprintf(stderr, "an error occurs.\n");
    return;
}
/* 本文の読み込みを行う */
if (eb_read_heading(&book, NULL, NULL, NULL, MAX_LENGTH,
    text, &text_length) != EB_SUCCESS) {
    fprintf(stderr, "an error occurs.\n");
    return;
}

クロス検索でも、見出しの内容を読み込む方法は他の検索メソッドと変わりはなく、eb_read_heading() を使います。変わっているのは、本文の読み込みです。 eb_read_text() ではなく、eb_read_heading() を使います。見出しを読み込むための関数 eb_read_heading() を、本文を読み込むために呼ぶというのは奇妙な話ですが、これはクロス検索の本文が見出しと同じ形式になっているためです。通常、見出しは一行程度しか書かれていませんが、実際のところクロス検索の本文も一行程度しかありません。

また、本文は見出しのすぐ後に書かれているため、上記のように見出しを読み込んだ後で eb_forward_heading() という関数を呼び、その後で本文を読み込むためにもう一度 eb_read_heading() を呼ぶという変わった手順を踏みます。

本文だけが必要で見出しが要らなければ、シーク直後に eb_forward_heading() を呼ぶようにします。その後で eb_read_heading() を呼ぶと、本文を読み込みます。

著作権表示

先に記したように、テキストデータには何種類かあり、その中に著作権表示 (copyright notice) というものがあります。名前の通り、著作権表示に関するテキストデータを収めたものです。

一般に、著作権表示は本文とはまったく独立したデータとして用意されます。したがって、本文を先頭から末尾まで読んでみても、著作権表示はどこにも見つかりません。

選択中の副本について、著作権表示の開始位置を知るには eb_copyright() を使います。この関数は、副本が著作権表示を持っていなければ EB_ERR_NO_SUCH_SEARCH を返しますので、著作権表示の有無も同時に分かります。 (開始位置は取得せずに、有無だけを調べたいときは、 eb_have_copyright() という関数が使えます。)

EB_Position position;
EB_Error_Code err;

err = eb_copyright(&book, &position);
if (err == EB_ERR_NO_SUCH_SEARCH) {
    /* 著作権表示はない */
} else if (err != EB_SUCCESS) {
    /* それ以外のエラー */
   return;
}

後は、得られた位置 (position) にシークして、 eb_read_text() でテキストデータを読み込みます。

メニュー

本文とは独立したテキストデータとしては、著作権表示の他にメニュー (menu) というものがあります。メニューは、主に本文の補助となるデータを収録しています。代表的なものでは、「前書き (序)」「凡例」といったものが挙げられます。

メニューでは「別項目参照」というエスケープシーケンスを多用して、階層的な構造になっているのが一般的です。このエスケープシーケンスには、参照先のテキストの位置が記録されています。

たとえば、ある CD-ROM 書籍のメニューが次のようになっていたとします。この例では、メニューには 3 つの項目があります。

 * 序文
 * 表記について
 * 奥付

メニューのそれぞれの項目には、参照先があります。テキストデータの内部表現では、「序文」「表記について」「奥付」のそれぞれの文字列の前後に別項目参照開始および終了エスケープシーケンスが付いた形になっています。視覚的に分かるように記すと、次のような形になっています。

 * <別項目参照開始シーケンス> "序文" <別項目参照終了シーケンス>
 * <別項目参照開始シーケンス> "表記" <別項目参照終了シーケンス>
 * <別項目参照開始シーケンス> "奥付" <別項目参照終了シーケンス>

HTML の書き方を知っているなら、a タグと言えば分かるのではないかと思います。

<a href="./index.html">EB ライブラリのホームページ</a>

ただし、参照先の位置情報は終了シーケンス側に記載されますので、この点は HTML とは逆になります。蛇足ですが、別位置参照はメニューだけでなく、本文でも一般的に使用されます。

別項目参照開始および終了シーケンスに対して、それぞれフック EB_HOOK_BEGIN_REFERENCE と EB_HOOK_END_REFERENCE が用意されています。参照先の位置情報は、終了シーケンスへのフック関数に対して、引数として渡されます。たとえば、EB_HOOK_END_REFERENCE へのフック関数の冒頭では、次のようにすると良いかも知れません。

EB_Error_Code
hook_end_ref(EB_Book *book, EB_Appendix *appendix, void *container,
    EB_Hook_Code code, int argc, const unsigned int *argv)
{
    EB_Position position;

    position.page = argv[1];    # 参照先のページ番号
    position.offset = argv[2];  # 参照先のオフセット

参照先は、メニューの第 2 層となります。この書籍の「奥付」の参照先を辿ったら、次のような表記になっていました。

○○堂出版社 新国語辞典 第 2 版 (EPWING 版)
第 1 版 発行 1988年 2月
第 2 版 発行 1999年 11月
第 2 版 (EPWING 版) 発行 2000年 2月

同様に「序文」「表記に付いて」の参照先についても、こうした文章データが用意されていました。図示すると、メニューの階層は次のようになります。

　　　　　　　　　　　　┌─────┐
第１層　　　　　　　　　│メニュー　│
　　　　　　　　　　　　└──┰──┘
　　　　　　　　　　　　　　　┃
　　　　　　　┏━━━━━━━╋━━━━━━━┓
　　　　　　　┃　　　　　　　┃　　　　　　　┃
　　　　┌──┸──┐　┌──┸──┐　┌──┸──┐
第２層　│メニュー　│　│メニュー　│　│メニュー　│
　　　　└─────┘　└─────┘　└─────┘

この辞書の例では、メニューはここで終わりになっていますが、書籍によってはさらに第 3 層、第 4 層と続く場合もあります。また、メニュー全体が均一の階層数になっているとは限りません。メニューの参照先が本文や著作権表示になっていることもあります。

選択中の副本について、(第 1 層の) メニューの開始位置を知るには eb_menu() を使います。この関数は、副本がメニューを持っていなければ EB_ERR_NO_SUCH_SEARCH を返しますので、メニューの有無も同時に分かります。 (開始位置は取得せずに、有無だけを調べたいときは、 eb_have_menu() という関数が使えます。)

EB_Position position;
EB_Error_Code err;

err = eb_menu(&book, &position);
if (err == EB_ERR_NO_SUCH_SEARCH) {
    /* メニューはない */
} else if (err != EB_SUCCESS) {
    /* それ以外のエラー */
   return;
}

後は、得られた位置 (position) にシークして、 eb_read_text() でテキストデータを読み込みます。

複合検索の候補一覧

「複合検索」(「複合検索」を参照のこと) のところで述べたように、複合検索では、入力語に候補一覧 (candidates) が用意されていることがあります。これは、入力語として有効な語をあらかじめ列挙しておき、アプリケーションプログラムのユーザに選択させる仕組みです。

たとえば、人名を検索するのために、次のような複合検索があったとします。

入力語 0: 国・地域
入力語 1: 時代
入力語 2: 性別
入力語 3: キーワード
入力語 4: キーワード

このうち、入力語 3 の「性別」には、入力語として有効な語は「男」と「女」の 2 つしかないでしょう。このように、入力語として有効な語が限られている場合に、候補一覧が用意されていることがあります。

候補一覧は検索のためのデータではありますが、内部構造はテキストデータそのものです。ユーザに対して候補を列記した示したテキストを示し、その中の一つを選択してもらうようになっています。

しかも、候補一覧のデータ構造はメニューと非常に似ており、メニューのような階層構造を持っています (「メニュー」を参照のこと)。たとえば、上の複合検索の入力語 2 「国・地域」にも候補の一覧を設けるとしたら、最初の階層は次のようになるかも知れません。

* 日本 (→選択)
* 日本以外のアジア (→詳細)
* ヨーロッパ (→詳細)
* 北アメリカ (→詳細)
* その他 (→詳細)

「日本」を選ぶと、そこで入力語が決定されたことになります。しかし、それ以外の項目についてはさらに細かく分類された選択肢が用意されています。ここでは、「北アメリカ」を選んでみましょう。すると、さらに次のような候補一覧のデータが提示されます。

* アメリカ (→選択)
* カナダ (→選択)

ここで、「アメリカ」「カナダ」を選ぶと、入力語が決定されます。

次に実際に、EB ライブラリを使ってこうした候補一覧を扱う方法について説明します。まず、アプリケーションプログラムは、複合検索の入力語が候補一覧を持っているかどうかを、確認する必要があるでしょう。 eb_multi_entry_candidates() を使うと、候補一覧データの開始位置を取得することができます。この関数は、候補一覧を持っていなければ EB_ERR_NO_CANDIDATES を返しますので、候補一覧の有無も分かります。 (開始位置は取得せずに、有無だけを調べたいときは、 eb_multi_entry_have_candidates() という関数が使えます。)

EB_Position position;
EB_Error_Code err;

/* mulit_id, entry_id で、どの複合検索の
 * 何番目の入力語について確認するのかを指定します。*/
err = eb_multi_entry_candidates(&book, multi_id, entry_id, &position);
if (err == EB_ERR_NO_CANDIDATES) {
    /* この入力語には、候補一覧が用意されていない */
   return;
} else if (err != EB_SUCCESS) {
    /* それ以外のエラー */
   return;
}

後は、得られた位置 (position) にシークして、 eb_read_text() でテキストデータを読み込みます。読み込んだテキストでは、候補となる語のそれぞれが候補開始と終了を表すエスケープシーケンスに挟まれた形になっています。

* <候補開始シーケンス> "日本" <候補終了シーケンス>
* <候補開始シーケンス> "日本以外のアジア" <候補終了シーケンス>
* <候補開始シーケンス> "ヨーロッパ" <候補終了シーケンス>
* <候補開始シーケンス> "北アメリカ" <候補終了シーケンス>
* <候補開始シーケンス> "その他" <候補終了シーケンス>

候補開始シーケンスに対しては、フックとして EB_HOOK_BEGIN_CANDIDATE が用意されています。終了シーケンスに対するフックは 2 種類あって、さらに次の階層へ続く場合に呼ばれる EB_HOOK_END_CANDIDATE_GROUP と、その語がそのまま入力語の候補となる場合に呼ばれる EB_HOOK_END_GROUP_LEAF に分かれています。

次の階層のデータの開始位置は、終了シーケンスのフック関数に、引数として渡ってきます。 (この点もメニューと同様なので、メニューの解説を参考にして下さい。)

終了シーケンスに対するフック関数の中では、eb_current_candidate() という関数が使えます。この関数は、開始シーケンスと終了シーケンスの間に挟まれた「候補」の文字列 (ポインタ) を返します。

const char *candidate;

candidate = eb_current_candidate(book);

区切りコードの問題

本文は、先頭から末尾まで一本の繋がったデータ列になっています。英語辞典なら、最初の単語 `A' から最後の `zzz' までの説明が、すべて一つの「本文」の中に書かれることになります。

一般に、アプリケーションプログラムがある単語を検索した際は、本文の中からその単語を説明した部分だけを抜き出して出力することになるでしょう。たとえば、`dictionary' という単語を引いた場合、次のような文章が出力される事が期待されます。その次や、次の次の単語の説明まで延々と表示されることを、おそらく大半のユーザは望まない筈です。

dictionary [名] (複: dictionaries)
辞典、事典
[類義] lexicon, glossary (用語辞典), encyclopedia (百科事典)

しかし、困ったことに CD-ROM 書籍には、単語の説明の終わりを示す印 (エスケープシーケンス) が定義されていません。つまり、ある語の説明部分を正確に抜き出すことは、電子ブックや EPWING では不可能なのです。

しかしながら、幸いにも市販の書籍の多くには、単語の説明の終了位置にだけ出現する、特有のエスケープシーケンスが存在します。もちろん、このエスケープシーケンスは本来「単語の説明の終了」を示すものではなく別の用途として用いるのですが、「終了位置」として代用できるという意味です。

EB ライブラリでは、この「終了位置」の印に使えるエスケープシーケンスのことを、区切りコード (stop code) と呼んでいます。 EB ライブラリは区切りコードを自動判定する機能を持っていますが、判定は完璧ではないので外れることもあります。外れると本文が途中で途切れたり、本文の続きが延々と出力されたりします。

その場合は、明示的に appendix (詳しくは ebappendix コマンドのマニュアルの「appendix (付録) とは」を参照のこと) で区切りコードを指定することによって回避できる書籍もありますが、残念ながら区切りコードがまったく存在しない書籍も少数ながら存在します。区切りコードを持たない書籍に対して、有効な対処方法は今のところありません。

eb_read_text() による本文の取得では、区切りコードが検出された時点で読み込みを止めます。さらに繰り返し eb_read_text() を呼んでも、区切りコードより先の本文は読み込めません。

区切りコードを検出したかどうかの判定には、eb_is_text_stopped() を使います。この関数は、最後に読み込みを行ったテキストデータの中に、区切りコードを検出していれば 1 を返します。

本文以外のテキストデータにも区切りコードの概念は存在しますので、 eb_is_text_stopped() を使って区切りコードを検出できます。しかし、本文以外では EB ライブラリが確実に区切りを判別できますので、誤判定の問題は起きません。

見出しにおける区切りは、それぞれの単語の見出しの終了位置となります。メニューおよび複合検索の候補一覧では、階層化された個々のメニューデータの終了位置で区切りと判定されます。 (同一階層に複数個のメニューデータがあっても、個々のメニューデータで区切られます。) 著作権表示では、全文の終了位置で区切りと判定されます。

サンプルプログラム

/*                                                            -*- C -*-
 * Copyright (c) 1999-2006  Motoyuki Kasahara
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. Neither the name of the project nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 */

/*
 * 使用方法:
 *     text <book-path> <subbook-index> <number>
 * 例:
 *     text /cdrom 0 10
 * 説明:
 *     <book-path> で指定した CD-ROM 書籍から特定の副本を選び、本文
 *     の先頭から <number> 個分の単語の説明を出力します。
 *
 *     <subbook-index> には、検索対象の副本のインデックスを指定しま
 *     す。インデックスは、書籍の最初の副本から順に 0、1、2 ... に
 *     なります。
 */
#include <stdio.h>
#include <stdlib.h>

#include <eb/eb.h>
#include <eb/error.h>
#include <eb/text.h>

#define MAXLEN_TEXT 1023

int
main(int argc, char *argv[])
{
    EB_Error_Code error_code;
    EB_Book book;
    EB_Subbook_Code subbook_list[EB_MAX_SUBBOOKS];
    int subbook_count;
    int subbook_index;
    EB_Position text_position;
    char text[MAXLEN_TEXT + 1];
    ssize_t text_length;
    int text_count;
    int i;

    /* コマンド行引数をチェック。*/
    if (argc != 4) {
        fprintf(stderr, "Usage: %s book-path subbook-index number\n",
            argv[0]);
        exit(1);
    }
    text_count = atoi(argv[3]);

    /* EB ライブラリと `book' を初期化。*/
    eb_initialize_library();
    eb_initialize_book(&book);

    /* 書籍を `book' に結び付ける。*/
    error_code = eb_bind(&book, argv[1]);
    if (error_code != EB_SUCCESS) {
        fprintf(stderr, "%s: failed to bind the book, %s: %s\n",
            argv[0], eb_error_message(error_code), argv[1]);
        goto die;
    }

    /* 副本の一覧を取得。*/
    error_code = eb_subbook_list(&book, subbook_list, &subbook_count);
    if (error_code != EB_SUCCESS) {
        fprintf(stderr, "%s: failed to get the subbbook list, %s\n",
            argv[0], eb_error_message(error_code));
        goto die;
    }

    /* 副本のインデックスを取得。*/
    subbook_index = atoi(argv[2]);

    /*「現在の副本 (current subbook)」を設定。*/
    error_code = eb_set_subbook(&book, subbook_list[subbook_index]);
    if (error_code != EB_SUCCESS) {
        fprintf(stderr, "%s: failed to set the current subbook, %s\n",
            argv[0], eb_error_message(error_code));
        goto die;
    }

    /* テキストの開始位置を取得。*/
    error_code = eb_text(&book, &text_position);
    if (error_code != EB_SUCCESS) {
        fprintf(stderr, "%s: failed to get text information, %s\n",
            argv[0], eb_error_message(error_code));
        goto die;
    }

    /* テキストをシーク。*/
    error_code = eb_seek_text(&book, &text_position);
    if (error_code != EB_SUCCESS) {
        fprintf(stderr, "%s: failed to seek text, %s\n",
            argv[0], eb_error_message(error_code));
        goto die;
    }

    i = 0;
    while (i < text_count) {
        /* テキストを取得。*/
        error_code = eb_read_text(&book, NULL, NULL, NULL, MAXLEN_TEXT,
            text, &text_length);
        if (error_code != EB_SUCCESS) {
            fprintf(stderr, "%s: failed to read text, %s\n",
                argv[0], eb_error_message(error_code));
            goto die;
        }
        fputs(text, stdout);

        if (!eb_is_text_stopped(&book))
            continue;

        fputs("\n----------------------------------------\n", stdout);

        /* 次の単語の説明へ移動。*/
        error_code = eb_forward_text(&book, NULL);
        if (error_code == EB_ERR_END_OF_CONTENT)
            fputs("\n[END]\n", stdout);
        else if (error_code != EB_SUCCESS) {
            fprintf(stderr, "%s: failed to read text, %s\n",
                argv[0], eb_error_message(error_code));
            goto die;
        }
        i++;
    }
        
    /* 書籍と EB ライブラリの利用を終了。*/
    eb_finalize_book(&book);
    eb_finalize_library();
    exit(0);

    /* エラー発生で終了するときの処理。*/
  die:
    eb_finalize_book(&book);
    eb_finalize_library();
    exit(1);
}

データ型の詳細

この節で説明しているデータ型を使うには、次のようにヘッダファイルを読み込んで下さい。

#include <eb/eb.h>

`EB_Hook_Code` 型

データ型 EB_Hook_Hook は、フックの設定位置コードを表します。

この型は符合付き整数型の別名として定義されていますので、2 つのコードを 2 項演算子 == と != で一致比較することができます。

EB ライブラリでは、全部で EB_NUMBER_OF_HOOKS 個のフックコードを定義しています。定義されている設定位置コードの一覧については、次の節 (「フックコードの一覧」を参照のこと) を参照して下さい。

`EB_Hook` 型

データ型 EB_Hook は、フックコードとそれに対応するフック関数の組を表します。内部構造は、次のように定義されています。

typedef struct EB_Hook_Struct EB_Hook;

struct EB_Hook_Struct {
    EB_Hook_Code code;
    EB_Error_Code (*FUNC)(EB_Book *, EB_Appendix *, void *,
        EB_Hook_Code, int, const unsigned int *);
};

アプリケーションプログラムは、直接 EB_Hook オブジェクトのメンバを参照したり、セットしたりしても構いません。

`EB_Hookset` 型

データ型 EB_Hookset は、フック一式を表します。 EB ライブラリで利用可能なすべてのフック設定位置に対して、どのようなフック関数を指定するのかを記録するための型です。

EB_Hookiset オブジェクトの操作は、すべて EB ライブラリが用意している関数で行います。アプリケーションプログラムは、直接 EB_Hookset オブジェクトのメンバを参照したり、セットしたりすべきではありません。

EB_Hookset オブジェクトを使用する際は、まずそのオブジェクトに対して eb_initialize_hookset() を呼んで初期化しなくてはなりません。

フック関数の詳細

この節では、フック関数の仕様について記します。

まず、フック関数を呼び出す eb_read_text() および eb_read_heading() のプロトタイプは次のようになっています。

EB_Error_Code
eb_read_text(EB_Book *book, EB_Appendix *appendix,
    EB_Hookset *hookset, void *container, size_t text_max_length,
    char *text, ssize_t *text_length)

一方、フック関数のプロトタイプは、次のようになっています。

EB_Error_Code
hook_function(EB_Book *book, EB_Appendix *appendix, void *container,
    EB_Hook_Code code, int argc, const unsigned int *argv);

引数 book, appendix, container は、 eb_read_text() あるいは eb_read_heading() に渡された値がそのままフック関数にも渡ってきます。

appendix というのは、書籍に対する補助データを提供するオブジェクトです (appendix (付録) について詳しくは ebappendix コマンドのマニュアルの「appendix (付録) とは」を参照のこと)。

引数 container は、アプリケーションプログラムからフック関数に何かデータを渡したいときに使います。

最後の argc と argv には、加工前のテキストデータが渡されます。文字に対するフックでは、文字コード番号が渡ってきます。エスケープシーケンスに対するフックでは、そのシーケンス自体のコード (1f で始まるコード) と、もしあればエスケープシーケンスへの引数をが渡ってきます。個々のフックにおいて、argc と argv にどうような値が渡ってくるのか、詳しくは「フックコードの一覧」を参照のこと。

フック関数の中から次に挙げる関数を呼び出すことで、テキストデータへの書き込みを行うことができます。

eb_write_text()
eb_write_text_string()
eb_write_text_byte1()
eb_write_text_byte2()

これらの関数の仕様に関して詳しくは「[テキストデータ] 関数の詳細」を参照のこと。

フック関数が EB_SUCCESS 以外の値を返すと、フック関数を呼び出した eb_read_text(), eb_read_heading() はエラーが発生したものと見なし、そのエラーコードをそのままアプリケーションプログラムに返します。

フック関数の中では、book に対して以下の関数を呼び出してはいけません。呼び出したときの動作は、未定義です。

eb_seek_text()
eb_read_text()
eb_read_heading()
eb_read_rawtext()
eb_forward_text()
eb_backward_text()
eb_set_subbook()
eb_unset_subbook()
eb_load_all_subbook()
eb_bind()
eb_finalize_book()
eb_finalize_library()

フックコードの一覧

この節で説明しているフックコードを使うには、次のようにヘッダファイルを読み込んで下さい。

#include <eb/text.h>

定数 `EB_HOOK_NULL`

EB_HOOK_NULL は厳密にはフックではなく、 eb_set_hooks() で複数のフック関数を登録する際に、 EB_Hook 配列の末尾の要素を示すために用います。このフックコードに対して、フック関数は登録できません。

詳しくは、「[テキストデータ] フック関数の詳細」を参照のこと。

定数 `EB_HOOK_INITIALIZE`

EB_HOOK_INITIALIZE は、eb_seek_text() を呼び出した直後の最初の eb_read_text(), eb_read_heading() の呼び出し時に処理されます。何か初期化処理をしたいときに、使うと良いでしょう。

このフックが、フック関数に渡す argc は 0 です。フック関数を登録していない状態では、このフックはテキストデータに何も書き込みません。

定数 `EB_HOOK_BEGIN_NARROW`

定数 `EB_HOOK_END_NARROW`

EB_HOOK_BEGIN_NARROW および EB_HOOK_END_NARROW は、半角表示の開始と終了を表すエスケープシーケンスに対するフックです。

どちらのフックも、フック関数に渡す argc は 1 です。 argv[0] はエスケープシーケンスのコードそのもので、 EB_HOOK_BEGIN_NARROW なら 0x1f04、 EB_HOOK_END_NARROW なら 0x1f05 になります。

フック関数を登録していない状態では、これらのフックはテキストデータに何も書き込みません。

定数 `EB_HOOK_BEGIN_SUBSCRIPT`

定数 `EB_HOOK_END_SUBSCRIPT`

EB_HOOK_BEGIN_SUBSCRIPT および EB_HOOK_END_SUBSCRIPT は、下付き表示の開始と終了を表すエスケープシーケンスに対するフックです。

どちらのフックも、フック関数に渡す argc は 1 です。 argv[0] の値はエスケープシーケンスのコードそのもので、 EB_HOOK_BEGIN_SUBSCRIPT なら 0x1f06、 EB_HOOK_END_SUBSCRIPT なら 0x1f07 になります。

フック関数を登録していない状態では、これらのフックはテキストデータに何も書き込みません。

定数 `EB_HOOK_SET_INDENT`

EB_HOOK_SET_INDENT は、テキストデータの行頭の字下げ指定を表すエスケープシーケンスに対するフックです。

このフックが、フック関数に渡す argc は 2 です。 argv[0] はエスケープシーケンスのコードそのもので、 0x1f09 になります。 argv[1] が、字下げの量を表します。

字下げの量の単位が、何であるのかは不明です。また、字下げ量の最小値は、0 の場合と 1 の場合の二通りがあります。いずれにしろ、字下げは 1 ずつ増えたり減ったりします。

フック関数を登録していない状態では、このフックはテキストデータに何も書き込みません。

定数 `EB_HOOK_NEWLINE`

EB_HOOK_SET_NEWLINE は、改行を表すエスケープシーケンスに対するフックです。

ただし、eb_read_heading() (見出しの読み込み) による処理では、改行を表すエスケープシーケンスは区切りコードとしても扱われます。そのため、エスケープシーケンスが見つかってもこのフックの処理は行われず、ただちに読み込み処理は終了します。

このフックが、フック関数に渡す argc は 1 です。 argv[0] はエスケープシーケンスのコードそのもので、 0x1f0a になります。

フック関数を登録していない状態では、このフックはテキストデータに何も書き込みませんが、eb_initialize_hookset() で EB_Hook オブジェクトを初期化すると、フック関数として eb_hook_newline() が自動的に登録されます。

定数 `EB_HOOK_BEGIN_SUPERSCRIPT`

定数 `EB_HOOK_END_SUPERSCRIPT`

EB_HOOK_BEGIN_SUPERSCRIPT および EB_HOOK_END_SUPERSCRIPT は、上付き表示の開始と終了を表すエスケープシーケンスに対するフックです。

どちらのフックも、フック関数に渡す argc は 1 です。 argv[0] はエスケープシーケンスのコードそのもので、 EB_HOOK_BEGIN_SUPERSCRIPT なら 0x1f0e、 EB_HOOK_END_SUPERSCRIPT なら 0x1f0f になります。

フック関数を登録していない状態では、これらのフックはテキストデータに何も書き込みません。

定数 `EB_HOOK_BEGIN_NO_NEWLINE`

定数 `EB_HOOK_END_NO_NEWLINE`

EB_HOOK_BEGIN_NO_NEWLINE および EB_HOOK_END_NO_NEWLINE は、改行禁止の開始と終了を表すエスケープシーケンスに対するフックです。

どちらのフックも、フック関数に渡す argc は 1 です。 argv[0] はエスケープシーケンスのコードそのもので、 EB_HOOK_BEGIN_NO_NEWLINE なら 0x1f10、 EB_HOOK_END_NO_NEWLINE なら 0x1f11 になります。

フック関数を登録していない状態では、これらのフックはテキストデータに何も書き込みません。

定数 `EB_HOOK_BEGIN_EMPHASIS`

定数 `EB_HOOK_END_EMPHASIS`

EB_HOOK_BEGIN_EMPHASIS および EB_HOOK_END_EMPHASIS は、強調表示の開始と終了を表すエスケープシーケンスに対するフックです。

どちらのフックも、フック関数に渡す argc は 1 です。 argv[0] はエスケープシーケンスのコードそのもので、 EB_HOOK_BEGIN_EMPHASIS なら 0x1f12、 EB_HOOK_END_EMPHASIS なら 0x1f13 になります。

フック関数を登録していない状態では、これらのフックはテキストデータに何も書き込みません。

定数 `EB_HOOK_BEGIN_CANDIDATE`

定数 `EB_HOOK_END_CANDIDATE_LEAF`

定数 `EB_HOOK_END_CANDIDATE_GROUP`

EB_HOOK_BEGIN_CANDIDATE は、複合検索の候補となる語の開始を表すエスケープシーケンスに対するフックです。

それに対して、終了を表すエスケープシーケンスに対するフックは 2 種類あります。一つは EB_HOOK_END_CANDIDATE_LEAF で、候補となる語が実際に検索の入力語として使えるものであることを示します。もう一つは EB_HOOK_END_CANDIDATE_GROUP で、候補となる語はさらに細かい選択肢に分かれていることを示します。 (したがって、候補となる語を検索の入力語として使うことはできません。)

フック EB_HOOK_BEGIN_CANDIDATES が、フック関数に渡す argc は 1 です。 argv[0] はエスケープシーケンスのコードそのもので、 0x1f43 になります。

フック EB_HOOK_END_CANDIDATE_LEAF および EB_HOOK_END_CANDIDATE_GROUP が、フック関数に渡す argc は 3 です。どちらのフックも、argv[0] はエスケープシーケンスのコードそのもので、0x1f63 になります。フック EB_HOOK_END_CANDIDATE_GROUP の argv[1] と argv[2] は、次の階層の候補一覧データの開始ページ番号とオフセットです。これは、EB_Position オブジェクト (「[検索] データ型の詳細」を参照のこと) の page および offset メンバの値に相当します。フック EB_HOOK_END_CANDIDATE_LEAF では、argv[1], argv[2] は 2 つとも 0 になっています。

フック関数を登録していない状態では、これらのフックはテキストデータに何も書き込みません。

定数 `EB_HOOK_BEGIN_REFERENCE`

定数 `EB_HOOK_END_REFERENCE`

EB_HOOK_BEGIN_REFERENCE および EB_HOOK_END_REFERENCE は、別位置のテキストデータの参照開始と終了を表すエスケープシーケンスに対するフックです。

フック EB_HOOK_BEGIN_REFERENCE が、フック関数に渡す argc は 2 です。 argv[0] はエスケープシーケンスのコードそのもので、 0x1f42 になります。 argv[1] の意味は不明です。

EB_HOOK_END_REFERENCE が、フック関数に渡す argc は 3 です。 argv[0] はエスケープシーケンスのコードそのもので、 0x1f62 になります。 argv[1] と argv[2] は、参照先のページ番号とオフセットです。これは、EB_Position オブジェクト (「[検索] データ型の詳細」を参照のこと) の page および offset メンバの値に相当します。

フック関数を登録していない状態では、これらのフックはテキストデータに何も書き込みません。

定数 `EB_HOOK_BEGIN_KEYWORD`

定数 `EB_HOOK_END_KEYWORD`

EB_HOOK_BEGIN_KEYWORD および EB_HOOK_END_KEYWORD は、検索キーの開始と終了を表すエスケープシーケンスに対するフックです。

フック EB_HOOK_BEGIN_KEYWORD が、フック関数に渡す argc は 2 です。 argv[0] はエスケープシーケンスのコードそのもので、 0x1f41 になります。 argv[1] の意味は不明です。

EB_HOOK_END_KEYWORD は、フック関数に 1 個の引数を渡します。 argv[0] はエスケープシーケンスのコードそのもので、 0x1f61 になります。

フック関数を登録していない状態では、これらのフックはテキストデータに何も書き込みません。

定数 `EB_HOOK_BEGIN_DECORATION`

定数 `EB_HOOK_END_DECORATION`

EB_HOOK_BEGIN_DECORATION および EB_HOOK_END_DECORATION は、文字修飾の開始と終了を表すエスケープシーケンスに対するフックです。

フック EB_HOOK_BEGIN_DECORATION が、フック関数に渡す argc は 2 です。 argv[0] はエスケープシーケンスのコードそのもので、 0x1fe0 になります。 argv[1] の意味は不明です。

EB_HOOK_END_KEYWORD は、フック関数に 1 個の引数を渡します。 argv[0] はエスケープシーケンスのコードそのもので、 0x1fe1 になります。

フック関数を登録していない状態では、これらのフックはテキストデータに何も書き込みません。

定数 `EB_HOOK_NARROW_FONT`

定数 `EB_HOOK_WIDE_FONT`

EB_HOOK_NARROW_FONT および EB_HOOK_WIDE_FONT は、それぞれ半角外字と全角外字に対するフックです。

どちらのフックも、フック関数に渡す argc は 1 です。 argv[0] は、外字の文字番号を表します。

フック関数を登録していない状態では、このフックはテキストデータに何も書き込みませんが、eb_initialize_hookset() で EB_Hook オブジェクトを初期化すると、フック関数として eb_hook_narrow_character_text() および eb_hook_wide_character_text() が自動的に登録されます。

定数 `EB_HOOK_ISO8859_1`

EB_HOOK_ISO8859_1 は、ISO 8859-1 (ラテン文字 1) 文字に対するフックです。

このフックが、フック関数に渡す argc は 1 です。 argv[0] は、ISO 8859-1 の文字番号を表します。

フック関数を登録していない状態では、argv[0] の値をそのままテキストデータに書き込みます。つまり、文字はそのまま ISO 8859-1 として、1 バイト書き込まれます。

このフックが利用されるのは、処理中の書籍の文字コードが EB_CHARCODE_ISO8859_1 の場合だけです。

定数 `EB_HOOK_NARROW_JISX0208`

定数 `EB_HOOK_WIDE_JISX0208`

EB_HOOK_NARROW_JISX0208 と EB_HOOK_WIDE_JISX0208 は、半角および全角の JIS X 0208 (日本語のかな漢字) 文字に対するフックです。

どちらのフックも、フック関数に渡す argc は 1 です。 argv[0] は、JIS X 0208 の文字を日本語 EUC で表現したときの文字番号を表します。

フック関数を登録していない状態では、argv[0] の値をそのままテキストデータに書き込みます。つまり、文字はそのまま日本語 EUC として、2 バイト書き込まれます。

このフックが利用されるのは、処理中の書籍の文字コードが EB_CHARCODE_JISX0208 か EB_CHARCODE_JISX0208_GB2312 の場合だけです。

定数 `EB_HOOK_GB2312`

EB_HOOK_GB2312 は、GB 2312 (中国語の簡体字) 文字に対するフックです。

このフックが、フック関数に渡す argc は 1 です。 argv[0] は、GB 2312 の文字を中国語 EUC で表現したときの文字番号を表します。

フック関数を登録していない状態では、argv[0] の値をそのままテキストデータに書き込みます。つまり、文字はそのまま中国語 EUC として、2 バイト書き込まれます。

このフックが利用されるのは、処理中の書籍の文字コードが EB_CHARCODE_JISX0208_GB2312 の場合だけです。

定数 `EB_HOOK_BEGIN_MONO_GRAPHIC`

定数 `EB_HOOK_END_MONO_GRAPHIC`

EB_HOOK_BEGIN_MONO_GRAPHIC および EB_HOOK_END_MONO_GRAPIHC は、モノクロ図版の開始と終了を表すエスケープシーケンスに対するフックです。

フック EB_HOOK_BEGIN_MONO_GRAPHIC が、フック関数に渡す argc は 4 です。 argv[0] はエスケープシーケンスのコードそのもので、 0x1f32 か 0x1f44 のいずれかになります。 argv[2] と argv[3] は、図版の高さと幅 (ピクセル数) を意味します。ただし、電子ブックのモノクロ図版 (最初の引数が 0x1f32 の場合) には、図版の高さと幅の情報が欠けているので、値はどちらも 0 になります。 argv[1] の意味は不明です。

EB_HOOK_END_MONO_GRAPHIC が、フック関数に渡す argc は 3 です。 argv[0] は、エスケープシーケンスのコードそのものです。 EB_HOOK_BEGIN_MONO_GRAPHIC の argv[0] が 0x1f32 なら、EB_HOOK_END_MONO_GRAPHIC の argv[0] は 0x1f52 になり、0x1f44 なら 0x1f64 になります。 argv[1] と argv[2] は、図版データのページ番号とオフセットです。これは、EB_Position オブジェクト (「[検索] データ型の詳細」を参照のこと) の page および offset メンバの値に相当します。

図版データの取り出し方については、「モノクロ図版」を参照してください。

フック関数を登録していない状態では、これらのフックはテキストデータに何も書き込みません。

定数 `EB_HOOK_BEGIN_GRAY_GRAPHIC`

定数 `EB_HOOK_END_GRAY_GRAPHIC`

これらのフック名称は、グレースケール図版のために予約されていますが、本バージョンの EB ライブラリではまだ対応していません。

定数 `EB_HOOK_BEGIN_COLOR_BMP`

定数 `EB_HOOK_BEGIN_COLOR_JPEG`

定数 `EB_HOOK_END_COLOR_GRAPHIC`

EB_HOOK_BEGIN_COLOR_BMP と EB_HOOK_COLOR_JPEG は、それぞれ BMP 形式と JPEG 形式のカラー図版の開始を表すエスケープシーケンスに対するフックです。開始のフックは BMP と JPEG とでフックが分かれていますが、終了のフックは共通で、EB_HOOK_END_COLOR_GRAPIHC になります。

フック EB_HOOK_BEGIN_COLOR_BMP と EB_HOOK_COLOR_JPEG が、フック関数に渡す argc は 4 です。 argv[0] はエスケープシーケンスのコードそのもので、 0x1f4d になります。 argv[2] と argv[3] は、図版の幅と高さ (ピクセル数) を意味します。 argv[1] の意味は不明です。

フック EB_HOOK_END_COLOR_BMP が、フック関数に渡す argc は 3 です。 argv[0] はエスケープシーケンスのコードそのもので、 0x1f6d になります。 argv[1] と argv[2] は、図版データのページ番号とオフセットです。これは、EB_Position オブジェクト (「[検索] データ型の詳細」を参照のこと) の page および offset メンバの値に相当します。

図版データの取り出し方については、「カラー図版」を参照してください。

フック関数を登録していない状態では、これらのフックはテキストデータに何も書き込みません。

定数 `EB_HOOK_BEGIN_IN_COLOR_BMP`

定数 `EB_HOOK_BEGIN_IN_COLOR_JPEG`

定数 `EB_HOOK_END_IN_COLOR_GRAPHIC`

EB_HOOK_BEGIN_IN_COLOR_BMP と EB_HOOK_IN_COLOR_JPEG は、それぞれ BMP 形式と JPEG 形式のインラインカラー図版の開始を表すエスケープシーケンスに対するフックです。開始のフックは BMP と JPEG とでフックが分かれていますが、終了のフックは共通で、EB_HOOK_END_IN_COLOR_GRAPIHC になります。

フック EB_HOOK_BEGIN_IN_COLOR_BMP と EB_HOOK_IN_COLOR_JPEG が、フック関数に渡す argc は 4 です。 argv[0] はエスケープシーケンスのコードそのもので、 0x1f3c になります。 argv[2] と argv[3] は、図版の幅と高さ (ピクセル数) を意味します。 argv[1] の意味は不明です。

フック EB_HOOK_END_IN_COLOR_BMP が、フック関数に渡す argc は 3 です。 argv[0] はエスケープシーケンスのコードそのもので、 0x1f5c になります。 argv[1] と argv[2] は、図版データのページ番号とオフセットです。これは、EB_Position オブジェクト (「[検索] データ型の詳細」を参照のこと) の page および offset メンバの値に相当します。

図版データの取り出し方については、「カラー図版」を参照してください。

フック関数を登録していない状態では、これらのフックはテキストデータに何も書き込みません。

定数 `EB_HOOK_BEGIN_CLICKABLE_AREA`

定数 `EB_HOOK_END_CLICKABLE_AREA`

EB_HOOK_BEGIN_CLICKABLE_AREA は、カラー図版およびインラインカラー図版内の特定矩形領域に対して、参照先情報を表現した開始エスケープシーケンスに対するフックです。同様に、EB_HOOK_END_CLICKABLE_AREA は終了エスケープシーケンスに対するフックです。

フック EB_HOOK_BEGIN_CLICKABLE_AREA が、フック関数に渡す argc は 7 です。 argv[0] はエスケープシーケンスのコードそのもので、 0x1f4f になります。 argv[1] と argv[2] は、それぞれ矩形領域の開始 x, y 座標を表します。それぞれ矩形領域の開始 x, y 座標を表します。カラー図版の左上の座標が (0, 0) です。同様に、argv[3] と argv[4] が図版の右方向への幅と、下方向への高さを表します。最後の argv[5] と argv[6] が参照先のページ番号とオフセットとなります。

　　　　　　　　　参照先付きカラー図版
（０，０）
　　┌─────────────────────┐
　　│　　　　　　　　　　　　　　　　　　　　　│
　　│（ｘ，ｙ）　　　　　　　　　　　　　　　　│
　　│　　┌　─　─　─　─　─　─　┐　　　　│
　　│　　│　　　　　　　　　高さ↑　│　　　　│
　　│　　　　　　　　　　　　　　│　　　　　　│
　　│　　│　　矩形領域　　　　　│　│　　　　│
　　│　　　　　　　　　　　　　　│　　　　　　│
　　│　　│　　　　　　　　　　　│　│　　　　│
　　│　　　　　　　幅　　　　　　│　　　　　　│
　　│　　│←──────────┼→│　　　　│
　　│　　　　　　　　　　　　　　↓　　　　　　│
　　│　　└　─　─　─　─　─　─　┘　　　　│
　　│　　　　　　　　　　　　　　　　　　　　　│
　　└─────────────────────┘

EB_HOOK_END_CLICKABLE_AREA が、フック関数に渡す argc は 1 です。 argv[0] はエスケープシーケンスのコードそのもので、 0x1f6f になります。

参照先情報の取り出し方については、「参照先付きカラー図版」を参照して下さい。

フック関数を登録していない状態では、これらのフックはテキストデータに何も書き込みません。

定数 `EB_HOOK_BEGIN_WAVE`

定数 `EB_HOOK_END_WAVE`

EB_HOOK_BEGIN_WAVE および EB_HOOK_END_WAVE は、 WAVE (PCM) 形式の音声データの開始と終了を表すエスケープシーケンスに対するフックです。

フック EB_HOOK_BEGIN_WAVE が、フック関数に渡す argc は 6 です。 argv[0] はエスケープシーケンスのコードそのもので、 0x1f4a になります。 argv[2] と argv[3] は音声データの開始位置のページ番号とオフセット、argv[4] と argv[5] は終了位置のページ番号とオフセットをそれぞれ表します。 argv[1] の意味は不明です。

EB_HOOK_END_WAVE が、フック関数に渡す argc は 1 です。 argv[0] はエスケープシーケンスのコードそのもので、 0x1f6a になります。

音声データの取り出し方については、「WAVE 音声」を参照して下さい。

フック関数を登録していない状態では、これらのフックはテキストデータに何も書き込みません。

定数 `EB_HOOK_BEGIN_MPEG`

定数 `EB_HOOK_END_MPEG`

EB_HOOK_BEGIN_MPEG および EB_HOOK_END_MPEG は、 MPEG 形式の動画データの開始と終了を表すエスケープシーケンスに対するフックです。

フック EB_HOOK_BEGIN_MPEG が、フック関数に渡す argc は 6 です。 argv[0] はエスケープシーケンスのコードそのもので、 0x1f39 になります。 argv[2] 〜 argv[5] は、動画データのファイル名をエンコードした数値列になります。 argv[1] の意味は不明です。

EB_HOOK_END_MPEG が、フック関数に渡す argc は 1 です。 argv[0] はエスケープシーケンスのコードそのもので、 0x1f59 になります。

動画データの取り出し方については、「MPEG 動画」を参照して下さい。

フック関数を登録していない状態では、これらのフックはテキストデータに何も書き込みません。

フックセット操作関数の詳細

この節で説明している関数を使うには、次のようにヘッダファイルを読み込んで下さい。

#include <eb/text.h>

`void eb_initialize_hookset (EB_Hookset *hookset)`

関数 initialize_hookset() は、hookset の指す EB_Hookset オブジェクトを初期化します。 EB_Hookiset オブジェクトに対して EB ライブラリの他の関数を呼ぶ前に、必ずそのオブジェクトを初期化しなくてはなりません。初期化していないオブジェクトに対して、EB ライブラリの他の関数を呼んだ場合の動作は未定義です。また、すでに初期化したオブジェクトに対して、再度 eb_initialize_hookset() を呼んではいけません。呼んだ場合の動作は未定義です。

この関数は、各フックの初期値を次のようにセットします。

フック	フック関数
`EB_HOOK_NARROW_JISX0208`	`eb_hook_euc_to_ascii()`
`EB_HOOK_NARROW_FONT`	`eb_hook_narrow_character_text()`
`EB_HOOK_WIDE_FONT`	`eb_hook_wide_character_text()`
`EB_HOOK_NEWLINE`	`eb_hook_newline()`
上記以外のフック	`NULL` (フック関数なし)

`EB_Error_Code eb_finalize_hookset (EB_Hookset *hookset)`

関数 eb_finalize_hookset() は、hookset が指す EB_Hooksest オブジェクトの後始末を行います。

オブジェクトが割り当てて管理していたメモリは、すべて解放されます。すべてのフックには、フック関数として NULL がセットされます。

後始末をしたオブジェクトに対して eb_set_hook(), eb_set_hooks() を呼ぶことで、オブジェクトを再利用することができます。

`EB_Error_Code eb_set_hook (EB_Hookset hookset, const EB_Hook hook)`

関数 eb_set_hook() は、hookset が指す EB_Hooksest オブジェクトに、フック関数を一つ登録します。登録するフックの種類とフック関数は、hook で指定します。

同じフックコードに複数回フック関数を登録しても、有効になるのは最後に登録したものだけですので、注意して下さい。フック関数として NULL を指定すると、登録されているフックが解除されます。

成功すると、この関数は EB_SUCCESS を返します。失敗すると、原因を示すエラーコードを返します。

`EB_Error_Code eb_set_hooks (EB_Hookset hookset, const EB_Hook hooks)`

この関数は eb_set_hook() に似ていますが、任意の個数のフック関数を一度に登録できる点が異なります。

登録するフックの種類とフック関数は、hooks で指定します。 hooks は EB_Hook オブジェクトの配列 (の先頭) を指していなければなりません。また、この配列の末尾には、フックコード EB_HOOK_NULL をセットした EB_Hook オブジェクトを配列要素として置く必要があります。

eb_set_hooks() は、配列の先頭から順番に、指定されたフックコードに対してフック関数を登録していきます。エラーが発生すると、残りのフックの登録はせずに、原因を示すエラーコードをただちに返します。すべてのフック関数の登録に成功すると、EB_SUCCESS を返します。

組み込みフック関数の詳細

EB ライブラリは、基本的なフック関数をいくつか用意しています。本節では、これらのフック関数についての仕様を解説します。

この節で説明している関数を使うには、次のようにヘッダファイルを読み込んで下さい。

#include <eb/text.h>

いずれのフック関数も、引数 appendix と container に NULL を渡されても、動作に支障はないようになっています。

`EB_Error_Code eb_hook_euc_to_ascii (EB_Book book, EB_Appendix appendix, void container, EB_Hook_Code code, int argc, const unsigned int argv)`

eb_hook_euc_to_ascii() は、フックコード EB_HOOK_NARROW_JISX0208 (半角 JIS X 0208 文字) のためのフック関数です。

EB_Hookset オブジェクトを関数 eb_initialiez_hookset() で初期化すると、この関数が自動的に登録されます。

このフック関数は、argv[0] として渡された JIS X 0208 の文字 (エンコーディングは日本語 EUC) を調べ、対応する ASCII 文字が存在すればその ASCII 文字をテキストデータとして書き込み、なければ JIS X 0208 の文字をそのまま書き込みます。

常に EB_SUCCESS を返します。

`EB_Error_Code eb_hook_narrow_character_text (EB_Book book, EB_Appendix appendix, void container, EB_Hook_Code code, int argc, const unsigned int argv)`

`EB_Error_Code eb_hook_wide_character_text (EB_Book book, EB_Appendix appendix, void container, EB_Hook_Code code, int argc, const unsigned int argv)`

eb_hook_narrow_character_text() は、フックコード EB_HOOK_NARROW_FONT (半角外字) のためのフック関数です。同様に eb_hook_wide_character_text() は、フックコード EB_HOOK_WIDE_FONT (全角外字) のためのフック関数です。

EB_Hookset オブジェクトを関数 eb_initialiez_hookset() で初期化すると、これらの関数が自動的に登録されます。

この関数は、appendix の選択中している副本が、 argv[0] として渡された外字の代替文字列を持っているかどうか調べます。持っていればその文字列をテキストデータとして書き込み、持っていなければ <?> という文字列を書き込みます。

appendix が NULL の場合や、付録が副本を選択中でない場合も、代替文字列を持っていないものとして扱います。

この関数は、常に EB_SUCCESS を返します。

`EB_Error_Code eb_hook_newline (EB_Book book, EB_Appendix appendix, void container, EB_Hook_Code code, int argc, const unsigned int argv)`

eb_hook_narrow_newline() は、フックコード EB_HOOK_NEWLINE (改行) のためのフック関数です。

EB_Hookset オブジェクトを関数 eb_initialiez_hookset() で初期化すると、これらの関数が自動的に登録されます。

この関数は、テキストデータに \n を書き込みます。常に EB_SUCCESS を返します。

`EB_Error_Code eb_hook_empty (EB_Book book, EB_Appendix appendix, void container, EB_Hook_Code code, int argc, const unsigned int argv)`

eb_hook_empty() は、何もしないフック関数です。常に EB_SUCCESS を返します。

テキストデータ操作関数の詳細

この節で説明している関数を使うには、次のようにヘッダファイルを読み込んで下さい。

#include <eb/text.h>

`int eb_have_text (EB_Book *book)`

`int eb_have_menu (EB_Book *book)`

`int eb_have_copyright (EB_Book *book)`

関数 eb_have_text() は、book の選択している副本が、本文を持っているかどうかを調べます。同様に、eb_have_menu() はメニューを持っているかどうか、 eb_have_copyright() は著作権表示を持っているかどうか調べます。

いずれの関数も、持っていれば 1 を返し、持っていなければ 0 を返します。 book が副本を選択していない場合も 0 を返します。

`EB_Error_Code eb_text (EB_Book book, EB_Position position)`

`EB_Error_Code eb_menu (EB_Book book, EB_Position position)`

`EB_Error_Code eb_copyright (EB_Book book, EB_Position position)`

関数 eb_text() は、book が選択している副本の本文の開始位置を position の指す領域に書き込みます。同様に、eb_menu() はメニューの開始位置を、 eb_have_copyright() は著作権表示の開始位置を書き込みます。

成功すると、これらの関数は EB_SUCCESS を返します。失敗すると、position に必ずシークが失敗する位置を書き込んで、原因を示すエラーコードを返します。

あらかじめ、book 内のいずれかの副本が選択されていなくてはなりません。 book が副本を選択していなければ、EB_ERR_NO_CUR_SUB を返します。選択中の副本が、対象となるテキストデータを持っていなければ、 EB_ERR_NO_SUCH_SEARCH を返します。

`EB_Error_Code eb_seek_text (EB_Book book, const EB_Position position)`

関数 eb_seek_text() は、book が選択している副本のテキストデータファイルをシークします。シーク位置は position で指定します。このとき、position は常にファイルの先頭からの位置として解釈されます。 (相対位置へのシーク機能は、EB ライブラリにはありません。)

シークを行うと、それまでに行った読み込みの状態記録がリセットされます。 eb_read_text(), eb_read_heading(), eb_read_rawtext() を用いてテキストデータを読み込むには、前もってこの関数を呼び出しておく必要があります。

成功すると、この関数は EB_SUCCESS を返します。失敗すると、原因を示すエラーコードを返します。

あらかじめ、book 内のいずれかの副本が選択されていなくてはなりません。 book が副本を選択していなければ、EB_ERR_NO_CUR_SUB を返します。選択中の副本にテキストデータが存在しないときは、EB_ERR_NO_TEXT を返します。

なお、書籍によっては、テキストデータを収めたファイルには他のデータも一緒に格納されていることがありますが、テキスト以外のデータにアクセスしても、テキストデータの現在位置、読み込みに関する状態記録は変化しません。

`EB_Error_Code eb_tell_text (EB_Book book, EB_Position position)`

関数 eb_seek_text() は、book が選択している副本のテキストデータファイルの現在のアクセス位置を返します。

成功すると、position の指す領域に現在のアクセス位置を書き込み、 EB_SUCCESS を返します。失敗すると、シークが必ず失敗する位置を書き込み、原因を示すエラーコードを返します。

`EB_Error_Code eb_read_text (EB_Book book, EB_Appendix appendix, EB_Hookset hookset, void container, size_t text_max_length, char text, ssize_t text_length)`

`EB_Error_Code eb_read_heading (EB_Book book, EB_Appendix appendix, EB_Hookset hookset, void container, size_t text_max_length, char text, ssize_t text_length)`

関数 eb_read_text() と eb_read_heading() は、 book が選択している副本のテキストデータファイルの現在のアクセス位置からデータを読み込みます。 eb_read_heading() は見出しの読み込みに用い、 eb_read_text() はそれ以外のテキストデータの読み込みに用います。

読み込まれたテキストデータは、必要に応じて文字コードの変換 (「文字コード」を参照のこと) が行われた後に、hookset の指すフックセットにしたがって加工されます。 hookset が NULL のときは、代わりに EB ライブラリ側で用意している標準のフックセット (default hookset) が用いられます。このフックセットは、eb_initialize_hookset() によって初期化しただけのフックセットと等価です。

フックセットによって加工された後に、テキストデータは text の指す領域に書き込まれ、書き込んだバイト数が text_length の指す領域に書き込まれます。 text はナル文字で終端されますが、text_length にはナル文字の分は勘定に入れません。テキストデータは、text_max_length で指定されたバイト数を超えて書き込むことはありません。ただし、text_max_length にもナル文字の分は勘定に入っていませんので、text は text_max_length + 1 バイト分のデータを格納できる大きさが必要です。

どちらの関数も、成功すれば EB_SUCCESS を返し、失敗すれば text_length の指す領域に 0 を書き込んで原因を示すエラーコードを返します。

あらかじめ、book 内のいずれかの副本が選択されていなくてはなりません。 book が副本を選択していなければ、EB_ERR_NO_CUR_SUB を返します。

また、eb_read_text() と eb_read_heading() を呼び出すには、あらかじめ eb_seek_text() の呼び出しを成功させ、テキストデータのアクセス位置がセットされた状態にしておかなくてはなりません。シークをせずに呼び出すと、EB_ERR_NO_PREV_SEEK を返します。

逆に一度シークすれば、区切りコードが検出されるまでの間なら、関数を繰り返し呼ぶことでテキストデータの続きを読み込むことができます。区切りコードが検出されると、関数を呼び出しても読み込みは行われません。その場合でも、他にエラーが発生しなければ EB_SUCCESS が返り、 text には空文字列が書き込まれます。

ただし、一度 eb_read_text() を呼び出してテキストデータを読み込み始めたら、繰り返し呼び出す際も、eb_read_text() を使わなければなりません。途中から eb_read_heading() および後述の eb_read_rawtext() に切り替えて呼び出すと EB_ERR_DIFF_CONTENT エラーが返ります。関数 eb_read_heading() についても同様です。この制限は、再度 eb_seek_text() を呼び出すか、 eb_set_subbook() で副本を選択し直すまで続きます。

渡された appendix が区切りコードの情報を持った副本を選択中であれば、本文の区切りコードとしてその値を使用します。それ以外の場合は、eb_read_text() が区切りコードを自動判別を試みます。ただし、この判定は完璧なものではないので、書籍によっては変な位置で本文が切れてしまうかも知れません。 (本文以外のテキストデータに関しては、このような問題は起きません。)

引数 container は、アプリケーションプログラムからフック関数にデータを渡すためのものです。 eb_read_text(), eb_read_heading() では、直接この引数の値を参照することはありません。

引数 appendix, container は、そのままフック関数に渡されます。これらの引数は NULL でも構いません。 (呼び出されるフック関数で支障がなければ。)

なお、フック関数や eb_read_text(), eb_read_heading() 自身が文字ないしエスケープシーケンス一個分に対するデータを書き込もうとしたときに、text に十分な空き領域がないということが起こり得ます。その場合、関数は途中まで text に書き込むことはせずに、いったん処理を終えて戻ります。したがって、マルチバイト文字のデータが途中で切れたりすることはありません。

書き込めなかった分は、当然ながら text_length の勘定には入りません。書き込めなかったデータは book 内部に保存されているので、もう一度 eb_read_text(), eb_read_heading() を呼び出すと、前回の呼び出しで書き込めなかったデータがまず text の先頭に書き込まれます。書き込んだデータは text_length の勘定に入ります。

ただし、book が保存しているデータの長さが text_max_length を超えていると、何も書き込まずに関数は終了します。このとき、書き込めなかったデータは引き続き保存されます。つまり、text_max_length があまりに小さく、かつ保持しているデータのほうが長いと、何度呼び出しても text への書き込みが進みませんので、注意が必要です。

eb_seek_text() を呼び出すか、eb_set_subbook() で副本を選択し直すと、保存していたデータは破棄されます。

`EB_Error_Code eb_read_rawtext (EB_Book book, size_t text_max_length, char text, ssize_t *text_length)`

関数 eb_read_rawtext() は、book が選択している副本のテキストデータファイルの現在のアクセス位置からデータを読み込みます。

eb_read_text() と似ていますが、この関数はフックセットによるデータの加工や文字コードの変換を一切行わず、データを内部表現のまま返します。読み込むテキストデータの種類は、何であっても構いません。

読み込んだテキストデータは text の指す領域に書き込まれ、書き込んだバイト数が text_length の指す領域に書き込まれます。テキストデータは、text_max_length で指定されたバイト数を超えて書き込むことはありません。ただし、eb_read_text() と異なり、text はナル文字で終端されません。マルチバイト文字やエスケープシーケンスの途中で text の残り領域が足りなくなった場合も、途中までは書き込みます。

処理が成功すれば EB_SUCCESS を返し、失敗すれば text_length の指す領域に 0 を書き込んで原因を示すエラーコードを返します。

あらかじめ、book 内のいずれかの副本が選択されていなくてはなりません。 book が副本を選択していなければ、EB_ERR_NO_CUR_SUB を返します。

また、この関数を呼び出すには、あらかじめ eb_seek_text() の呼び出しを成功させ、テキストデータのアクセス位置がセットされた状態にしておかなくてはなりません。シークをせずに呼び出すと、EB_ERR_NO_PREV_SEEK を返します。

この関数は、繰り返し呼び出すことで、前回読み込んだテキストデータの続きを読み込むことができます。ただし、区切りコードの検出を行いませんので、ひたすら呼び出しを続けると、テキストデータファイルの末尾まで行ってしまいます。

一度 eb_read_rawtext() を呼び出してテキストデータを読み込み始めたら、繰り返し呼び出す際も、eb_read_rawtext() を使わなければなりません。途中から、eb_read_text() や eb_read_heading() に切り替えると、 EB_ERR_DIFF_CONTENT エラーが返ります。この制限は、再度 eb_seek_text() を呼び出すか、 eb_set_subbook() で副本を選択し直すまで続きます。

`int eb_is_text_stopped (EB_Book *book)`

関数 eb_is_text_stopped() は、最後に読み込んだテキストデータが末尾に達したかどうかを判定します。

book が選択中の副本で、最後に eb_read_text() または eb_read_heading() でテキストデータを読み込んだ際に、区切りコードを検出したか、テキストデータ全体の一番後ろの位置に達して読み込みを終えていれば、この関数は 1 を返します。それ以外のときは、0 を返します。

book が副本を選択していない場合や、選択中の副本にテキストデータが存在しない場合も 0 が返ります。

eb_read_text() または eb_read_heading() でテキストデータを読み込んでいない場合も、同様に 0 が返ります。テキストデータを読み込んだ後であっても、テキストデータの読み込みに関する状態記録をリセットする関数 (eb_read_text() の項を参照) を呼んでしまうと、読み込んでいないと見なされますので、注意して下さい。

通常はこの関数を使わなくても、eb_read_text() や eb_read_heading() が 0 を返したら、テキストデータの末尾に達したとみなして差し支えないでしょう。ただしその際は、引数 text_max_length の値を十分大きく取って下さい。

`EB_Error_Code eb_write_text_byte1 (EB_Book *book, int byte1)`

`EB_Error_Code eb_write_text_byte2 (EB_Book *book, int byte1, int byte2)`

`EB_Error_Code eb_write_text_string (EB_Book book, const char string)`

`EB_Error_Code eb_write_text (EB_Book book, const char stream, size_t stream_length)`

これらの関数は、いずれもフック関数の中から、テキストデータを書き込むために用います。書き込むデータの種類によって、使い分けて下さい。

eb_write_text_byte1() は、byte1 で指定した 1 バイトの値を書き込みます。 eb_write_text_byte2() は、byte1, byte2 で指定した 2 バイトを書き込みます。 eb_write_text_string() は、string で指定した文字列を書き込みます。 eb_write_text() は、stream から始まる長さ stream_length バイトのバイト列を書き込みます。

どの関数も、成功すると EB_SUCCESS を返し、失敗すると原因を示すエラーコードを返します。

最終的に、書き込んだテキストデータは、フック関数の呼び出し元である eb_read_text(), eb_read_heading() からアプリケーションプログラムに渡されます。

フック関数として呼び出されていないときに、これらの関数を呼び出した場合の動作は未定義です。

`const char eb_current_candidate (EB_Book book)`

関数 eb_current_candidate() は、アクセス中のテキストデータの現在位置に書かれている、複合検索の候補となる語を返します。

返す文字列の長さは、最長で EB_MAX_WORD_LENGTH バイトになります。ただし、この長さにナル文字は含みません。

この関数は非常に特殊で、複合検索の候補となる語の終了を意味するエスケープシーケンスへのフックである EB_HOOK_END_CANDIDATE_LEAF および EB_HOOK_END_CANDIDATE_GROUP に対するフック関数の中でのみ呼び出すことができます。それ以外の場所で呼び出したときの動作は、未定義です。

この関数の呼び出し方ですが、フック関数に渡ってきた EB_Book オブジェクト (へのポインタ) を、そのままこの関数に引数として渡してやります。

book の文字コード (「[CD-ROM 書籍と EB_Book オブジェクト] データ型の詳細」を参照のこと) が EB_CHARCODE_ISO8859_1 なら、関数の返す文字列は ISO 8859-1 になり、それ以外の文字コードの場合は日本語 EUC になります。関数の返す文字列は、他のフックによる加工処理の影響を受けません。文字コードの変換を行う以外は、内部データをそのまま返します。

なお、この関数が返した文字列を参照できるのは、フック関数から戻るまでの間だけですので、注意して下さい。

`EB_Error_Code eb_forward_text (EB_Book book, EB_Appendix appendix)`

`EB_Error_Code eb_backward_text (EB_Book book, EB_Appendix appendix)`

関数 eb_forward_text() と eb_backward_text() は、 book が選択している副本の本文のアクセス位置を前後に移動させ、本文の区切りコードを単位とした頭出しを行います。ちょうど、音楽 CD の曲の頭出しと同じです。

eb_forward_text() は本文の末尾方向に向かってアクセス位置を進め、eb_backward_text() は先頭方向に向かってアクセス位置を戻します。

eb_forward_text() の呼び出しでは、アクセス位置は必ず次の語の説明の開始位置まで移動します。それに対して eb_backward_text() の呼び出しでは、移動先が状態によって異なります。もし、現在のアクセス位置がその単語の説明の先頭にあるときは、 eb_backward_text() の呼び出しによって、一つ前の単語の説明の先頭にアクセス位置が移動します。アクセス位置が単語の説明の途中や末尾にあるときは、その単語の説明の先頭に移動します。

この関数は、成功すると EB_SUCCESS を返し、失敗すると原因を示すエラーコードを返します。

あらかじめ、book 内のいずれかの副本が選択されていなくてはなりません。 book が副本を選択していなければ、EB_ERR_NO_CUR_SUB を返します。

加えて、これらの関数を呼び出すには、あらかじめ eb_seek_text() か eb_read_text() を呼び出しが成功していないといけません。 (eb_read_text() の呼び出しを成功させるには、さらに前もって eb_seek_text() の呼び出しを成功させることが条件となります。)

eb_read_text() ではなく、eb_read_heading() や eb_read_rawtext() の呼び出しに成功した後でこの関数を呼び出すと、EB_ERR_DIFF_CONTENT を返します。また、前もって eb_seek_text() でシークせずにこの関数を呼び出すと、EB_ERR_NO_PREV_SEEK を返します。

本文データの末尾や先頭に達してしまって、その方向にもう本文がないときは、 EB_ERR_END_OF_CONTENT を返します。

appendix が NULL ではなく、区切りコードの情報を持った副本を選択中であれば、本文の区切りコードとしてその値を使用します。それ以外の場合は、eb_read_text() と同じ方法で区切りコードの自動判別を試みます。

アクセス位置上にあるのがメニューや著作権表示のように、本文以外のテキストデータであっても構いません。ただし、本文以外のテキストデータの内部には、頭出し位置がデータの先頭位置にしかありませんので、この関数が役に立つ状況はほとんどありません。

(メニューでは、個々の階層のメニューデータが、それぞれ独立したテキストデータになっているため、頭出しを行っても前後のメニューデータへは移動できません。複合検索の候補一覧も同様です。)

`EB_Error_Code eb_forward_heading (EB_Book *book)`

関数 eb_forward_heading() は、book が選択している副本の見出しのアクセス位置を後に移動させ、見出しの区切りを単位とした頭出しを行います。

本文の頭出しを行う関数 eb_forward_text() の見出し版です。ただし、見出しで頭出しを行う機会は、クロス検索の本文取得に限られるため、 eb_backward_heading() という関数は用意していません。

この関数を呼ぶと、アクセス位置が次の見出しの開始位置まで移動します。 (クロス検索では、見出し領域の中に「見出し」と「本文」が交互に書かれていますが、データ構造上「本文」と「見出し」は区別が付きません。アクセス位置がクロス検索の見出し領域内の場合、この関数を呼ぶと最も近い「見出し」もしくは「本文」の開始位置まで移動します。)

eb_read_heading() ではなく、eb_read_text() や eb_read_rawtext() の呼び出しに成功した後でこの関数を呼び出すと、EB_ERR_DIFF_CONTENT を返します。また、前もって eb_seek_text() でシークせずにこの関数を呼び出すと、EB_ERR_NO_PREV_SEEK を返します。

この関数は、成功すると EB_SUCCESS を返し、失敗すると原因を示すエラーコードを返します。

クロス検索以外の検索メソッドの見出しの格納位置に対して、この関数を呼ぶことも可能ですが、そのような必要に迫られる機会はないでしょう。

[前へ] [次へ] [目次]