lib/XML/Feed/Entry.pm

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