lib/XML/Feed.pm

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