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