.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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
.\" ========================================================================
.\"
.IX Title "XML::RSS::Feed 3pm"
.TH XML::RSS::Feed 3pm "2023-09-14" "perl v5.36.0" "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::RSS::Feed \- Persistant XML RSS Encapsulation
.SH "VERSION"
.IX Header "VERSION"
2.212
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
A quick and dirty non-POE example that uses a blocking \fBsleep\fR.  The
magic is in the \fBlate_breaking_news\fR method that returns only 
headlines it hasn't seen.
.PP
.Vb 2
\&    use XML::RSS::Feed;
\&    use LWP::Simple qw(get);
\&
\&    my $feed = XML::RSS::Feed\->new(
\&        url    => "http://www.jbisbee.com/rdf/",
\&        name   => "jbisbee",
\&        delay  => 10,
\&        debug  => 1,
\&        tmpdir => "/tmp", # optional caching
\&    );
\&
\&    while (1) {
\&        $feed\->parse(get($feed\->url));
\&        print $_\->headline . "\en" for $feed\->late_breaking_news;
\&        sleep($feed\->delay); 
\&    }
.Ve
.PP
\&\s-1ATTENTION\s0! \- If you want a non-blocking way to watch multiple \s-1RSS\s0 sources 
with one process use POE::Component::RSSAggregator.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.ie n .SS "XML::RSS::Feed\->new( url => $url, name => $name )"
.el .SS "XML::RSS::Feed\->new( url => \f(CW$url\fP, name => \f(CW$name\fP )"
.IX Subsection "XML::RSS::Feed->new( url => $url, name => $name )"
.IP "\fBRequired Params\fR" 4
.IX Item "Required Params"
.RS 4
.PD 0
.IP "\(bu" 4
.PD
\&\fBname\fR
.Sp
Identifier and hash lookup key for the \s-1RSS\s0 feed.
.IP "\(bu" 4
\&\fBurl\fR
.Sp
The \s-1URL\s0 of the \s-1RSS\s0 feed
.RE
.RS 4
.RE
.IP "\fBOptional Params\fR" 4
.IX Item "Optional Params"
.RS 4
.PD 0
.IP "\(bu" 4
.PD
\&\fBdelay\fR
.Sp
Number of seconds between updates (defaults to 600)
.IP "\(bu" 4
\&\fBtmpdir\fR
.Sp
Directory to keep a cached feed (using Storable) to keep persistance between instances.
.IP "\(bu" 4
\&\fBdebug\fR
.Sp
Turn debuging on.
.IP "\(bu" 4
\&\fBheadline_as_id\fR
.Sp
Boolean value to use the headline as the id when \s-1URL\s0 isn't unique within a feed.
.IP "\(bu" 4
\&\fBhlobj\fR
.Sp
A class name sublcassed from XML::RSS::Headline
.IP "\(bu" 4
\&\fBmax_headlines\fR
.Sp
The max number of headlines to keep.  (default is unlimited)
.RE
.RS 4
.RE
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "$feed\->parse( $xml_string )"
.el .SS "\f(CW$feed\fP\->parse( \f(CW$xml_string\fP )"
.IX Subsection "$feed->parse( $xml_string )"
Pass in a xml string to parse with \s-1XML::RSS\s0 and then call 
process to process the results.
.ie n .SS "$feed\->process( $items, $title, $link )"
.el .SS "\f(CW$feed\fP\->process( \f(CW$items\fP, \f(CW$title\fP, \f(CW$link\fP )"
.IX Subsection "$feed->process( $items, $title, $link )"
.ie n .SS "$feed\->process( $items, $title )"
.el .SS "\f(CW$feed\fP\->process( \f(CW$items\fP, \f(CW$title\fP )"
.IX Subsection "$feed->process( $items, $title )"
.ie n .SS "$feed\->process( $items )"
.el .SS "\f(CW$feed\fP\->process( \f(CW$items\fP )"
.IX Subsection "$feed->process( $items )"
Calls \fBpre_process\fR, \fBprocess_items\fR, \fBpost_process\fR, \fBtitle\fR, and \fBlink\fR
methods to process the parsed results of an \s-1RSS XML\s0 feed.
.IP "\(bu" 4
\&\fB\f(CB$items\fB\fR
.Sp
An array of hash refs which will eventually become XML::RSS::Headline objects.  Look
at XML::RSS::Headline\->\fBnew()\fR for acceptable arguments.
.IP "\(bu" 4
\&\fB\f(CB$title\fB\fR
.Sp
The title of the \s-1RSS\s0 feed.
.IP "\(bu" 4
\&\fB\f(CB$link\fB\fR
.Sp
The \s-1RSS\s0 channel link (normally a \s-1URL\s0 back to the homepage) of the \s-1RSS\s0 feed.
.ie n .SS "$feed\->pre_process"
.el .SS "\f(CW$feed\fP\->pre_process"
.IX Subsection "$feed->pre_process"
Mark all headlines from previous run as seen.
.ie n .SS "$feed\->process_items( $items )"
.el .SS "\f(CW$feed\fP\->process_items( \f(CW$items\fP )"
.IX Subsection "$feed->process_items( $items )"
Turn an array refs of hash refs into XML::RSS::Headline objects and 
added to the internal list of headlines.
.ie n .SS "$feed\->post_process"
.el .SS "\f(CW$feed\fP\->post_process"
.IX Subsection "$feed->post_process"
Post process cleanup, cache headlines (if tmpdir), and debug messages.
.ie n .SS "$feed\->create_headline( %args)"
.el .SS "\f(CW$feed\fP\->create_headline( \f(CW%args\fP)"
.IX Subsection "$feed->create_headline( %args)"
Create a new XML::RSS::Headline object and add it to the interal list.  
Check \fBXML::RSS::Headline\->\fBnew()\fB\fR for acceptable values for \fB\f(CB%args\fB\fR.
.ie n .SS "$feed\->num_headlines"
.el .SS "\f(CW$feed\fP\->num_headlines"
.IX Subsection "$feed->num_headlines"
Returns the number of headlines for the feed.
.ie n .SS "$feed\->seen_headline( $id )"
.el .SS "\f(CW$feed\fP\->seen_headline( \f(CW$id\fP )"
.IX Subsection "$feed->seen_headline( $id )"
Just a boolean test to see if we've seen a headline or not.
.ie n .SS "$feed\->headlines"
.el .SS "\f(CW$feed\fP\->headlines"
.IX Subsection "$feed->headlines"
Returns an array or array reference (based on context) of 
XML::RSS::Headline objects
.ie n .SS "$feed\->late_breaking_news"
.el .SS "\f(CW$feed\fP\->late_breaking_news"
.IX Subsection "$feed->late_breaking_news"
Returns an array or the number of elements (based on context) of the 
\&\fBlatest\fR XML::RSS::Headline objects.
.ie n .SS "$feed\->cache"
.el .SS "\f(CW$feed\fP\->cache"
.IX Subsection "$feed->cache"
If tmpdir is defined the rss info is cached.
.ie n .SS "$feed\->set_last_updated"
.el .SS "\f(CW$feed\fP\->set_last_updated"
.IX Subsection "$feed->set_last_updated"
.ie n .SS "$feed\->set_last_updated( Time::HiRes::time )"
.el .SS "\f(CW$feed\fP\->set_last_updated( Time::HiRes::time )"
.IX Subsection "$feed->set_last_updated( Time::HiRes::time )"
Set the time of when the feed was last processed.  If you pass in a value
it will be used otherwise calls Time::HiRes::time.
.ie n .SS "$feed\->last_updated"
.el .SS "\f(CW$feed\fP\->last_updated"
.IX Subsection "$feed->last_updated"
The time (in epoch seconds) of when the feed was last processed.
.ie n .SS "$feed\->last_updated_hires"
.el .SS "\f(CW$feed\fP\->last_updated_hires"
.IX Subsection "$feed->last_updated_hires"
The time (in epoch seconds and milliseconds) of when the feed was last 
processed.
.SH "SET/GET ACCESSOR METHODS"
.IX Header "SET/GET ACCESSOR METHODS"
.ie n .SS "$feed\->title"
.el .SS "\f(CW$feed\fP\->title"
.IX Subsection "$feed->title"
.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 \s-1RSS\s0 feed.
.ie n .SS "$feed\->debug"
.el .SS "\f(CW$feed\fP\->debug"
.IX Subsection "$feed->debug"
.ie n .SS "$feed\->debug( $bool )"
.el .SS "\f(CW$feed\fP\->debug( \f(CW$bool\fP )"
.IX Subsection "$feed->debug( $bool )"
Turn on debugging messages
.ie n .SS "$feed\->init"
.el .SS "\f(CW$feed\fP\->init"
.IX Subsection "$feed->init"
.ie n .SS "$feed\->init( $bool )"
.el .SS "\f(CW$feed\fP\->init( \f(CW$bool\fP )"
.IX Subsection "$feed->init( $bool )"
init is used so that we just load the current headlines and don't return all 
headlines.  in other words we initialize them.  Takes a boolean argument.
.ie n .SS "$feed\->name"
.el .SS "\f(CW$feed\fP\->name"
.IX Subsection "$feed->name"
.ie n .SS "$feed\->name( $name )"
.el .SS "\f(CW$feed\fP\->name( \f(CW$name\fP )"
.IX Subsection "$feed->name( $name )"
The identifier of an \s-1RSS\s0 feed.
.ie n .SS "$feed\->delay"
.el .SS "\f(CW$feed\fP\->delay"
.IX Subsection "$feed->delay"
.ie n .SS "$feed\->delay( $seconds )"
.el .SS "\f(CW$feed\fP\->delay( \f(CW$seconds\fP )"
.IX Subsection "$feed->delay( $seconds )"
Number of seconds between updates.
.ie n .SS "$feed\->link"
.el .SS "\f(CW$feed\fP\->link"
.IX Subsection "$feed->link"
.ie n .SS "$feed\->link( $rss_channel_url )"
.el .SS "\f(CW$feed\fP\->link( \f(CW$rss_channel_url\fP )"
.IX Subsection "$feed->link( $rss_channel_url )"
The url in the \s-1RSS\s0 feed with a link back to the site where the \s-1RSS\s0 feed 
came from.
.ie n .SS "$feed\->url"
.el .SS "\f(CW$feed\fP\->url"
.IX Subsection "$feed->url"
.ie n .SS "$feed\->url( $url )"
.el .SS "\f(CW$feed\fP\->url( \f(CW$url\fP )"
.IX Subsection "$feed->url( $url )"
The url in the \s-1RSS\s0 feed with a link back to the site where the \s-1RSS\s0 feed 
came from.
.ie n .SS "$feed\->headline_as_id"
.el .SS "\f(CW$feed\fP\->headline_as_id"
.IX Subsection "$feed->headline_as_id"
.ie n .SS "$feed\->headline_as_id( $bool )"
.el .SS "\f(CW$feed\fP\->headline_as_id( \f(CW$bool\fP )"
.IX Subsection "$feed->headline_as_id( $bool )"
Within some \s-1RSS\s0 feeds the \s-1URL\s0 may not always be unique, in these cases
you can use the headline as the unique id.  The id is used to check whether
or not a feed is new or has already been seen.
.ie n .SS "$feed\->hlobj"
.el .SS "\f(CW$feed\fP\->hlobj"
.IX Subsection "$feed->hlobj"
.ie n .SS "$feed\->hlobj( $class )"
.el .SS "\f(CW$feed\fP\->hlobj( \f(CW$class\fP )"
.IX Subsection "$feed->hlobj( $class )"
Ablity to use a subclass of XML::RSS::Headline.  (See Perl Jobs example in 
XML::RSS::Headline::PerlJobs).  This should just be the name of the subclass.
.ie n .SS "$feed\->tmpdir"
.el .SS "\f(CW$feed\fP\->tmpdir"
.IX Subsection "$feed->tmpdir"
.ie n .SS "$feed\->tmpdir( $tmpdir )"
.el .SS "\f(CW$feed\fP\->tmpdir( \f(CW$tmpdir\fP )"
.IX Subsection "$feed->tmpdir( $tmpdir )"
Temporay directory to store cached \s-1RSS XML\s0 between instances for persistance.
.ie n .SS "$feed\->max_headlines"
.el .SS "\f(CW$feed\fP\->max_headlines"
.IX Subsection "$feed->max_headlines"
.ie n .SS "$feed\->max_headlines( $integer )"
.el .SS "\f(CW$feed\fP\->max_headlines( \f(CW$integer\fP )"
.IX Subsection "$feed->max_headlines( $integer )"
The maximum number of headlines you'd like to keep track of.  
(0 means infinate)
.SH "DEPRECATED METHODS"
.IX Header "DEPRECATED METHODS"
.ie n .SS "$feed\->failed_to_fetch"
.el .SS "\f(CW$feed\fP\->failed_to_fetch"
.IX Subsection "$feed->failed_to_fetch"
This should was deprecated because, the object shouldn't really know
anything about fetching, it just processes the results.  This method 
currently will always return false
.ie n .SS "$feed\->failed_to_parse"
.el .SS "\f(CW$feed\fP\->failed_to_parse"
.IX Subsection "$feed->failed_to_parse"
This method was deprecated because, \f(CW$feed\fR\->parse now returns a bool value.
This method will always return false
.SH "AUTHOR"
.IX Header "AUTHOR"
Jeff Bisbee, \f(CW\*(C`<jbisbee at cpan.org>\*(C'\fR
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-xml\-rss\-feed at rt.cpan.org\*(C'\fR, or through the web interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=XML\-RSS\-Feed>.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.
.SH "SUPPORT"
.IX Header "SUPPORT"
You can find documentation for this module with the perldoc command.
.PP
.Vb 1
\&    perldoc XML::RSS::Feed
.Ve
.PP
You can also look for information at:
.IP "\(bu" 4
AnnoCPAN: Annotated \s-1CPAN\s0 documentation
.Sp
<http://annocpan.org/dist/XML\-RSS\-Feed>
.IP "\(bu" 4
\&\s-1CPAN\s0 Ratings
.Sp
<http://cpanratings.perl.org/d/XML\-RSS\-Feed>
.IP "\(bu" 4
\&\s-1RT: CPAN\s0's request tracker
.Sp
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML\-RSS\-Feed>
.IP "\(bu" 4
Search \s-1CPAN\s0
.Sp
<http://search.cpan.org/dist/XML\-RSS\-Feed>
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Special thanks to Rocco Caputo, Martijn van Beers, Sean Burke, Prakash Kailasa
and Randal Schwartz for their help, guidance, patience, and bug reports. Guys 
thanks for actually taking time to use the code and give good, honest feedback.
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2006 Jeff Bisbee, all rights reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
XML::RSS::Headline, XML::RSS::Headline::PerlJobs, XML::RSS::Headline::Fark, XML::RSS::Headline::UsePerlJournals, POE::Component::RSSAggregator