NAME¶
XML::Atom::Feed - Atom feed
SYNOPSIS¶
use XML::Atom::Feed;
use XML::Atom::Entry;
my $feed = XML::Atom::Feed->new;
$feed->title('My Weblog');
$feed->id('tag:example.com,2006:feed-id');
my $entry = XML::Atom::Entry->new;
$entry->title('First Post');
$entry->id('tag:example.com,2006:entry-id');
$entry->content('Post Body');
$feed->add_entry($entry);
$feed->add_entry($entry, { mode => 'insert' });
my @entries = $feed->entries;
my $xml = $feed->as_xml;
## Get a list of the <link rel="..." /> tags in the feed.
my $links = $feed->link;
## Find all of the Atom feeds on a given page, using auto-discovery.
my @uris = XML::Atom::Feed->find_feeds('http://www.example.com/');
## Use auto-discovery to load the first Atom feed on a given page.
my $feed = XML::Atom::Feed->new(URI->new('http://www.example.com/'));
USAGE¶
XML::Atom::Feed->new([ $stream ])¶
Creates a new feed object, and if
$stream is supplied,
fills it with the data specified by
$stream.
Automatically handles autodiscovery if
$stream is a URI
(see below).
Returns the new
XML::Atom::Feed object. On failure, returns
"undef".
$stream can be any one of the following:
- •
- Reference to a scalar
This is treated as the XML body of the feed.
- •
- Scalar
This is treated as the name of a file containing the feed XML.
- •
- Filehandle
This is treated as an open filehandle from which the feed XML can be
read.
- •
- URI object
This is treated as a URI, and the feed XML will be retrieved from the URI.
If the content type returned from fetching the content at URI is
text/html, this method will automatically try to perform
auto-discovery by looking for a <link> tag describing the
feed URL. If such a URL is found, the feed XML will be automatically
retrieved.
If the URI is already of a feed, no auto-discovery is necessary, and the
feed XML will be retrieved and parsed as normal.
XML::Atom::Feed->find_feeds($uri)¶
Given a URI
$uri, use auto-discovery to find all of the
Atom feeds linked from that page (using
<link> tags).
Returns a list of feed URIs.
$feed->link¶
If called in scalar context, returns an
XML::Atom::Link object
corresponding to the first
<link> tag found in the feed.
If called in list context, returns a list of
XML::Atom::Link objects
corresponding to all of the
<link> tags found in the feed.
$feed->add_link($link)¶
Adds the link
$link, which must be an
XML::Atom::Link object, to the feed as a new
<link> tag.
For example:
my $link = XML::Atom::Link->new;
$link->type('text/html');
$link->rel('alternate');
$link->href('http://www.example.com/');
$feed->add_link($link);
$feed->add_entry($entry)¶
Adds the entry
$entry, which must be an
XML::Atom::Entry object, to the feed. If you want to add an entry
before existent entries, you can pass optional hash reference containing
"mode" value set to "insert".
$feed->add_entry($entry, { mode => 'insert' });
$feed->entries¶
Returns list of XML::Atom::Entry objects contained in the feed.
$feed->language¶
Returns the language of the feed, from
xml:lang.
$feed->author([ $author ])¶
Returns an
XML::Atom::Person object representing the author of the entry,
or "undef" if there is no author information present.
If
$author is supplied, it should be an
XML::Atom::Person object representing the author. For example:
my $author = XML::Atom::Person->new;
$author->name('Foo Bar');
$author->email('foo@bar.com');
$feed->author($author);
$feed->id([ $id ])¶
Returns an id for the feed. If
$id is supplied, set the id.
When generating the new feed, it is your responsibility to generate unique ID
for the feed and set to XML::Atom::Feed object. You can use
http
permalink,
tag URI scheme or
urn:uuid for handy.
UNICODE FLAGS¶
By default, XML::Atom takes off all the Unicode flag fro mthe feed content. For
example,
my $title = $feed->title;
the variable $title contains UTF-8 bytes without Unicode flag set, even if the
feed title contains some multibyte chracters.
If you don't like this behaviour and wants to andle everything as Unicode
characters (rather than UTF-8 bytes), set $XML::Atom::ForceUnicode flag to 1.
$XML::Atom::ForceUnicode = 1;
then all the data returned from XML::Atom::Feed object and XML::Atom::Entry
object etc., will have Unicode flag set.
The only exception will be "$entry->content->body", if content
type is not text/* (e.g. image/gif). In that case, the content body is still
binary data, without Unicode flag set.
CREATING ATOM 1.0 FEEDS¶
By default, XML::Atom::Feed and other classes (Entry, Link and Content) will
create entities using Atom 0.3 namespaces. In order to create 1.0 feed and
entry elements, you can set
Version as a parameter, like:
$feed = XML::Atom::Feed->new(Version => 1.0);
$entry = XML::Atom::Entry->new(Version => 1.0);
Setting those Version to every element would be sometimes painful. In that case,
you can override the default version number by setting
$XML::Atom::DefaultVersion global variable to "1.0".
use XML::Atom;
$XML::Atom::DefaultVersion = "1.0";
my $feed = XML::Atom::Feed->new;
$feed->title("blah");
my $entry = XML::Atom::Entry->new;
$feed->add_entry($entry);
$feed->version; # 1.0
AUTHOR & COPYRIGHT¶
Please see the
XML::Atom manpage for author, copyright, and license
information.