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    => '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",
   },
 );

 $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)",
   },
 );

 $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.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 => '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"
                 );

 # 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 maintaining RDF Site Summary (RSS) files. This distribution also contains many examples that allow you to generate HTML from an RSS, convert between 0.9, 0.91, and 1.0 version, and other nifty things. This might be helpful if you want to include news feeds on your Web site from sources like Slashot and Freshmeat or if you want to syndicate your 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.html for 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 for Netscape Netcenter channels, however, many Web sites have since adopted it as a simple syndication format. With the advent of RSS 1.0, users are now able to syndication many different kinds of content including 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 default version is 1.0. The default encoding is UTF-8. You may also specify the output format regarless of the input version. This comes in handy when you want to convert RSS between versions. The XML::RSS modules will convert between any of the formats.

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 mode is append, which adds the item to the end of the list. To insert an item, set the mode to 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.

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 cannot be more the 40 characters, the link 500, and the description 500 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 argument like 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 the image, link is the URL the image is linked to. title, url, and link parameters are required if you are going to use an image in your RSS file. The remaining image elements are used in 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 it is for channel().

parse ($string)

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

parsefile ($file)

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

save ($file)

Saves the RSS to a specified file.

skipHours (hour=>$hour)

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

skipDays (day=>$day)

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

strict ($boolean)

If it's set to 1, it will adhere to the lengths as specified by 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 for RSS 1.0.

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

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

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

RSS 1.0 MODULES

XML-Namespace-based modularization affords RSS 1.0 compartmentalized extensibility. The only modules that ship "in the box" with RSS 1.0 are Dublin Core (http://purl.org/rss/1.0/modules/dc/) and Syndication (http://purl.org/rss/1.0/modules/syndication/). Consult the appropriate module's documentation for further information.

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

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

For elements of the Dublin Core module, use the key 'dc'. For elements of the Syndication module, 'syn'. 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/

Dublin Core elements may occur in channel, image, item(s), and textinput -- albeit uncomming to find them under image and textinput. Syndication elements are limited to the channel element.

Access to module elements after parsing an RSS 1.0 document using XML::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};

For future extensibility, XML::RSS will grab elements of other namespaces which appear in an RSS 1.0 document. They are not, however, currently accessible via a simple prefix; access them via their namespace URL like so:

print $rss->{items}->[0]->{'http://purl.org/foo/elements/0.0/'}->{bar};

XML::RSS does not at this time support insertion of non-standard module data into created RSS documents.

AUTHOR

Jonathan Eisenzopf <eisen@pobox.com>

CREDITS

Wojciech Zwiefka <wojtekz@cnt.pl>
Chris Nandor <pudge@pobox.com>
Jim Hebert <jim@cosource.com>
Randal Schwartz <merlyn@stonehenge.com>
rjp@browser.org
Rael Dornfest <rael@oreilly.com>

SEE ALSO

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