##
13.5.1 XMLParser Objects

`xmlparser` オブジェクトは以下のようなメソッドを持ちます。

`Parse`( | data[, isfinal])

  文字列 data の内容を解析し、解析されたデータを処理するための 適切な関数を呼び出します。このメソッドを最後に呼び出す時は isfinal を真にしなければなりません。 data は空の文字列を取ることもできます。

`ParseFile`( | file)

  file オブジェクトから読み込んだXMLデータを解析します。 file には `read(nbytes)` メソッドのみが必要です。 このメソッドはデータなくなった場合に空文字列を返さねばなりません。。

`SetBase`( | base)

  (XML) 宣言中のシステム識別子中の相対 URI を解決するための、 基底 URI を設定します。相対識別子の解決はアプリケーションに 任されます: この値は関数 `ExternalEntityRefHandler` や `NotationDeclHandler`、`UnparsedEntityDeclHandler` に引数 base としてそのまま渡されます。

`GetBase`( | )

  以前の `SetBase()` によって設定された基底 URI を文字列の形で 返します。`SetBase()`が呼ばれていないときには `None` を 返します。

`GetInputContext`( | )

  現在のイベントを発生させた入力データを文字列として返します。 データはテキストの入っているエンティティが持っているエンコードに なります。 イベントハンドラがアクティブでないときに呼ばれると、戻り値は `None`となります。 バージョン2.1 以降で新規追加された 仕様です。

`ExternalEntityParserCreate`( | context[, encoding])

  親となるパーザで解析された内容が参照している、外部で解析される エンティティを解析するために使える ``子の'' パーザを作成します。 context パラメータは、以下に記すように `ExternalEntityRefHandler()` ハンドラ関数に渡される文字列でなければなりません。子のパーザは `ordered_attributes`、`returns_unicode`、 `specified_attributes` が現在のパーザの値に設定されて 生成されます。

`xmlparser` オブジェクトは次のような属性を持ちます:

`buffer_size`
  `buffer_text` が真の時に使われるバッファのサイズです。 この値は変更できません。 バージョン2.3 以降で新規追加された 仕様です。

`buffer_text`
  この値を真にすると、`xmlparser` オブジェクトが Expatから返された もとの内容をバッファに保持するようになります。これにより可能なときに 何度も `CharacterDataHandler()` を呼び出してしまうようなことを 避けることができます。Expatは通常、文字列のデータを行末ごと大量に破棄 するため、かなりパフォーマンスを改善できるはずです。この属性はデフォルト では偽で、いつでも変更可能です。 バージョン2.3 以降で新規追加された 仕様です。

`buffer_used`
  `buffer_text` が利用可能なとき、バッファに保持されたバイト数です。 これらのバイトはUTF-8でエンコードされたテキストを表します。この属性は `buffer_text` が偽の時には意味がありません。 バージョン2.3 以降で新規追加された 仕様です。

`ordered_attributes`
  この属性をゼロ以外の整数にすると、報告される(XMLノードの) 属性を 辞書型ではなくリスト型にします。属性は文書のテキスト中の出現順で示されます。 それぞれの属性は、2つのリストのエントリ: 属性名とその値、が与えられます。 (このモジュールの古いバージョンでも、同じフォーマットが使われています。) デフォルトでは、この属性はデフォルトでは偽となりますが、 いつでも変更可能です。 バージョン2.1 以降で新規追加された 仕様です。

`returns_unicode`
  この属性をゼロ以外の整数にすると、ハンドラ関数に Unicode 文字列が 渡されます。 `returns_unicode` が 0 の時には、UTF-8でエンコード されたデータを含む 8 ビット文字列がハンドラに渡されます。 バージョン1.6 以降で変更された 仕様: 戻り値の型がいつでも変更できるように変更されたはずです

`specified_attributes`
  ゼロ以外の整数にすると、パーザは文書のインスタンスで特定される 属性だけを報告し、属性宣言から導出された属性は報告しないようになります。 この属性が指定されたアプリケーションでは、XMLプロセッサの振る舞いに 関する標準に従うために必要とされる (文書型) 宣言によって、どのような 付加情報が利用できるのかということについて特に注意を払わなければなりません。 デフォルトで、この属性は偽となりますが、いつでも変更可能です。 バージョン2.1 以降で新規追加された 仕様です。

以下の属性には、 `xmlparser` オブジェクトで最も最近に起きた エラーに関する値が入っており、また `Parse()` または `ParseFile()`メソッドが `xml.parsers.expat.ExpatError` 例外を送出した際にのみ正しい値となります。

`ErrorByteIndex`
  エラーが発生したバイトのインデクスです。

`ErrorCode`
  エラーを特定する数値によるコードです。この値は`ErrorString()` に 渡したり、 `errors` オブジェクトで定義された内容と比較できます。

`ErrorColumnNumber`
  エラーの発生したカラム番号です。

`ErrorLineNumber`
  エラーの発生した行番号です。

以下に指定可能なハンドラのリストを示します。 `xmlparser` オブジェクト o に ハンドラを指定するには、`o.handlername = func` を使用します。 handlername は、以下のリストに挙げた値をとらねば ならず、また func は正しい数の引数を受理する呼び出し可能な オブジェクトでなければなりません。引数は特に明記しない限り、すべて 文字列となります。

`XmlDeclHandler`( | version, encoding, standalone)

  XML 宣言が解析された時に呼ばれます。XML宣言とは、XML勧告の適用 バージョン (オプション)、文書テキストのエンコード、そしてオプションの ``スタンドアロン'' の宣言です。 version と encoding は `returns_unicode` 属性によって指示された型を示す文字列となり、 standalone は、文書がスタンドアロンであると宣言される場合には `1`に、文書がスタンドアロンでない場合には `0` に、 スタンドアロン宣言を省略する場合には `-1` になります。 このハンドラは Expat のバージョン1.95.0以降のみ使用できます。 バージョン2.1 以降で新規追加された 仕様です。

`StartDoctypeDeclHandler`( | doctypeName, systemId, publicId, has_internal_subset)

  Expatが文書型宣言`<!DOCTYPE ...`)を解析し始めたときに 呼び出されます。doctypeName は、与えられた値がそのまま Expat に提供されます。systemId と publicId パラメタが 指定されている場合、それぞれシステムと公開識別子を与えます。 省略する時には`None` にします。文書が内部的な文書宣言のサブセット (internal document declaration subset) を持つか、サブセット自体の 場合、has_internal_subset は true になります。 このハンドラには、Expat version 1.2以上が必要です。

`EndDoctypeDeclHandler`( | )

  Expatが文書型宣言の解析を終えたときに呼び出されます。 このハンドラには、Expat version 1.2以上が必要です。

`ElementDeclHandler`( | name, model)

  それぞれの要素型宣言ごとに呼び出されます。nameは要素型の名前であり、 model は内容モデル (content model) の表現です。

`AttlistDeclHandler`( | elname, attname, type, default, required)

  ひとつの要素型で宣言される属性ごとに呼び出されます。属性リストの宣言が 3つの属性を宣言したとすると、このハンドラはひとつの属性に1度づつ、 3度呼び出されます。 elname は要素名であり、これに対して宣言が適用され、attnameが 宣言された属性名となります。 属性型は文字列で、type として渡され ます; 取りえる値は、`'CDATA'`, `'ID'`,`'IDREF'`, ... です。 defaultは、属性が文書のインスタンスによって指定されていないときに 使用されるデフォルト値を与えます。デフォルト値(`#IMPLIED` values)が 存在しないときには`None`を与えます。文書のインスタンスによって属性値が 与えられる必要のあるときにはrequiredがtrueになります。 このメソッドはExpat version 1.95.0 以上が必要です。

`StartElementHandler`( | name, attributes)

  要素の開始を処理するごとに呼び出されます。name は要素名を格納した 文字列で、attributes はその値に属性名を対応付ける辞書型です。

`EndElementHandler`( | name)

  要素の終端を処理するごとに呼び出されます。

`ProcessingInstructionHandler`( | target, data)

  Called for every processing instruction. 処理命令を処理するごとに呼び出されます。

`CharacterDataHandler`( | data)

  文字データを処理するときに呼びだされます。このハンドラは通常の文字データ、 CDATAセクション、無視できる空白文字列のために呼び出されます。 これらを識別しなければならないアプリケーションは、要求された情報を 収集するために `StartCdataSectionHandler`, `EndCdataSectionHandler`, and `ElementDeclHandler`コールバックメソッドを使用できます。

`UnparsedEntityDeclHandler`( | entityName, base, systemId, publicId, notationName)

  解析されていない (NDATA) エンティティ宣言を処理するために呼び出されます。 このハンドラは Expat ライブラリのバージョン1.2のためだけに存在します; より最近のバージョンでは、 代わりに`EntityDeclHandler`を使用してください (根底にある Expat ライブラリ内の関数は、撤廃されたものであると宣言されています)。

`EntityDeclHandler`( | entityName, is_parameter_entity, value, base, systemId, publicId, notationName)

  エンティティ宣言ごとに呼び出されます。パラメタと内部エンティティに ついて、value はエンティティ宣言の宣言済みの内容を与える文字列 となります; 外部エンティティの時には`None` となります。解析済み エンティティの場合、notationName パラメタは `None` となり、 解析されていないエンティティの時には記法 (notation) 名となります。 is_parameter_entity は、エンティティがパラメタエンティティの 場合真に、一般エンティティ (general entitiy) の場合には偽になります (ほとんどのアプリケーションでは、一般エンティティのことしか気に する必要がありません)。 このハンドラは Expat ライブラリのバージョン1.95.0 以降でのみ使用できます。 バージョン2.1 以降で新規追加された 仕様です。

`NotationDeclHandler`( | notationName, base, systemId, publicId)

  記法の宣言 (notation declaration) で呼び出されます。 notationName, base, systemId, および publicId を与える場合、文字列にします。public な識別子が省略された場合、 publicId は `None` になります。

`StartNamespaceDeclHandler`( | prefix, uri)

  要素が名前空間宣言を含んでいる場合に呼び出されます。名前空間宣言は、 宣言が配置されている要素に対して `StartElementHandler` が 呼び出される前に処理されます。

`EndNamespaceDeclHandler`( | prefix)

  名前空間宣言を含んでいたエレメントの終了タグに到達したときに 呼び出されます。このハンドラは、要素に関する名前空間宣言ごとに、 `StartNamespaceDeclHandler` とは逆の順番で一度だけ呼び 出され、各名前空間宣言のスコープが開始されたことを示します。 このハンドラは、要素が終了する際、対応する `EndElementHandler` が呼ばれた後に呼び出されます。

`CommentHandler`( | data)

  コメントで呼び出されます。data はコメントのテキストで、 先頭の ``<!-``-`' と末尾の ``-``->`' を除きます。

`StartCdataSectionHandler`( | )

  CDATA セクションの開始時に呼び出されます。CDATA セクションの 構文的な開始と終了位置を識別できるようにするには、このハンドラと `StartCdataSectionHandler` が必要です。

`EndCdataSectionHandler`( | )

  CDATA セクションの終了時に呼び出されます。

`DefaultHandler`( | data)

  XML 文書中で、適用可能なハンドラが指定されていない 文字すべてに対して呼び出されます。この文字とは、検出されたことが 報告されるが、ハンドラは指定されていないような コンストラクト (construct) の一部である文字を意味します。

`DefaultHandlerExpand`( | data)

  `DefaultHandler` と同じですが、内部エンティティの 展開を禁止しません。エンティティ参照はデフォルトハンドラに 渡されません。

`NotStandaloneHandler`( | )

  XML 文書がスタンドアロンの文書として宣言されていない場合に呼び出されます。 外部サブセットやパラメタエンティティへの参照が存在するが、XML 宣言が XML 宣言中で standalone 変数を `yes` に設定していない場合に 起きます。このハンドラが `0` を返すと、パーザは `XML_ERROR_NOT_STANDALONE` を送出します。 このハンドラが設定されていなければ、パーザは前述の事態で 例外を送出しません。

`ExternalEntityRefHandler`( | context, base, systemId, publicId)

  外部エンティティの参照時に呼び出されます。base は現在の基底 (base) で、以前の `SetBase()` で設定された値になっています。 public、および system の識別子である、systemId とpublicId が指定されている場合、値は文字列です; public 識別子が指定されていない 場合、 publicId は `None` になります。 context の値は不明瞭なものであり、以下に記述するようにしか 使ってはなりません。

  外部エンティティが解析されるようにするには、このハンドラを実装 しなければなりません。このハンドラは、 `ExternalEntityParserCreate(context)` を使って 適切なコールバックを指定し、子パーザを生成して、 エンティティを解析する役割を担います。このハンドラは整数を 返さねばなりません; `0` を返した場合、パーザは `XML_ERROR_EXTERNAL_ENTITY_HANDLING` エラーを送出します。 そうでないばあい、解析を継続します。

  このハンドラが与えられておらず、 `DefaultHandler` コールバックが指定されていれば、 外部エンティティは`DefaultHandler` で報告されます。