lib/XML/Feed/Entry.pm

   1 # $Id$
   2
   3 package XML::Feed::Entry;
   4 use strict;
   5 use base qw( Class::ErrorHandler );
   6
   7 use Scalar::Util qw( blessed );
   8
   9 use Carp;
  10
  11 sub wrap {
  12     my $class = shift;
  13     my($item) = @_;
  14     bless { entry => $item }, $class;
  15 }
  16
  17 sub unwrap { $_[0]->{entry} }
  18
  19 sub new {
  20     my $class = shift;
  21     my($format) = @_;
  22     $format ||= 'Atom';
  23     my $format_class = 'XML::Feed::Format::' . $format;
  24     eval "use $format_class";
  25     Carp::croak("Unsupported format $format: $@") if $@;
  26     my $entry = bless {}, join('::', __PACKAGE__, "Format", $format);
  27     $entry->init_empty or return $class->error($entry->errstr);
  28     $entry;
  29 }
  30
  31 sub init_empty { 1 }
  32
  33 sub convert {
  34     my $entry = shift;
  35     my($format) = @_;
  36     my $new = __PACKAGE__->new($format);
  37     for my $field (qw( title link content summary author id issued modified lat long )) {
  38         my $val = $entry->$field();
  39         next unless defined $val;
  40         next if blessed $val && $val->isa('XML::Feed::Content') && ! defined $val->body;
  41         $new->$field($val);
  42     }
  43     for my $field (qw( category )) {
  44         my @val = $entry->$field();
  45         next unless @val;
  46         $new->$field(@val);
  47     }
  48     $new;
  49 }
  50
  51 sub title;
  52 sub link;
  53 sub content;
  54 sub summary;
  55 sub category;
  56 sub author;
  57 sub id;
  58 sub issued;
  59 sub modified;
  60 sub lat;
  61 sub long;
  62 sub format;
  63 sub tags { shift->category(@_) }
  64 sub enclosure;
  65
  66 1;
  67 __END__
  68
  69 =head1 NAME
  70
  71 XML::Feed::Entry - Entry/item in a syndication feed
  72
  73 =head1 SYNOPSIS
  74
  75     ## $feed is an XML::Feed object.
  76     for my $entry ($feed->entries) {
  77         print $entry->title, "\n", $entry->summary, "\n\n";
  78     }
  79
  80 =head1 DESCRIPTION
  81
  82 I<XML::Feed::Entry> represents an entry/item in an I<XML::Feed> syndication
  83 feed.
  84
  85 =head1 USAGE
  86
  87 =head2 XML::Feed::Entry->new($format)
  88
  89 Creates a new I<XML::Feed::Entry> object in the format I<$format>, which
  90 should be either I<RSS> or I<Atom>.
  91
  92 =head2 $entry->convert($format)
  93
  94 Converts the I<XML::Feed::Entry> object into the I<$format> format, and
  95 returns the new object.
  96
  97 =head2 $entry->title([ $title ])
  98
  99 The title of the entry.
 100
 101 =head2 $entry->base([ $base ])
 102
 103 The url base of the entry.
 104
 105 =head2 $entry->link([ $uri ])
 106
 107 The permalink of the entry, in most cases, except in cases where it points
 108 instead to an offsite URI referenced in the entry.
 109
 110 =head2 $entry->content([ $content ])
 111
 112 Bn I<XML::Feed::Content> object representing the full entry body, or as
 113 much as is available in the feed.
 114
 115 In RSS feeds, this method will look first for
 116 I<http://purl.org/rss/1.0/modules/content/#encoded> and
 117 I<http://www.w3.org/1999/xhtml#body> elements, then fall back to a
 118 I<E<lt>descriptionE<gt>> element.
 119
 120 =head2 $entry->summary([ $summary ])
 121
 122 An I<XML::Feed::Content> object representing a short summary of the entry.
 123 Possibly.
 124
 125 Since RSS feeds do not have the idea of a summary separate from the entry
 126 body, this may not always be what you want. If the entry contains both a
 127 I<E<lt>descriptionE<gt>> element B<and> another element typically used for
 128 the full content of the entry--either I<http://www.w3.org/1999/xhtml/body>
 129 or I<http://purl.org/rss/1.0/modules/content/#encoded>--we treat that as
 130 the summary. Otherwise, we assume that there isn't a summary, and return
 131 an I<XML::Feed::Content> object with an empty string in the I<body>.
 132
 133 =head2 $entry->category([ $category ])
 134
 135 The category in which the entry was posted.
 136
 137 Returns a list of categories if called in array context or the first
 138 category if called in scalar context.
 139
 140 B<WARNING> It's possible this API might change to have an
 141 I<add_category> instead.
 142
 143 =head2 $entry->tags([ $tag ])
 144
 145 A synonym for I<category>;
 146
 147 =head2 $entry->author([ $author ])
 148
 149 The name or email address of the person who posted the entry.
 150
 151 =head2 $entry->id([ $id ])
 152
 153 The unique ID of the entry.
 154
 155 =head2 $entry->issued([ $issued ])
 156
 157 A I<DateTime> object representing the date and time at which the entry
 158 was posted.
 159
 160 If present, I<$issued> should be a I<DateTime> object.
 161
 162 =head2 $entry->modified([ $modified ])
 163
 164 A I<DateTime> object representing the last-modified date of the entry.
 165
 166 If present, I<$modified> should be a I<DateTime> object.
 167
 168 =head2 $entry->wrap
 169
 170 Take an entry in its native format and turn it into an I<XML::Feed::Entry> object.
 171
 172 =head2 $entry->unwrap
 173
 174 Take an I<XML::Feed::Entry> object and turn it into its native format.
 175
 176 =head1 AUTHOR & COPYRIGHT
 177
 178 Please see the I<XML::Feed> manpage for author, copyright, and license
 179 information.
 180
 181 =cut