PLISAXC の SAX イベント構造の説明

イベント構造には、19 個の ENTRY 変数があります。これらの変数は、さまざまなイベントでパーサーが呼び出す関数をポイントしています。

このトピックの各イベントの説明は、次の XML ドキュメントの例を参照しています。

xmlDocument =
   '<?xml version="1.0" standalone="yes"?>'
|| '<!--This document is just an example-->'
|| '<sandwich>'
|| '<bread type="baker&quot;s best"/>'
|| '<?spread please use real mayonnaise ?>'
|| '<meat>Ham &amp; turkey</meat>'
|| '<filling>Cheese, lettuce, tomato, etc.</filling>'
|| 'We should add a <relish> element in future!'
|| '</sandwich>'
|| 'junk';

説明の中の XML テキストという用語は、イベントに渡されるポインターおよび長さに基づいて構成された文字列です。この構造体での出現順に、パーサーは次のイベントを認識することができます。

start_of_document

ドキュメントの構文解析が開始されるときに、1 回発生します。パーサーは、このイベントにはパラメーターを渡しません (ユーザートークンを除く)。

version_information

オプションの XML 宣言内のバージョン情報に対して発生します。パーサーは、バージョン値 (上記の例では "1.0") が入ったテキストのアドレスと長さを渡します。

encoding_declaration

XML 宣言内のオプションのエンコーディング宣言に対して発生します。パーサーは、エンコーディング値が含まれたテキストのアドレスと長さを渡します。

standalone_declaration

XML 宣言内のオプションのスタンドアロン宣言に対して発生します。パーサーは、スタンドアロン値 (上記の例では "yes") が入ったテキストのアドレスと長さを渡します。

document_type_declaration

パーサーがドキュメントタイプ宣言を検出したときに発生します。ドキュメントタイプ宣言は、文字シーケンス <!DOCTYPE" から始まり、> 文字で終わります。この間には、内容を記述するやや複雑な文法規則が入ります。

パーサーは、宣言全体が含まれたテキストのアドレスと長さを渡します。これには、開始と終了の文字シーケンスが含まれます。このイベントは、XML テキストに区切り文字が含まれる唯一のイベントです。上記の例には、ドキュメントタイプ宣言はありません。

end_of_document

ドキュメントの構文解析が完了したときに 1 回発生します。パーサーは、このイベントにはパラメーターを渡しません (ユーザートークンを除く)。

start_of_element

エレメント開始タグまたは空エレメントタグごとに 1 回発生します。パーサーは、エレメント名および該当するネームスペース情報を含んでいるテキストのアドレスと長さを渡します。上記の例では、構文解析で最初に発生する start_of_element イベントに、文字列 sandwich が含まれています。

attribute_name

エレメント開始タグまたは空エレメントタグ内の属性ごとに、有効な名前を認識した後に発生します。パーサーは、属性名および該当するネームスペース情報を含んでいるテキストのアドレスと長さを渡します。上記の例に含まれる属性名は、type だけです。

attribute_characters

属性値のフラグメントごとに発生します。パーサーは、フラグメントが含まれたテキストのアドレスと長さを渡します。属性値は通常、次のように複数の行に分割されている場合でも、ただ 1 つの文字列で構成されます。

<element attribute="This attribute value is
split across two lines"/>

end_of_element

エレメント終了タグまたは空エレメントタグごとに、パーサーがタグの終了不等号かっこを認識したときに 1 回発生します。パーサーは、エレメント名および該当するネームスペース情報を含んでいるテキストのアドレスと長さを渡します。

start_of_CDATA_section

CDATA セクションの開始時に発生します。CDATA セクションは文字列 <![CDATA[ で始まり、文字列 ]] で終わります。これは、XML マークアップとして認識される文字を含むテキストのブロックをエスケープするために使用します。パーサーは、このイベントにはパラメーターを渡しません (ユーザートークンを除く)。

このイベントの後で、パーサーはこれらの区切り文字間にある CDATA セクションの内容を、1 つまたは複数の content-characters イベントとして渡します。上記の例では、content-characters イベントとしてWe should add a <relish> element in future! が渡されます。

end_of_CDATA_section

パーサーが CDATA セクションの終了を認識したときに発生します。パーサーは、このイベントにはパラメーターを渡しません (ユーザートークンを除く)。

content_characters

このイベントは、XML ドキュメントの本体を表します。これは、エレメント開始タグとエレメント終了タグの間にある文字データです。パーサーは、このデータが含まれたテキストのアドレスと長さを渡します。これは、次のように複数の行に分割されている場合でも、ただ 1 つの文字列で構成されます。

<element1>This character content is
split across two lines"</element1>

パーサーは、次のイベントによって内容の一部を構成する他の文字が提供されるかどうかを示す、フラグバイトも渡します。開始と終了のタグ間に多くのデータがあるときが、これに該当します。

また、パーサーは content_characters イベントを使用して CDATA セクションのテキストをアプリケーションに渡します。

processing_instruction

処理命令 (Processing Instruction; PI) を使用すると、XML ドキュメントにアプリケーション用の特別な命令を含めることができます。このイベントは、パーサーが PI 開始文字シーケンス <? に続く名前を認識したときに発生します。また、このイベントは、PI ターゲットに続く PI 終了文字シーケンス ?> までのデータ (?> 自体は含まない) も対象とします。データの末尾にある空白文字は含まれますが、先頭にある空白文字は含まれません。パーサーは、ターゲットが含まれるテキスト (上記の例では spread) のアドレスと長さ、およびデータが入ったテキスト (上記の例では please use real mayonnaise) のアドレスと長さを渡します。

comment

XML ドキュメント内のコメントに対して発生します。パーサーは、開始および終了コメント区切り文字 (それぞれ ) の間にあるテキストのアドレスと長さを渡します。上記の例では、This document is just an example だけがコメントのテキストです。

namespace_declare

XML ドキュメントのすべてのネームスペース宣言に発生します。パーサーは、ネームスペースプレフィックス (ある場合) のアドレスと長さ、およびネームスペース URI のアドレスと長さを渡します。ネームスペースプレフィックスがない場合、渡される長さはゼロでアドレスの値は使用されません。PLIXSAXA と PLISAXB ビルトインには、対応するイベントはありません。

end_of_input

このイベントは、パーサーが現在の入力バッファーの終わりに達すると発生します。パーサーは、(BYVALUE ユーザートークンとともに) 2 つの BYADDR パラメーター、つまり次のバッファーのアドレスと長さを渡し、処理されるようにします。BYADDR パラメーターを持つイベントは、このイベントとコンテンツ文字イベントに限られますが、このイベントは呼び出されたイベントによって変更されるパラメーターを持つ唯一のイベントです。PLIXSAXA と PLISAXB ビルトインには対応するイベントはなく、このイベントが PLISAXC による任意サイズの XML ドキュメントの解析を許可するイベントです。

unresolved_reference

このイベントは、XML ドキュメントですべての未解決リファレンスに発生します。パーサーは、未解決リファレンスのアドレスと長さを渡します。

unknown_attribute_reference

属性値の中で、定義済みエンティティ参照 (イベント attribute_predefined_reference の説明で示したもの) 以外のエンティティ参照に対して発生します。パーサーは、エンティティ名が含まれたテキストのアドレスと長さを渡します。

exception

XML ドキュメントの処理中にエラーを検出すると、パーサーはこのイベントを生成します。