XML::Writerモジュール（日本語チョー訳）

by Hippo2000(1999/10/18)

XML::Writerモジュールなのです。

なおこのドキュメントではXML::WriterのHTMLを元にしています。わかりにくい部分は本物を見てください。(^^;;

原本の著作権はDavid Megginsonさんがお持ちです。メールで了解をいただいています。

なお内容等が間違っていたら修正します。ご連絡ください

名前

XML::Writer - XMLドキュメントを書き出すためのPerl拡張

概要

  use XML::Writer;
  use IO;

  my $output = new IO::File(">output.xml");

  my $writer = new XML::Writer(OUTPUT => $output);
  $writer->startTag("greeting", 
                    "class" => "simple");
  $writer->characters("Hello, world!");
  $writer->endTag("greeting");
  $writer->end();
  $output->close();

説明

XML::Writer はXMLドキュメントを出力するPerlプログラムのためのヘルパー・モジュールです。このモジュールは、属性値や文字データのすべてのエスケープをおこない、タグ、コメント、処理命令といった異なるマークアップの型を作り出します。

デフォルトでは、このモジュールは出力時のエラーを捕らえるために、多くのウェルフォームド（整形式）であるかのチェックを行います。このチェックは開発やデバッグのとき、とても便利です。しかし製品グレードのコードのために、はずすこともできます。

このモジュールは通常モードもしくは名前空間処理モードで動作させることができます。名前空間モードでは、このモジュールは名前空間宣言そのものを生成し、出力時に追加のチェックを行います。

メソッド

XMLの出力

new([$params])

新しいXML::Writeオブジェクトを生成します。

  my $writer = new XML::Writer(OUTPUT => $output, NEWLINES => 1);

引数はパラメータの無名ハッシュになります。

OUTPUT

IO::Handleまたは、(IO::Fileのような）そのサブクラスに結び付けられたオブジェクト。もしこのパラメータが指定されなければ、このモジュールは標準出力に出力します。

NAMESPACES

true (1) または false (0, undef) ; もしこのパラメータが指定され、値がtrueであれば、このモジュールは、以下の例のように、２つの要素を持つ配列へのリファレンスを、要素と属性の名前の場所で受け取ります：

  my $rdfns = "http://www.w3.org/1999/02/22-rdf-syntax-ns#";;
  my $writer = new XML::Writer(NAMESPACES => 1);
  $writer->startTag([$rdfns, "Description"]);

配列の最初の要素が名前空間URL、そして２番目の要素は修飾された名前のローカル部分となります。このモジュールは、適切な名前空間宣言を自動的に生成し、URI部分を接頭辞に置き換えます。

PREFIX_MAP

ハッシュへのリファレンス。このパラメータが指定され、このモジュールが名前空間処理を行うならば、（NAMESPACESパラメータを参照）、このモジュールは名前空間URIのための接頭辞を探すのに、このハッシュを優先して検索します。

  my $rdfns = "http://www.w3.org/1999/02/22-rdf-syntax-ns#";;
  my $writer = new XML::Writer(NAMESPACES => 1,
                               PREFIX_MAP => {$rdfns => 'rdf'});

ハッシュテーブルのキーが名前空間URIとなり、値が割り当てられる接頭辞になります。名前空間URIのための優先される接頭辞がそのハッシュになければ、モジュールは自動的に"_NS1", "_NS2"等の形式で接頭辞を生成します。

デフォルルトの名前空間を設定するためには、接頭辞を''としてください。

NEWLINES

true または false。もしこのパラメータが指定され、値がtrueであれば、このモジュールは開始、終了、空タグのデリミタの前に、ドキュエｍントが１つの長い行で終わらないことを保証するために余分な改行をいれます。このパラメータがなければ、このモジュールは改行をいれません。

UNSAFE

true または false；このパラメータが指定され、値がtrueであれば、ウェルフォームド（整形式）であるかのエラーチェックの大半をとばします。このパラーメータが指定されなければ、デフォルトとしてウェルフォームド（整形式）エラーチェックをおこないます。エラーチェックをはずすのは御自分のリスクの上で行ってください。

end()

XMLドキュメントの作成を終わります。このメソッドはドキュメントがまさに１つのdocument要素を持っており、開始したタグが閉じているかをチェックします：

  $writer->end();

xmlDecl([$standalone])

XML 宣言をXMLドキュメントの最初に追加します。バージョンは常に"1.0"、そしてencodingは常に"UTF-8"になります。$standalone 引数を指定すると、このモジュールは擬似属性'standalone'の値として、それの値をいれます。

  $writer->xmlDecl();

comment($text)

XMLドキュメントにコメントを追加します。コメントがドキュメント要素の外側に現れるならば（最初の開始タグの前または最後の終了タグの後のどちらか）、このモジュールは改行を追加して、読みやすくします。

  $writer->comment("This is a comment");

pi($target [, $data])

処理命令をXMLドキュメントに追加します。

  $writer->pi('xml-stylesheet', 'href="style.css" type="text/css"');

処理命令がドキュメント要素の外側に現れるならば（最初の開始タグの前または最後の終了タグの後のどちらか）、このモジュールは改行を追加して、読みやすくします。

$target 引数は単一のXML名でなければなりません。$data 引数を指定すると、このモジュールは$target引数の後ろに、１つの空白で区切って、その内容を挿入します。

startTag($name [, $aname1 => $value1, ...])

XMLドキュメントに開始タグを追加します。要素名の後ある引数はすべて、属性の名前／値の組であると見なし、このモジュールは属性の値にある、すべての'&'、'<'、、'>'、'"'文字を予め決まっているXMLエンティティにエスケープします。

  $writer->startTag('doc', 'version' => '1.0',
                           'status' => 'draft',
                           'topic' => 'AT&T');

すべての開始タグは最終的に対応する終了タグを持たなければなりません。

emptyTag($name [, $aname1 => $value1, ...])

空タグをXMLドキュメントに追加します。要素名の後ろにある引数はすべて、属性の名前／値の組であると見なされます。（詳細はstartTag()をご覧ください）

  $writer->emptyTag('img', 'src' => 'portrait.jpg',
                           'alt' => 'Portrait of Emma.');

endTag([$name])

終了タグをXMLドキュメントに追加します。終了タグは一番近い開始タグに対応しなければならず、対応し、各開始タグについて正しくネストした終了タグがなければなりません。

  $writer->endTag('doc');

$name が省略されると、モジュールは現在開いている要素の名前を自動的に設定します。

  $writer->startTag('p');
  $writer->endTag();

characters($data)

XMLドキュメントに文字データを追加します。$data引数のなかの、すべての'<'、'>'、'&'文字は自動的に予め決まっているXMLエンティティにエスケープされます。

  $writer->characters("Here is the formula: ");
  $writer->characters("a < 100 && a > 5");

このメソッドはドキュメント要素の中だけで呼び出すことができます。（つまり最初の開始タグの後で最後の終了タグの前）

XMLの問い合わせ

in_element($name)

一番最後に開いた要素が$nameにマッチすればtrueを返します。

  if ($writer->in_element('dl')) {
    $writer->startTag('dt');
  } else {
    $writer->startTag('li');
  }

within_element($name)

開いている要素のいずれかが$nameにマッチすればtrueを返します。

  if ($writer->within_element('body')) {
    $writer->startTag('h1');
  } else {
    $writer->startTag('title');
  }

current_element()

現在開いている要素の名前を返します。

  my $name = $writer->current_element();

これは以下のものと同等です。

  my $name = $writer->ancestor(0);

ancestor($n)

n番目の先祖の名前を返します。$n=0であれば現在開いている要素になります。

追加名前空間のサポート

警告：ドキュメントを書いている最中にこれらのメソッドを使ってはなりません、そうしなければ結果は予測できません。

addPrefix($uri, $prefix): 名前空間URIと接頭辞間の優先マッピングを追加します。PREFIX_MAP コンストラクタ・パラメータをご覧下さい。
デフォルトの名前空間を設定するには、$prefixパラメータを省略するか’’を設定してください。
removePrefix($uri): 名前空間URIと接頭辞間の優先マッピングを削除します。
デフォルトの名前空間を設定するには、$prefixパラメータを省略するか’’を設定してください。

エラー報告

デフォルトの設定では、XML::Writer モジュールはいくつかの基本的なXMLウェルフォームド（整形式）についてのエラーを検出することができます。

(最上位）ドキュメント要素の欠如、あるいは複数のドキュメント要素
閉じていない開始タグ
処理命令またはコメントの内容にデリミタの位置がおかしい
XML宣言の位置がおかしい、または重複
DOCTYPE宣言の位置がおかしい、または重複
DOCTYPE宣言でのドキュメント・タイプ名とドキュメント要素の名前が合わない
開始タグと終了タグがマッチしない
ドキュメント要素の外へ文字データを挿入しようとしている
同じ名前の属性が複数ある

名前空間処理をするときには、このモジュールはさらに以下のエラーを検出することができます。

PIターゲット、要素、属性名にコロンを持ったものを指定しようとしている
"xmlns"で始まる名前を持った属性を使おうとしている

すべてのエラーが検出できるようにするためには、ドキュメントの書き出しが終了したらプログラムはendメソッドも呼び出さなければなりません。

  $writer->startTag('greeting');
  $writer->characters("Hello, world!");
  $writer->endTag('greeting');
  $writer->end();

このエラー報告はXMLドキュメントを生成するPerlプログラムの多くの隠れたバグを捕らえることができます。しかし必要であれば、UNSAFEパラメータを指定することにより、はずすこともできます。

  my $writer = new XML::Writer(OUTPUT => $output, UNSAFE => 1);

作者

David Megginson, david@megginson.com

参考資料

XML::Parser

ホーム　Perlの小技

ご意見、ご質問はこちらの掲示板で受け付けています。
またメールは河馬屋(Nifty)にお願いします。

XML::Writerモジュール（日本語チョー訳）

目次