lib/XML/Feed.pm

   1 # $Id: Feed.pm 1958 2006-08-14 05:31:27Z btrott $
   2
   3 package XML::Feed;
   4 use strict;
   5
   6 use base qw( Class::ErrorHandler );
   7 use Feed::Find;
   8 use URI::Fetch;
   9 use LWP::UserAgent;
  10 use Carp;
  11
  12 our $VERSION = '0.22';
  13
  14 sub new {
  15     my $class = shift;
  16     my $format = shift || 'Atom';
  17     my $format_class = 'XML::Feed::' . $format;
  18     eval "use $format_class";
  19     Carp::croak("Unsupported format $format: $@") if $@;
  20     my $feed = bless {}, join('::', __PACKAGE__, $format);
  21     $feed->init_empty(@_) or return $class->error($feed->errstr);
  22     $feed;
  23 }
  24
  25 sub init_empty { 1 }
  26
  27 sub parse {
  28     my $class = shift;
  29     my($stream, $specified_format) = @_;
  30     return $class->error("Stream parameter is required") unless $stream;
  31     my $feed = bless {}, $class;
  32     my $xml = '';
  33     if (UNIVERSAL::isa($stream, 'URI')) {
  34         my $ua  = LWP::UserAgent->new;
  35         $ua->env_proxy; # force allowing of proxies
  36         my $res = URI::Fetch->fetch($stream, UserAgent => $ua)
  37             or return $class->error(URI::Fetch->errstr);
  38         return $class->error("This feed has been permanently removed")
  39             if $res->status == URI::Fetch::URI_GONE();
  40         $xml = $res->content;
  41     } elsif (ref($stream) eq 'SCALAR') {
  42         $xml = $$stream;
  43     } elsif (ref($stream)) {
  44         while (read($stream, my($chunk), 8192)) {
  45             $xml .= $chunk;
  46         }
  47     } else {
  48         open my $fh, $stream
  49             or return $class->error("Can't open $stream: $!");
  50         while (read $fh, my($chunk), 8192) {
  51             $xml .= $chunk;
  52         }
  53         close $fh;
  54     }
  55     return $class->error("Can't get feed XML content from $stream")
  56         unless $xml;
  57     my $format;
  58     if ($specified_format) {
  59         $format = $specified_format;
  60     } else {
  61         $format = $feed->identify_format(\$xml) or return $class->error($feed->errstr);
  62     }
  63
  64     my $format_class = join '::', __PACKAGE__, $format;
  65     eval "use $format_class";
  66     return $class->error("Unsupported format $format: $@") if $@;
  67     bless $feed, $format_class;
  68     $feed->init_string(\$xml) or return $class->error($feed->errstr);
  69     $feed;
  70 }
  71
  72 sub identify_format {
  73     my $feed = shift;
  74     my($xml) = @_;
  75     ## Auto-detect feed type based on first element. This is prone
  76     ## to breakage, but then again we don't want to parse the whole
  77     ## feed ourselves.
  78     my $tag;
  79     while ($$xml =~ /<(\S+)/sg) {
  80         (my $t = $1) =~ tr/a-zA-Z0-9:\-\?!//cd;
  81         my $first = substr $t, 0, 1;
  82         $tag = $t, last unless $first eq '?' || $first eq '!';
  83     }
  84     return $feed->error("Cannot find first element") unless $tag;
  85     $tag =~ s/^.*://;
  86     if ($tag eq 'rss' || $tag eq 'RDF') {
  87         return 'RSS';
  88     } elsif ($tag eq 'feed') {
  89         return 'Atom';
  90     } else {
  91         return $feed->error("Cannot detect feed type");
  92     }
  93 }
  94
  95 sub find_feeds {
  96     my $class = shift;
  97     my($uri) = @_;
  98     my @feeds = Feed::Find->find($uri)
  99         or return $class->error(Feed::Find->errstr);
 100     @feeds;
 101 }
 102
 103 sub convert {
 104     my $feed = shift;
 105     my($format) = @_;
 106     my $new = __PACKAGE__->new($format);
 107     for my $field (qw( title link description language author copyright modified generator )) {
 108         my $val = $feed->$field();
 109         next unless defined $val;
 110         $new->$field($val);
 111     }
 112     for my $entry ($feed->entries) {
 113         $new->add_entry($entry->convert($format));
 114     }
 115     $new;
 116 }
 117
 118 sub splice {
 119     my $feed = shift;
 120     my($other) = @_;
 121     my %ids = map { $_->id => 1 } $feed->entries;
 122     for my $entry ($other->entries) {
 123         $feed->add_entry($entry) unless $ids{$entry->id}++;
 124     }
 125 }
 126
 127 sub format;
 128 sub title;
 129 sub link;
 130 sub self_link;
 131 sub description;
 132 sub language;
 133 sub author;
 134 sub copyright;
 135 sub modified;
 136 sub generator;
 137 sub add_entry;
 138 sub entries;
 139 sub as_xml;
 140 sub id;
 141
 142 sub tagline { shift->description(@_) }
 143 sub items   { $_[0]->entries     }
 144
 145 1;
 146 __END__
 147
 148 =head1 NAME
 149
 150 XML::Feed - Syndication feed parser and auto-discovery
 151
 152 =head1 SYNOPSIS
 153
 154     use XML::Feed;
 155     my $feed = XML::Feed->parse(URI->new('http://example.com/atom.xml'))
 156         or die XML::Feed->errstr;
 157     print $feed->title, "\n";
 158     for my $entry ($feed->entries) {
 159     }
 160
 161     ## Find all of the syndication feeds on a given page, using
 162     ## auto-discovery.
 163     my @feeds = XML::Feed->find_feeds('http://example.com/');
 164
 165 =head1 DESCRIPTION
 166
 167 I<XML::Feed> is a syndication feed parser for both RSS and Atom feeds. It
 168 also implements feed auto-discovery for finding feeds, given a URI.
 169
 170 I<XML::Feed> supports the following syndication feed formats:
 171
 172 =over 4
 173
 174 =item * RSS 0.91
 175
 176 =item * RSS 1.0
 177
 178 =item * RSS 2.0
 179
 180 =item * Atom
 181
 182 =back
 183
 184 The goal of I<XML::Feed> is to provide a unified API for parsing and using
 185 the various syndication formats. The different flavors of RSS and Atom
 186 handle data in different ways: date handling; summaries and content;
 187 escaping and quoting; etc. This module attempts to remove those differences
 188 by providing a wrapper around the formats and the classes implementing
 189 those formats (I<XML::RSS> and I<XML::Atom::Feed>). For example, dates are
 190 handled differently in each of the above formats. To provide a unified API for
 191 date handling, I<XML::Feed> converts all date formats transparently into
 192 I<DateTime> objects, which it then returns to the caller.
 193
 194 =head1 USAGE
 195
 196 =head2 XML::Feed->new($format)
 197
 198 Creates a new empty I<XML::Feed> object using the format I<$format>.
 199
 200     $feed = XML::Feed->new('Atom');
 201     $feed = XML::Feed->new('RSS');
 202     $feed = XML::Feed->new('RSS', version => '0.91');
 203
 204 =head2 XML::Feed->parse($stream)
 205
 206 =head2 XML::Feed->parse($stream, $format)
 207
 208 Parses a syndication feed identified by I<$stream>. I<$stream> can be any
 209 one of the following:
 210
 211 =over 4
 212
 213 =item * Scalar reference
 214
 215 A reference to string containing the XML body of the feed.
 216
 217 =item * Filehandle
 218
 219 An open filehandle from which the feed XML will be read.
 220
 221 =item * File name
 222
 223 The name of a file containing the feed XML.
 224
 225 =item * URI object
 226
 227 A URI from which the feed XML will be retrieved.
 228
 229 =back
 230
 231 C<$format> allows you to override format guessing.
 232
 233 =head2 XML::Feed->find_feeds($uri)
 234
 235 Given a URI I<$uri>, use auto-discovery to find all of the feeds linked
 236 from that page (using I<E<lt>linkE<gt>> tags).
 237
 238 Returns a list of feed URIs.
 239
 240 =head2 $feed->convert($format)
 241
 242 Converts the I<XML::Feed> object into the I<$format> format, and returns
 243 the new object.
 244
 245 =head2 $feed->splice($other_feed)
 246
 247 Splices in all of the entries from the feed I<$other_feed> into I<$feed>,
 248 skipping posts that are already in I<$feed>.
 249
 250 =head2 $feed->format
 251
 252 Returns the format of the feed (C<Atom>, or some version of C<RSS>).
 253
 254 =head2 $feed->title([ $title ])
 255
 256 The title of the feed/channel.
 257
 258 =head2 $feed->link([ $uri ])
 259
 260 The permalink of the feed/channel.
 261
 262 =head2 $feed->tagline([ $tagline ])
 263
 264 The description or tagline of the feed/channel.
 265
 266 =head2 $feed->description([ $description ])
 267
 268 Alias for I<$feed-E<gt>tagline>.
 269
 270 =head2 $feed->author([ $author ])
 271
 272 The author of the feed/channel.
 273
 274 =head2 $feed->language([ $language ])
 275
 276 The language of the feed.
 277
 278 =head2 $feed->copyright([ $copyright ])
 279
 280 The copyright notice of the feed.
 281
 282 =head2 $feed->modified([ $modified ])
 283
 284 A I<DateTime> object representing the last-modified date of the feed.
 285
 286 If present, I<$modified> should be a I<DateTime> object.
 287
 288 =head2 $feed->generator([ $generator ])
 289
 290 The generator of the feed.
 291
 292 =head2 $feed->self_link ([ $uri ])
 293
 294 The Atom Self-link of the feed:
 295
 296 L<http://validator.w3.org/feed/docs/warning/MissingAtomSelfLink.html>
 297
 298 A string.
 299
 300 =head2 $feed->entries
 301
 302 A list of the entries/items in the feed. Returns an array containing
 303 I<XML::Feed::Entry> objects.
 304
 305 =head2 $feed->add_entry($entry)
 306
 307 Adds an entry to the feed. I<$entry> should be an I<XML::Feed::Entry>
 308 object in the correct format for the feed.
 309
 310 =head2 $feed->as_xml
 311
 312 Returns an XML representation of the feed, in the format determined by
 313 the current format of the I<$feed> object.
 314
 315 =head1 PACKAGE VARIABLES
 316
 317 =over 4
 318
 319 =item C<$XML::Feed::RSS::PREFERRED_PARSER>
 320
 321 If you want to use another RSS parser class than XML::RSS (default), you can
 322 change the class by setting C<$PREFERRED_PARSER> variable in XML::Feed::RSS
 323 package.
 324
 325     $XML::Feed::RSS::PREFERRED_PARSER = "XML::RSS::LibXML";
 326
 327 B<Note:> this will only work for parsing feeds, not creating feeds.
 328
 329 =back
 330
 331 =head1 LICENSE
 332
 333 I<XML::Feed> is free software; you may redistribute it and/or modify it
 334 under the same terms as Perl itself.
 335
 336 =head1 AUTHOR & COPYRIGHT
 337
 338 Except where otherwise noted, I<XML::Feed> is Copyright 2004-2008
 339 Six Apart, cpan@sixapart.com. All rights reserved.
 340
 341 =head1 SUBVERSION
 342
 343 The latest version of I<XML::Feed> can be found at
 344
 345     http://code.sixapart.com/svn/XML-Feed/trunk/
 346
 347 =cut