Feed::Pipe - Pipe Atom/RSS feeds through UNIX-style high-level filters
SYNOPSIS
use Feed::Pipe;
my $pipe = Feed::Pipe
->new(title => "Mah Bukkit")
->cat( qw(1.xml 2.rss 3.atom) )
->grep(sub{$_->title =~ /lolrus/i })
->sort
->head
;
my $feed = $pipe->as_atom_obj; # returns XML::Atom::Feed
# Add feed details such as author and self link. Then...
print $feed->as_xml;
DESCRIPTION
This module is a Feed model that can mimic the functionality of
standard UNIX pipe and filter style text processing tools. Instead of
operating on lines from text files, it operates on entries from Atom
(or RSS) feeds. The idea is to provide a high-level tool set for
combining, filtering, and otherwise manipulating bunches of Atom data
from various feeds.
Yes, you could do this with Yahoo Pipes. Until they decide to take it
down, or start charging for it. And if your code is guaranteed to have
Internet access.
Also, you could probably do it with Plagger, if you're genius enough to
figure out how.
CONSTRUCTOR
To construct a feed pipe, call new(%options), where the keys of
%options correspond to any of the method names described under ACCESSOR
METHODS. If you do not need to set any options, cat may also be called
on a class and will return an instance.
my $pipe = Feed::Pipe->new(title => 'Test Feed');
FILTER METHODS
cat(@feeds)
my $pipe = Feed::Pipe->new(title => 'Test')->cat(@feeds);
# This also works:
my $pipe = Feed::Pipe->cat(@feeds);
Combine entries from each feed listed, in the order received, into a
single feed. RSS feeds will automatically be converted to Atom before
their entries are added. (NOTE: Some data may be lost in the
conversion. See XML::Feed.)
If called as a class method, will implicitly call new with no options
to return an instance before adding the passed @feeds.
Values passed to cat may be an instance of Feed::Pipe, XML::Atom::Feed,
XML::Feed, or URI, a reference to a scalar variable containing the XML
to parse, or a filename that contains the XML to parse. URI objects
will be dereferenced and fetched, and the result parsed.
Returns the feed pipe itself so that you can chain method calls.
grep(sub{})
# Keeps all entries with the word "Keep" in the title
my $pipe = Feed::Pipe
->cat($feed)
->grep( sub { $_->title =~ /Keep/ } )
;
Filters the list of entries to those for which the passed function
returns true. If no function is passed, the default is to keep entries
which have content (or a summary). The function should test the entry
object aliased in $_ which will be a XML::Atom::Entry.
Returns the feed pipe itself so that you can chain method calls.
head(Int $limit=10)
Output $limit entries from the top of the feed, where $limit defaults
to 10. If your entries are sorted in standard reverse chronological
order, this will pull the $limit most recent entries.
Returns the feed pipe itself so that you can chain method calls.
map(\&mapfunction)
# Converts upper CASE to lower case in each entry title.
my $pipe = Feed::Pipe
->cat($feed)
->map( sub { $_->title =~ s/CASE/case/; return $_; } )
;
Constructs a new list of entries composed of the return values from
mapfunction. The mapfunc must return one or more XML::Atom::Entry
objects, or an empty list. Within the mapfunction $_ will be aliased to
the XML::Atom::Entry it is visiting.
Returns the feed pipe itself so that you can chain method calls.
reverse()
Returns the feed with entries sorted in the opposite of the input
order. This is just for completeness, you could easily do this with
sort instead.
sort(sub{})
# Returns a feed with entries sorted by title
my $pipe = Feed::Pipe
->cat($feed)
->sort(sub{$_[0]->title cmp $_[1]->title})
;
Sort the feed's entries using the comparison function passed as the
argument. If no function is passed, sorts in standard reverse
chronological order. The sort function should be as described in Perl's
sort, but using $_[0] and $_[1] in place of $a and $b, respectively.
The two arguments will be XML::Atom::Entry objects.
Returns the feed pipe itself so that you can chain method calls.
tail(Int $limit=10)
Output $limit entries from the end of the feed, where $limit defaults
to 10. If your entries are sorted in standard reverse chronological
order, this will pull the $limit oldest entries.
Returns the feed pipe itself so that you can chain method calls.
ACCESSOR METHODS
NOTE: These methods are not filters. They do not return the feed pipe
and must not be used in a filter chain (except maybe at the end).
title
Human readable title of the feed. Defaults to "Combined Feed".
id
A string conforming to the definition of an Atom ID. Defaults to a
newly generated UUID.
updated
A DateTime object representing when the feed should claim to have been
updated. Defaults to "now".
OTHER METHODS
NOTE: These methods are not filters. They do not return the feed pipe
and must not be used in a filter chain (except maybe at the end).
as_atom_obj
Returns the XML::Atom::Feed object represented by the feed pipe.
as_xml
Serialize the feed object to an XML (Atom 1.0) string and return the
string. Equivalent to calling $pipe->as_atom_obj->as_xml. NOTE: The
current implementation does not guarantee that the resultant output
will be valid Atom. In particular, you are likely to be missing
required author and link elements. For the moment, you should use
as_atom_obj and manipulate the feed-level elements as needed if you
require validatable output.
count
Returns the number of entries in the feed.
entries
Returns the list of XML::Atom::Entry objects in the feed.
