lib/XML/Feed.pm

   1 # $Id: Feed.pm,v 1.8 2004/07/29 16:44:18 btrott Exp $
   2
   3 package XML::Feed;
   4 use strict;
   5
   6 use base qw( XML::Feed::ErrorHandler );
   7 use LWP::UserAgent;
   8 use HTML::Parser;
   9
  10 use vars qw( $VERSION );
  11 $VERSION = '0.02';
  12
  13 use constant FEED_MIME_TYPES => [
  14     'application/x.atom+xml',
  15     'application/atom+xml',
  16     'text/xml',
  17     'application/rss+xml',
  18     'application/rdf+xml',
  19 ];
  20
  21 sub parse {
  22     my $class = shift;
  23     my($stream) = @_;
  24     return $class->error("Stream parameter is required") unless $stream;
  25     my $feed = bless {}, $class;
  26     my $xml = '';
  27     if (UNIVERSAL::isa($stream, 'URI')) {
  28         my $ua = LWP::UserAgent->new;
  29         my $req = HTTP::Request->new(GET => $stream);
  30         my $res = $ua->request($req);
  31         if ($res->is_success) {
  32             $xml = $res->content;
  33         }
  34     } elsif (ref($stream) eq 'SCALAR') {
  35         $xml = $$stream;
  36     } elsif (ref($stream)) {
  37         while (read($stream, my($chunk), 8192)) {
  38             $xml .= $chunk;
  39         }
  40     } else {
  41         open my $fh, $stream
  42             or return $class->error("Can't open $stream: $!");
  43         while (read $fh, my($chunk), 8192) {
  44             $xml .= $chunk;
  45         }
  46         close $fh;
  47     }
  48     return $class->error("Can't get feed XML content from $stream")
  49         unless $xml;
  50     ## Auto-detect feed type based on first element. This is prone
  51     ## to breakage, but then again we don't want to parse the whole
  52     ## feed ourselves.
  53     my $tag;
  54     while ($xml =~ /<(\S+)/sg) {
  55         (my $t = $1) =~ tr/a-zA-Z0-9:\-\?//cd;
  56         $tag = $t, last unless substr($t, 0, 1) eq '?';
  57     }
  58     return $class->error("Cannot find first element") unless $tag;
  59     $tag =~ s/^.*://;
  60     if ($tag eq 'rss' || $tag eq 'RDF') {
  61         require XML::Feed::RSS;
  62         bless $feed, 'XML::Feed::RSS';
  63     } elsif ($tag eq 'feed') {
  64         require XML::Feed::Atom;
  65         bless $feed, 'XML::Feed::Atom';
  66     } else {
  67         return $class->error("Cannot detect feed type");
  68     }
  69     $feed->init_string($xml) or return;
  70     $feed;
  71 }
  72
  73 sub find_feeds {
  74     my $class = shift;
  75     my($uri) = @_;
  76     my $ua = LWP::UserAgent->new;
  77     my $req = HTTP::Request->new(GET => $uri);
  78     my $res = $ua->request($req);
  79     return unless $res->is_success;
  80     my @feeds;
  81     my %is_feed = map { $_ => 1 } @{ FEED_MIME_TYPES() };
  82     my $ct = $res->content_type;
  83     if ($is_feed{$ct}) {
  84         @feeds = ($uri);
  85     } elsif ($ct eq 'text/html' || $ct eq 'application/xhtml+xml') {
  86         my $base_uri = $uri;
  87         my $find_links = sub {
  88             my($tag, $attr) = @_;
  89             if ($tag eq 'link') {
  90                 return unless $attr->{rel};
  91                 my %rel = map { $_ => 1 } split /\s+/, lc($attr->{rel});
  92                 (my $type = lc $attr->{type}) =~ s/^\s*//;
  93                 $type =~ s/\s*$//;
  94                 push @feeds, URI->new_abs($attr->{href}, $base_uri)->as_string
  95                    if $is_feed{$type} &&
  96                       ($rel{alternate} || $rel{'service.feed'});
  97             } elsif ($tag eq 'base') {
  98                 $base_uri = $attr->{href};
  99             }
 100         };
 101         my $p = HTML::Parser->new(api_version => 3,
 102                                   start_h => [ $find_links, "tagname, attr" ]);
 103         $p->parse($res->content);
 104     }
 105     @feeds;
 106 }
 107
 108 sub format;
 109 sub title;
 110 sub link;
 111 sub description;
 112 sub language;
 113 sub copyright;
 114 sub modified;
 115 sub generator;
 116 sub entries;
 117
 118 sub tagline { $_[0]->description }
 119 sub items   { $_[0]->entries     }
 120
 121 1;
 122 __END__
 123
 124 =head1 NAME
 125
 126 XML::Feed - Syndication feed parser and auto-discovery
 127
 128 =head1 SYNOPSIS
 129
 130     use XML::Feed;
 131     my $feed = XML::Feed->parse(URI->new('http://example.com/atom.xml'))
 132         or die XML::Feed->errstr;
 133     print $feed->title, "\n";
 134     for my $entry ($feed->entries) {
 135     }
 136
 137     ## Find all of the syndication feeds on a given page, using
 138     ## auto-discovery.
 139     my @feeds = XML::Feed->find_feeds('http://example.com/');
 140
 141 =head1 DESCRIPTION
 142
 143 I<XML::Feed> is a syndication feed parser for both RSS and Atom feeds. It
 144 also implements feed auto-discovery for finding feeds, given a URI.
 145
 146 I<XML::Feed> supports the following syndication feed formats:
 147
 148 =over 4
 149
 150 =item * RSS 0.91
 151
 152 =item * RSS 1.0
 153
 154 =item * RSS 2.0
 155
 156 =item * Atom
 157
 158 =back
 159
 160 The goal of I<XML::Feed> is to provide a unified API for parsing and using
 161 the various syndication formats. The different flavors of RSS and Atom
 162 handle data in different ways: date handling; summaries and content;
 163 escaping and quoting; etc. This module attempts to remove those differences
 164 by providing a wrapper around the formats and the classes implementing
 165 those formats (I<XML::RSS> and I<XML::Atom::Feed>). For example, dates are
 166 handled differently in each of the above formats. To provide a unified API for
 167 date handling, I<XML::Feed> converts all date formats transparently into
 168 I<DateTime> objects, which it then returns to the caller.
 169
 170 =head1 USAGE
 171
 172 =head2 XML::Feed->parse($stream)
 173
 174 Parses a syndication feed identified by I<$stream>. I<$stream> can be any
 175 one of the following:
 176
 177 =over 4
 178
 179 =item * Scalar reference
 180
 181 A reference to string containing the XML body of the feed.
 182
 183 =item * Filehandle
 184
 185 An open filehandle from which the feed XML will be read.
 186
 187 =item * File name
 188
 189 The name of a file containing the feed XML.
 190
 191 =item * URI object
 192
 193 A URI from which the feed XML will be retrieved.
 194
 195 =back
 196
 197 =head2 XML::Feed->find_feeds($uri)
 198
 199 Given a URI I<$uri>, use auto-discovery to find all of the feeds linked
 200 from that page (using I<E<lt>linkE<gt>> tags).
 201
 202 Returns a list of feed URIs.
 203
 204 =head2 $feed->format
 205
 206 Returns the format of the feed (C<Atom>, or some version of C<RSS>).
 207
 208 =head2 $feed->title
 209
 210 The title of the feed/channel.
 211
 212 =head2 $feed->link
 213
 214 The permalink of the feed/channel.
 215
 216 =head2 $feed->tagline
 217
 218 The description or tagline of the feed/channel.
 219
 220 =head2 $feed->description
 221
 222 Alias for I<$feed-E<gt>tagline>.
 223
 224 =head2 $feed->language
 225
 226 The language of the feed.
 227
 228 =head2 $feed->copyright
 229
 230 The copyright notice of the feed.
 231
 232 =head2 $feed->modified
 233
 234 A I<DateTime> object representing the last-modified date of the feed.
 235
 236 =head2 $feed->generator
 237
 238 The generator of the feed.
 239
 240 =head2 $feed->entries
 241
 242 A list of the entries/items in the feed. Returns an array containing
 243 I<XML::Feed::Entry> objects.
 244
 245 =head1 LICENSE
 246
 247 I<XML::Feed> is free software; you may redistribute it and/or modify it
 248 under the same terms as Perl itself.
 249
 250 =head1 AUTHOR & COPYRIGHT
 251
 252 Except where otherwise noted, I<XML::Feed> is Copyright 2004 Benjamin
 253 Trott, cpan@stupidfool.org. All rights reserved.
 254
 255 =cut