NAME

XML::Atom::Syndication - a simple lightweight client for consuming Atom syndication feeds.

SYNOPSIS

 #!/usr/bin/perl -w
 use XML::Atom::Syndication;
 my $atomic = XML::Atom::Syndication->instance;
 my $doc = $atomic->get('http://www.timaoutloud.org/xml/atom.xml');
 my($feed_title)= $doc->query('/feed/title');
 print $feed_title->text_value."\n\n";
 foreach ($doc->query('//entry')) {
     print $_->query('title')->text_value."\n";
     print $_->query('summary')->text_value."\n";
     print $_->query('link/@href')."\n\n";
 }

 XML::Atom::Syndication->xpath_namespace('tima','http://www.timaoutloud.org/');
 print XML::Atom::Syndication->xpath_namespace('http://www.timaoutloud.org/')."\n";
 print XML::Atom::Syndication->xpath_namespace('tima')."\n";

DESCRIPTION

While the real strength of the Atom effort is the API and its unified format, retreiving feeds over HTTP and consuming their contents, similar like with RSS, will be a common use. The module endeavors to provide developers with a package that is simple, lightweight and easy install.

Development began with two primary goals:

To create something simpler and more lightweight then using XML::Atom for the specific and common purpose of fetching Atom feeds.

To see how quickly and easily I could cobble together such a package with existing modules.

The latter of these goals will be less of a focus going forward. That experiment has run its course. It went together quite easier and having developed the XML::RSS::Parser and XML::RAI modules, Atom data is much easier to process and use.

While keeping things simple was a priority, the XPath online interface may be a bit too spartan. Going forward, refining this interface so it is easier to work with will be a priority. (Feedback is appreciated.)

This interface is still somewhat in flux and is subject to change.

METHODS

XML::Atom::Syndication->instance

Returns the XML::Atom::Syndication singleton.

$instance->parse($text|IO_HANDLE)

Pass through to the parse method of the XML::Parser instance being used by the client. Returns the root XML::Atom::Syndication::Element object for the feed.

$instance->parse_file(FILE_HANDLE)

Pass through to the parsefile method of the XML::Parser instance being used by the client. Returns the root XML::Atom::Syndication::Element object for the feed.

$instance->get($url[,$file])

A method for fetching an Atom feed and parsing it. If an optional file name is provided, the method will mirror the feed to the file system location that is specified. Like the parse methods, returns the root XML::Atom::Syndication::Element object for the feed.

$XML::Atom::Syndication->xpath_namespace($prefix,$uri)

$XML::Atom::Syndication->xpath_namespace($prefix)

$XML::Atom::Syndication->xpath_namespace($uri)

A class method accessor to the XPath namespace mappings. XPath query namespaces declarations are independant of the document it is querying. By default this module contains the followiing declarations:

 (default/no prefix) http://purl.org/atom/ns#
 dc                  http://purl.org/dc/elements/1.1/
 dcterms             http://purl.org/dc/terms/
 sy                  http://purl.org/rss/1.0/modules/syndication/
 trackback           http://madskills.com/public/xml/rss/module/trackback/
 xhtml               http://www.w3.org/1999/xhtml/
 xml                 http://www.w3.org/XML/1998/namespace/

To add or modify a mapping, call this method with the prefix and then URI to be registered. To lookup the associated URI of a prefix just pass in the prefix string. If a URI is passed in then the associated prefix is returned. In either case undef will be returned if no value has been set.

DEPENDENCIES

XML::Parser, XML::Parser::Style::Elemental, Class::XPath, LWP::Simple

SEE ALSO

XML::Atom::Syndication::Document, XML::Atom::Syndication::Element, XML::Atom::Syndication::Characters, XML::Atom

AtomEnabled Alliance - http://www.atomenabled.org/

atom-syntax mailing list - http://www.imc.org/atom-syntax/

BUGS

• Handling of unregistered XPath namespaces is incorrect.

• Will complain if LWP::Simple::mirror call in get fails.

TO DO

• Refine the interface. Feedback appreciated.

• Implement auto-discovery find method.

• Implement a means of passing through unescaped content markup if desired. (This would be helpful with unescaped content blocks.) Or perhaps an as_xml method using XML::Generator?

• Implement means of LWP status/error reporting with get.

• Implement ETag support within get. LWP::Simple mirror only uses last-modified headers which are not always available with dynamic content.

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::Atom::Syndication is Copyright 2004, Timothy Appnel, cpan@timaoutloud.org. All rights reserved.