Add pod and coverage tests

[catagits/XML-Feed.git] / lib / XML / Feed.pm

diff --git a/lib/XML/Feed.pm b/lib/XML/Feed.pm
index ea0500a..254ccc9 100644 (file)
--- a/lib/XML/Feed.pm
+++ b/lib/XML/Feed.pm
@@ -6,9 +6,10 @@ use strict;
 use base qw( Class::ErrorHandler );
 use Feed::Find;
 use URI::Fetch;
+use LWP::UserAgent;
 use Carp;
 
-our $VERSION = '0.12';
+our $VERSION = '0.23';
 
 sub new {
     my $class = shift;
@@ -30,7 +31,9 @@ sub parse {
     my $feed = bless {}, $class;
     my $xml = '';
     if (UNIVERSAL::isa($stream, 'URI')) {
-        my $res = URI::Fetch->fetch($stream)
+        my $ua  = LWP::UserAgent->new;
+        $ua->env_proxy; # force allowing of proxies
+        my $res = URI::Fetch->fetch($stream, UserAgent => $ua)
             or return $class->error(URI::Fetch->errstr);
         return $class->error("This feed has been permanently removed")
             if $res->status == URI::Fetch::URI_GONE();
@@ -121,9 +124,20 @@ sub splice {
     }
 }
 
+sub _convert_entry {
+    my $feed   = shift;
+    my $entry  = shift;
+    my $feed_format  = ref($feed);   $feed_format  =~ s!^XML::Feed::!!;
+    my $entry_format = ref($entry);  $entry_format =~ s!^XML::Feed::Entry::!!;
+    return $entry if $entry_format eq $feed_format;
+    return $entry->convert($feed_format); 
+}
+
+sub base;
 sub format;
 sub title;
 sub link;
+sub self_link;
 sub description;
 sub language;
 sub author;
@@ -133,6 +147,7 @@ sub generator;
 sub add_entry;
 sub entries;
 sub as_xml;
+sub id;
 
 sub tagline { shift->description(@_) }
 sub items   { $_[0]->entries     }
@@ -192,6 +207,10 @@ I<DateTime> objects, which it then returns to the caller.
 
 Creates a new empty I<XML::Feed> object using the format I<$format>.
 
+    $feed = XML::Feed->new('Atom');
+    $feed = XML::Feed->new('RSS');
+    $feed = XML::Feed->new('RSS', version => '0.91');
+
 =head2 XML::Feed->parse($stream)
 
 =head2 XML::Feed->parse($stream, $format)
@@ -219,7 +238,7 @@ A URI from which the feed XML will be retrieved.
 
 =back
 
-C<$format> allows you to override format guessing.
+I<$format> allows you to override format guessing.
 
 =head2 XML::Feed->find_feeds($uri)
 
@@ -228,6 +247,10 @@ from that page (using I<E<lt>linkE<gt>> tags).
 
 Returns a list of feed URIs.
 
+=head2 XML::Feed->identify_format($xml)
+
+Given the xml of a feed return what format it is in (C<Atom>, or some version of C<RSS>).
+
 =head2 $feed->convert($format)
 
 Converts the I<XML::Feed> object into the I<$format> format, and returns
@@ -246,6 +269,10 @@ Returns the format of the feed (C<Atom>, or some version of C<RSS>).
 
 The title of the feed/channel.
 
+=head2 $feed->base([ $base ])
+
+The url base of the feed/channel.
+
 =head2 $feed->link([ $uri ])
 
 The permalink of the feed/channel.
@@ -280,11 +307,23 @@ If present, I<$modified> should be a I<DateTime> object.
 
 The generator of the feed.
 
+=head2 $feed->self_link ([ $uri ])
+
+The Atom Self-link of the feed:
+
+L<http://validator.w3.org/feed/docs/warning/MissingAtomSelfLink.html>
+
+A string.
+
 =head2 $feed->entries
 
 A list of the entries/items in the feed. Returns an array containing
 I<XML::Feed::Entry> objects.
 
+=head2 $feed->items
+
+A synonym for I<$feed->entries>.
+
 =head2 $feed->add_entry($entry)
 
 Adds an entry to the feed. I<$entry> should be an I<XML::Feed::Entry>
@@ -311,6 +350,46 @@ B<Note:> this will only work for parsing feeds, not creating feeds.
 
 =back
 
+=head1 VALID FEEDS
+
+For reference, this cgi script will create valid, albeit nonsensical feeds 
+(according to C<http://feedvalidator.org> anyway) for Atom 1.0 and RSS 0.90, 
+0.91, 1.0 and 2.0. 
+
+    #!perl -w
+
+    use strict;
+    use CGI;
+    use CGI::Carp qw(fatalsToBrowser);
+    use DateTime;
+    use XML::Feed;
+
+    my $cgi  = CGI->new;
+    my @args = ( $cgi->param('format') || "Atom" );
+    push @args, ( version => $cgi->param('version') ) if $cgi->param('version');
+
+    my $feed = XML::Feed->new(@args);
+    $feed->id("http://".time.rand()."/");
+    $feed->title('Test Feed');
+    $feed->link($cgi->url);
+    $feed->self_link($cgi->url( -query => 1, -full => 1, -rewrite => 1) );
+    $feed->modified(DateTime->now);
+
+    my $entry = XML::Feed::Entry->new();
+    $entry->id("http://".time.rand()."/");
+    $entry->link("http://example.com");
+    $entry->title("Test entry");
+    $entry->summary("Test summary");
+    $entry->content("Foo");
+    $entry->modified(DateTime->now);
+    $entry->author('test@example.com (Testy McTesterson)');
+    $feed->add_entry($entry);
+
+    my $mime = ("Atom" eq $feed->format) ? "application/atom+xml" : "application/rss+xml";
+    print $cgi->header($mime);
+    print $feed->as_xml;
+
+
 =head1 LICENSE
 
 I<XML::Feed> is free software; you may redistribute it and/or modify it
@@ -318,7 +397,13 @@ under the same terms as Perl itself.
 
 =head1 AUTHOR & COPYRIGHT
 
-Except where otherwise noted, I<XML::Feed> is Copyright 2004-2005
+Except where otherwise noted, I<XML::Feed> is Copyright 2004-2008
 Six Apart, cpan@sixapart.com. All rights reserved.
 
+=head1 SUBVERSION 
+
+The latest version of I<XML::Feed> can be found at
+
+    http://code.sixapart.com/svn/XML-Feed/trunk/
+
 =cut