XML/Feed/Entry.pm

# $Id: Entry.pm 1872 2005-08-12 04:28:42Z btrott $

package XML::Feed::Entry;
use strict;
use base qw( Class::ErrorHandler );

use Carp;

sub wrap {
    my $class = shift;
    my($item) = @_;
    bless { entry => $item }, $class;
}

sub unwrap { $_[0]->{entry} }

sub new {
    my $class = shift;
    my($format) = @_;
    $format ||= 'Atom';
    my $format_class = 'XML::Feed::' . $format;
    eval "use $format_class";
    Carp::croak("Unsupported format $format: $@") if $@;
    my $entry = bless {}, join('::', __PACKAGE__, $format);
    $entry->init_empty or return $class->error($entry->errstr);
    $entry;
}

sub init_empty { 1 }

sub convert {
    my $entry = shift;
    my($format) = @_;
    my $new = __PACKAGE__->new($format);
    for my $field (qw( title link content summary category author id issued modified )) {
        my $val = $entry->$field();
        next unless defined $val;
        $new->$field($val);
    }
    $new;
}

sub title;
sub link;
sub content;
sub summary;
sub category;
sub author;
sub id;
sub issued;
sub modified;

1;
__END__

=head1 NAME

XML::Feed::Entry - Entry/item in a syndication feed

=head1 SYNOPSIS

    ## $feed is an XML::Feed object.
    for my $entry ($feed->entries) {
        print $entry->title, "\n", $entry->summary, "\n\n";
    }

=head1 DESCRIPTION

I<XML::Feed::Entry> represents an entry/item in an I<XML::Feed> syndication
feed.

=head1 USAGE

=head2 XML::Feed::Entry->new($format)

Creates a new I<XML::Feed::Entry> object in the format I<$format>, which
should be either I<RSS> or I<Atom>.

=head2 $entry->convert($format)

Converts the I<XML::Feed::Entry> object into the I<$format> format, and
returns the new object.

=head2 $entry->title([ $title ])

The title of the entry.

=head2 $entry->link([ $uri ])

The permalink of the entry, in most cases, except in cases where it points
instead to an offsite URI referenced in the entry.

=head2 $entry->content([ $content ])

Bn I<XML::Feed::Content> object representing the full entry body, or as
much as is available in the feed.

In RSS feeds, this method will look first for
I<http://purl.org/rss/1.0/modules/content/#encoded> and
I<http://www.w3.org/1999/xhtml#body> elements, then fall back to a
I<E<lt>descriptionE<gt>> element.

=head2 $entry->summary([ $summary ])

An I<XML::Feed::Content> object representing a short summary of the entry.
Possibly.

Since RSS feeds do not have the idea of a summary separate from the entry
body, this may not always be what you want. If the entry contains both a
I<E<lt>descriptionE<gt>> element B<and> another element typically used for
the full content of the entry--either I<http://www.w3.org/1999/xhtml/body>
or I<http://purl.org/rss/1.0/modules/content/#encoded>--we treat that as
the summary. Otherwise, we assume that there isn't a summary, and return
an I<XML::Feed::Content> object with an empty string in the I<body>.

=head2 $entry->category([ $category ])

The category in which the entry was posted.

=head2 $entry->author([ $author ])

The name or email address of the person who posted the entry.

=head2 $entry->id([ $id ])

The unique ID of the entry.

=head2 $entry->issued([ $issued ])

A I<DateTime> object representing the date and time at which the entry
was posted.

If present, I<$issued> should be a I<DateTime> object.

=head2 $entry->modified([ $modified ])

A I<DateTime> object representing the last-modified date of the entry.

If present, I<$modified> should be a I<DateTime> object.

=head1 AUTHOR & COPYRIGHT

Please see the I<XML::Feed> manpage for author, copyright, and license
information.

=cut
1	dpavlin	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