NAME

XML::RSS::Parser - A liberal object-oriented parser for RSS feeds.

SYNOPSIS

#!/usr/bin/perl -w

use strict; 
use XML::RSS::Parser;

my $p = new XML::RSS::Parser; 
my $feed = $p->parsefile('/path/to/some/rss/file');

# output some values 
my $feed_title = $feed->query('/channel/title');
print $feed_title->text_content;
my $count = $feed->item_count;
print " ($count)\n";
foreach my $i ( $feed->query('//item') ) { 
    my $node = $i->query('title');
    print '  '.$node->text_content;
    print "\n"; 
}

DESCRIPTION

XML::RSS::Parser is a lightweight liberal parser of RSS feeds. This parser is "liberal" in that it does not demand compliance of a specific RSS version and will attempt to gracefully handle tags it does not expect or understand. The parser's only requirements is that the file is well-formed XML and remotely resembles RSS. Roughly speaking, well formed XML with a channel element as a direct sibling or the root tag and item elements etc.

There are a number of advantages to using this module then just using a standard parser-tree combination. There are a number of different RSS formats in use today. In very subtle ways these formats are not entirely compatible from one to another. XML::RSS::Parser makes a couple assumptions to "normalize" the parse tree into a more consistent form. For instance, it forces channel and item into a parent-child relationship. For more detail see "SPECIAL PROCESSING NOTES".

This module is leaner then XML::RSS -- the majority of code was for generating RSS files. It also provides a XPath-esque interface to the feed's tree.

While XML::RSS::Parser creates a normalized parse tree, it still leaves the mapping of overlapping and alternate tags common in the RSS format space to the developer. For this look at the XML::RAI (RSS Abstraction Interface) package which provides an object-oriented layer to XML::RSS::Parser trees that transparently maps these various tags to one common interface.

Your feedback and suggestions are greatly appreciated. See the "TO DO" section for some brief thoughts on next steps.

SPECIAL PROCESSING NOTES

There are a number of different RSS formats in use today. In very subtle ways these formats are not entirely compatible from one to another. What's worse is that there are unlabeled versions within the standard in addition to tags with overlapping purposes and vague definitions. (See Mark Pilgrim's "The myth of RSS compatibility" http://diveintomark.org/archives/2004/02/04/incompatible-rss for just a sampling of what I mean.) To ease working with RSS data in different formats, the parser does not create the feed's parse tree verbatim. Instead it makes a few assumptions to "normalize" the parse tree into a more consistent form.

With the refactoring of this module and the switch to a true tree structure, the normalization process has been simplified. Some of the version 2x proved to be problematic with more advanced and complex feeds.

• The RSS namespace (if any) is extracted from the first sibling of the root tag. We don't use the root tag because in RSS 1.0 the root tag is in the RDF namespace and not RSS. That namespace is treated as the '#default' (no prefix) namespace for the parse tree.

• The parser will not include the root tags of rss or RDF in the tree. Namespace declaration information is still extracted. The version attribute, if defined, is moved to the channel element.

• The parser forces channel and item into a parent-child relationship. In versions 0.9 and 1.0, channel and item tags are siblings.

METHODS

The following objects and methods are provided in this package.

XML::RSS::Parser->new

Constructor. Returns a reference to a new XML::RSS::Parser object.

$parser->parse(source)

Inherited from XML::Parser, the SOURCE parameter should either open an IO::Handle or a string containing the whole XML document. A die call is thrown if a parse error occurs otherwise it will return a XML::RSS::Parser::Feed object.

$parser->parsefile(file)

Inherited from XML::Parser, FILE is an open handle. The file is closed no matter how parse returns. A die call is thrown if a parse error occurs otherwise it will return a XML::RSS::Parser::Feed object.

XML::RSS::Parser->ns_qualify(element, namesapce_uri)

An simple utility method implemented as an abstract method that will return a fully namespace qualified string for the supplied element.

DEPENDENCIES

XML::Parser, XML::Elemental, Class::XPath 1.4*

Versions up to 1.4 have a design flaw that would cause it to choke on feeds with the / character in an attribute value. For example the Yahoo! feeds.

SEE ALSO

XML::RAI

The Feed Validator http://www.feedvalidator.org/

What is RSS? http://www.xml.com/pub/a/2002/12/18/dive-into-xml.html

Raising the Bar on RSS Feed Quality "/www.oreillynet.com/pub/a/webservices/2002/11/19/ rssfeedquality.html" in http:

The myth of RSS compatibility http://diveintomark.org/archives/2004/02/04/incompatible-rss

TO DO

• Add whitespace filtering switch.

AUTHOR & COPYRIGHT

Please see the XML::RAI manpage for author, copyright, and license information.

cpanm XML::RAI

perl -MCPAN -e shell
install XML::RAI