Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
XML::RAI(3)	      User Contributed Perl Documentation	   XML::RAI(3)

NAME
       XML::RAI	- RSS Abstraction Interface.

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 not 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! The	above document had some	coding errors, which are explained
       below:

       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?

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

NAME | SYNOPSIS | DESCRIPTION | METHODS | PLUGINS | DEPENDENCIES | TO DO | PARTICIPATION | LICENSE | AUTHOR & COPYRIGHT | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XML::RAI&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help