##
13.10.1 ContentHandler オブジェクト

`ContentHandler` はアプリケーション側でサブクラス化して利用する ことが前提になっています。パーサは入力ドキュメントのイベントにより、そ れぞれに対応する以下のメソッドを呼び出します。

`setDocumentLocator`( | locator)

  アプリケーションにドキュメント・イベントの発生位置を通知するためにパー サから呼び出されます。

  SAX パーサによるロケータの提供は強く推奨されています(必須ではありま せん)。もし提供する場合は、DocumentHandler インターフェースのどのメ ソッドよりも先にこのメソッドが呼び出されるようにしなければなりません。

  アプリケーションはパーサがエラーを通知しない場合でもロケータによって、 すべてのドキュメント関連イベントの終了位置を知ることが可能になります。 典型的な利用方法としては、アプリケーション側でこの情報を使い独自のエ ラーを発生させること(文字コンテンツがアプリケーション側で決めた規則 に沿っていない場合等)があげられます。しかしロケータが返す情報は検索 エンジンなどで利用するものとしてはおそらく不充分でしょう。

  ロケータが正しい情報を返すのは、インターフェースからイベントの呼出し が実行されている間だけです。それ以外のときは使用すべきでありません。

`startDocument`( | )

  ドキュメントの開始通知を受け取ります。

  SAX パーサはこのインターフェースやDTDHandler のどのメソッド (`setDocumentLocator()`を除く)よりも先にこのメソッドを一度だ け呼び出します。

`endDocument`( | )

  ドキュメントの終了通知を受け取ります。

  SAX パーサはこのメソッドを一度だけ、パース過程の最後に呼び出します。 パーサは(回復不能なエラーで)パース処理を中断するか、あるいは入力の 最後に到達するまでこのメソッドを呼び出しません。

`startPrefixMapping`( | prefix, uri)

  プリフィックスと URI の名前空間の関連付けを開始します。

  このイベントから返る情報は通常の名前空間処理では使われません。SAX XML リーダは `feature_namespaces` 機能が有効になっている場合(デ フォルト)、要素と属性名のプリフィックスを自動的に置換するようになっ ています。

  しかしアプリケーション側でプリフィックスを文字データや属性値の中で扱 う必要が生じることもあります。この場合プリフィックスの自動展開は保証 されないため、必要に応じ `startPrefixMapping()` や `endPrefixMapping()` イベントからアプリケーションに提供される 情報を用いてプリフィックスの展開をおこないます。

  `startPrefixMapping()` と `endPrefixMapping()` イベン トは相互に正しい入れ子関係になることが保証されていないので注意が必要 です。すべての `startPrefixMapping()` は対応する `startElement()` の前に発生し、`endPrefixMapping()` イ ベントは対応する `endElement()` の後で発生しますが、その順序 は保証されていません。

`endPrefixMapping`( | prefix)

  プリフィックスと URI の名前空間の関連付けを終了します。

  詳しくは `startPrefixMapping()` を参照してください。このイベ ントは常に対応する `endElement()` の後で発生しますが、複数の `endPrefixMapping()` イベントの順序は特に保証されません。

`startElement`( | name, attrs)

  非名前空間モードで要素の開始を通知します。

  name パラーメータには要素型の raw XML 1.0名を文字列として、 attrs パラメータには要素の属性を保持する `Attributes` インターフェース オブジェクトをそれぞれ指定します。attrs として渡されたオブジェ クトはパーサで再利用することも可能ですが、属性のコピーを保持するた めにこれを参照し続けるのは確実な方法ではありません。属性のコピーを保 持したいときは attrs オブジェクトの `copy()` メソッドを 用いてください。

`endElement`( | name)

  非名前空間モードで要素の終了を通知します。

  name パラメータには `startElement()` イベント同様の要素 型名を指定します。

`startElementNS`( | name, qname, attrs)

  名前空間モードで要素の開始を通知します。

  name パラーメータには要素型を `(uri, localname)` のタプルとして、qname パラメータにはソース・ ドキュメントで用いられている raw XML 1.0名、attrs には要素の属 性を保持する `AttributesNS` インターフェース のインスタンスをそれぞれ指定します。要 素に関連付けられた名前空間がないときは、name コンポーネントの uri が `None` になります。attrs として渡されたオブジェ クトはパーサで再利用することも可能ですが、属性のコピーを保持するた めにこれを参照し続けるのは確実な方法ではありません。属性のコピーを保 持したいときは attrs オブジェクトの `copy()` メソッドを 用いてください。

  `feature_namespace_prefixes` 機能が有効になっていなければ、パー サで qname を `None` にセットすることも可能です。

`endElementNS`( | name, qname)

  非名前空間モードで要素の終了を通知します。

  name パラメータには `startElementNS()` イベント同様の要素 型を指定します。qname パラメータも同じです。

`characters`( | content)

  文字データの通知を受け取ります。

  パーサは文字データのチャンクごとにこのメソッドを呼び出して通知します。 SAX パーサは一連の文字データを単一のチャンクとして返す場合と複数のチャ ンクに分けて返す場合がありますが、ロケータの情報が正しく保たれるよう に、一つのイベントの文字データは常に同じ外部エンティティのものでなけ ればなりません。

  content はユニコード文字列、バイト文字列のどちらでもかまいませ んが、`expat` リーダ・モジュールは常にユニコード文字列を生成す るようになっています。

  注意: Python XML SIG が提供していた初期 SAX 1 では、このメソッドにもっ と JAVA 風のインターフェースが用いられています。しかし Python で採用 されている大半のパーサでは古いインターフェースを有効に使うことができ ないため、よりシンプルなものに変更されました。古いコードを新しいイン ターフェースに変更するには、古い offset と length パラメー タでスライスせずに、content を指定するようにしてください。

`ignorableWhitespace`( | )

  要素コンテンツに含まれる無視可能な空白文字の通知を受け取ります。

  妥当性検査をおこなうパーサは無視可能な空白文字(W3C XML 1.0 勧告のセ クション 2.10 参照)のチャンクごとに、このメソッドを使って通知しなけ ればなりません。妥当性検査をしないパーサもコンテンツモデルの利用とパー スが可能な場合、このメソッドを利用することが可能です。

  SAX パーサは一連の空白文字を単一のチャンクとして返す場合と複数のチャ ンクに分けて返す場合がありますが、ロケータの情報が正しく保たれるよう に、一つのイベントの文字データは常に同じ外部エンティティのものでなけ ればなりません。

`processingInstruction`( | target, data)

  処理命令の通知を受け取ります。

  パーサは処理命令が見つかるたびにこのメソッドを呼び出します。処理命令 はメインのドキュメント要素の前や後にも発生することがあるので注意して ください。

  SAX パーサがこのメソッドを使って XML 宣言(XML 1.0 のセクション 2.8)や テキスト宣言(XML 1.0 のセクション 4.3.1)の通知をすることはありません。

`skippedEntity`( | name)

  スキップしたエンティティの通知を受け取ります。

  パーサはエンティティをスキップするたびにこのメソッドを呼び出します。 妥当性検査をしないプロセッサは(外部 DTD サブセットで宣言されているな どの理由で)宣言が見当たらないエンティティをスキップします。すべての プロセッサは `feature_external_ges` および `feature_external_pes` 属性の値によっては外部エンティティをスキッ プすることがあります。