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( whitespace)

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

妥当性検査をおこなうパーサは無視可能な空白文字(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 属性の値によっては外部エンティティをスキップすることがあります。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。