FreePWING プログラミングドキュメント

[前へ] [目次]

# リファレンスマニュアル

## `FreePWING::FPWUtils::Word2` クラス

`FreePWING::FPWUtils::Word2` は、前方一致および後方一致検索 用の検索語一覧を同時に生成するためのクラスです。 以下のメソッドを持っています。

`new()`
  `FreePWING::FPWUtils::Word2` クラスのオブジェクトを生成して、 そのリファレンスを返すクラスメソッドです。
`open()`
  書き込み用に検索語ファイルを開きます。 ファイル名は、あらかじめモジュール内で指定されたものが使用されます。 成功すれば 1 を、失敗すれば 0 を返します。
`close()`
  開いていた検索語ファイルを閉じます。 開いていなければ何もしません。 このメソッドは常に 1 を返します。
`add_entry($word, $heading_position, $text_position)`
  検索語ファイルに検索語を一つ追加します。 `$word` が追加する検索語、 `$heading_position` が見出しの位置、 `$text_position` が本文の位置です。 見出しと本文の位置は、`FreePWING::FPWUtils::Heading` および `FreePWING::FPWUtils::Text` クラスのオブジェクトが持っている `entry_position()` メソッドを使って取得します。 このメソッドは成功すれば 1 を、失敗すれば 0 を返します。 追加する検索語の最大長は 255 バイトです。
`file_name()`
  検索語ファイルを開いたときに指定したファイル名を返します。
`entry_count()`
  現在までに書き込んだエントリ数を返します。
`error_message()`
  このクラスのメソッドを呼び出して、処理結果が失敗に終わった場合 (0 を 返してきた場合)、エラーメッセージを返します。 エラーが発生していなければ、空の文字列が返ります。

## `FreePWING::FPWUtils::KeyWord` クラス

`FreePWING::FPWUtils::KeyWord` は、条件検索用の検索語一覧を 同時に生成するためのクラスです。 このクラスのオブジェクトが有するメソッドは、 `FreePWING::FPWUtils::Word2`クラス とまったく同じですので、そちらを参照して下さい。

## `FreePWING::FPWUtils::Text` クラス

`FreePWING::FPWUtils::Text` は、本文を生成するためのクラス です。 以下のメソッドを持っています。

`new()`
  `FreePWING::FPWUtils::Text` クラスのオブジェクトを生成して、 そのリファレンスを返すクラスメソッドです。 通常は直接このメソッドを呼び出さずに、fpwutils が提供する `initialize_fpwparser()` サブルーチンを用います。
`open()`
  書き込み用に本文ファイルを開きます。 ファイル名は、あらかじめモジュール内で指定されたものが使用されます。 成功すれば 1 を、失敗すれば 0 を返します。 通常は直接このメソッドを呼び出さずに、fpwutils が提供する `initialize_fpwparser()` サブルーチンを用います。
`close()`
  `open()` メソッドで開いたファイルをすべて閉じます。 成功すれば 1 を、失敗すれば 0 を返します。 開いていなければ何もせず、1 を返します。 通常は直接このメソッドを呼び出さずに、fpwutils が提供する `finalize_fpwparser()` サブルーチンを用います。
`new_context()`
  現在のエントリおよびコンテキストを終端させ、新たなコンテキストを開始 します。 成功すれば 1 を、失敗すれば 0 を返します。 このメソッドを呼び出すには、あらかじめ本文ファイルを開いていなければ なりません。 本文ファイル開いた直後の一文字もデータを書き込んでいない状態で、この メソッドを呼んでも、新たなコンテキストを開始することはしません。 これにより、最初のコンテキストに対しては、明示的にこのメソッドを 呼んでも呼ばなくてもどちらでも良いようになっています。
`new_entry()`
  現在のエントリを終端させ、新たなエントリを開始します。 成功すれば 1 を、失敗すれば 0 を返します。 このメソッドを呼び出すには、あらかじめ本文ファイルを開いていなければ なりません。 ファイル開いた直後および `new_context()` で新たな コンテキストを開始した直後の一文字もデータを書き込んでいない状態で、 このメソッドを呼んでも、さらに新たなエントリを開始することはしません。 これにより、先頭のエントリに対しては、明示的にこのメソッドを呼んでも 呼ばなくてもどちらでも良いようになっています。
`add_text($text)`
  引数 `$text` で指定した文字列を本文に追加します。 文字列は、EUC-JP で書かれていなくてはなりません。 ただし、`$text` 中に出現する改行文字 (CR および LF) は無視 されます。 このメソッドを呼び出すには、あらかじめ本文ファイルを開いていなければ なりません。 成功すれば 1 を、失敗すれば 0 を返します。
`add_half_user_character($character_name)`
`add_full_user_character($character_name)`
  `add_half_user_character()` は引数 `$character_name` で指定した半角外字を本文に追加します。 同様に `add_full_user_character()` は、全角外字を追加します。 `$character_name` は、外字定義ファイルの中で定義されている 外字名でなければなりません。 成功すれば 1 を、失敗すれば 0 を返します。
`add_entry_tag($tag)`
  `add_entry_tag($tag)` は本文の現在のエントリの先頭位置に 対して、それぞれ `$tag` という名前のタグを設定します。 これらのメソッドを呼び出すには、あらかじめ本文ファイルと 参照情報ファイル、タグファイルを開いていなければなりません。 タグ名は本文、メニュー、著作権表示データ内で一意のものでなくては なりません。 このメソッドは成功すれば 1 を、失敗すれば 0 を返します。
`add_keyword_start()`
`add_keyword_end()`
  `add_keyword_start()` は検索キー開始指定子を、 `add_keyword_end()` は検索キー終了指定子を、それぞれ 呼ばれた時点での本文の現在位置に挿入します。 メソッドを呼び出すには、あらかじめ本文ファイルを開いていなければ なりません。 いずれのメソッドも成功すれば 1 を、失敗すれば 0 を返します。 使用方法に関しては、 読み込んだ見出しの処理、 本文に関する注意点、 修飾指定子 の節もあわせてご覧下さい。
`add_reference_start()`
`add_reference_end($position)`
  `add_reference_start()` は参照開始指定子を、 `add_reference_end()` は参照終了指定子を、それぞれ呼ばれた 時点での本文の現在位置に挿入します。 参照先の位置は `$position` で指定します。 メソッドを呼び出すには、あらかじめ本文ファイルを開いていなければ なりません。 成功すれば 1 を、失敗すれば 0 を返します。 使用方法に関しては、 相互参照 の節もあわせてご覧下さい。
`add_subscript_start()`
`add_subscript_end()`
  `add_subscript_start()` は下添え字開始指定子を、 `add_subscript_end()` は下添え字終了指定子を、それぞれ 呼ばれた時点での本文の現在位置に挿入します。 メソッドを呼び出すには、あらかじめ本文ファイルを開いていなければ なりません。 成功すれば 1 を、失敗すれば 0 を返します。 使用方法に関しては、 修飾指定子 の節もあわせてご覧下さい。
`add_indent_level($level)`
  本文の行頭の字下げ量を `$level` に設定します。 指定できるのは、2 から 6 までの整数です。 また、各エントリ開始時に自動的に 1 に設定されます。 メソッドを呼び出すには、あらかじめ本文ファイルを開いていなければ なりません。 成功すれば 1 を、失敗すれば 0 を返します。
`add_newline()`
  本文の現在位置に改行を挿入します。 メソッドを呼び出すには、あらかじめ本文ファイルを開いていなければなりま せん。 成功すれば 1 を、失敗すれば 0 を返します。
`add_superscript_start()`
`add_superscript_end()`
  `add_superscript_start()` は上添え字開始指定子を、 `add_superscript_end()` は上添え字終了指定子を、それぞれ 呼ばれた時点での本文の現在位置に挿入します。 メソッドを呼び出すには、あらかじめ本文ファイルを開いていなければ なりません。 成功すれば 1 を、失敗すれば 0 を返します。 使用方法に関しては、 修飾指定子 の節もあわせてご覧下さい。
`add_nowrap_start()`
`add_nowrap_end()`
  `add_nowrap_start()` は分割禁止開始指定子を、 `add_nowrap_end()` は分割禁止終了指定子を、それぞれ呼ばれた 時点での本文の現在位置に挿入します。 メソッドを呼び出すには、あらかじめ本文ファイルを開いていなければ なりません。 成功すれば 1 を、失敗すれば 0 を返します。 使用方法に関しては、 修飾指定子 の節もあわせてご覧下さい。
`add_emphasis_start()`
`add_emphasis_end()`
  `add_emphasis_start()` は強調開始指定子を、 `add_emphasis_end()` は強調終了指定子を、それぞれ呼ばれた 時点での本文の現在位置に挿入します。 メソッドを呼び出すには、あらかじめ本文ファイルを開いていなければ なりません。 成功すれば 1 を、失敗すれば 0 を返します。 使用方法に関しては、 修飾指定子 の節もあわせてご覧下さい。
`add_font_start($font_name)`
`add_font_end()`
  `add_font_start()` は別フォント開始指定子を、 `add_font_end()` は同終了指定子を、それぞれ呼ばれた時点での 本文の現在位置に挿入します。 引数の `$font_name` として有効な値は、`'italic'` (イタリック体を指定) および `'bold'` (ボールド体を指定) の 2 種類です。 メソッドを呼び出すには、あらかじめ本文ファイルを開いていなければ なりません。 成功すれば 1 を、失敗すれば 0 を返します。 使用方法に関しては、 修飾指定子 の節もあわせてご覧下さい。
`add_color_graphic_start($graphic_name)`
`add_color_graphic_end()`
  `add_color_graphic_start()` はカラー図版参照開始指定子を、 `add_color_graphic_end()` は参照終了指定子を、それぞれ 呼ばれた時点での本文の現在位置に挿入します。 参照先のカラー図版名は `$graphic_name` で指定します。 メソッドを呼び出すには、あらかじめ本文ファイルを開いていなければ なりません。 成功すれば 1 を、失敗すれば 0 を返します。 使用方法に関しては、 カラー図版 の節もあわせてご覧下さい。
`file_name()`
  現在開いている本文のファイル名を返します。 本文のファイルを開いていなければ、空の文字列を返します。
`reference_file_name()`
  現在開いている参照情報ファイル名を返します。 参照情報ファイルを開いていなければ、空の文字列を返します。
`tag_file_name()`
  現在開いているタグファイル名を返します。 タグファイルを開いていなければ、空の文字列を返します。
`context_position()`
  現在のコンテキストの先頭位置を返します。 ただし、本文のファイルを開いていない場合は 0 を返します。
`entry_position()`
  現在のエントリの先頭位置を返します。 ただし、本文のファイルを開いていない場合は 0 を返します。
`context_count()`
  現在のコンテキストが、何番目のコンテキストなのかを返します。
`entry_count()`
  現在のエントリが、現在のコンテキストの中で何番目のコンテキストなのかを 返します。
`total_entry_count()`
  現在のエントリが、本文ファイル全体の中で何番目のコンテキストなのかを返 します。
`error_message()`
  このクラスのメソッドを呼び出して、処理結果が失敗に終わった場合 (0 を返してきた場合)、エラーメッセージを返します。 エラーが発生していなければ、空の文字列が返ります。

## `FreePWING::FPWUtils::Heading` クラス

`FreePWING::FPWUtils::Heading` は、見出しを生成するための クラスです。 `FreePWING::FPWUtils::Text` クラスとだいたい同じメソッドを 持っていますが、次のメソッドは使用できなくなっています。

- new_context()
- add_tag()
- add_keyword_start()
- add_keyword_end()
- add_reference_start()
- add_reference_end()
- add_newline()
- add_indent_level()

その他のメソッドの使用方法については、 `FreePWING::FPWUtils::Text` クラス を参照して下さい。

## `FreePWING::FPWUtils::Menu` クラス

`FreePWING::FPWUtils::Menu` は、メニューを生成するための クラスです。 `FreePWING::FPWUtils::Text` とまったく同じメソッド群を 持っています。

## `FreePWING::FPWUtils::Copyright` クラス

`FreePWING::FPWUtils::Copyright` は、著作権表示を生成する ためのクラスです。 `FreePWING::FPWUtils::Text` とまったく同じメソッド群を 持っています。

## `FreePWING::FPWUtils::FPWParser` モジュール

他の FreePWING 付属の Perl モジュールとは異なり、 `FreePWING::FPWUTils::FPWParser` モジュールではクラスを定義 しません。 代わりに、`main` パッケージに対してサブルーチンや変数を定義 し、コマンド行のオプションの解析処理を行います。

### サブルーチン

`FreePWING::FPWUTils::FPWParser` モジュールが定義する サブルーチンには `initialize_fpwparser()` と `finalize_fpwparser()` があります。

`initialize_fpwparser()` は FreePWING 関係のクラスの オブジェクトを初期化するためのサブルーチンで、次のように 2 つの要素を 組にして並べたものを引数にとります。

>     initialize_fpwparser('word2' => \$w, 'text' => \$t);

要素の組はそれぞれ、1 番目の引数には `'word'`, `'endword'` のような名前を示す文字列をとり、2 番目の引数 には変数へのリファレンスを取るようにします。 1 番目のパラメタとして認識される文字列とその用途は、次の通りです。

`word2`
  前方一致、後方一致検索ための検索語の登録用に `FreePWING::FPWUtils::Word2` クラスのオブジェクトを生成し、 初期化します。
`heading`
  見出しデータ登録用に `FreePWING::FPWUtils::Heading` クラス のオブジェクトを生成し、初期化します。
`text`
  本文データ登録用に `FreePWING::FPWUtils::Text` クラスの オブジェクトを生成し、初期化します。
`menu`
  メニューのデータ登録用に `FreePWING::FPWUtils::Text` クラス のオブジェクトを生成し、初期化します。
`copyright`
  著作権表示データ登録用に `FreePWING::FPWUtils::Text` クラス のオブジェクトを生成し、初期化します。

生成して初期化されたオブジェクトは、要素の各組の 2 番目の引数に 参照先としてセットされます。 このサブルーチンは、処理に成功すると 1 を、失敗すると 0 を返します。

`finalize_fpwparser()` は `initialize_fpwparser()` で生成したオブジェクトを 使い終わったときに呼び出すサブルーチンで、各オブジェクトに対して 後処理を行います。 引数の書式は `initialize_fpwparser()` とまったく同じです。 このサブルーチンも、処理に成功すると 1 を、失敗すると 0 を返します。

`initialize_fpwparser()`, `finalize_fpwparser()` の具体的な使用例については fpwutils 対応 をご覧下さい。

### 変数

`FreePWING::FPWUtils::FPWParser` モジュールによって定義 される変数には以下のものがあります。

`$work_directory`
  作業ディレクトリ名
  (コマンド行オプションの解析 を参照 のこと)
`$text_file_name`
  本文を記録するファイル名
  (値: `"$work_directory/text"`)
  通常、`FreePWING::FPWUtils::Word2::add_entry()` を呼び出す 際に、第 2 引数として渡します。
`$text_ref_file_name`
  本文用の参照情報ファイルを記録するファイル名
  (値: `"$work_directory/textref"`)
`$text_tag_file_name`
  本文用のタグファイルを記録するファイル名
  (値: `"$work_directory/texttag"`)
`$menu_file_name`
  メニューを記録するファイル名
  (値: `"$work_directory/menu"`)
`$menu_ref_file_name`
  メニュー用の参照情報ファイルを記録するファイル名
  (値: `"$work_directory/menuref"`)
`$menu_tag_file_name`
  メニュー用のタグファイルを記録するファイル名
  (値: `"$work_directory/menutag"`)
`$copyright_file_name`
  著作権表示を記録するファイル名
  (値: `"$work_directory/copy"`)
`$copyright_ref_file_name`
  著作権表示用の参照情報ファイルを記録するファイル名
  (値: `"$work_directory/copyref"`)
`$copyright_tag_file_name`
  著作権表示用のタグファイルを記録するファイル名
  (値: `"$work_directory/copytag"`)
`$heading_file_name`
  見出しを記録するファイル名
  (値: `"$work_directory/head"`)
  通常、`FreePWING::Word2::add_entry()` を呼び出す際に、 第 3 引数として渡します。
`$word_file_name`
  前方一致検索用の検索語一覧を記録するファイル名
  (値: `"$work_directory/word"`)
`$endword_file_name`
  後方一致検索用の検索語一覧を記録するファイル名
  (値: `"$work_directory/eword"`)
`$sort_file_name`
  前方一致検索用のソート済み検索語一覧を記録するファイル名
  (値: `"$work_directory/sort"`)
`$endsort_file_name`
  後方一致検索用のソート済み検索語一覧を記録するファイル名
  (値: `"$work_directory/esort"`)
`$index_file_name`
  前方一致検索インデックスを記録するファイル名の接頭辞
  (値: `"$work_directory/idx"`)
`$index_ref_file_name`
  前方一致検索インデックス用の参照情報を記録するファイル名の接頭辞
  (値: `"$work_directory/idxref"`)
`$endindex_file_name`
  後方一致検索インデックスを記録するファイル名
  (値: `"$work_directory/eidx"`)
`$endindex_ref_file_name`
  後方一致検索インデックス用の参照情報を記録するファイル名
  (値: `"$work_directory/eidxref"`)
`$control_file_name`
  書籍管理情報を記録するファイル名
  (値: `"$work_directory/ctrl"`)
`$control_ref_file_name`
  書籍管理情報用の参照情報を記録するファイル名
  (値: `"$work_directory/ctrlref"`)
`$honmon_file_name`
  JIS X 4081 形式の最終生成ファイル名
  (値: `"honmon"`)
`$half_char_name_file_name`
  半角外字の名前と文字番号の割り当ての対応表を記録するファイル名
  (値: `"$work_directory/halfchar"`)
`$full_char_name_file_name`
  全角外字の名前と文字番号の割り当ての対応表を記録するファイル名
  (値: `"$work_directory/fullchar"`)
`$half_char_bitmap_16_file_name`
`$half_char_bitmap_24_file_name`
`$half_char_bitmap_30_file_name`
`$half_char_bitmap_48_file_name`
  半角外字のビットマップファイル名
  (値: `"gai16h"`、`"gai24h"`、`"gai30h"`、 `"gai48h"`)
`$full_char_bitmap_16_file_name`
`$full_char_bitmap_24_file_name`
`$full_char_bitmap_30_file_name`
`$full_char_bitmap_48_file_name`
  全角外字のビットマップファイル名
  (値: `"gai16f"`、`"gai24f"`、`"gai30f"`、 `"gai48f"`)

### コマンド行オプションの解析

`FreePWING::FPWUTils::FPWParser` は `Getopt::Long` モジュールを用いてコマンド行オプションの解析 を行います。 この解析処理は、モジュールを読み込みさえすれば自動的に行われますので、 ユーザ側で明示的にサブルーチンを呼ぶ必要はありません。 今のところ、コマンド行オプションには次のものが定義されています。

`-workdir` directory
  作業ディレクトリの位置を指定します。 指定しなければ `'work'` が使われます。 プログラム内では、変数`$work_directory` で参照できます。

解析後、指定されたオプションは `@ARGV` から取り除かれます。 残りの引数をどう解釈するかは、ユーザの処理プログラムに任されます。 未知のオプションが指定された場合はエラーとなり、その時点でプログラムを 強制的に終了します。

### 古い作業ファイルの削除

`FreePWING::FPWUtils::FPWParser` は古い作業ファイルが 作業ディレクトリに残っていると、それを削除します。 削除に失敗しても、エラーとして報告することはしません。

## `fpwmake` コマンド

fpwmake コマンドの実体は sh スクリプトで、中で GNU make を呼び出します。

たとえば、GNU make のコマンド名が `/usr/local/bin/gmake`、 `fpwutils.mk` ファイルがインストールされているディレクトリ が `/usr/local/share/freepwing` だとすると、

>     % fpwmake 引数...

という呼び出しは、実際には

>     % /usr/local/bin/gmake -I/usr/local/share/freepwing 引数...

という処理を手動で実行するのとまったく同じことです。

GNU make について詳しく知りたい方は、GNU make のドキュメントをお読み 下さい。

## `fpwutils.mk` ファイル

`fpwutils.mk` ファイルの中で、いくつかの変数、生成規則を 定義していますが、詳細については `fpwutils.mk` ファイルを 直接ご覧になって下さい。

[前へ] [目次]