.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "XML::Feed 3pm"
.TH XML::Feed 3pm "2019-02-06" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
XML::Feed \- Syndication feed parser and auto\-discovery
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\& use XML::Feed;
\& my $feed = XML::Feed\->parse(URI\->new(\*(Aqhttp://example.com/atom.xml\*(Aq))
\& or die XML::Feed\->errstr;
\& print $feed\->title, "\en";
\& for my $entry ($feed\->entries) {
\& }
\&
\& ## Find all of the syndication feeds on a given page, using
\& ## auto\-discovery.
\& my @feeds = XML::Feed\->find_feeds(\*(Aqhttp://example.com/\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIXML::Feed\fR is a syndication feed parser for both \s-1RSS\s0 and Atom feeds. It
also implements feed auto-discovery for finding feeds, given a \s-1URI.\s0
.PP
\&\fIXML::Feed\fR supports the following syndication feed formats:
.IP "\(bu" 4
\&\s-1RSS 0.91\s0
.IP "\(bu" 4
\&\s-1RSS 1.0\s0
.IP "\(bu" 4
\&\s-1RSS 2.0\s0
.IP "\(bu" 4
Atom
.PP
The goal of \fIXML::Feed\fR is to provide a unified \s-1API\s0 for parsing and using
the various syndication formats. The different flavors of \s-1RSS\s0 and Atom
handle data in different ways: date handling; summaries and content;
escaping and quoting; etc. This module attempts to remove those differences
by providing a wrapper around the formats and the classes implementing
those formats (\s-1XML::RSS\s0 and XML::Atom::Feed). For example, dates are
handled differently in each of the above formats. To provide a unified \s-1API\s0 for
date handling, \fIXML::Feed\fR converts all date formats transparently into
DateTime objects, which it then returns to the caller.
.SH "USAGE"
.IX Header "USAGE"
.SS "XML::Feed\->new($format)"
.IX Subsection "XML::Feed->new($format)"
Creates a new empty \fIXML::Feed\fR object using the format \fI\f(CI$format\fI\fR.
.PP
.Vb 3
\& $feed = XML::Feed\->new(\*(AqAtom\*(Aq);
\& $feed = XML::Feed\->new(\*(AqRSS\*(Aq);
\& $feed = XML::Feed\->new(\*(AqRSS\*(Aq, version => \*(Aq0.91\*(Aq);
.Ve
.SS "XML::Feed\->parse($stream)"
.IX Subsection "XML::Feed->parse($stream)"
.ie n .SS "XML::Feed\->parse($stream, $format)"
.el .SS "XML::Feed\->parse($stream, \f(CW$format\fP)"
.IX Subsection "XML::Feed->parse($stream, $format)"
Parses a syndication feed identified by \fI\f(CI$stream\fI\fR and returns an
\&\fIXML::Feed\fR object. \fI\f(CI$stream\fI\fR can be any
one of the following:
.IP "\(bu" 4
Scalar reference
.Sp
A reference to string containing the \s-1XML\s0 body of the feed.
.IP "\(bu" 4
Filehandle
.Sp
An open filehandle from which the feed \s-1XML\s0 will be read.
.IP "\(bu" 4
File name
.Sp
The name of a file containing the feed \s-1XML.\s0
.IP "\(bu" 4
\&\s-1URI\s0 object
.Sp
A \s-1URI\s0 from which the feed \s-1XML\s0 will be retrieved.
.PP
\&\fI\f(CI$format\fI\fR allows you to override format guessing.
.SS "XML::Feed\->get_uri($uri)"
.IX Subsection "XML::Feed->get_uri($uri)"
Gets a feed from a \s-1URI.\s0
.SS "XML::Feed\->find_feeds($uri)"
.IX Subsection "XML::Feed->find_feeds($uri)"
Given a \s-1URI\s0 \fI\f(CI$uri\fI\fR, use auto-discovery to find all of the feeds linked
from that page (using \fI\fR tags).
.PP
Returns a list of feed URIs.
.SS "XML::Feed\->identify_format(\e$xml)"
.IX Subsection "XML::Feed->identify_format($xml)"
Given the xml of a feed return what format it is in, with \f(CW\*(C`Atom\*(C'\fR or \f(CW\*(C`RSS\*(C'\fR for
all versions of \s-1RSS.\s0 Note that you pass in a scalar ref to the xml string.
.ie n .SS "$feed\->convert($format)"
.el .SS "\f(CW$feed\fP\->convert($format)"
.IX Subsection "$feed->convert($format)"
Converts the \fIXML::Feed\fR object into the \fI\f(CI$format\fI\fR format, and returns
the new object.
.ie n .SS "$feed\->splice($other_feed)"
.el .SS "\f(CW$feed\fP\->splice($other_feed)"
.IX Subsection "$feed->splice($other_feed)"
Splices in all of the entries from the feed \fI\f(CI$other_feed\fI\fR into \fI\f(CI$feed\fI\fR,
skipping posts that are already in \fI\f(CI$feed\fI\fR.
.ie n .SS "$feed\->format"
.el .SS "\f(CW$feed\fP\->format"
.IX Subsection "$feed->format"
Returns the format of the feed (\f(CW\*(C`Atom\*(C'\fR, or some version of \f(CW\*(C`RSS\*(C'\fR).
.ie n .SS "$feed\->title([ $title ])"
.el .SS "\f(CW$feed\fP\->title([ \f(CW$title\fP ])"
.IX Subsection "$feed->title([ $title ])"
The title of the feed/channel.
.ie n .SS "$feed\->base([ $base ])"
.el .SS "\f(CW$feed\fP\->base([ \f(CW$base\fP ])"
.IX Subsection "$feed->base([ $base ])"
The url base of the feed/channel.
.ie n .SS "$feed\->link([ $uri ])"
.el .SS "\f(CW$feed\fP\->link([ \f(CW$uri\fP ])"
.IX Subsection "$feed->link([ $uri ])"
The permalink of the feed/channel.
.ie n .SS "$feed\->tagline([ $tagline ])"
.el .SS "\f(CW$feed\fP\->tagline([ \f(CW$tagline\fP ])"
.IX Subsection "$feed->tagline([ $tagline ])"
The description or tagline of the feed/channel.
.ie n .SS "$feed\->description([ $description ])"
.el .SS "\f(CW$feed\fP\->description([ \f(CW$description\fP ])"
.IX Subsection "$feed->description([ $description ])"
Alias for \fI\f(CI$feed\fI\->tagline\fR.
.ie n .SS "$feed\->author([ $author ])"
.el .SS "\f(CW$feed\fP\->author([ \f(CW$author\fP ])"
.IX Subsection "$feed->author([ $author ])"
The author of the feed/channel.
.ie n .SS "$feed\->language([ $language ])"
.el .SS "\f(CW$feed\fP\->language([ \f(CW$language\fP ])"
.IX Subsection "$feed->language([ $language ])"
The language of the feed.
.ie n .SS "$feed\->copyright([ $copyright ])"
.el .SS "\f(CW$feed\fP\->copyright([ \f(CW$copyright\fP ])"
.IX Subsection "$feed->copyright([ $copyright ])"
The copyright notice of the feed.
.ie n .SS "$feed\->modified([ $modified ])"
.el .SS "\f(CW$feed\fP\->modified([ \f(CW$modified\fP ])"
.IX Subsection "$feed->modified([ $modified ])"
A \fIDateTime\fR object representing the last-modified date of the feed.
.PP
If present, \fI\f(CI$modified\fI\fR should be a \fIDateTime\fR object.
.ie n .SS "$feed\->generator([ $generator ])"
.el .SS "\f(CW$feed\fP\->generator([ \f(CW$generator\fP ])"
.IX Subsection "$feed->generator([ $generator ])"
The generator of the feed.
.ie n .SS "$feed\->self_link ([ $uri ])"
.el .SS "\f(CW$feed\fP\->self_link ([ \f(CW$uri\fP ])"
.IX Subsection "$feed->self_link ([ $uri ])"
The Atom Self-link of the feed:
.PP
.PP
A string.
.ie n .SS "$feed\->entries"
.el .SS "\f(CW$feed\fP\->entries"
.IX Subsection "$feed->entries"
A list of the entries/items in the feed. Returns an array containing
XML::Feed::Entry objects.
.ie n .SS "$feed\->items"
.el .SS "\f(CW$feed\fP\->items"
.IX Subsection "$feed->items"
A synonym (alias) for <$feed\->entries>.
.ie n .SS "$feed\->add_entry($entry)"
.el .SS "\f(CW$feed\fP\->add_entry($entry)"
.IX Subsection "$feed->add_entry($entry)"
Adds an entry to the feed. \fI\f(CI$entry\fI\fR should be an XML::Feed::Entry
object in the correct format for the feed.
.ie n .SS "$feed\->as_xml"
.el .SS "\f(CW$feed\fP\->as_xml"
.IX Subsection "$feed->as_xml"
Returns an \s-1XML\s0 representation of the feed, in the format determined by
the current format of the \fI\f(CI$feed\fI\fR object.
.ie n .SS "$feed\->first_link ([ $uri ])"
.el .SS "\f(CW$feed\fP\->first_link ([ \f(CW$uri\fP ])"
.IX Subsection "$feed->first_link ([ $uri ])"
The Atom First-link for feed paging and archiving (\s-1RFC 5005\s0).
.PP
.ie n .SS "$feed\->last_link ([ $uri ])"
.el .SS "\f(CW$feed\fP\->last_link ([ \f(CW$uri\fP ])"
.IX Subsection "$feed->last_link ([ $uri ])"
The Atom Last-link for feed paging and archiving.
.ie n .SS "$feed\->next_link ([ $uri ])"
.el .SS "\f(CW$feed\fP\->next_link ([ \f(CW$uri\fP ])"
.IX Subsection "$feed->next_link ([ $uri ])"
The Atom Next-link for feed paging and archiving.
.ie n .SS "$feed\->previous_link ([ $uri ])"
.el .SS "\f(CW$feed\fP\->previous_link ([ \f(CW$uri\fP ])"
.IX Subsection "$feed->previous_link ([ $uri ])"
The Atom Previous-link for feed paging and archiving.
.ie n .SS "$feed\->current_link ([ $uri ])"
.el .SS "\f(CW$feed\fP\->current_link ([ \f(CW$uri\fP ])"
.IX Subsection "$feed->current_link ([ $uri ])"
The Atom Current-link for feed paging and archiving.
.ie n .SS "$feed\->next_archive_link ([ $uri ])"
.el .SS "\f(CW$feed\fP\->next_archive_link ([ \f(CW$uri\fP ])"
.IX Subsection "$feed->next_archive_link ([ $uri ])"
The Atom Next-link for feed paging and archiving.
.ie n .SS "$feed\->prev_archive_link ([ $uri ])"
.el .SS "\f(CW$feed\fP\->prev_archive_link ([ \f(CW$uri\fP ])"
.IX Subsection "$feed->prev_archive_link ([ $uri ])"
The Atom Prev-Archive-link for feed paging and archiving.
.SH "PACKAGE VARIABLES"
.IX Header "PACKAGE VARIABLES"
.ie n .IP "$XML::Feed::Format::RSS::PREFERRED_PARSER" 4
.el .IP "\f(CW$XML::Feed::Format::RSS::PREFERRED_PARSER\fR" 4
.IX Item "$XML::Feed::Format::RSS::PREFERRED_PARSER"
If you want to use another \s-1RSS\s0 parser class than \s-1XML::RSS\s0 (default), you can
change the class by setting \f(CW$PREFERRED_PARSER\fR variable in the
XML::Feed::Format::RSS package.
.Sp
.Vb 1
\& $XML::Feed::Format::RSS::PREFERRED_PARSER = "XML::RSS::LibXML";
.Ve
.Sp
\&\fBNote:\fR this will only work for parsing feeds, not creating feeds.
.Sp
\&\fBNote:\fR Only \f(CW\*(C`XML::RSS::LibXML\*(C'\fR version 0.3004 is known to work at the moment.
.ie n .IP "$XML::Feed::MULTIPLE_ENCLOSURES" 4
.el .IP "\f(CW$XML::Feed::MULTIPLE_ENCLOSURES\fR" 4
.IX Item "$XML::Feed::MULTIPLE_ENCLOSURES"
Although the \s-1RSS\s0 specification states that there can be at most one enclosure per item
some feeds break this rule.
.Sp
If this variable is set then \f(CW\*(C`XML::Feed\*(C'\fR captures all of them and makes them available as a list.
.Sp
Otherwise it returns the last enclosure parsed.
.Sp
\&\fBNote:\fR \f(CW\*(C`XML::RSS\*(C'\fR version 1.44 is needed for this to work.
.SH "VALID FEEDS"
.IX Header "VALID FEEDS"
For reference, this cgi script will create valid, albeit nonsensical feeds
(according to \f(CW\*(C`http://feedvalidator.org\*(C'\fR anyway) for Atom 1.0 and \s-1RSS 0.90,
0.91, 1.0\s0 and 2.0.
.PP
.Vb 1
\& #!perl \-w
\&
\& use strict;
\& use CGI;
\& use CGI::Carp qw(fatalsToBrowser);
\& use DateTime;
\& use XML::Feed;
\&
\& my $cgi = CGI\->new;
\& my @args = ( $cgi\->param(\*(Aqformat\*(Aq) // "Atom" );
\& push @args, ( version => $cgi\->param(\*(Aqversion\*(Aq) ) if $cgi\->param(\*(Aqversion\*(Aq);
\&
\& my $feed = XML::Feed\->new(@args);
\& $feed\->id("http://".time.rand()."/");
\& $feed\->title(\*(AqTest Feed\*(Aq);
\& $feed\->link($cgi\->url);
\& $feed\->self_link($cgi\->url( \-query => 1, \-full => 1, \-rewrite => 1) );
\& $feed\->modified(DateTime\->now);
\&
\& my $entry = XML::Feed::Entry\->new();
\& $entry\->id("http://".time.rand()."/");
\& $entry\->link("http://example.com");
\& $entry\->title("Test entry");
\& $entry\->summary("Test summary");
\& $entry\->content("Foo");
\& $entry\->modified(DateTime\->now);
\& $entry\->author(\*(Aqtest@example.com (Testy McTesterson)\*(Aq);
\& $feed\->add_entry($entry);
\&
\& my $mime = ("Atom" eq $feed\->format) ? "application/atom+xml" : "application/rss+xml";
\& print $cgi\->header($mime);
\& print $feed\->as_xml;
.Ve
.SH "LICENSE"
.IX Header "LICENSE"
\&\fIXML::Feed\fR is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.
.SH "AUTHOR & COPYRIGHT"
.IX Header "AUTHOR & COPYRIGHT"
Except where otherwise noted, \fIXML::Feed\fR is Copyright 2004\-2008
Six Apart. All rights reserved.
.SH "SUPPORT"
.IX Header "SUPPORT"
For support contact the XML::Feed mailing list \- xml\-feed@perlhacks.com.
.SH "SOURCE CODE"
.IX Header "SOURCE CODE"
The latest version of \fIXML::Feed\fR can be found at
.PP
.Vb 1
\& http://github.com/davorg/XML\-Feed
.Ve