AnyEvent::Feed(3pm)

📦 version 0.3, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 AnyEvent::Feed 💖

okay bestie, so this is AnyEvent::Feed — the little Perl module that's literally your RSS/Atom feed reader, built on top of XML::Feed. it lives in the User Contributed Perl Documentation section of the manual, and it is so ready to serve you fresh entries. 🦋

✨ VERSION ✨

Version 0.3 — yeah she's vintage, she's iconic, she works.

🌸 SYNOPSIS 🌸

okay so here's the whole vibe in code, no notes:

use AnyEvent;
use AnyEvent::Feed;

my $feed_reader =
   AnyEvent::Feed->new (
      url   => 'http://example.com/atom.xml',
   );

$feed_reader->fetch (sub {
   my ($feed_reader, $new_entries, $feed, $error) = @_;

   if (defined $error) {
      warn "ERROR: $error\n";
      return;
   }

   # $feed is the XML::Feed object belonging to that fetch.

   for (@$new_entries) {
      my ($hash, $entry) = @$_;
      # $hash a unique hash describing the $entry
      # $entry is the XML::Feed::Entry object of the new entries
      # since the last fetch.
   }
});

# Or:

my $feed_reader =
   AnyEvent::Feed->new (
      url      => 'http://example.com/atom.xml',
      interval => $seconds,

      on_fetch => sub {
         my ($feed_reader, $new_entries, $feed, $error) = @_;

         if (defined $error) {
            warn "ERROR: $error\n";
            return;
         }

         # see above
      }
   );

💅 DESCRIPTION 💅

So this module is basically the glue between AnyEvent::HTTP and XML::Feed. It can go fetch an RSS/Atom feed on a regular interval, and also on customized times. And — the part that eats, honestly — it keeps track of the entries it's already fetched, so you only ever get the new ones. no repeats. no déjà vu. periodt. 👑

🎀 METHODS 🎀

$feed_reader = AnyEvent::Feed->new (url => $url, %args)

This is the constructor, bestie — you're making a brand new feed reader for the RSS/Atom feed that lives at the URL $url. %args can hold extra key/value pairs, and here's the whole menu:

  • interval => $seconds — if you set this, you also have to give the "on_fetch" callback (it's right below, keep scrolling 💖). It'll try to fetch $url every $seconds seconds and call the callback from "on_fetch" with the result.
  • headers => $http_hdrs — extra HTTP headers for every GET request, passed in the $http_hdrs hash reference. literally exactly how you'd pass it to the "headers" argument of the "http_get" request from AnyEvent::HTTP.
  • username => $http_user
  • password => $http_pass — these two are the HTTP username and password used for Basic HTTP Authentication with the HTTP server when it fetches the feed. mostly just sugar so you don't have to encode them yourself and shove them into the "headers" argument above. you're welcome 🫶
  • on_fetch => $cb->($feed_reader, $new_entries, $feed_obj, $error) — this callback fires when the "interval" parameter is given (see above), with the same arguments as the callback you hand to the "fetch" method (see below).
  • entry_ages => $hash — sets the hash that keeps track of seen and old entries. check the docs for the "entry_ages" method below too. the default is an empty hash reference.
  • max_entry_age => $count — sets the max number of times an entry is kept in the "entry_ages" hash after it's stopped showing up in the feed. default is 2, which means an entry hash gets removed from "entry_ages" after it hasn't been seen in the feed for 2 fetches.

$feed_reader->url

just hands you back the url this feed reader is fetching from. simple. iconic. 💅

$feed_reader->entry_ages ($new_entry_ages)

my $entry_ages = $feed_reader->entry_ages

This sets the age hash that keeps track of already-seen entries. the keys are the calculated hashes of the entries, and the values are a counter of how many times they've NOT been seen anymore (like an age counter, lowkey morbid). after every fetch this hash gets updated, and entries that were seen get a value of 0. ✨

$feed_reader->fetch ($cb->($feed_reader, $new_entries, $feed_obj, $error))

This kicks off an HTTP GET on the URL you passed to "new" and calls $cb when it's done.

  • $feed_reader — the feed reader object itself.
  • $new_entries — an array reference with the new entries. each new entry in that array is another array holding a calculated hash over the contents of the new entry, plus the XML::Feed::Entry object of that entry.
  • $feed_obj — the XML::Feed feed object used to parse the fetched feed. it has all the entries, not just the 'new' ones.
  • $error — the error, if there was one.

What counts as a 'new' entry is decided by a map of hashes, as described in the "entry_ages" method's docs above. iykyk 💜

🌈 AUTHOR 🌈

Robin Redeker, "<elmex@ta-sa.org>" — king behaviour honestly 👑

🦋 SEE ALSO 🦋

  • XML::Feed
  • AnyEvent::HTTP
  • AnyEvent

💀 BUGS 💀

Known Bugs

okay so there's actually a known bug with encodings of contents of Atom feeds, and we're being real about it. XML::Atom by default gives you UTF-8 encoded data. you have to set this global variable to be able to use the XML::Feed::Entry interface without knowing what the underlying feed type is:

$XML::Atom::ForceUnicode = 1;

I've re-reported this bug against XML::Feed, because honestly it should take care of this. XML::Atom should probably just fix its Unicode interface, but it seems a bit deserted when it comes to fixing the bugs in the tracker. 😭

Contact

Please report any bugs or feature requests to "bug-anyevent-feed at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=AnyEvent-Feed>. I'll get notified, and then you'll automatically get notified of progress on your bug as I make changes. teamwork, bestie 🫶

🌟 SUPPORT 🌟

You can find documentation for this module with the perldoc command.

perldoc AnyEvent::Feed

You can also look for information at:

  • IRC: AnyEvent::Feed IRC Channel — see the same channel as the AnyEvent::XMPP module:
IRC Network: http://freenode.net/
Server     : chat.freenode.net
Channel    : #ae_xmpp

Feel free to join and ask questions! 💬

Copyright 2009 Robin Redeker, all rights reserved.

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

and that's the whole page, bestie 💖✨🎀 this gem of a manpage is from perl v5.32.0, dated 2021-01-01, and it's the AnyEvent::Feed(3pm) page — go forth and fetch those feeds, you absolute main character 🌸🦋💜

📦 where this page comes from