[catagits/XML-Feed.git] / lib / XML / Feed / Entry.pm

# $Id$

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::' . $format;
    eval "use $format_class";
    Carp::croak("Unsupported format $format: $@") if $@;
    my $entry = bless {}, join('::', __PACKAGE__, "Format", $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 author id issued modified lat long )) {
        my $val = $entry->$field();
        next unless defined $val;
        next if blessed $val && $val->isa('XML::Feed::Content') && ! defined $val->body;
        $new->$field($val);
    }
    for my $field (qw( category )) {
        my @val = $entry->$field();
        next unless @val;
        $new->$field(@val);
    }
    $new;
}

sub title;
sub link;
sub content;
sub summary;
sub category;
sub author;
sub id;
sub issued;
sub modified;
sub lat;
sub long;
sub format;
sub tags { shift->category(@_) }
sub enclosure;

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 L<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->base([ $base ])

The url base 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 ])

An L<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
L<http://purl.org/rss/1.0/modules/content/#encoded> and
L<http://www.w3.org/1999/xhtml#body> elements, then fall back to a
I<E<lt>descriptionE<gt>> element.

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

An L<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 L<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 L<XML::Feed::Content> object with an empty string in the I<body>.

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

The category in which the entry was posted.

Returns a list of categories if called in array context or the first
category if called in scalar context.

B<WARNING> It's possible this API might change to have an 
I<add_category> instead.

=head2 $entry->tags([ $tag ])

A synonym (alias) for I<category>;

=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.

=head2 $entry->wrap

Take an entry in its native format and turn it into an I<XML::Feed::Entry> object.

=head2 $entry->unwrap

Take an I<XML::Feed::Entry> object and turn it into its native format.

=head1 AUTHOR & COPYRIGHT

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

=cut
Commit	Line	Data
3353d70c	1	# $Id$
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';
729cd7a8	23	my $format_class = 'XML::Feed::Format::' . $format;
973e1f9e	24	eval "use $format_class";
973e1f9e	25	Carp::croak("Unsupported format $format: $@") if $@;
729cd7a8	26	my $entry = bless {}, join('::', __PACKAGE__, "Format", $format);
973e1f9e	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);
ff32fd51	37	for my $field (qw( title link content summary author id issued modified lat long )) {
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	}
ff32fd51	43	for my $field (qw( category )) {
	44	my @val = $entry->$field();
	45	next unless @val;
	46	$new->$field(@val);
	47	}
973e1f9e	48	$new;
	49	}
	50
0d5e38d1	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;
9a36f82c	60	sub lat;
9a36f82c	61	sub long;
3bdbab6f	62	sub format;
a0cca2a4	63	sub tags { shift->category(@_) }
12a4079f	64	sub enclosure;
0d5e38d1	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
200ce863	82	I<XML::Feed::Entry> represents an entry/item in an L<XML::Feed> syndication
0d5e38d1	83	feed.
	84
	85	=head1 USAGE
	86
973e1f9e	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 ])
0d5e38d1	98
	99	The title of the entry.
	100
5383a560	101	=head2 $entry->base([ $base ])
	102
	103	The url base of the entry.
	104
973e1f9e	105	=head2 $entry->link([ $uri ])
0d5e38d1	106
0d5e38d1	107	The permalink of the entry, in most cases, except in cases where it points
fe71566d	108	instead to an offsite URI referenced in the entry.
0d5e38d1	109
973e1f9e	110	=head2 $entry->content([ $content ])
0d5e38d1	111
200ce863	112	An L<XML::Feed::Content> object representing the full entry body, or as
a749d9b9	113	much as is available in the feed.
0d5e38d1	114
0d5e38d1	115	In RSS feeds, this method will look first for
200ce863	116	L<http://purl.org/rss/1.0/modules/content/#encoded> and
200ce863	117	L<http://www.w3.org/1999/xhtml#body> elements, then fall back to a
0d5e38d1	118	I<E<lt>descriptionE<gt>> element.
0d5e38d1	119
973e1f9e	120	=head2 $entry->summary([ $summary ])
0d5e38d1	121
200ce863	122	An L<XML::Feed::Content> object representing a short summary of the entry.
a749d9b9	123	Possibly.
0d5e38d1	124
0d5e38d1	125	Since RSS feeds do not have the idea of a summary separate from the entry
a749d9b9	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>
200ce863	129	or L<http://purl.org/rss/1.0/modules/content/#encoded>--we treat that as
a749d9b9	130	the summary. Otherwise, we assume that there isn't a summary, and return
200ce863	131	an L<XML::Feed::Content> object with an empty string in the I<body>.
0d5e38d1	132
973e1f9e	133	=head2 $entry->category([ $category ])
0d5e38d1	134
	135	The category in which the entry was posted.
	136
a0cca2a4	137	Returns a list of categories if called in array context or the first
	138	category if called in scalar context.
	139
a759e13e	140	B<WARNING> It's possible this API might change to have an
	141	I<add_category> instead.
	142
a0cca2a4	143	=head2 $entry->tags([ $tag ])
a0cca2a4	144
200ce863	145	A synonym (alias) for I<category>;
a0cca2a4	146
973e1f9e	147	=head2 $entry->author([ $author ])
0d5e38d1	148
	149	The name or email address of the person who posted the entry.
	150
973e1f9e	151	=head2 $entry->id([ $id ])
0d5e38d1	152
	153	The unique ID of the entry.
	154
973e1f9e	155	=head2 $entry->issued([ $issued ])
0d5e38d1	156
	157	A I<DateTime> object representing the date and time at which the entry
	158	was posted.
	159
973e1f9e	160	If present, I<$issued> should be a I<DateTime> object.
	161
	162	=head2 $entry->modified([ $modified ])
0d5e38d1	163
	164	A I<DateTime> object representing the last-modified date of the entry.
	165
973e1f9e	166	If present, I<$modified> should be a I<DateTime> object.
973e1f9e	167
8c30ad3d	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
0d5e38d1	176	=head1 AUTHOR & COPYRIGHT
	177
	178	Please see the I<XML::Feed> manpage for author, copyright, and license
	179	information.
	180
	181	=cut