\section{\module{xmllib} ---
         XML ドキュメントのパーサ}

\declaremodule{standard}{xmllib}
\modulesynopsis{XML ドキュメントのパーサ。}
\moduleauthor{Sjoerd Mullender}{Sjoerd.Mullender@cwi.nl}
\sectionauthor{Sjoerd Mullender}{Sjoerd.Mullender@cwi.nl}


\index{XML}
\index{Extensible Markup Language}

\deprecated{2.0}{代わりに \refmodule{xml.sax} を使ってください。新しい
                  XML パッケージは XML 1.0 をフルにサポートしています。}

\versionchanged[名前空間のサポートを追加]{1.5.2}

このモジュールには XML (Extensible Markup Language) 形式で記述されたテ
キストファイルのパースに必要な基本機能を提供する \class{XMLParser} ク
ラスが定義されています。

\begin{classdesc}{XMLParser}{}
\class{XMLParser} XMLParser クラスのインスタンス生成は引数を指定せずにおこ
ないます。
\footnote{実際には、パーサに非標準的な形式のドキュメントを許容す
  るための、いくつかのキーワード引数を指定できるようになっており、その
  内容は次の通りです。これらのデフォルト値はすべて \code{0} (false) で
  すが、最後のキーワード引数だけは \code{1} (true)になっています。
\var{accept_unquoted_attributes} (特定の属性がクォートされていなくても
  受け入れるようにする)、 \var{accept_missing_endtag_name} (\code{</>}
  のようなタグ名なしの終了タグを許容する)、\var{map_case} (タグや属性
  名が大文字で書かれていても、小文字で解釈する)、 \var{accept_utf8} (UTF-8
文字列の入力を許容する。これは XML 標準規格で必須とされている内容ですが、
  Python は今のところ UTF-8 を適切に処理できないため、デフォルトでは無
  効になっています。)、 \var{translate_attribute_references} (属性値と
  して使われている文字列や実体参照はそれ以上解釈しない。)}
\end{classdesc}

このクラスは次のインターフェース・メソッドとインスタンス変数を提供して
います。

\begin{memberdesc}{attributes}
要素名のマッピングへのマッピング・オブジェクトで、デフォルトは空の辞書
です。このデフォルト変数はすべての \class{XMLParser} インスタンスで
共有されるため、継承せずにオーバーライドする必要があります。なお、要素
名のマッピングの方は、その要素に妥当な属性名とそのデフォルトの属性値を
マッピングしており、デフォルト値がない場合は \code{None} になります。
\end{memberdesc}

\begin{memberdesc}{elements} 
要素名からタプルへのマッピングです。タプルには要素の開始タグと終了タグ
をそれぞれ処理する関数、または \method{unknown_starttag()} や
\method{unknown_endtag()} 呼出された場合に使用する \code{None} が含ま
れます。デフォルトは空の辞書になっています。このデフォルト変数はすべての 
\class{XMLParser} インスタンスで共有されるため、継承せずにオーバーライ
ドする必要があります。

\end{memberdesc}

\begin{memberdesc}{entitydefs}
エンティティ名からその値へのマッピングです。デフォルトで \code{'lt'}、 
\code{'gt'}、 \code{'amp'}、 \code{'quot'}、 and \code{'apos'} の定義
がされています。

\end{memberdesc}

\begin{methoddesc}{reset}{}
インスタンスをリセットします。同時に未処理のデータはすべて失われます。
このメソッドはインスタンス生成時、暗黙裡に呼び出されます。
\end{methoddesc}

\begin{methoddesc}{setnomoretags}{}
タグの処理を中止します。このメソッドの呼び出し以降、すべての入力はリテラ
ル(CDATA)として扱われます。
\end{methoddesc}

\begin{methoddesc}{setliteral}{}
リテラルモード(CDATA mode)に入ります。このモードは最後に処理した開始タ
グに対応する終了タグが見つかった時点で自動的に終了します。
\end{methoddesc}

\begin{methoddesc}{feed}{data}
テキストをパーサに送ります。完全なタグで構成された部分までを処理し、不
完全なタグは次のデータが来るか \method{close()} が呼び出されるまでバッ
ファリングされます。
\end{methoddesc}

\begin{methoddesc}{close}{}
現在バッファリング中のデータの前に end-of-file ファイルが来たものと強
制的にみなします。このメソッドは派生クラスにおいて、入力終了時におこな
う追加処理のために再定義されることもありますが、再定義したメソッドの中
で必ずこの \method{close()} を呼び出さなければなりません。
\end{methoddesc}

\begin{methoddesc}{translate_references}{data}
\var{data} の中にある実体参照と文字参照をすべて変換し、変換後
の文字列を返します。
\end{methoddesc}

\begin{methoddesc}{getnamespace}{}
現在有効な名前空間の短縮名から名前空間 URI へのマッピングを返します。
\end{methoddesc}

\begin{methoddesc}{handle_xml}{encoding, standalone}
このメソッドは \samp{<?xml ...?>} タグを処理します。引数はタグ中のエン
コーディングの値とスタンドアロン宣言です。エンコーディングとスタンドア
ロン属性はともにオプションです。デフォルトはそれぞれ \code{None} と文
字列 \code{'no'} になります。
\end{methoddesc}

\begin{methoddesc}{handle_doctype}{tag, pubid, syslit, data}

このメソッド\index{DOCTYPE declaration}は \samp{<!DOCTYPE...>} 宣言を
処理します。引数にはルート要素のタグ名、公式公開識別子\index{Formal
Public Identifier} (指定されていない場合は \code{None})、システム識別
子、および内部 DTD サブセットを処理せずそのまま文字列で指定します(指定
されていない場合は \code{None})。
\end{methoddesc}

\begin{methoddesc}{handle_starttag}{tag, method, attributes}
このメソッドはインスタンス変数 \member{elements} にハンドラが定義され
ている開始タグを処理します。\var{tag} はタグ名で、\var{method} は開始
タグの意味解析サポートに使われる関数(メソッド)です。\var{attributes} 
は \code{<>} タグ内に記述されている属性名がキー、属性値を値として持つ
辞書になります。文字およびエンティティの参照は解釈されます。たとえば、
開始タグ \code{<A HREF="http://www.cwi.nl/">} に対するこのメドッドの呼
出しは \code{handle_starttag('A', self.elements['A'][0], \{'HREF':
'http://www.cwi.nl/'\})} となります。基本的な実装は単純で、引数に 
\var{attributes} を使い、\var{method} を呼び出すだけのものです。
\end{methoddesc}

\begin{methoddesc}{handle_endtag}{tag, method}
このメソッドはインスタンス変数 \member{elements} にハンドラが定義され
ている終了タグを処理します。\var{tag} はタグ名で、\var{method} は終了
タグの意味解析サポートに使われる関数(メソッド)です。たとえば、終了タグ 
\code{</A>} に対するこのメドッドの呼出しは \code{handle_endtag('A',
self.elements['A'][1])} となります。基本的な実装は単純で、\var{method} 
を呼び出すだけのものです。
\end{methoddesc}

\begin{methoddesc}{handle_data}{data}
これは任意のデータを処理するメソッドです。派生クラスでオーバライドして
使います。基底クラスの実装では何もおこないません。
\end{methoddesc}

\begin{methoddesc}{handle_charref}{ref}
このメソッドは \samp{\&\#\var{ref};} 形式の文字参照を処理します。
\var{ref} は10進数または頭に\character{x}を付けた16進数のどちらでもか
まいません。基本実装おいて \var{ref} の値として許される範囲は0から255 
までに限定されています。この値が \ASCII{} に変換された後、その文字列を
引数にしてメソッド \method{handle_data()} が呼び出されます。\var{ref} 
の値が許容範囲外のときは、エラーハンドリングのために
\code{unknown_charref(\var{ref})} が呼び出されます。\ASCII{} 範囲外の
文字をサポートするには、サブクラスでこのメソッドをオーバーライドする必
要があります。
\end{methoddesc}

\begin{methoddesc}{handle_comment}{comment}
コメントを検出すると、このメソッドが呼び出されます。引数 \var{comment} 
は、デリミタ \samp{<!--} から \samp{-->} の間にある文字列であり、デリ
ミタ自体は含まれません。たとえばコメント \samp{<!--text-->} を処理する
場合、引数は \code{'text'} でこのメソッドが呼び出されます。このメソッドは
デフォルトでは何もしません。
\end{methoddesc}

\begin{methoddesc}{handle_cdata}{data}
CDATA 要素を検出すると、このメソッドが呼び出されます。引数 \var{data} 
は、デリミタ \samp{<![CDATA[} と \samp{]]>} の間にある文字列であり、デリ
ミタ自体は含まれません。たとえばエンティティ \samp{<![CDATA[text]]>} を処理する
場合、引数は \code{'text'} でこのメソッドが呼び出されます。このメソッドは
デフォルトでは何もしないため、オーバーライドして使用します。
\end{methoddesc}

\begin{methoddesc}{handle_proc}{name, data}
処理命令 (PI) を検出すると、このメソッドが呼び出されます。引数 
\var{name} は処理命令のターゲット、\var{data} は、処理命令ターゲットと
終了デリミタの間にある文字列であり、デリミタ自体は含まれません。たとえ
ば命令 \samp{<?XML text?>} を処理する場合、引数は \code{'XML'} と 
\code{'text'} の2つでこのメソッドが呼び出されます。このメソッドはデフォ
ルトでは何もしません。なおドキュメントの冒頭に現れる \samp{<?xml ..?>} 
は \method{handle_xml()} で処理されます。
\end{methoddesc}

\begin{methoddesc}{handle_special}{data}
宣言を検出すると、このメソッドが呼び出されます。引数 \var{data} は、デ
リミタ \samp{<!} と \samp{>} の間にある文字列であり、デリミタ自体は含
まれません。たとえば\index{ENTITY declaration}エンティティ宣言 
\samp{<!ENTITY text>} を処理する場合、引数は \code{'ENTITY text'} でこの
メソッドが呼び出されます。このメソッドはデフォルトでは何もしないため、
オーバーライドして使用します。なおドキュメントの冒頭に現れる
\samp{<!DOCTYPE ...>} は別途処理しなければなりません。
\end{methoddesc}

\begin{methoddesc}{syntax_error}{message}
シンタックスエラーが発生すると、このメソッドが呼び出されます。引数 
\var{message} はエラー内容を知らせるテキストです。このメソッドはデフォ
ルトで \exception{RuntimeError} 例外を発生させます。メソッドをオーバラ
イドして、return するように変えることも可能です。なお、このメソッドが
呼び出されるのは回復可能なエラーの場合だけです。回復不能なエラー発生し
たときは、\method{syntax_error()} を呼び出すことなく
\exception{RuntimeError} が発生します。
\end{methoddesc}

\begin{methoddesc}{unknown_starttag}{tag, attributes}
未知の開始タグを検出すると、このメドッドが呼び出されます。派生クラスで
オーバライドして使います。基底クラスの実装では何もおこないません。
\end{methoddesc}

\begin{methoddesc}{unknown_endtag}{tag}
未知の終了タグを検出すると、このメドッドが呼び出されます。派生クラスで
オーバライドして使います。基底クラスの実装では何もおこないません。
\end{methoddesc}

\begin{methoddesc}{unknown_charref}{ref}
解決できない文字参照を検出すると、このメドッドが呼び出されます。派
生クラスでオーバライドして使います。基底クラスの実装では何もおこないま
せん。
\end{methoddesc}

\begin{methoddesc}{unknown_entityref}{ref}
解決できない実体参照を検出すると、このメドッドが呼び出されます。派生ク
ラスでオーバライドして使います。基底クラスの実装では 
\method{syntax_error()} でエラーを通知するようになっています。
\end{methoddesc}


\begin{参考文献}
  \seetitle[http://www.w3.org/TR/REC-xml]{Extensible Markup Language
            (XML) 1.0}{World Wide Web Consortium (W3C) が発行した XML 
            の仕様書で、XML のシンタックスと処理に必要な内容が定義され
            ています。仕様書の翻訳など、そのほかの文献は 
            \url{http://www.w3.org/XML/} で参照できます。}

  \seetitle[http://www.python.org/topics/xml/]{Python and XML
            Processing}{Python XML トピックガイドは Python で XML を扱
            うための情報と XML 関連情報源へのリンクを数多く提供してい
            ます。}

  \seetitle[http://www.python.org/sigs/xml-sig/]{SIG for XML
            Processing in Python}{Python XML Special Interest Group は 
            Python で XML を扱うための開発に多大な貢献をしています。}
\end{seealso}


\subsection{XML 名前空間 \label{xml-namespace}}

このモジュールは XML 名前空間勧告に定義された名前空間をサポートします。
\indexii{XML}{namespaces}

XML 名前空間に定義されたタグ名と属性名は、名前空間(名前空間を定義した
URL)の後ににスペース置き、それに続くタグ名または属性名として扱われます。
たとえば、タグが \code{<html xmlns='http://www.w3.org/TR/REC-html40'>} 
の場合、タグ名は \code{'http://www.w3.org/TR/REC-html40 html'} として
処理され、この要素の中にタグ \code{<html:a href='http://frob.com'>} が
現れた場合、タグ名は \code{'http://www.w3.org/TR/REC-html40 a'} で、属
性名は \code{'http://www.w3.org/TR/REC-html40 href'} となります。

古い XML 名前空間勧告ドラフトに基いたものも処理可能ですが、警告が発せ
られます。

\begin{参考文献}
  \seetitle[http://www.w3.org/TR/REC-xml-names/]{Namespaces in XML}{ 
           この W3 コンソーシアム 勧告には、XML 名前空間の正確なシンタ
           クスと処理に必要な内容について述べられています。}
\end{seealso}
