by Hippo2000(1999/4/20)
日本語チョウ訳 XMLの巻 XML::Parserモジュールなのです。
なおこのドキュメントではXML-Parserモジュールをインストールしたときに作成されるC:\Perl\html\lib\site\xml\Parser.htmlではなく、pod2htmlを使って抽出した内容を、私が日本語に訳そうとしたものです。
これもやっぱり、わかりにくい説明は本物を見てください。(^^;
原本の著作権はLary Wall氏、Clark Cooper 氏がお持ちです（詳しくは著作権情報を見てください）。Clark Cooper氏にメールで、翻訳の許可をいただきました。
内容等が間違っていたら修正します。ご連絡ください。
XML::Parser - XML文書を解析するPerlモジュール
use XML::Parser;
$p1 = new XML::Parser(Style => 'Debug');
$p1->parsefile('REC-xml-19980210.xml');
$p1->parse('<foo id="me">Hello World</foo>');
# 他の書き方(1)
$p2 = new XML::Parser(Handlers => {Start => \&handle_start,
End => \&handle_end,
Char => \&handle_char});
$p2->parse($socket);
# 他の書き方(2) $p3 = new XML::Parser(ErrorContext => 2);
$p3->setHandlers(Char => \&text,
Default => \&other);
open(FOO, 'xmlgenerator |');
$p3->parse(*FOO, ProtocolEncoding => 'ISO-8859-1');
close(FOO);
$p3->parsefile('junk.xml', ErrorContext => 3);
このモジュールはXML文書の解析する手段を提供します。これはXMLの最上位に構築されます。James Clark氏のexpatライブラリへの下位レベルのインターフェースになっています。解析するメソッドを呼び出すたびに、文書を解析するために使われるXML::Parser::Expatの新しいインスタンスを作成されます。ＥｘｐａｔオプションはXML::parserオブジェクトが生成されるときに指定することが出来ます。これらのオプションは、解析の呼び出しが行われるたびにExpatオブジェクトに渡されます。また特別な引数として解析メソッドに指定することもできます。その場合、XML::Parser生成時のオプションを上書きします。
パーサの動きはStyle、Handlersオプションのどちらかあるいは両方、もしくはsetHandlersメソッドによって制御されます。これらはすべて、XML::Parser::Expatが必要としているハンドラを設定するための仕組みを提供しています。StyleもHandlersも指定されていない場合には、文書がウェルフォームドであるかどうかだけがチェックされます。
ハンドラが呼び出されるとき、第１パラメータにはParserオブジェクトではなく、Ｅｘｐａｔオブジェクトをが渡されます。
このオプションはパーサの決まっているスタイルを作成する簡単な方法を提供します。組み込まれているスタイルには: Debug, Subs, Tree, Objects, Streamがあります。特注のスタイルは少なくとも１つ'.::'をもっているフルパッケージ名によって指定することが出来ます。このパッケージにはインストールされることを要求されている各ハンドラを定義したサブルーチンがなければなりません。この後のスタイル で組み込みスタイルのそれぞれについて説明しています。
指定するとき、このオプションはハンドラの種類をキー、値をその種類のイベントのハンドラへのサブルーチン・リファレンスという無名ハッシュで指定します。すべてのハンドラは第１パラメータとしてその文書を解析するexpatのインスタンスを受け取ります。ハンドラについての詳細は ハンドラにあります。ここに指定されたハンドラはＳｔｙｌｅオプションで指定された対応するハンドルを上書きします。
ある種のスタイルはこのパッケージで定義されたサブルーチンを参照します。指定されなければ、デフォルトはコンストラクタを呼び出したパッケージになります。
Ｅｘｐａｔのオプション。このオプションが指定されると、エラーが文脈でレポートされます。エラーが発生した行の上下何行を表示するかの行数で指定します。
Ｅｘｐａｔオプション。プロトコル・エンコーディング名を設定します。デフォルトは無しです。組み込まれているエンコーディングは：UTF-8、ISO-8859-1,UTF-16、US-ASCIIです。@Encoding_Pathリストにあるディレクトリの１つにエンコーディング・マップがあれば、他のエンコーディングも使えます。 エンコーディング・マップの詳細についてはエンコーディングをご覧下さい。プロトコルエンコーディングを設定するとXML宣言でのいかなるエンコーディングも上書きします。
Expatオプション。trueが設定されると、解析の途中で名前空間の処理がおこなわれます。名前空間処理についてはXMLをご覧下さい。
Ｅｘｐａｔオプション。通常パーサは内部サブセットで定義されたエンティティへの参照を展開しようとします。このオプションにｔrueが設定され、Defaultハンドラも設定されていると、テキストにエンティティ参照が見つかったときにDefaultハンドラが呼び出されます。Defaultハンドラが登録されていなければ、何も影響がありません。また内部属性値のなかのエンティティの展開には何の影響も与えません。
Ｅｘｐａｔオプション。文字列値を取ります。ストリームを解析中にこの文字列だけの行を見つかると ファイルの最後であるかのように解析を終了します。MIMEマルチパート形式でのXML文書のストリームで使われることを想定しています。文字列の後ろには改行が付いてはいけません。
指定するならば、Ｅｘｐａｔへ渡さないオプションをキーとする無名ハッシュで指定しなければいけません。これはXML::Parseのサブクラスにだけ関連しています。
Expatはイベントを基本としたパーサです。パーサが文書の部分を理解すると（XML要素の開始または終了タグを見つけると）、その種類のイベントために登録されたハンドラが、適切なパラメータで呼び出されます。すべてのハンドラは第１パラメータとしてXML::Parser::Expatのインスタンスを受け取ります。このオブジェクトで呼び出すことができるメソッドの説明についてはXMLをご覧下さい。
文書のはじまりを解析する直前に呼び出させれます。
解析が終了した直後に呼ばれます、ただし解析中になにもエラーが発生しなかった場合だけです。Parseではこの戻り値を返します。
このイベントはXML開始タグが見つかると発生します。Elementは開始タグによって開かれたXML要素型の名前です。 開始タグでの各属性毎にAttrとValのペアが設定されます。
このイベントはＸＭＬ終了タグが見つかると発生されます。XML空要素タグ(<foo/>)は開始と終了の両方のイベントを発生することに注意してください。
このイベントはマーク付きでない部分を見つけたときに発生します。マーク付きでない文字列はStringに入ります。一連のマーク付きでない文字列が、このハンドラを何回も呼び出すかもしれません。元の文書での文字列のエンコーディングがなんであれ、ハンドラにはUTF-8で渡されます。
このイベントは処理命令が見つかると発生します。
このイベントはコメントが見つかると発生します。
CDATAセクションの開始時点で呼び出されます。
CDATAセクションの終了時点で呼び出されます。
登録されているハンドラに対応しない文字列があると呼び出されます。これにはイベントを発生させないマーク付けの部分（マーク付けの宣言）の文字列やイベントを発生させるがハンドラが登録されていない文字列の両方が含まれます。
元の文書のエンコードがなんであれば、ハンドラに戻される文字列はUTF-8で返されます。
パース対象外エンティティの宣言のために呼ばれます。Entityはそのエンティティの名前になります。Baseは相対的URIを解決するために使われるベースです。Sysidはシステム識別子、Pubidは公開識別子。Notationは記法名です。BaseとPubidは未定義かもしれません。
記法名の宣言のために呼ばれます。Notationは記法名。Baseは相対的URIを解決するために使われるベース。Sysidはシステム識別子、Pubidは公開識別子です。 Base, Sysid, Pubidはすべて未定義かもしれません。
外部エンティティが参照されている場合に呼び出されます。Baseは相対的URIを解決するために使われるベースです。Sysidはシステム識別子、Pubidは公開識別子。BaseとPubidは未定義かもしれません。
このハンドラは、外部エンティティの内容を表す文字列、外部エンティティの内容を取得するためのオープンされたファイルハンドル、外部エンティティが見つからず解析エラーが発生することを示すundefのいずれかを返さなければいけません。
オープンされたファイルハンドルを返すときには、グロブ(*FOO)またはグロブへのリファレンス（つまりIO::Handleのインスタンス）として返します。 パーサはこれを使った後クローズします。
デフォルトハンドラXML::Parser::default_ext_ent_handlerはこのためにインストールされています。これはファイルをURLメソッドで扱うだけで、もしなければ"file:"だと仮定します。expatのbaseメソッドは相対パス名を設定するためのベース名を設定するために使われます。ベース名が指定されなければ、またはベース名そのものが相対名であれば、現在の作業ディレクトリからの相対になります。
エンティティが内部サブセットで宣言されたときに呼び出されます。内部エンティティではValパラメータに値が入り、残りの３つのパラメータは未定義になります。外部エンティティでは、Valパラメータが未定義になり、Sysidパラメータにはシステム識別子、Pubidパラメータにはもし与えられていれば公開識別子（そうでなければ未定義）、Ndataパラメータにはパース対象外エンティティの記法名が入ります。もしパラメータ・エンティティ宣言だったときには、名前には'%'が付きます。
このハンドラと上記のUnparsedハンドラはぶつかります。両方とも設定すると、パース対象外エンティティにはこのハンドラは呼ばれません。
elementハンドラは、内部サブセットで要素定義が見つかると呼び出されます。Nameは要素名、Modelはコンテント・モデルが文字列で入ります。
このハンドラは内部サブセットでのATTLIST宣言の各属性で呼ばれます。そのためATTLIST宣言に複数の属性があると、このハンドラが複数回、呼び出されます。Elnameパラメータは属性が結びつけられる要素の名前。Attnameパラメータは属性の名前。Typeは属性の型を文字列にしたもの。Defaultはデフォルト値で、"#REQUIRED'', "#IMPLIED'' 、クォート化された文字列（つまり返される文字列の始めと終わりがクォート文字になります）のいずれかになります。もしFixedがtrueならば、これは固定化された属性になります。
このハンドルは文書型（DOCTYPE）宣言のために呼ばれます。Nameは文書型名。Sysidは文書型のシステム識別子（指定されれば。そうでなければ未定義値）。Pubidは文書型の公開識別子、公開識別子が指定されなければ未定義値。Internalは内部サブセットが文字列で与えられます。なにも内部サブセットがなければ、未定義値になります。Internalは内部サブセットでの空白、コメント、処理命令、宣言のすべてが入ります。他のハンドラ（Unparsedハンドラによって処理されるパース対象外エンティティを除いて）によって処理されるかどうかに関わらず、宣言はそこにはいります。しかしコメント、処理命令は対応するハンドラで処理されていれば、現れません。
このハンドラはXML宣言のために呼ばれます。Versionにはバージョンが入った文字列。Encodingは未定義値か、エンコーディング文字列が入ります。Standaloneはtrueまたはfalseまたは未定義値で、それぞれstandalone属性がyes, no,またはまだ作成されていないことを示します。
これは単にアウトライン形式で文書を出力します。parseによって特別なものは何も返りません。
要素が始まるたびに、Startハンドラが呼び出されたのと同じパラメータでPkgオプションによって指定されたパッケージのなかのその名前のサブルーチンが呼び出されます。
要素が終わるたびに、Endハンドラが呼び出されるのと同じパラメータで、後ろにアンダースコア("_")が付けられた名前をもつサブルーチンが呼び出されます。
parseによって特別なものは何も返りません。
文書のツリー構造を返します。例えば以下のものを解析すると
<foo><head id="a">Hello</head><bar>There<ref/></bar>All</foo>
こうなります:
[foo, [{}, head, [{id => "a"}, 0, Hello],
bar, [{}, 0, There,
ref, [{}]
],
0, All
]
]
Treeスタイルに似ています。ただし各要素に対してハッシュオブジェクトが生成される点で異なります。対応するオブジェクトは、Pkgオプションで設定されたパッケージ名の後ろに"::"と要素名を付けた名前のます。マーク付テキストでなければ、::Charactersクラスになります。対応するオブジェクトの内容は、そのオブジェクトのKidsプロパティの値である無名配列に入ります。
このスタイルもPkgパッケージを使います。このスタイルが探すサブルーチンがなければ、このスタイルでの解析の結果は、コメントや宣言をなくした型通りの文書のコピーを出力します。すべてのサブルーチンは文書を解析するExpatインスタンスを第１パラメータとして受け取ります。
以下のサブルーチンを探します:
解析を始めるときに呼び出されます
開始タグがあるたびに、第２パラメータが要素型で呼び出されます。$_変数にタグのコピーが、%_変数にその要素に指定された属性値が入ります。
終了タグがあるたびに第２パラメータが要素型で呼び出されます。 $_変数に終了タグのコピーが入ります。
テキストの開始または終了タグの直前で呼び出されます。$_変数にそこまでのマーク付きでない文字が入ります。
処理命令のために呼び出されます。$_変数にはPIのコピーが入り、ターゲット、データはそれぞれ第２、３パラメータとして送られます。
解析の終了時点で呼び出されます。
XML文書は、Unicodeキャラクタセットにマップできるキャラクタセットであるかぎりは、Unicode以外のキャラクタセットでエンコードされていることが許されます。Expatはエンコーディングについて、より厳しい制限をもっています。これらの制限についての詳細はexpatで配布されるxmlparse.hヘッダファイルをお読みください。
ExpatではUTF-8,
ISO-8859-1, UTF-16, and US-ASCIIのエンコーディングが組み込まれています。エンコーディングはXML宣言のエンコーディング属性を通して、あるいはXML::Parser、XML::Parser::ExpatのProtocolEncodingオプションを通して設定されます。
組み込み以外のエンコーディングを使うために、expatはExpatパッケージでload_encoding関数をエンコーディング名を使って呼び出します。この関数はパスのリスト@XML::Parser::Expat::Encoding_Pathの、小文字の名前でマッチし拡張子が'.enc'であるファイルを検索します。最初に見つかったものがロードされます。
もし独自のエンコーディング・マップを作りたいと思うならばCPANからXML::Encodingをチェックアウトしてください。
Larry Wall <larry@wall.org> wrote version 1.0.
Clark Cooper <coopercl@sch.ge.com> picked up support, changed the API for this version (2.x), provided documentation, and added some standard package features.
ご意見、ご質問はこちらの掲示板で受け付けています。
またメールは河馬屋(Nifty)にお願いします。