rss(3)

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",
  },
  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 => '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'}0;
    print "link: $item->{'link'}0;
}
# 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 distribu
tion also contains many examples that allow you to gener
ate 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 syn
dicate 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/quick
start.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, out
put=>$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 spec ify 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 descrip tion 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=>$copy
right, pubDate=>$pubDate, lastBuildDate=>$lastBuild,
docs=>$docs, managingEditor=>$editor, webMaster=>$webMas
ter)

Channel information is required in RSS. The title can
not 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 cchhaannnneell(()).

parse ($string)

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

parsefile ($file)

Same as ppaarrssee(()) 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 gener
ating 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 cchhaannnneell(()) and iimmaaggee(()).

add_module(prefix=>$prefix, uri=>$uri) Adds a module
namespace declaration to the XML::RSS object, allowing you
to add modularity outside of the the standard RSS 1.0 mod
ules. At present, the standard modules Dublin Core (dc)
and Syndication (syn) are predefined for your convenience.
The Taxonomy (taxo) module is also internally supported.

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

For more information on RSS 1.0 Modules, read on.

RSS 1.0 MODULES

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

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 compartmentaliza
tion of their key/value paris in a second-level hash.

$rss->add_item (title=>$title, link=>$link, dc=>{ sub

ject=>$subject, creator=>$creator });

For elements of the Dublin Core module, use the key 'dc'.
For elements of the Syndication module, 'syn'. For ele
ments of the Taxonomy module, 'taxo'. These are the pre
fixes used in the RSS XML document itself. They are asso
ciated 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. Syndication elements are limited to the
channel element. Taxonomy elements can occur in the chan
nel or item elements.

Access to module elements after parsing an RSS 1.0 docu
ment 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/ele

ments/1.1/'}->{subject};

XML::RSS also has support for "non-standard" RSS 1.0 modu
larization at the channel, image, item, and textinput lev
els. Parsing an RSS document grabs any elements of other
namespaces which might appear. XML::RSS also allows the
inclusion of arbitrary namespaces and associated elements
when building RSS documents.

For example, to add elements of a made-up "My" module,
first declare the namespace 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=>{ rat

ing=>$rating });

Non-standard namespaces are not, however, currently acces
sible via a simple prefix; access them via their namespace
URL like so:

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

ule/'}->{rating};

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

AUTHOR

Jonathan Eisenzopf <eisen@pobox.com> Rael Dornfest
<rael@oreilly.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

SEE ALSO

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

perl v5.8.0 2001-03-22 RSS(3)