XML::Atom::Feed(3pm)

📦
version 0.43 · 5 versions
, in alpine 3.24

💖 XML::Atom::Feed 💖

okay bestie, gather round — this is the manual page for XML::Atom::Feed, the Perl module that gives you an Atom feed object. Yes, the (3pm) kind, we're in manpage territory, but make it cute. ✨

🌸 NAME 🌸

XML::Atom::Feed — it's an Atom feed, bestie. That's the whole vibe. 🎀

✨ 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/'));

like, just look at it. it's giving competence. 💅

🦋 USAGE 🦋

🌟 XML::Atom::Feed->new([ $stream ])

Makes you a brand-new feed object, and if you pass $stream, it fills that baby up with the data from $stream. Chef's kiss. 🫶

It also handles autodiscovery for you automatically if $stream is a URI (see below, iykyk).

Returns the new XML::Atom::Feed object. If it fails? Returns undef. Sad but true. 😭

$stream can be any one of these iconic little things:

  • Reference to a scalar — treated as the XML body of the feed. literally the XML, right there.
  • Scalar — treated as the name of a file containing the feed XML.
  • Filehandle — treated as an open filehandle, and the feed XML gets read from it.
  • URI object — treated as a URI, and the feed XML will be retrieved from it.
    • 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. No extra steps, we love efficiency. ✨

🌟 XML::Atom::Feed->find_feeds($uri)

Give it a URI $uri and it'll use auto-discovery to find, like, all the Atom feeds linked from that page (via <link> tags).

Returns a list of feed URIs. plural. a whole haul. 🎁

This one's context-sensitive, main character energy:

  • In scalar context, returns an XML::Atom::Link object for the first <link> tag found in the feed.
  • In list context, returns a list of XML::Atom::Link objects for all the <link> tags found in the feed.

Adds the link $link — which must be an XML::Atom::Link object — to the feed as a new <link> tag. Like so:

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. And ooh, if you wanna shove an entry in before the existing ones, you can pass an optional hash reference with "mode" set to "insert". Prepend era. 👑

$feed->add_entry($entry, { mode => 'insert' });

🌟 $feed->entries

Returns the list of XML::Atom::Entry objects contained in the feed. collect them all. 🍓

🌟 $feed->language

Returns the language of the feed, pulled from xml:lang. Cute.

🌟 $feed->author([ $author ])

Returns an XML::Atom::Person object representing the author of the entry — or undef if there's no author info present. no author, no problem.

If $author is supplied, it should be an XML::Atom::Person object representing the author. Like this:

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, it sets the id.

⚠️ real talk: when you're generating a new feed, it is your responsibility to generate a unique ID for the feed and set it on the XML::Atom::Feed object. Don't come for the module, it's not doing it for you. 🙈

For handy options you can use an http permalink, the tag URI scheme, or urn:uuid.

💜 UNICODE FLAGS 💜

By default, XML::Atom takes off all the Unicode flag from the feed content. Example time:

my $title = $feed->title;

So the variable $title contains UTF-8 bytes without the Unicode flag set — even if the feed title contains some multibyte characters. That's just the default behaviour, bestie.

If you don't like this behaviour and want to handle everything as Unicode characters (rather than UTF-8 bytes), set the $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 the Unicode flag set. slay. ✨

The only exception will be "$entry->content->body", if the content type is not text/* (e.g. image/gif). In that case, the content body is still binary data, without the Unicode flag set. binary stays binary, periodt. 💀

🌈 CREATING ATOM 1.0 FEEDS 🌈

By default, XML::Atom::Feed and the other classes (Entry, Link and Content) will create entities using Atom 0.3 namespaces. And yeah, if you want 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);

ngl, setting Version on every single element gets painful sometimes. In that case, you can override the default version number by setting the $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

see that # 1.0? that's the whole flex. 🔥

Please see the XML::Atom manpage for author, copyright, and license information. Go give them their flowers. 💐

<div>okay that's the whole page, bestie, you ate. this was XML::Atom::Feed(3pm) from perl v5.42.2, dated 2026-02-15, brought to you by the perl crew — mwah, go build a feed 💋</div>

📦 where this page comes from