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 _convert_entry {
 128     my $feed   = shift;
 129     my $entry  = shift;
 130     my $feed_format  = ref($feed);   $feed_format  =~ s!^XML::Feed::!!;
 131     my $entry_format = ref($entry);  $entry_format =~ s!^XML::Feed::Entry::!!;
 132     return $entry if $entry_format eq $feed_format;
 133     return $entry->convert($feed_format);
 134 }
 135
 136 sub base;
 137 sub format;
 138 sub title;
 139 sub link;
 140 sub self_link;
 141 sub description;
 142 sub language;
 143 sub author;
 144 sub copyright;
 145 sub modified;
 146 sub generator;
 147 sub add_entry;
 148 sub entries;
 149 sub as_xml;
 150 sub id;
 151
 152 sub tagline { shift->description(@_) }
 153 sub items   { $_[0]->entries     }
 154
 155 1;
 156 __END__
 157
 158 =head1 NAME
 159
 160 XML::Feed - Syndication feed parser and auto-discovery
 161
 162 =head1 SYNOPSIS
 163
 164     use XML::Feed;
 165     my $feed = XML::Feed->parse(URI->new('http://example.com/atom.xml'))
 166         or die XML::Feed->errstr;
 167     print $feed->title, "\n";
 168     for my $entry ($feed->entries) {
 169     }
 170
 171     ## Find all of the syndication feeds on a given page, using
 172     ## auto-discovery.
 173     my @feeds = XML::Feed->find_feeds('http://example.com/');
 174
 175 =head1 DESCRIPTION
 176
 177 I<XML::Feed> is a syndication feed parser for both RSS and Atom feeds. It
 178 also implements feed auto-discovery for finding feeds, given a URI.
 179
 180 I<XML::Feed> supports the following syndication feed formats:
 181
 182 =over 4
 183
 184 =item * RSS 0.91
 185
 186 =item * RSS 1.0
 187
 188 =item * RSS 2.0
 189
 190 =item * Atom
 191
 192 =back
 193
 194 The goal of I<XML::Feed> is to provide a unified API for parsing and using
 195 the various syndication formats. The different flavors of RSS and Atom
 196 handle data in different ways: date handling; summaries and content;
 197 escaping and quoting; etc. This module attempts to remove those differences
 198 by providing a wrapper around the formats and the classes implementing
 199 those formats (I<XML::RSS> and I<XML::Atom::Feed>). For example, dates are
 200 handled differently in each of the above formats. To provide a unified API for
 201 date handling, I<XML::Feed> converts all date formats transparently into
 202 I<DateTime> objects, which it then returns to the caller.
 203
 204 =head1 USAGE
 205
 206 =head2 XML::Feed->new($format)
 207
 208 Creates a new empty I<XML::Feed> object using the format I<$format>.
 209
 210     $feed = XML::Feed->new('Atom');
 211     $feed = XML::Feed->new('RSS');
 212     $feed = XML::Feed->new('RSS', version => '0.91');
 213
 214 =head2 XML::Feed->parse($stream)
 215
 216 =head2 XML::Feed->parse($stream, $format)
 217
 218 Parses a syndication feed identified by I<$stream>. I<$stream> can be any
 219 one of the following:
 220
 221 =over 4
 222
 223 =item * Scalar reference
 224
 225 A reference to string containing the XML body of the feed.
 226
 227 =item * Filehandle
 228
 229 An open filehandle from which the feed XML will be read.
 230
 231 =item * File name
 232
 233 The name of a file containing the feed XML.
 234
 235 =item * URI object
 236
 237 A URI from which the feed XML will be retrieved.
 238
 239 =back
 240
 241 C<$format> allows you to override format guessing.
 242
 243 =head2 XML::Feed->find_feeds($uri)
 244
 245 Given a URI I<$uri>, use auto-discovery to find all of the feeds linked
 246 from that page (using I<E<lt>linkE<gt>> tags).
 247
 248 Returns a list of feed URIs.
 249
 250 =head2 $feed->convert($format)
 251
 252 Converts the I<XML::Feed> object into the I<$format> format, and returns
 253 the new object.
 254
 255 =head2 $feed->splice($other_feed)
 256
 257 Splices in all of the entries from the feed I<$other_feed> into I<$feed>,
 258 skipping posts that are already in I<$feed>.
 259
 260 =head2 $feed->format
 261
 262 Returns the format of the feed (C<Atom>, or some version of C<RSS>).
 263
 264 =head2 $feed->title([ $title ])
 265
 266 The title of the feed/channel.
 267
 268 =head2 $feed->base([ $base ])
 269
 270 The url base of the feed/channel.
 271
 272 =head2 $feed->link([ $uri ])
 273
 274 The permalink of the feed/channel.
 275
 276 =head2 $feed->tagline([ $tagline ])
 277
 278 The description or tagline of the feed/channel.
 279
 280 =head2 $feed->description([ $description ])
 281
 282 Alias for I<$feed-E<gt>tagline>.
 283
 284 =head2 $feed->author([ $author ])
 285
 286 The author of the feed/channel.
 287
 288 =head2 $feed->language([ $language ])
 289
 290 The language of the feed.
 291
 292 =head2 $feed->copyright([ $copyright ])
 293
 294 The copyright notice of the feed.
 295
 296 =head2 $feed->modified([ $modified ])
 297
 298 A I<DateTime> object representing the last-modified date of the feed.
 299
 300 If present, I<$modified> should be a I<DateTime> object.
 301
 302 =head2 $feed->generator([ $generator ])
 303
 304 The generator of the feed.
 305
 306 =head2 $feed->self_link ([ $uri ])
 307
 308 The Atom Self-link of the feed:
 309
 310 L<http://validator.w3.org/feed/docs/warning/MissingAtomSelfLink.html>
 311
 312 A string.
 313
 314 =head2 $feed->entries
 315
 316 A list of the entries/items in the feed. Returns an array containing
 317 I<XML::Feed::Entry> objects.
 318
 319 =head2 $feed->add_entry($entry)
 320
 321 Adds an entry to the feed. I<$entry> should be an I<XML::Feed::Entry>
 322 object in the correct format for the feed.
 323
 324 =head2 $feed->as_xml
 325
 326 Returns an XML representation of the feed, in the format determined by
 327 the current format of the I<$feed> object.
 328
 329 =head1 PACKAGE VARIABLES
 330
 331 =over 4
 332
 333 =item C<$XML::Feed::RSS::PREFERRED_PARSER>
 334
 335 If you want to use another RSS parser class than XML::RSS (default), you can
 336 change the class by setting C<$PREFERRED_PARSER> variable in XML::Feed::RSS
 337 package.
 338
 339     $XML::Feed::RSS::PREFERRED_PARSER = "XML::RSS::LibXML";
 340
 341 B<Note:> this will only work for parsing feeds, not creating feeds.
 342
 343 =back
 344
 345 =head1 LICENSE
 346
 347 I<XML::Feed> is free software; you may redistribute it and/or modify it
 348 under the same terms as Perl itself.
 349
 350 =head1 AUTHOR & COPYRIGHT
 351
 352 Except where otherwise noted, I<XML::Feed> is Copyright 2004-2008
 353 Six Apart, cpan@sixapart.com. All rights reserved.
 354
 355 =head1 SUBVERSION
 356
 357 The latest version of I<XML::Feed> can be found at
 358
 359     http://code.sixapart.com/svn/XML-Feed/trunk/
 360
 361 =cut