[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 category 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);
    }
    $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(@_) }

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->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 ])

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.

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

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

A synonym 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);
9a36f82c	37	for my $field (qw( title link content summary category 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	}
	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;
9a36f82c	55	sub lat;
9a36f82c	56	sub long;
3bdbab6f	57	sub format;
a0cca2a4	58	sub tags { shift->category(@_) }
0d5e38d1	59
	60	1;
	61	__END__
	62
	63	=head1 NAME
	64
	65	XML::Feed::Entry - Entry/item in a syndication feed
	66
	67	=head1 SYNOPSIS
	68
	69	## $feed is an XML::Feed object.
	70	for my $entry ($feed->entries) {
	71	print $entry->title, "\n", $entry->summary, "\n\n";
	72	}
	73
	74	=head1 DESCRIPTION
	75
	76	I<XML::Feed::Entry> represents an entry/item in an I<XML::Feed> syndication
	77	feed.
	78
	79	=head1 USAGE
	80
973e1f9e	81	=head2 XML::Feed::Entry->new($format)
	82
	83	Creates a new I<XML::Feed::Entry> object in the format I<$format>, which
	84	should be either I<RSS> or I<Atom>.
	85
	86	=head2 $entry->convert($format)
	87
	88	Converts the I<XML::Feed::Entry> object into the I<$format> format, and
	89	returns the new object.
	90
	91	=head2 $entry->title([ $title ])
0d5e38d1	92
	93	The title of the entry.
	94
5383a560	95	=head2 $entry->base([ $base ])
	96
	97	The url base of the entry.
	98
973e1f9e	99	=head2 $entry->link([ $uri ])
0d5e38d1	100
0d5e38d1	101	The permalink of the entry, in most cases, except in cases where it points
fe71566d	102	instead to an offsite URI referenced in the entry.
0d5e38d1	103
973e1f9e	104	=head2 $entry->content([ $content ])
0d5e38d1	105
a749d9b9	106	Bn I<XML::Feed::Content> object representing the full entry body, or as
a749d9b9	107	much as is available in the feed.
0d5e38d1	108
	109	In RSS feeds, this method will look first for
	110	I<http://purl.org/rss/1.0/modules/content/#encoded> and
	111	I<http://www.w3.org/1999/xhtml#body> elements, then fall back to a
	112	I<E<lt>descriptionE<gt>> element.
	113
973e1f9e	114	=head2 $entry->summary([ $summary ])
0d5e38d1	115
a749d9b9	116	An I<XML::Feed::Content> object representing a short summary of the entry.
a749d9b9	117	Possibly.
0d5e38d1	118
0d5e38d1	119	Since RSS feeds do not have the idea of a summary separate from the entry
a749d9b9	120	body, this may not always be what you want. If the entry contains both a
	121	I<E<lt>descriptionE<gt>> element B<and> another element typically used for
	122	the full content of the entry--either I<http://www.w3.org/1999/xhtml/body>
	123	or I<http://purl.org/rss/1.0/modules/content/#encoded>--we treat that as
	124	the summary. Otherwise, we assume that there isn't a summary, and return
	125	an I<XML::Feed::Content> object with an empty string in the I<body>.
0d5e38d1	126
973e1f9e	127	=head2 $entry->category([ $category ])
0d5e38d1	128
	129	The category in which the entry was posted.
	130
a0cca2a4	131	Returns a list of categories if called in array context or the first
	132	category if called in scalar context.
	133
	134	=head2 $entry->tags([ $tag ])
	135
	136	A synonym for I<category>;
	137
973e1f9e	138	=head2 $entry->author([ $author ])
0d5e38d1	139
	140	The name or email address of the person who posted the entry.
	141
973e1f9e	142	=head2 $entry->id([ $id ])
0d5e38d1	143
	144	The unique ID of the entry.
	145
973e1f9e	146	=head2 $entry->issued([ $issued ])
0d5e38d1	147
	148	A I<DateTime> object representing the date and time at which the entry
	149	was posted.
	150
973e1f9e	151	If present, I<$issued> should be a I<DateTime> object.
	152
	153	=head2 $entry->modified([ $modified ])
0d5e38d1	154
	155	A I<DateTime> object representing the last-modified date of the entry.
	156
973e1f9e	157	If present, I<$modified> should be a I<DateTime> object.
973e1f9e	158
8c30ad3d	159	=head2 $entry->wrap
	160
	161	Take an entry in its native format and turn it into an I<XML::Feed::Entry> object.
	162
	163	=head2 $entry->unwrap
	164
	165	Take an I<XML::Feed::Entry> object and turn it into its native format.
	166
0d5e38d1	167	=head1 AUTHOR & COPYRIGHT
	168
	169	Please see the I<XML::Feed> manpage for author, copyright, and license
	170	information.
	171
	172	=cut