=encoding euc-jp

=head1 名前

XML::RSS - RSSファイルを作成し更新します

=head1 概要

 # RSS 1.0ファイル(http://purl.org/rss/1.0/)を作成します
 use XML::RSS;
 my $rss = new XML::RSS (version => '1.0');
 $rss->channel(
   title        => "freshmeat.net",
   link         => "http://freshmeat.net",
   description  => "the one-stop-shop for all your Linux software needs",
   dc => {
     date       => '2000-08-23T07:00+00:00',
     subject    => "Linux Software",
     creator    => 'scoop@freshmeat.net',
     publisher  => 'scoop@freshmeat.net',
     rights     => 'Copyright 1999, Freshmeat.net',
     language   => 'en-us',
   },
   syn => {
     updatePeriod     => "hourly",
     updateFrequency  => "1",
     updateBase       => "1901-01-01T00:00+00:00",
   },
   taxo => [
     'http://dmoz.org/Computers/Internet',
     'http://dmoz.org/Computers/PC'
   ]
 );

 $rss->image(
   title  => "freshmeat.net",
   url    => "http://freshmeat.net/images/fm.mini.jpg",
   link   => "http://freshmeat.net",
   dc => {
     creator  => "G. Raphics (graphics at freshmeat.net)",
   },
 );

 $rss->add_item(
   title       => "GTKeyboard 0.85",
   link        => "http://freshmeat.net/news/1999/06/21/930003829.html",
   description => "GTKeyboard is a graphical keyboard that ...",
   dc => {
     subject  => "X11/Utilities",
     creator  => "David Allen (s2mdalle at titan.vcu.edu)",
   },
   taxo => [
     'http://dmoz.org/Computers/Internet',
     'http://dmoz.org/Computers/PC'
   ]
 );

 $rss->textinput(
   title        => "quick finder",
   description  => "Use the text input below to search freshmeat",
   name         => "query",
   link         => "http://core.freshmeat.net/search.php3",
 );

 # オプションで標準ではないmodule/namespaceの要素の混在

 $rss->add_module(prefix=>'my', uri=>'http://purl.org/my/rss/module/');

 $rss->add_item(
   title       => "xIrc 2.4pre2"
   link        => "http://freshmeat.net/projects/xirc/",
   description => "xIrc is an X11-based IRC client which ...",
   my => {
     rating    => "A+",
     category  => "X11/IRC",
   },
 );

  $rss->add_item (title=>$title, link=>$link, slash=>{ topic=>$topic });

 # RSS 0.91ファイルの作成
 use XML::RSS;
 my $rss = new XML::RSS (version => '0.91');
 $rss->channel(title          => 'freshmeat.net',
               link           => 'http://freshmeat.net',
               language       => 'en',
               description    => 'the one-stop-shop for all your Linux software needs',
               rating         => '(PICS-1.1 "http://www.classify.org/safesurf/" 1 r (SS~~000 1))',
               copyright      => 'Copyright 1999, Freshmeat.net',
               pubDate        => 'Thu, 23 Aug 1999 07:00:00 GMT',
               lastBuildDate  => 'Thu, 23 Aug 1999 16:20:26 GMT',
               docs           => 'http://www.blahblah.org/fm.cdf',
               managingEditor => 'scoop@freshmeat.net',
               webMaster      => 'scoop@freshmeat.net'
               );

 $rss->image(title       => 'freshmeat.net',
             url         => 'http://freshmeat.net/images/fm.mini.jpg',
             link        => 'http://freshmeat.net',
             width       => 88,
             height      => 31,
             description => 'This is the Freshmeat image stupid'
             );

 $rss->add_item(title => "GTKeyboard 0.85",
                link  => "http://freshmeat.net/news/1999/06/21/930003829.html",
                description => 'blah blah'
                );

 $rss->skipHours(hour => 2);
 $rss->skipDays(day => 1);

 $rss->textinput(title => "quick finder",
                 description => "Use the text input below to search freshmeat",
                 name  => "query",
                 link  => "http://core.freshmeat.net/search.php3"
                 );

 # RSS 0.9ファイルの作成
 use XML::RSS;
 my $rss = new XML::RSS (version => '0.9');
 $rss->channel(title => "freshmeat.net",
               link  => "http://freshmeat.net",
               description => "the one-stop-shop for all your Linux software needs",
               );

 $rss->image(title => "freshmeat.net",
             url   => "http://freshmeat.net/images/fm.mini.jpg",
             link  => "http://freshmeat.net"
             );

 $rss->add_item(title => "GTKeyboard 0.85",
                link  => "http://freshmeat.net/news/1999/06/21/930003829.html"
                );

 $rss->textinput(title => "quick finder",
                 description => "Use the text input below to search freshmeat",
                 name  => "query",
                 link  => "http://core.freshmeat.net/search.php3"
                 );

 # RSSを文字列で出力
 print $rss->as_string;

 # それをファイルに保存
 $rss->save("fm.rdf");

 # RSSファイルに要素を挿入し、既に15個の要素があるならば、
 # 最も古い要素を削除します
 my $rss = new XML::RSS;
 $rss->parsefile("fm.rdf");
 pop(@{$rss->{'items'}}) if (@{$rss->{'items'}} == 15);
 $rss->add_item(title => "MpegTV Player (mtv) 1.0.9.7",
                link  => "http://freshmeat.net/news/1999/06/21/930003958.html",
                mode  => 'insert'
                );

 # ファイルの代わりに文字列を解析します
 $rss->parse($string);

 # 各RSS要素のtitleとlinkを出力します
 foreach my $item (@{$rss->{'items'}}) {
     print "title: $item->{'title'}\n";
     print "link: $item->{'link'}\n\n";
 }

 # RSS 0.9あるいは0.91ファイルをRSS 1.0で出力します
 $rss->{output} = '1.0';
 print $rss->as_string;

=head1 説明

このモジュールはRDF Site Summary(RSS)の作成と管理のための基本的な
フレームワークを提供します。このディストリビューションにはさまざまな
例が入っています。それによりRSSからのHTMLの生成、0.9、0.91、1.0の間の
変換、その他の気の利いたことを可能にしてくれます。
これは、あなたのWebサイトにSlashdotやFreshmeatのような情報源からの
ニュースの提供をいれたいのであれば、あるいはあなた自身のコンテンツを
配信したいのであれば便利でしょう。

XML::RSSは現在、RSSの0.9、0.91、そして1.0バージョンをサポートしています。
RSS 0.91についての情報は http://my.netscape.com/publish/help/mnn20/quickstart.html
をご覧ください。RSS 0.90 については http://my.netscape.com/publish/help/　を
ご覧ください。RSS 1.0については http://purl.org/rss/1.0/ 。

RSSは初めはNetscapeによってNetscape Netcenterチャンネルのために開発されました。
しかし多くのWebサイトが、それ以来、簡単な配信フォーマットとして
それを採用してきました。RSS 1.0ができてからは、ユーザは今では
ニュースの見出し、スレッド化されたメッセージ、製品カタログなどを含めた
多くの異なる種類の配信が可能になりました。

=head1 メソッド

=over 4

=item new XML::RSS (version=>$version, encoding=>$encoding,
output=>$output)

XML::RSSのコンストラクタ。XML::RSSオブジェクトへのリファレンスを返します。
RSSのバージョンと使用するXMLエンコーディングを渡すこともできます。
デフォルトのB<version>は1.0です。デフォルトのB<encoding>はUTF-8です。
入力のバージョンとは関係なく出力(B<output>)フォーマットを指定することもできます。
これによりバージョン間でRSSを変換したいときに役に立ちます。<encode_output>を
設定すると、XML::RSSモジュールは生成されるRSSでのすべてのエンティティを確実に
エンコードします。現在では、これがデフォルトで有効になっています。

=item add_item (title=>$title, link=>$link, description=>$desc, mode=>$mode)

XML::RSSオブジェクトに要素を追加します。B<mode>とB<description>はオプションです。
デフォルトのB<mode>はappendで、これはその要素をリストの最後に追加します。
要素を挿入するためには、modeをB<insert>に設定してください。

要素は配列array @{$obj->{'items'}}に格納されます。ここでの
B<$obj>はXML::RSSオブジェクトへのリファレンスです。

=item as_string;

そのXML::RSSオブジェクトのためのRSSが入った文字列を返します。その
さい、このメソッドは特殊文字のエンコードも行います。

=item channel (title=>$title, link=>$link, description=>$desc,
language=>$language, rating=>$rating, copyright=>$copyright,
pubDate=>$pubDate, lastBuildDate=>$lastBuild, docs=>$docs,
managingEditor=>$editor, webMaster=>$webMaster)


RSSではチャンネル情報が必須です。RSS 0.9で出力するときには、
B<title>は40文字、B<link>は500文字、B<description>は500文字
よりも長くすることはできません。B<title>、 B<link>、そしてB<description>は
RSS 1.0が必須です。RSS 0.91ではB<language>が必須です。
そのほかのパラメータはRSS 0.91と1.0でのオプションです。

チャンネルの値を取り出すためには、以下のようにその値の
名前(title、linkあるいはdescription)を先頭で唯一の引数として
渡してください:

$title = channel('title');

=item image (title=>$title, url=>$url, link=>$link, width=>$width,
height=>$height, description=>$desc)

imegeを追加することは必須ではありません。B<url>は画像のURL、
B<link>はその画像がリンクされるURLです。B<title>、 B<url>、B<link>は
RSSファイルのなかでimageを使うのであれば必須です。残りのimage要素は
RSS 0.91で使われるか、rss091名前空間を通してオプションでRSS 1.0に
インポートされています。

imageのための値を取り出すための方法は、B<channel()>のための方法と
同じです。

=item parse ($string)

B<parse()>に先頭のパラメータとして渡された、RDF Site Summaryを解析します。

文字列が解析されるとき、自動的にモジュールを追加する命令については
add_module()メソッドをご覧ください。

=item parsefile ($file)

文字列ではなくファイルを解析するという点を除けばB<parse()>と同じです。

文字列が解析されるとき、自動的にモジュールを追加する命令については
add_module()メソッドをご覧ください。

=item save ($file)

指定されたファイルにRSSを保存します。

=item skipHours (hour=>$hour)

RSSファイルを取得する前にサーバーが待たなければならない時間数を
指定します。skipHoursメソッドを使うときには、B<hour>が必須です。
このメソッドは現在、壊れています。

=item skipDays (day=>$day)

RSSファイルを取得する前にサーバーが待たなければならない日数を
指定します。skipDaysメソッドを使うときには、B<day>が必須です。
このメソッドは現在、壊れています。

=item strict ($boolean)

1に設定されると、Netscape Netcenterの必要条件によって
指定されている長さを頑なに守ります。デフォルトでは0に設定されます。
あなたが生成するRSSファイルがNetcenterのためのものであれば、
これを使ってください。strictはRSS 0.9と0.91だけで機能します。
RSS 1.0では使わないでください。

=item textinput (title=>$title, description=>$desc, name=>$name, link=>$link);

このRSS要素もオプションです。これを使うとユーザにHTMLフォームを通して
Webサーバー上のプログラムに問い合わせを提示(submit)することができます。B<name>は
HTMLフォームの名前、B<link>はそのプログラムへのURLです。内容はGETメソッドを
使って提示されます。

B<textinput>の値にアクセスは、B<channel()>やB<image()>と同じです。

=item add_module(prefix=>$prefix, uri=>$uri)

XML::RSSオブジェクトにモジュール名前空間宣言を追加します。
これにより標準のRSS 1.0モジュールの外側にモジュールを追加することができます。
利便性を考え、現在、標準モジュールDublin Core (dc) と Syndication (syn) が
事前に定義されています。Taxonomy (taxo)も内部的にサポートされています。

モジュールはハッシュ %{$obj->{'modules'}}に格納されます。ここでの
B<$obj>はXML::RSSオブジェクトへのリファレンスです。

もしパーザーが見つけたモジュールを自動的に名前空間に追加したければ、
$XML::RSS::AUTO_ADD変数にtrue値を設定してください。デフォルトでは
その値はfalseです。

=back

=head2 RSS 1.0 モジュール

XML名前空間をベースとしたモジュール化によりRSS1.0に区画に仕切られた
拡張性を与えています。RSS 1.0で"あらかじめ"備えているモジュールは
Dublin Core (http://purl.org/rss/1.0/modules/dc/)、 Syndication
(http://purl.org/rss/1.0/modules/syndication/)、 そして Taxonomy
(http://purl.org/rss/1.0/modules/taxonomy/)だけです。更なる情報については
適切なモジュールのドキュメントにあたってください。

これらのモジュールからXML::RSSに要素を追加することは、title、link、そして
descriptionのような他の属性を追加することと同じくらい簡単です。違いは、
第2レベルのハッシュでそれらのキー/値のペアの区画分けだけです。

  $rss->add_item (title=>$title, link=>$link, dc=>{ subject=>$subject, creator=>$creator });

Dublin Coreモジュールの要素には、キー 'dc'を、
Syndicationモジュールの要素には'syn'、Taxonomyモジュールの要素には'taxo'を
使ってください。これらはRSS XML それ自身で使われる接頭辞です。
これらは適切なURIをベースとした名前空間で関連付けられます:

  syn:  http://purl.org/rss/1.0/modules/syndication/
  dc:   http://purl.org/dc/elements/1.1/
  taxo: http://purl.org/rss/1.0/modules/taxonomy/

Dublin Core 要素はchannel、item、textinputで発生するかもしれません
-- 例えimageやtextinputの下で見つけることがあまりなかったとしても。
Syndication要素はchannel要素に限られています。Taxonomyはchannelあるいは
item要素で発生することができます。

XML::RSSを使ってRSS 1.0ドキュメントを解析した後、モジュール要素への
アクセスは、あなたの都合に合わせて接頭辞あるいは名前空間URIのどちらかを
通してください。

  print $rss->{items}->[0]->{dc}->{subject};

  または

  print $rss->{items}->[0]->{'http://purl.org/dc/elements/1.1/'}->{subject};

XML::RSSは、channel、image、item、そしてtextinputレベルでの"標準ではない" RSS 1.0
モジュール化もサポートしています。RSSドキュメントの解析は、出現するかもしれない
他の名前空間の要素をすべて捕らえます。XML::RSSは、RSSドキュメントを構築するとき
任意の名前空間と関連付けられた要素を入れることも許しています。

例えば、作られた"My"モジュールの要素を追加するためには、まず接頭辞をURIに
関連付けることにより名前空間を宣言します:

  $rss->add_module(prefix=>'my', uri=>'http://purl.org/my/rss/module/');

それから通常通り続けていきます:

  $rss->add_item (title=>$title, link=>$link, my=>{ rating=>$rating });

しかし標準では名前空間は、現在のところ簡単な接頭辞を通してアクセスすることは
できません;それらの名前空間URLを通してアクセスしてください。そのため以下の
ようになります:

  print $rss->{items}->[0]->{'http://purl.org/my/rss/module/'}->{rating};

XML::RSSはそれらが現れたように標準のRSS 1.0 モジュールの組込みサポートを
提供し続けます。

=head1 ソースの取得場所(=SOURCE AVAILABILITY)

このソースはSourceForgeプロジェクトの一部となっており、そこでは
CVSに最新のソースが前のリリースと同様に入っています。

        https://sourceforge.net/projects/perl-rss/
        http://perl-rss.sourceforge.net

もし、私がこの世からいなくなっても、プロジェクトの他のメンバーの
だれかが、このモジュールを適切に導くことができます。

=head1 作者(=AUTHOR)

        元のコード: Jonathan Eisenzopf <eisen@pobox.com>
        さらなる変更: Rael Dornfest <rael@oreilly.com>
        
        現在: perl-rss project (http://perl-rss.sourceforge.net)


=head1 著作権(=COPYRIGHT)

Copyright (c) 2001 Jonathan Eisenzopf <eisen@pobox.com>
and Rael Dornfest <rael@oreilly.com>

XML::RSS is free software. You can redistribute it and/or
modify it under the same terms as Perl itself.

=head1 クレジット(=CREDITS)

 Wojciech Zwiefka <wojtekz@cnt.pl>
 Chris Nandor <pudge@pobox.com>
 Jim Hebert <jim@cosource.com>
 Randal Schwartz <merlyn@stonehenge.com>
 rjp@browser.org
 Kellan <kellan@protest.net>
 Rafe Colburn <rafe@rafe.us>
 Adam Trickett <adam.trickett@btinternet.com>
 Aaron Straup Cope <asc@vineyard.net>
 Ian Davis <iand@internetalchemy.org>

=head1 参考資料

perl(1), XML::Parser(3).