README
1NAME
2 XML::RSS::Feed - Persistant XML RSS Encapsulation
3
4VERSION
5 2.4
6
7SYNOPSIS
8 A quick and dirty non-POE example that uses a blocking sleep. The magic
9 is in the late_breaking_news method that returns only headlines it
10 hasn't seen.
11
12 use XML::RSS::Feed;
13 use LWP::Simple qw(get);
14
15 my $feed = XML::RSS::Feed->new(
16 url => "http://www.jbisbee.com/rdf/",
17 name => "jbisbee",
18 delay => 10,
19 debug => 1,
20 tmpdir => "/tmp", # optional caching
21 );
22
23 while (1) {
24 $feed->parse(get($feed->url));
25 print $_->headline . "\n" for $feed->late_breaking_news;
26 sleep($feed->delay);
27 }
28
29 ATTENTION! - If you want a non-blocking way to watch multiple RSS
30 sources with one process use POE::Component::RSSAggregator.
31
32 If you want to fetch a feed, mark all the headlines as seen, then get
33 events for any new headlines, pass 'init_headlines_seen => 1' to the
34 constructor.
35
36CONSTRUCTOR
37 XML::RSS::Feed->new( url => $url, name => $name )
38 Required Params
39
40 * name
41
42 Identifier and hash lookup key for the RSS feed.
43
44 * url
45
46 The URL of the RSS feed
47
48 Optional Params
49
50 * delay
51
52 Number of seconds between updates (defaults to 600)
53
54 * tmpdir
55
56 Directory to keep a cached feed (using Storable) to keep
57 persistance between instances.
58
59 * init_headlines_seen
60
61 Mark all headlines as seen from the intial fetch, and only
62 report new headlines that appear from that point forward.
63
64 * debug
65
66 Turn debuging on.
67
68 * headline_as_id
69
70 Boolean value to use the headline as the id when URL isn't
71 unique within a feed.
72
73 * hlobj
74
75 A class name sublcassed from XML::RSS::Headline
76
77 * max_headlines
78
79 The max number of headlines to keep. (default is unlimited)
80
81METHODS
82 $feed->parse( $xml_string )
83 Pass in a xml string to parse with XML::RSS and then call process to
84 process the results.
85
86 $feed->process( $items, $title, $link )
87 $feed->process( $items, $title )
88 $feed->process( $items )
89 Calls pre_process, process_items, post_process, title, and link methods
90 to process the parsed results of an RSS XML feed.
91
92 * $items
93
94 An array of hash refs which will eventually become
95 XML::RSS::Headline objects. Look at XML::RSS::Headline->new() for
96 acceptable arguments.
97
98 * $title
99
100 The title of the RSS feed.
101
102 * $link
103
104 The RSS channel link (normally a URL back to the homepage) of the
105 RSS feed.
106
107 $feed->pre_process
108 Mark all headlines from previous run as seen.
109
110 $feed->process_items( $items )
111 Turn an array refs of hash refs into XML::RSS::Headline objects and
112 added to the internal list of headlines.
113
114 $feed->post_process
115 Post process cleanup, cache headlines (if tmpdir), and debug messages.
116
117 $feed->create_headline( %args)
118 Create a new XML::RSS::Headline object and add it to the interal list.
119 Check XML::RSS::Headline->new() for acceptable values for %args.
120
121 $feed->init_all_headlines_seen()
122 After fetching a feed for the first time, mark all headlines as seen so
123 we don't generate a flood of events. Basically don't issue an event for
124 any existing headlines, but for any headline from that point on.
125
126 $feed->num_headlines
127 Returns the number of headlines for the feed.
128
129 $feed->seen_headline( $id )
130 Just a boolean test to see if we've seen a headline or not.
131
132 $feed->headlines
133 Returns an array or array reference (based on context) of
134 XML::RSS::Headline objects
135
136 $feed->late_breaking_news
137 Returns an array or the number of elements (based on context) of the
138 latest XML::RSS::Headline objects.
139
140 $feed->cache
141 If tmpdir is defined the rss info is cached.
142
143 $feed->set_last_updated
144 $feed->set_last_updated( Time::HiRes::time )
145 Set the time of when the feed was last processed. If you pass in a value
146 it will be used otherwise calls Time::HiRes::time.
147
148 $feed->last_updated
149 The time (in epoch seconds) of when the feed was last processed.
150
151 $feed->last_updated_hires
152 The time (in epoch seconds and milliseconds) of when the feed was last
153 processed.
154
155SET/GET ACCESSOR METHODS
156 $feed->title
157 $feed->title( $title )
158 The title of the RSS feed.
159
160 $feed->debug
161 $feed->debug( $bool )
162 Turn on debugging messages
163
164 $feed->init
165 $feed->init( $bool )
166 init is used so that we just load the current headlines and don't return
167 all headlines. in other words we initialize them. Takes a boolean
168 argument.
169
170 $feed->name
171 $feed->name( $name )
172 The identifier of an RSS feed.
173
174 $feed->delay
175 $feed->delay( $seconds )
176 Number of seconds between updates.
177
178 $feed->link
179 $feed->link( $rss_channel_url )
180 The url in the RSS feed with a link back to the site where the RSS feed
181 came from.
182
183 $feed->url
184 $feed->url( $url )
185 The url in the RSS feed with a link back to the site where the RSS feed
186 came from.
187
188 $feed->headline_as_id
189 $feed->headline_as_id( $bool )
190 Within some RSS feeds the URL may not always be unique, in these cases
191 you can use the headline as the unique id. The id is used to check
192 whether or not a feed is new or has already been seen.
193
194 $feed->hlobj
195 $feed->hlobj( $class )
196 Ablity to use a subclass of XML::RSS::Headline. (See Perl Jobs example
197 in XML::RSS::Headline::PerlJobs). This should just be the name of the
198 subclass.
199
200 $feed->tmpdir
201 $feed->tmpdir( $tmpdir )
202 Temporay directory to store cached RSS XML between instances for
203 persistance.
204
205 $feed->init_headlines_seen
206 $feed->init_headlines_seen( $bool )
207 Boolean value to mark all headlines as seen from the intial fetch, and
208 only report new headlines that appear from that point forward.
209
210 $feed->max_headlines
211 $feed->max_headlines( $integer )
212 The maximum number of headlines you'd like to keep track of. (0 means
213 infinate)
214
215DEPRECATED METHODS
216 $feed->failed_to_fetch
217 This should was deprecated because, the object shouldn't really know
218 anything about fetching, it just processes the results. This method
219 currently will always return false
220
221 $feed->failed_to_parse
222 This method was deprecated because, $feed->parse now returns a bool
223 value. This method will always return false
224
225AUTHOR
226 Jeff Bisbee, "<jbisbee at cpan.org>"
227
228BUGS
229 Please report any bugs or feature requests to "bug-xml-rss-feed at
230 rt.cpan.org", or through the web interface at
231 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=XML-RSS-Feed>. I will be
232 notified, and then you'll automatically be notified of progress on your
233 bug as I make changes.
234
235SUPPORT
236 You can find documentation for this module with the perldoc command.
237
238 perldoc XML::RSS::Feed
239
240 You can also look for information at:
241
242 * AnnoCPAN: Annotated CPAN documentation
243
244 <http://annocpan.org/dist/XML-RSS-Feed>
245
246 * CPAN Ratings
247
248 <http://cpanratings.perl.org/d/XML-RSS-Feed>
249
250 * RT: CPAN's request tracker
251
252 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-RSS-Feed>
253
254 * Search CPAN
255
256 <http://search.cpan.org/dist/XML-RSS-Feed>
257
258ACKNOWLEDGEMENTS
259 Special thanks to Rocco Caputo, Martijn van Beers, Sean Burke, Prakash
260 Kailasa and Randal Schwartz for their help, guidance, patience, and bug
261 reports. Guys thanks for actually taking time to use the code and give
262 good, honest feedback.
263
264 Thank for to Carl Furstenberg for providing feedback for new constructor
265 param of 'init_headlines_seen' so you won't get flooded with headlines
266 on the first fetch of the feed.
267
268 Thanks to Slaven Rezic for pointing out that t/008_store_retrieve.t
269 pointed to broken rss tests on jbisbee.com (that I don't own anymore)
270
271 Thanks to Aaron Krowne for patch for XML::RSS::Headline to use guid as
272 the unique id instead of url if its available.
273
274COPYRIGHT & LICENSE
275 Copyright 2006 Jeff Bisbee, all rights reserved.
276
277 This program is free software; you can redistribute it and/or modify it
278 under the same terms as Perl itself.
279
280SEE ALSO
281 XML::RSS::Headline, XML::RSS::Headline::PerlJobs,
282 XML::RSS::Headline::Fark, XML::RSS::Headline::UsePerlJournals,
283 POE::Component::RSSAggregator
284
285