[catagits/XML-Feed.git] / lib / 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 Scalar::Util qw( blessed );

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