\section{\module{xml.sax.xmlreader} ---
         XML パーサのインターフェース}

\declaremodule{standard}{xml.sax.xmlreader}
\modulesynopsis{SAX 準拠の XML パーサが実装すべきインターフェースです。}
\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
\moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no}

\versionadded{2.0}

各 SAX パーサは Python モジュールとして \class{XMLReader} インターフェー
スを実装しており、関数 \function{create_parser()} を提供しています。こ
の関数は新たなパーサ・オブジェクトを生成する際、
\function{xml.sax.make_parser()} から引き数なしで呼び出されます。

\begin{classdesc}{XMLReader}{}
  SAX パーサが継承可能な基底クラスです。
\end{classdesc}

\begin{classdesc}{IncrementalParser}{}

  入力ソースをパースする際、すべてを一気に処理しないで、途中でドキュメ
  ントのチャンクを取得したいことがあります。SAX リーダは通常、ファイル
  全体を一気に読み込まずチャンク単位で処理するのですが、全体の処理が終
  わるまで \method{parse()} は return しません。つまり、
  IncrementalParser インターフェースは \method{parse()} にこのような排
  他的挙動を望まないときに使われます。

  パーサのインスタンスが作成されると、feed メソッドを通じてすぐに、デー
  タを受け入れられるようになります。close メソッドの呼出しでパースが終
  わると、パーサは新しいデータを受け入れられるように、reset メソッドを
  呼び出されなければなりません。

  これらのメソッドをパース処理の途中で呼び出すことはできません。つまり、
  パースが実行された後で、パーサから return する前に呼び出す必要がある
  のです。

  なお、SAX 2.0 ドライバを書く人のために、XMLReader インターフェースの 
  parse メソッドがデフォルトで、IncrementalParser の feed、close、
  reset メソッドを使って実装されています。

\end{classdesc}

\begin{classdesc}{Locator}{}

  SAX イベントとドキュメントの位置を関連付けるインターフェースです。
  locator オブジェクトは DocumentHandler メソッドを呼び出している間
  だけ正しい情報を返し、それ以外とのときに呼び出すと、予測できない結果
  が返ります。情報を取得できない場合、メソッドは \code{None} を返すこ
  ともあります。

\end{classdesc}

\begin{classdesc}{InputSource}{\optional{systemId}}
  \class{XMLReader} がエンティティを読み込むために必要な情報をカプセ
  ル化します。

  このクラスには公開識別子、システム識別子、(場合によっては文字エンコー
  ディング情報を含む)バイト・ストリーム、そしてエンティティの文字スト
  リームなどの情報が含まれます。

  アプリケーションは \method{XMLReader.parse()} メソッドに渡す引き数、
  または EntityResolver.resolveEntity の戻り値としてこのオブジェトを作
  成します。

  \class{InputSource} はアプリケーション側に属します。
  \class{XMLReader} はアプリケーションから渡された \class{InputSource} 
  オブジェクトの変更を許していませんが、コピーを作り、それを変更するこ
  とは可能です。
\end{classdesc}

\begin{classdesc}{AttributesImpl}{attrs}
  \ulink{\class{Attributes} interface}{attributes-objects.html}
  (~\ref{attributes-objects} 参照)の実装です。辞書風のオブジェクトで、
  \method{startElement()} 内で要素の属性表示をおこないます。多くの辞書
  風オブジェクト操作に加え、ほかにもインターフェースに記述されているメ
  ソッドを、多数サポートしています。このクラスのオブジェクトはリーダ
  によってインスタンスを作成しなければなりません。また、\var{attrs} は 
  属性名と属性値を含む辞書風オブジェクトでなければなりません。
\end{classdesc}

\begin{classdesc}{AttributesNSImpl}{attrs, qnames}
  \class{AttributesImpl} を名前空間認識型に改良したクラスで、
  \method{startElementNS()} に渡されます。\class{AttributesImpl} の派
  生クラスですが、\var{namespaceURI} と \var{localname}、この2つのタプ
  ルを解釈します。さらに、元のドキュメントに出てくる修飾名を返す多くの
  メソッドを提供します。このクラスは \ulink{\class{AttributesNS}
  interface}{attributes-ns-objects.html} (
  section~\ref{attributes-ns-objects} 参照) の実装です。
\end{classdesc}


\subsection{XMLReader オブジェクト \label{xmlreader-objects}}

\class{XMLReader} は次のメソッドをサポートします。:

\begin{methoddesc}[XMLReader]{parse}{source}
  入力ソースを処理し、SAX イベントを発生させます。\var{source} オブジェ
  クトにはシステム識別子(入力ソースを特定する文字列 -- 一般にファイル
  名やURL)、ファイル風オブジェクト、または \class{InputSource} オブジェ
  クトを指定できます。\method{parse()} から return された段階で、入力
  データの処理は完了、パーサ・オブジェクトは破棄ないしリセットされます。
  なお、現在の実装はバイト・ストリームのみをサポートしており、文字スト
  リームの処理は将来の課題になっています。
\end{methoddesc}

\begin{methoddesc}[XMLReader]{getContentHandler}{}
  現在の \class{ContentHandler} を返します。
\end{methoddesc}

\begin{methoddesc}[XMLReader]{setContentHandler}{handler}
  現在の \class{ContentHandler} をセットします。\class{ContentHandler} 
  がセットされていない場合、コンテント・イベントは破棄されます。
\end{methoddesc}

\begin{methoddesc}[XMLReader]{getDTDHandler}{}
  現在の \class{DTDHandler} を返します。
\end{methoddesc}

\begin{methoddesc}[XMLReader]{setDTDHandler}{handler}
  現在の \class{DTDHandler} をセットします。\class{DTDHandler} がセッ
  トされていない場合、DTD イベントは破棄されます。
\end{methoddesc}

\begin{methoddesc}[XMLReader]{getEntityResolver}{}
  現在の \class{EntityResolver} を返します。
\end{methoddesc}

\begin{methoddesc}[XMLReader]{setEntityResolver}{handler}
  現在の \class{EntityResolver} をセットします。\class{EntityResolver} 
  がセットされていない場合、外部エンティティとして解決されるべきものが、
  システム識別子として解釈されてしまうため、該当するものがなければ結果
  的にエラーとなります。
\end{methoddesc}

\begin{methoddesc}[XMLReader]{getErrorHandler}{}
  現在の \class{ErrorHandler} を返します。
\end{methoddesc}

\begin{methoddesc}[XMLReader]{setErrorHandler}{handler}
  現在のエラー・ハンドラをセットします。\class{ErrorHandler} がセット
  されていない場合、エラーは例外を発生し、警告が表示されます。
\end{methoddesc}

\begin{methoddesc}[XMLReader]{setLocale}{locale}
  アプリケーションにエラーや警告のロカール設定を許可します。

  SAX パーサにとって、エラーや警告の地域化は必須ではありません。しかし、
  パーサは要求されたロカールをサポートしていない場合、SAX 例外を発生さ
  せなければなりません。アプリケーションはパースの途中でロカールを変更
  することもできます。
\end{methoddesc}

\begin{methoddesc}[XMLReader]{getFeature}{featurename}
  機能 \var{featurename} の現在の設定を返します。その機能が認識できな
  いときは、\exception{SAXNotRecognizedException} を発生させます。広く
  使われている機能名の一覧はモジュール \module{xml.sax.handler} に書か
  れています。
\end{methoddesc}

\begin{methoddesc}[XMLReader]{setFeature}{featurename, value}
  機能名 \var{featurename} に値 \var{value} をセットします。その機能が
  認識できないときは、\exception{SAXNotRecognizedException} を発生させ
  ます。また、パーサが指定された機能や設定をサポートしていないとき
  は、\var{SAXNotSupportedException} を発生させます。
\end{methoddesc}

\begin{methoddesc}[XMLReader]{getProperty}{propertyname}
  属性名 \var{propertyname} の現在の値を返します。その属性が認識でき
  ないときは、 \exception{SAXNotRecognizedException} を発生させます。
  広く使われている属性名の一覧はモジュール \module{xml.sax.handler} に
  書かれています。
\end{methoddesc}

\begin{methoddesc}[XMLReader]{setProperty}{propertyname, value}
  属性名 \var{propertyname} に値 \var{value} をセットします。その機能
  が認識できないときは、\exception{SAXNotRecognizedException} を発生さ
  せます。また、パーサが指定された機能や設定をサポートしていないときは、
  \var{SAXNotSupportedException} is raised を発生させます。
\end{methoddesc}


\subsection{IncrementalParser オブジェクト
            \label{incremental-parser-objects}}

\class{IncrementalParser} のインスタンスは次の追加メソッドを提供します。:

\begin{methoddesc}[IncrementalParser]{feed}{data}
  \var{data} のチャンクを処理します。
\end{methoddesc}

\begin{methoddesc}[IncrementalParser]{close}{}
  ドキュメントの終わりを決定します。終わりに達した時点でドキュメントが
  整形式であるかどうかを判別、ハンドラを起動後、パース時に使用した資源
  を解放します。
\end{methoddesc}

\begin{methoddesc}[IncrementalParser]{reset}{}
  このメソッドは close が呼び出された後、次のドキュメントをパース可能
  にするため、パーサのリセットするのに呼び出されます。close 後、reset 
  を呼び出さずに parse や feed を呼び出した場合の戻り値は未定義です。
\end{methoddesc}


\subsection{Locator オブジェクト \label{locator-objects}}

\class{Locator} のインスタンスは次のメソッドを提供します。:

\begin{methoddesc}[Locator]{getColumnNumber}{}
  現在のイベントが終了する列番号を返します。
\end{methoddesc}

\begin{methoddesc}[Locator]{getLineNumber}{}
  現在のイベントが終了する行番号を返します。
\end{methoddesc}

\begin{methoddesc}[Locator]{getPublicId}{}
  
\end{methoddesc}
  現在の文書イベントの公開識別子を返します。
\begin{methoddesc}[Locator]{getSystemId}{}
  現在のイベントのシステム識別子を返します。
\end{methoddesc}


\subsection{InputSource オブジェクト \label{input-source-objects}}

\begin{methoddesc}[InputSource]{setPublicId}{id}
  この \class{InputSource} の公開識別子をセットします。
\end{methoddesc}

\begin{methoddesc}[InputSource]{getPublicId}{}
  この \class{InputSource} の公開識別子を返します。
\end{methoddesc}

\begin{methoddesc}[InputSource]{setSystemId}{id}
  この \class{InputSource} のシステム識別子をセットします。
\end{methoddesc}

\begin{methoddesc}[InputSource]{getSystemId}{}
  この \class{InputSource} のシステム識別子を返します。
\end{methoddesc}

\begin{methoddesc}[InputSource]{setEncoding}{encoding}
  この \class{InputSource} の文字エンコーディングをセットします。

  指定するエンコーディングは XML エンコーディング宣言として定義された
  文字列でなければなりません(セクション 4.3.3 の XML 勧告を参照)。
 
  \class{InputSource} のエンコーディング属性は、\class{InputSource} が
  たとえ文字ストリームを含んでいたとしても、無視されます。
\end{methoddesc}

\begin{methoddesc}[InputSource]{getEncoding}{}
  この \class{InputSource} の文字エンコーディングを取得します。
\end{methoddesc}

\begin{methoddesc}[InputSource]{setByteStream}{bytefile}
  この入力ソースのバイトストリーム(Python のファイル風オブジェクトです
  が、バイト列と文字の相互変換はサポートしません)を設定します。

  なお、文字ストリームが指定されてもSAX パーサは無視し、バイト・ストリー
  ムを使って指定された URI に接続しようとします。
  
  アプリケーション側でバイト・ストリームの文字エンコーディングを知って
  いる場合は、setEncoding メソッドを使って指定する必要があります。
\end{methoddesc}

\begin{methoddesc}[InputSource]{getByteStream}{}
  この入力ソースのバイトストリームを取得します。
        
  getEncoding メソッドは、このバイト・ストリームの文字エンコーディング
  を返します。認識できないときは None を返します。
\end{methoddesc}

\begin{methoddesc}[InputSource]{setCharacterStream}{charfile}
  この入力ソースの文字ストリームをセットします(ストリームは Python 1.6 
  の Unicode-wrapped なファイル風オブジェクトで、ユニコード文字列への
  変換をサポートしていなければなりません)。
  
  なお、文字ストリームが指定されても SAX パーサは無視、システム識別子
  とみなし、バイト・ストリームを使って URI に接続しようとします。
\end{methoddesc}

\begin{methoddesc}[InputSource]{getCharacterStream}{}
  この入力ソースの文字ストリームを取得します。
\end{methoddesc}


\subsection{The \class{Attributes} インターフェース \label{attributes-objects}}

\class{Attributes} オブジェクトは \method{copy()}、\method{get()}、
\method{has_key()}、\method{items()}、 \method{keys()}、
\method{values()} などを含む、マッピング・プロトコルの一部を実装したも
のです。さらに次のメソッドも提供されています。:

\begin{methoddesc}[Attributes]{getLength}{}
  属性の数を返す。
\end{methoddesc}

\begin{methoddesc}[Attributes]{getNames}{}
  属性の名前を返す。
\end{methoddesc}

\begin{methoddesc}[Attributes]{getType}{name}
  属性名 \var{name} のタイプを返す。通常は \code{'CDATA'}。
\end{methoddesc}

\begin{methoddesc}[Attributes]{getValue}{name}
  属性 \var{name} の値を返す。
\end{methoddesc}

% getValueByQName, getNameByQName, getQNameByName, getQNames available
% here already, but documented only for derived class.


\subsection{\class{AttributesNS} インターフェース \label{attributes-ns-objects}}

このインターフェースは \ulink{\class{Attributes}
interface}{attributes-objects.html} 
(セクション~\ref{attributes-objects}参照) のサブタイプです。
Attributes インターフェー
スがサポートしているすべてのメソッドは \class{AttributesNS} オブジェク
トでも利用可能です。

そのほか、次のメソッドがサポートされています。:

\begin{methoddesc}[AttributesNS]{getValueByQName}{name}
  修飾名の値を返す。
\end{methoddesc}

\begin{methoddesc}[AttributesNS]{getNameByQName}{name}
  修飾名 \var{name} に対応する \code{(\var{namespace},
  \var{localname})} のペアを返す。
\end{methoddesc}

\begin{methoddesc}[AttributesNS]{getQNameByName}{name}
  \code{(\var{namespace}, \var{localname})} のペアに対応する修飾名を返す。
\end{methoddesc}

\begin{methoddesc}[AttributesNS]{getQNames}{}
  すべての属性の修飾名を返す。
\end{methoddesc}
