XML::FeedPP(3pm)

📦
version 0.95 · 5 versions
, in ubuntu jammy, ubuntu noble

okay so bestie, you just typed man XML::FeedPP and now you're here, in the User Contributed Perl Documentation section, and honestly?? this module is a whole main character. Let me walk you through it like we're texting at 1am. 💖

✨ NAME ✨

XML::FeedPP — Parse/write/merge/edit RSS/RDF/Atom syndication feeds. 🦋

🌸 SYNOPSIS 🌸

Scenario one: grab an RSS file and parse it. Literally that easy:

use XML::FeedPP ();
my $source = 'http://use.perl.org/index.rss';
my $feed = XML::FeedPP->new( $source );
print "Title: ", $feed->title(), "\n";
print "Date: ", $feed->pubDate(), "\n";
foreach my $item ( $feed->get_item() ) {
    print "URL: ", $item->link(), "\n";
    print "Title: ", $item->title(), "\n";
}

Scenario two: generate an RDF file and save it:

use XML::FeedPP ();
my $feed = XML::FeedPP::RDF->new();
$feed->title( "use Perl" );
$feed->link( "http://use.perl.org/" );
$feed->pubDate( "Thu, 23 Feb 2006 14:43:43 +0900" );
my $item = $feed->add_item( "http://search.cpan.org/~kawasaki/XML-TreePP-0.02" );
$item->title( "Pure Perl implementation for parsing/writing xml file" );
$item->pubDate( "2006-02-23T14:43:43+09:00" );
$feed->to_file( "index.rdf" );

Scenario three: convert some RSS/RDF files to Atom format:

use XML::FeedPP ();
my $feed = XML::FeedPP::Atom::Atom10->new();        # create empty atom file
$feed->merge( "rss.xml" );                          # load local RSS file
$feed->merge( "http://www.kawa.net/index.rdf" );    # load remote RDF file
my $now = time();
$feed->pubDate( $now );                             # touch date
my $atom = $feed->to_string();                      # get Atom source code

💅 DESCRIPTION 💅

XML::FeedPP is an all-purpose syndication utility that parses and publishes RSS 2.0, RSS 1.0 (RDF), Atom 0.3 and 1.0 feeds. It lets you add new content, merge feeds, and convert among these various formats. It's a pure Perl implementation and doesn't require any other module except for XML::TreePP. No cap. 🫶

🔥 METHODS FOR FEED 🔥

$feed = XML::FeedPP->new( "index.rss" );

This constructor method creates an XML::FeedPP feed instance. The only argument is the local filename. The format of $source must be one of the supported feed formats — RSS, RDF or Atom — or execution is halted. 💀 fr fr, it just stops.

$feed = XML::FeedPP->new( "http://use.perl.org/index.rss" );

The URL on the remote web server is also available as the first argument. Heads up: LWP::UserAgent is required to download it.

$feed = XML::FeedPP->new( '<rss version="2.0">...' );

The XML source code itself is also available as the first argument. Iconic, honestly.

$feed = XML::FeedPP->new( $source, -type => $type );

The -type argument lets you specify the type of $source, from a choice of 'file', 'url' or 'string'. ✨

$feed = XML::FeedPP->new( $source, utf8_flag => 1 );

This makes the utf8 flag on for all feed elements. Perl 5.8.1 or later is required to use this one, so check your version bestie.

Note that any other options for the XML::TreePP constructor are also allowed, like this. See more detail on XML::TreePP.

$feed = XML::FeedPP::RSS->new( $source );

This constructor method creates an instance for an RSS 2.0 feed. The first argument is optional, but must be a valid RSS source if you specify one. This method returns an empty instance when $source is undefined. 🎀

$feed = XML::FeedPP::RDF->new( $source );

This constructor method creates an instance for an RSS 1.0 (RDF) feed. The first argument is optional, but must be an RDF source if you specify one. This method returns an empty instance when $source is undefined.

$feed = XML::FeedPP::Atom->new( $source );

This constructor method creates an instance for an Atom 0.3/1.0 feed. The first argument is optional, but must be an Atom source if you specify one. This method returns an empty instance when $source is undefined.

Atom 1.0 feeds are also supported since XML::FeedPP version 0.30. Atom 0.3 is still the default, however — but future versions of this module would create Atom 1.0 as the default. iykyk 👀

$feed = XML::FeedPP::Atom::Atom03->new();

This creates an empty Atom 0.3 instance, obviously. 💅

$feed = XML::FeedPP::Atom::Atom10->new();

This creates an empty Atom 1.0 instance, as intended. 🌟

This creates an RSS instance which has link, title elements etc.

$feed->load( $source );

This method loads an RSS/RDF/Atom file, much like the new() method does. Same energy, different name. 🦋

$feed->merge( $source );

This method merges an RSS/RDF/Atom file into the existing $feed instance. Top-level metadata from the imported feed is incorporated only if missing from the present feed — so it won't stomp what you already have. periodt.

$string = $feed->to_string( $encoding );

This method generates XML source as a string and returns it. The output $encoding is optional, and the default encoding is 'UTF-8'. On Perl 5.8 and later, any encodings supported by the Encode module are available. On Perl 5.005 and 5.6.1, only four encodings supported by the Jcode module are available: 'UTF-8', 'Shift_JIS', 'EUC-JP' and 'ISO-2022-JP'. 'UTF-8' is recommended for overall compatibility. 🫶

$string = $feed->to_string( indent => 4 );

This makes the output more human readable by indenting appropriately. It does not strictly follow the XML specification, but it does look nice. ✨ aesthetic over spec, we respect it.

Note that any other options for the XML::TreePP constructor are also allowed, like this. See more detail on XML::TreePP.

$feed->to_file( $filename, $encoding );

This method generates an XML file. The output $encoding is optional, and the default is 'UTF-8'.

This method creates a new item/entry and returns its instance. The mandatory $link argument is the URL of the new item/entry.

$item = $feed->add_item( $srcitem );

This method duplicates an item/entry and adds it to $feed. $srcitem is a XML::FeedPP::*::Item class's instance, which is returned by the get_item() method, as described above. ♻️

This method creates a new item/entry which has link, title elements etc.

$item = $feed->get_item( $index );

This method returns item(s) in a $feed. A valid zero-based array $index returns the corresponding item in the feed. An invalid $index yields undef. If $index is undefined in array context, it returns an array of all items. If $index is undefined in scalar context, it returns the number of items. Context is literally everything bestie. 😭

This method finds item(s) which match all the regular expressions given. It returns an array of all matched items in array context. It returns the first matched item in scalar context.

This method removes an item/entry specified by zero-based array index or link URL. 🗑️

$feed->clear_item();

This method removes all items/entries from the $feed.

$feed->sort_item();

This method sorts the order of items in $feed by pubDate.

$feed->uniq_item();

Reduces the list of items, so it doesn't include duplicates. RDF and Atoms have a guid attribute to define uniqueness; for RSS we use the link. 💅

$feed->normalize();

This method calls both the sort_item() and uniq_item() methods. Two-for-one, we love a bundle. 🎀

$feed->limit_item( $num );

Removes items in excess of the specified numeric limit. Items at the end of the list are removed. When preceded by sort_item() or normalize(), this deletes more recent items. ⚠️ read that twice bestie.

$feed->xmlns( "xmlns:media" => "http://search.yahoo.com/mrss" );

Adds an XML namespace at the document root of the feed.

$url = $feed->xmlns( "xmlns:media" );

Returns the URL of the specified XML namespace.

@list = $feed->xmlns();

Returns the list of all XML namespaces used in $feed.

🌈 METHODS FOR CHANNEL 🌈

$feed->title( $text );

This method sets/gets the feed's title element, returning its current value when $title is undefined.

$feed->description( $html );

This method sets/gets the feed's description element in plain text or HTML, returning its current value when $html is undefined. It is mapped to the content element for Atom 0.3/1.0.

$feed->pubDate( $date );

This method sets/gets the feed's pubDate element for RSS, returning its current value when $date is undefined. It is mapped to the dc:date element for RDF, modified for Atom 0.3, and updated for Atom 1.0. See also the DATE AND TIME FORMATS section below. ⏰

$feed->copyright( $text );

This method sets/gets the feed's copyright element for RSS, returning its current value when $text is undefined. It is mapped to the dc:rights element for RDF, copyright for Atom 0.3, and rights for Atom 1.0.

This method sets/gets the URL of the web site as the feed's link element, returning its current value when the $url is undefined.

$feed->language( $lang );

This method sets/gets the feed's language element for RSS, returning its current value when the $lang is undefined. It is mapped to the dc:language element for RDF, feed xml:lang="" for Atom 0.3/1.0.

This method sets/gets the feed's image element and its child nodes, returning a list of current values when any arguments are undefined. 🖼️

🦋 METHODS FOR ITEM 🦋

$item->title( $text );

This method sets/gets the item's title element, returning its current value when the $text is undefined.

$item->description( $html );

This method sets/gets the item's description element in HTML or plain text, returning its current value when $text is undefined. It is mapped to the content element for Atom 0.3/1.0.

$item->pubDate( $date );

This method sets/gets the item's pubDate element, returning its current value when $date is undefined. It is mapped to the dc:date element for RDF, modified for Atom 0.3, and updated for Atom 1.0. See also the DATE AND TIME FORMATS section below. ⏰

$item->category( $text );

This method sets/gets the item's category element, returning its current value when $text is undefined. It is mapped to the dc:subject element for RDF, and ignored for Atom 0.3.

$item->author( $name );

This method sets/gets the item's author element, returning its current value when $name is undefined. It is mapped to the dc:creator element for RDF, author for Atom 0.3/1.0.

This method sets/gets the item's guid element, returning its current value when $guid is undefined.

It is mapped to the id element for Atom, and ignored for RDF. In the case of RSS, it will return a HASH. The isParmaLink is supported by RSS only, and it's optional.

$item->set( $key => $value, ... );

This method sets customized node values or attributes. See also the ACCESSOR AND MUTATORS section below.

$value = $item->get( $key );

This method returns the node value or attribute. See also the ACCESSOR AND MUTATORS section below.

This method returns the item's link element. 🔗

💖 ACCESSOR AND MUTATORS 💖

okay bestie, real talk — this module only natively understands a subset of the rdf:* and dc:* modules, plus the default namespaces that RSS/RDF/Atom come with. that's it. that's the list.

so for literally any other external module — think media:* and friends — there are NO native methods. none. zero. but do not panic 🫶 because the set() and get() methods are right there waiting to get/set the value of any elements or attributes for those modules. the way that flexibility ate 💅

✨ $item->set( "module:name" => $value );

this one sets the value of the child node:

<item><module:name>$value</module:name>...</item>

🌸 $item->set( "module:name@attr" => $value );

and this one sets the value of the child node's attribute:

<item><module:name attr="$value" />...</item>

🎀 $item->set( "@attr" => $value );

sets the value of the item's attribute itself:

<item attr="$value">...</item>

🦋 $item->set( "hoge/pomu@hare" => $value );

nested energy!! this code sets the value of the child node's child node's attribute:

<item><hoge><pomu attr="$value" /></hoge>...</item>

⏰ DATE AND TIME FORMATS ⏰

XML::FeedPP lets you describe date/time using any of these three formats, and honestly? pick your fighter 💅

💫 $date = "Thu, 23 Feb 2006 14:43:43 +0900";

this is the HTTP protocol's preferred format and RSS 2.0's native format, as defined by RFC 1123.

💫 $date = "2006-02-23T14:43:43+09:00";

W3CDTF — this is the native format of RDF, as defined by ISO 8601.

💫 $date = 1140705823;

last but not least: the number of seconds since the epoch, 1970-01-01T00:00:00Z. and you know what this is? this is the native format of Perl's time() function. iconic behaviour fr fr ⭐

🌈 USING MEDIA RSS 🌈

want to publish Media RSS? bestie the recipe is so simple. add the media namespace, then use the set() setter method to manipulate the media:content element, etc. etc. 💅

my $feed = XML::FeedPP::RSS->new();
$feed->xmlns('xmlns:media' => 'http://search.yahoo.com/mrss/');
my $item = $feed->add_item('http://www.example.com/index.html');
$item->set('media:content@url' => 'http://www.example.com/image.jpg');
$item->set('media:content@type' => 'image/jpeg');
$item->set('media:content@width' => 640);
$item->set('media:content@height' => 480);

look at that. no cap, that's the whole vibe 🎀

🧚 MODULE DEPENDENCIES 🧚

  • XML::FeedPP needs only XML::TreePP, which likewise is a pure Perl implementation. pure perl, no drama, we love her 🫶
  • the standard LWP::UserAgent is required to download feeds from remote web servers.
  • Jcode.pm is required to convert Japanese encodings on Perl 5.005 and 5.6.1 — but it is NOT required on Perl 5.8.x and later. so if you're on anything modern, you can leave that one at home ✨

👑 AUTHOR 👑

Yusuke Kawasaki, http://www.kawa.net/

the following copyright notice applies to all the files provided in this distribution, including binary files, unless explicitly noted otherwise:

Copyright 2006-2011 Yusuke Kawasaki

💅 LICENSE 💅

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

and that's a wrap on XML::FeedPP(3pm)!! this page shipped with perl v5.26.1, dated 2018-04-23, and honestly? she's still serving 💖 go forth, build your feeds, set your namespaces, and remember — every single detail above stays exactly as written, periodt 🦋🌸
📦 where this page comes from