GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  XML::RAI (3)

.ds Aq ’

NAME

XML::RAI - RSS Abstraction Interface.

CONTENTS

SYNOPSIS



 #!/usr/bin/perl -w
 use strict;
 use XML::RAI;
 my $doc = <<DOC;
 <?xml version="1.0" encoding="iso-8859-1"?>
 <rss xmlns:dc="http://purl.org/dc/elements/1.1/"
     xmlns="http://purl.org/rss/1.0/">
     <channel>
         <title>tima thinking outloud</title>
         <link>http://www.timaoutloud.org/</link>
         <description></description>
         <dc:language>en-us</dc:language>
         <item>
             <title>His and Hers Weblogs.</title>
             <description>First it was his and hers Powerbooks. Now
             its weblogs. There goes the neighborhood.</description>
             <link>http://www.timaoutloud.org/archives/000338.html</link>
             <dc:subject>Musings</dc:subject>
             <dc:creator>tima</dc:creator>
             <dc:date>2004-01-23T12:33:22-05:00</dc:date>
         </item>
         <item>
             <title>Commercial Music Again.</title>
             <description>Last year I made a post about music used
             in TV commercials that I recognized and have been listening to.
             For all the posts I made about technology and other bits of sagely
             wisdom the one on commercial music got the most traffic of any
             each month. I need a new top post. Here are some more tunes that
             have appeared in commercials.</description>
             <guid isPermaLink="true">
               http://www.timaoutloud.org/archives/000337.html
             </guid>
             <category>Musings</category>
             <author>tima</author>
             <pubDate>Sun, 18 Jan 2004 14:09:03 GMT</pubDate>
         </item>
     </channel>
 </rss>
 DOC

 # The above is to demonstrate the value of RAI. It is not any
 # specific RSS format, nor does it exercise best practices.

 my $rai = XML::RAI->parse_string($doc);
 print $rai->channel->title."\n\n";
 foreach my $item ( @{$rai->items} ) {
    print $item->title."\n";
    print $item->link."\n";
    print $item->content."\n";
    print $item->issued."\n\n";
 }



DESCRIPTION

The RSS Abstraction Interface, or RAI (said ray), provides an object-oriented interface to XML::RSS::Parser trees that abstracts the user from handling namespaces, overlapping and alternate tag mappings.

It’s rather well known that, while popular, the RSS syntax is a bit of a mess. Anyone who has attempted to write software that consumes RSS feeds in the wild can attest to the headaches in handling the many formats and interpretations that are in use. For instance, in The myth of RSS compatibility <http://diveintomark.org/archives/2004/02/04/incompatible-rss> Mark Pilgrim identifies 9 different versions of RSS (there are 10 actually[1]) and that is not without going into tags with overlapping purposes. Even the acronym RSS has multiple though similar meanings.

The XML::RSS::Parser alone attempts to help developers cope with these issues through a liberal interpretation of what is RSS and routines to normalize the parse tree into a more common and manageable form.

RAI takes this one step further. Its intent is to give a developer the means to not have to care about what tags the feed uses to present its meta data.

RAI provides a single simplified interface that maps one method call to various overlapping and alternate tags used in RSS feeds. The interface also abstracts developers from needing to deal with namespaces. Method names are based on Dublin Core terminology.

With the release of version 1.0, the XML::RSS::Parser distribution was folded into XML::RAI.

[1] When initially released, RSS 2.0 had a namespace. When it was reported a few days later that some XSLT-based systems were breaking because of the change in the RSS namespace from "" (none) to http://backend.userland.com/rss2, the namespace was removed, but the version number was not incremented making it incompatible with itself. <http://groups.yahoo.com/group/rss-dev/message/4113> This version was not counted in Mark’s post.

METHODS

XML::RAI->new($rss_tree) Returns a populated RAI instance based on the XML::RSS::Parser::Feed object passed in.
XML::RAI->parse($string_or_file_handle) Passes through the string or file handle to the parse method to either parse_file or parse_string in XML::RSS::Parser. Returns a populated RAI instance.

To maintain backwards compatability this method is <B>notB> inherited from the underlying SAX implementation.

XML::RAI->parse_file
XML::RAI->parse_string
XML::RAI->parse_uri A pass-thru to the underlying SAX implentation. See XML::SAX::Base for more on these methods.
$rai->document Returns the XML::RSS::Parser parse tree being used as the source for the RAI object
$rai->channel Returns the XML::RAI::Channel object.
$rai->items Returns an array reference containing the XML::RAI::Item objects for the feed
$rai->item_count Returns the number of items as an integer.
$rai->image Returns the XML::RAI::Image object, if any. (Many feeds do not have an image block.)
$rai->time_format($timef) Sets the timestamp normalization format. RAI will attempt to parse the string into a data value and will output timestamp (date) values in this format.

RAI implements a few constants with common RSS timestamp formatting strings:



 W3CDTF     1999-09-01T22:10:40Z
 RFC8601    (other name for W3CDTF)
 RFC822     Wed, 01 Sep 1999 22:10:40 GMT
 EPOCH      (Seconds since system epoch.)
 PASS_THRU  (timestamp as it appear in the source. does not normalize.)



W3CDTF/RFC8601 is the default. For more detail on creating your own timestamp formats see the manpage for the strftime command.

PLUGINS

With the introduction of the add_mapping and the register_ns_prefix method in the underlying XML::RSS::Parser, RAI now has a plugin API for easily extending its mappings.

To create a RAI plugin module, simply create a package with an import method that makes all of the necessary add_mapping and register_ns_prefix calls. For an example plugin module see XML::RAI::TrackBack

DEPENDENCIES

XML::RSS::Parser 4.0, Date::Parse 2.26, Date::Format 2.22

TO DO

o Add Atom elements into mappings.
o Serialization module(s).
o DATETIME (DateTime object) constants and functionality for time_format.

PARTICIPATION

I welcome and accept patches in diff format. If you wish to hack on this code, please fork the git repository found at: <http://github.com/tima/perl-xml-rai/>

If you have something to push back to my repository, just use the pull request button on the github site.

LICENSE

The software is released under the Artistic License. The terms of the Artistic License are described at <http://www.perl.com/language/misc/Artistic.html>.

AUTHOR & COPYRIGHT

Except where otherwise noted, XML::RAI is Copyright 2003-2009, Timothy Appnel, tima@cpan.org. All rights reserved.

POD ERRORS

Hey! <B>The above document had some coding errors, which are explained below:B>
Around line 96: =begin without a target?
Around line 200: ’=item’ outside of any ’=over’
Around line 264: You forgot a ’=back’ before ’=head1’
Around line 316: ’=end’ without a target?
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 XML::RAI (3) 2009-08-14

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.