[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 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
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 );
	6
	7	use Carp;
0d5e38d1	8
	9	sub wrap {
	10	my $class = shift;
	11	my($item) = @_;
	12	bless { entry => $item }, $class;
	13	}
	14
973e1f9e	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 )) {
23103173	36	my $val = $entry->$field();
	37	next unless defined $val;
	38	$new->$field($val);
973e1f9e	39	}
	40	$new;
	41	}
	42
0d5e38d1	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
973e1f9e	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 ])
0d5e38d1	85
	86	The title of the entry.
	87
973e1f9e	88	=head2 $entry->link([ $uri ])
0d5e38d1	89
0d5e38d1	90	The permalink of the entry, in most cases, except in cases where it points
fe71566d	91	instead to an offsite URI referenced in the entry.
0d5e38d1	92
973e1f9e	93	=head2 $entry->content([ $content ])
0d5e38d1	94
a749d9b9	95	Bn I<XML::Feed::Content> object representing the full entry body, or as
a749d9b9	96	much as is available in the feed.
0d5e38d1	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
973e1f9e	103	=head2 $entry->summary([ $summary ])
0d5e38d1	104
a749d9b9	105	An I<XML::Feed::Content> object representing a short summary of the entry.
a749d9b9	106	Possibly.
0d5e38d1	107
0d5e38d1	108	Since RSS feeds do not have the idea of a summary separate from the entry
a749d9b9	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>.
0d5e38d1	115
973e1f9e	116	=head2 $entry->category([ $category ])
0d5e38d1	117
	118	The category in which the entry was posted.
	119
973e1f9e	120	=head2 $entry->author([ $author ])
0d5e38d1	121
	122	The name or email address of the person who posted the entry.
	123
973e1f9e	124	=head2 $entry->id([ $id ])
0d5e38d1	125
	126	The unique ID of the entry.
	127
973e1f9e	128	=head2 $entry->issued([ $issued ])
0d5e38d1	129
	130	A I<DateTime> object representing the date and time at which the entry
	131	was posted.
	132
973e1f9e	133	If present, I<$issued> should be a I<DateTime> object.
	134
	135	=head2 $entry->modified([ $modified ])
0d5e38d1	136
	137	A I<DateTime> object representing the last-modified date of the entry.
	138
973e1f9e	139	If present, I<$modified> should be a I<DateTime> object.
973e1f9e	140
0d5e38d1	141	=head1 AUTHOR & COPYRIGHT
	142
	143	Please see the I<XML::Feed> manpage for author, copyright, and license
	144	information.
	145
	146	=cut