.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" 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 turned on, 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 "2015-12-15" "perl v5.20.2" "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\->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