MAN page from Other perl-XML-RSS-1.02-1.i386.rpm

RSS

Section: User Contributed Perl Documentation (3)
Updated: 2003-02-20
Index

NAME

XML::RSS - creates and updates RSS files

SYNOPSIS

 # create an RSS 1.0 file (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    => 'scoopAATTfreshmeat.net',     publisher  => 'scoopAATTfreshmeat.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", );

 # Optionally mixing in elements of a non-standard 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 });

 # create an RSS 0.91 file 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 => 'scoopAATTfreshmeat.net',               webMaster      => 'scoopAATTfreshmeat.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"                 );

 # create an RSS 0.9 file 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"                 );

 # print the RSS as a string print $rss->as_string;

 # or save it to a file $rss->save("fm.rdf");

 # insert an item into an RSS file and removes the oldest item if # there are already 15 items 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'                );

 # parse a string instead of a file $rss->parse($string);

 # print the title and link of each RSS item foreach my $item (@{$rss->{'items'}}) {     print "title: $item->{'title'}\n";     print "link: $item->{'link'}\n\n"; }

 # output the RSS 0.9 or 0.91 file as RSS 1.0 $rss->{output} = '1.0'; print $rss->as_string;

DESCRIPTION

This module provides a basic framework for creating and maintainingRDF Site Summary (RSS) files. This distribution also contains manyexamples that allow you to generate HTML from an RSS, convert between0.9, 0.91, and 1.0 version, and other nifty things.This might be helpful if you want to include news feeds on your Website from sources like Slashot and Freshmeat or if you want to syndicateyour own content.

XML::RSS currently supports 0.9, 0.91, and 1.0 versions of RSS.See http://my.netscape.com/publish/help/mnn20/quickstart.htmlfor information on RSS 0.91. See http://my.netscape.com/publish/help/for RSS 0.9. See http://purl.org/rss/1.0/ for RSS 1.0.

RSS was originally developed by Netscape as the format forNetscape Netcenter channels, however, many Web sites have sinceadopted it as a simple syndication format. With the advent of RSS 1.0,users are now able to syndication many different kinds of contentincluding news headlines, threaded measages, products catalogs, etc.

METHODS

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

Constructor for XML::RSS. It returns a reference to an XML::RSS object.You may also pass the RSS version and the XML encoding to use. The defaultversion is 1.0. The default encoding is UTF-8. You may also specifythe output format regarless of the input version. This comes in handywhen you want to convert RSS between versions. The XML::RSS moduleswill convert between any of the formats. If you set <encode_output> XML::RSSwill make sure to encode any entities in generated RSS. This is now on by default.

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

Adds an item to the XML::RSS object. mode and description are optional.The default modeis append, which adds the item to the end of the list. To insert an item, set the modeto insert.

The items are stored in the array @{$obj->{'items'}} where$obj is a reference to an XML::RSS object.

as_string;

Returns a string containing the RSS for the XML::RSS object. Thismethod will also encode special characters along the way.

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

Channel information is required in RSS. The title cannotbe more the 40 characters, the link 500, and the description500 when outputting RSS 0.9. title, link, and description,are required for RSS 1.0. language is required for RSS 0.91.The other parameters are optional for RSS 0.91 and 1.0.

To retreive the values of the channel, pass the name of the value(title, link, or description) as the first and only argumentlike so:

$title = channel('title');

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

Adding an image is not required. url is the URL of theimage, link is the URL the image is linked to. title, url,and link parameters are required if you are going touse an image in your RSS file. The remaining image elements are usedin RSS 0.91 or optionally imported into RSS 1.0 via the rss091 namespace.

The method for retrieving the values for the image is the same as itis for channel().

parse ($string)

Parses an RDF Site Summary which is passed into parse() as the first parameter.

See the add_module() method for instructions on automatically addingmodules as a string is parsed.

parsefile ($file)

Same as parse() except it parses a file rather than a string.

See the add_module() method for instructions on automatically addingmodules as a string is parsed.

save ($file)

Saves the RSS to a specified file.

skipHours (hour=>$hour)

Specifies the number of hours that a server should wait before retrievingthe RSS file. The hour parameter is required if the skipHours methodis used. This method is currently broken.

skipDays (day=>$day)

Specified the number of days that a server should wait before retrievingthe RSS file. The day parameter is required if the skipDays methodis used. This method is currently broken.

strict ($boolean)

If it's set to 1, it will adhere to the lengths as specifiedby Netscape Netcenter requirements. It's set to 0 by default.Use it if the RSS file you're generating is for Netcenter.strict will only work for RSS 0.9 and 0.91. Do not use it forRSS 1.0.

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

This RSS element is also optional. Using it allows users to submit a Queryto a program on a Web server via an HTML form. name is the HTML form nameand link is the URL to the program. Content is submitted using the GETmethod.

Access to the textinput values is the the same as channel() andimage().

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

Adds a module namespace declaration to the XML::RSS object, allowing youto add modularity outside of the the standard RSS 1.0 modules. At present,the standard modules Dublin Core (dc) and Syndication (syn) are predefinedfor your convenience. The Taxonomy (taxo) module is also internally supported.

The modules are stored in the hash %{$obj->{'modules'}} where$obj is a reference to an XML::RSS object.

If you want to automatically add modules that the parser finds innamespaces, set the $XML::RSS::AUTO_ADD variable to a true value. Bydefault the value is false.

RSS 1.0 MODULES

XML-Namespace-based modularization affords RSS 1.0 compartmentalizedextensibility. The only modules that ship ``in the box'' with RSS 1.0are Dublin Core (http://purl.org/rss/1.0/modules/dc/), Syndication(http://purl.org/rss/1.0/modules/syndication/), and Taxonomy(http://purl.org/rss/1.0/modules/taxonomy/). Consult the appropriatemodule's documentation for further information.

Adding items from these modules in XML::RSS is as simple as adding otherattributes such as title, link, and description. The only differenceis the compartmentalization of their key/value paris in a second-levelhash.

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

For elements of the Dublin Core module, use the key 'dc'. For elementsof the Syndication module, 'syn'. For elements of the Taxonomy module,'taxo'. These are the prefixes used in the RSS XML document itself.They are associated with appropriate URI-based namespaces:

  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 elements may occur in channel, image, item(s), and textinput--- albeit uncomming to find them under image and textinput. Syndicationelements are limited to the channel element. Taxonomy elements can occurin the channel or item elements.

Access to module elements after parsing an RSS 1.0 document usingXML::RSS is via either the prefix or namespace URI for your convenience.

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

or

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

XML::RSS also has support for ``non-standard'' RSS 1.0 modularization atthe channel, image, item, and textinput levels. Parsing an RSS documentgrabs any elements of other namespaces which might appear. XML::RSSalso allows the inclusion of arbitrary namespaces and associated elementswhen building RSS documents.

For example, to add elements of a made-up ``My'' module, first declare thenamespace by associating a prefix with a URI:

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

Then proceed as usual:

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

Non-standard namespaces are not, however, currently accessible via a simpleprefix; access them via their namespace URL like so:

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

XML::RSS will continue to provide built-in support for standard RSS 1.0modules as they appear.

SOURCE AVAILABILITY

This source is part of a SourceForge project which always has thelatest sources in CVS, as well as all of the previous releases.

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

If, for some reason, I disappear from the world, one of the othermembers of the project can shepherd this module appropriately.

AUTHOR

        Original code: Jonathan Eisenzopf <eisenAATTpobox.com>        Further changes: Rael Dornfest <raelAATToreilly.com>

        Currently: perl-rss project (http://perl-rss.sourceforge.net)

COPYRIGHT

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

CREDITS

 Wojciech Zwiefka <wojtekzAATTcnt.pl> Chris Nandor <pudgeAATTpobox.com> Jim Hebert <jimAATTcosource.com> Randal Schwartz <merlynAATTstonehenge.com> rjpAATTbrowser.org Kellan <kellanAATTprotest.net> Rafe Colburn <rafeAATTrafe.us> Adam Trickett <adam.trickettAATTbtinternet.com> Aaron Straup Cope <ascAATTvineyard.net> Ian Davis <iandAATTinternetalchemy.org>

This document was created byman2html,using the manual pages.

RSS