1XML::RSS(3) User Contributed Perl Documentation XML::RSS(3)
2
6 XML::RSS - creates and updates RSS files
7
9 # create an RSS 1.0 file (http://purl.org/rss/1.0/)
10 use XML::RSS;
11 my $rss = new XML::RSS (version => '1.0');
12 $rss->channel(
13 title => "freshmeat.net",
14 link => "http://freshmeat.net",
15 description => "the one-stop-shop for all your Linux software needs",
16 dc => {
17 date => '2000-08-23T07:00+00:00',
18 subject => "Linux Software",
19 creator => 'scoop@freshmeat.net',
20 publisher => 'scoop@freshmeat.net',
21 rights => 'Copyright 1999, Freshmeat.net',
22 language => 'en-us',
23 },
24 syn => {
25 updatePeriod => "hourly",
26 updateFrequency => "1",
27 updateBase => "1901-01-01T00:00+00:00",
28 },
29 taxo => [
30 'http://dmoz.org/Computers/Internet',
31 'http://dmoz.org/Computers/PC'
32 ]
33 );
34 $rss->image(
36 title => "freshmeat.net",
37 url => "http://freshmeat.net/images/fm.mini.jpg",
38 link => "http://freshmeat.net",
39 dc => {
40 creator => "G. Raphics (graphics at freshmeat.net)",
41 },
42 );
43 $rss->add_item(
45 title => "GTKeyboard 0.85",
46 link => "http://freshmeat.net/news/1999/06/21/930003829.html",
47 description => "GTKeyboard is a graphical keyboard that ...",
48 dc => {
49 subject => "X11/Utilities",
50 creator => "David Allen (s2mdalle at titan.vcu.edu)",
51 },
52 taxo => [
53 'http://dmoz.org/Computers/Internet',
54 'http://dmoz.org/Computers/PC'
55 ]
56 );
57 $rss->textinput(
59 title => "quick finder",
60 description => "Use the text input below to search freshmeat",
61 name => "query",
62 link => "http://core.freshmeat.net/search.php3",
63 );
64 # Optionally mixing in elements of a non-standard module/namespace
66 $rss->add_module(prefix=>'my', uri=>'http://purl.org/my/rss/module/');
68 $rss->add_item(
70 title => "xIrc 2.4pre2",
71 link => "http://freshmeat.net/projects/xirc/",
72 description => "xIrc is an X11-based IRC client which ...",
73 my => {
74 rating => "A+",
75 category => "X11/IRC",
76 },
77 );
78 $rss->add_item (title=>$title, link=>$link, slash=>{ topic=>$topic });
80 # create an RSS 2.0 file
82 use XML::RSS;
83 my $rss = new XML::RSS (version => '2.0');
84 $rss->channel(title => 'freshmeat.net',
85 link => 'http://freshmeat.net',
86 language => 'en',
87 description => 'the one-stop-shop for all your Linux software needs',
88 rating => '(PICS-1.1 "http://www.classify.org/safesurf/" 1 r (SS~~000 1))',
89 copyright => 'Copyright 1999, Freshmeat.net',
90 pubDate => 'Thu, 23 Aug 1999 07:00:00 GMT',
91 lastBuildDate => 'Thu, 23 Aug 1999 16:20:26 GMT',
92 docs => 'http://www.blahblah.org/fm.cdf',
93 managingEditor => 'scoop@freshmeat.net',
94 webMaster => 'scoop@freshmeat.net'
95 );
96 $rss->image(title => 'freshmeat.net',
98 url => 'http://freshmeat.net/images/fm.mini.jpg',
99 link => 'http://freshmeat.net',
100 width => 88,
101 height => 31,
102 description => 'This is the Freshmeat image stupid'
103 );
104 $rss->add_item(title => "GTKeyboard 0.85",
106 # creates a guid field with permaLink=true
107 permaLink => "http://freshmeat.net/news/1999/06/21/930003829.html",
108 # alternately creates a guid field with permaLink=false
109 # guid => "gtkeyboard-0.85"
110 enclosure => { url=>$url, type=>"application/x-bittorrent" },
111 description => 'blah blah'
112 );
113 $rss->textinput(title => "quick finder",
115 description => "Use the text input below to search freshmeat",
116 name => "query",
117 link => "http://core.freshmeat.net/search.php3"
118 );
119 # create an RSS 0.9 file
121 use XML::RSS;
122 my $rss = new XML::RSS (version => '0.9');
123 $rss->channel(title => "freshmeat.net",
124 link => "http://freshmeat.net",
125 description => "the one-stop-shop for all your Linux software needs",
126 );
127 $rss->image(title => "freshmeat.net",
129 url => "http://freshmeat.net/images/fm.mini.jpg",
130 link => "http://freshmeat.net"
131 );
132 $rss->add_item(title => "GTKeyboard 0.85",
134 link => "http://freshmeat.net/news/1999/06/21/930003829.html"
135 );
136 $rss->textinput(title => "quick finder",
138 description => "Use the text input below to search freshmeat",
139 name => "query",
140 link => "http://core.freshmeat.net/search.php3"
141 );
142 # print the RSS as a string
144 print $rss->as_string;
145 # or save it to a file
147 $rss->save("fm.rdf");
148 # insert an item into an RSS file and removes the oldest ones if
150 # there are already 15 items or more
151 my $rss = new XML::RSS;
152 $rss->parsefile("fm.rdf");
153 while (@{$rss->{'items'}} >= 15)
155 {
156 pop(@{$rss->{'items'});
157 }
158 $rss->add_item(title => "MpegTV Player (mtv) 1.0.9.7",
160 link => "http://freshmeat.net/news/1999/06/21/930003958.html",
161 mode => 'insert'
162 );
163 # parse a string instead of a file
165 $rss->parse($string);
166 # print the title and link of each RSS item
168 foreach my $item (@{$rss->{'items'}}) {
169 print "title: $item->{'title'}\n";
170 print "link: $item->{'link'}\n\n";
171 }
172 # output the RSS 0.9 or 0.91 file as RSS 1.0
174 $rss->{output} = '1.0';
175 print $rss->as_string;
176
178 This module provides a basic framework for creating and maintaining RDF
179 Site Summary (RSS) files. This distribution also contains many examples
180 that allow you to generate HTML from an RSS, convert between 0.9, 0.91,
181 and 1.0 version, and other nifty things. This might be helpful if you
182 want to include news feeds on your Web site from sources like Slashdot
183 and Freshmeat or if you want to syndicate your own content.
184 XML::RSS currently supports 0.9, 0.91, and 1.0 versions of RSS. See
186 http://backend.userland.com/rss091 for information on RSS 0.91. See
187 http://www.purplepages.ie/RSS/netscape/rss0.90.html for RSS 0.9. See
188 http://web.resource.org/rss/1.0/ for RSS 1.0.
189 RSS was originally developed by Netscape as the format for Netscape
191 Netcenter channels, however, many Web sites have since adopted it as a
192 simple syndication format. With the advent of RSS 1.0, users are now
193 able to syndication many different kinds of content including news
194 headlines, threaded measages, products catalogs, etc.
195 Note: In order to parse and generate dates (such as "pubDate" and
197 "dc:date") it is recommended to use DateTime::Format::Mail and
198 DateTime::Format::W3CDTF , which is what XML::RSS uses internally and
199 requires.
200
202 new XML::RSS (version=>$version, encoding=>$encoding, output=>$output,
203 stylesheet=>$stylesheet_url, 'xml:base'=>$base)
204 Constructor for XML::RSS. It returns a reference to an XML::RSS
205 object. You may also pass the RSS version and the XML encoding to
206 use. The default version is 1.0. The default encoding is UTF-8. You
207 may also specify the output format regardless of the input version.
208 This comes in handy when you want to convert RSS between versions.
209 The XML::RSS modules will convert between any of the formats. If
210 you set <encode_output> XML::RSS will make sure to encode any
211 entities in generated RSS. This is now on by default.
212 You can also pass an optional URL to an XSL stylesheet that can be
214 used to output an "<?xsl-stylesheet ... ?>" meta-tag in the header
215 that will allow some browsers to render the RSS file as HTML.
216 You can also set "encode_cb" to a reference to a subroutine that
218 will encode the output in a custom way. This subroutine accepts two
219 parameters: a reference to the
220 "XML::RSS::Private::Output::Base"-derived object (which should
221 normally not concern you) and the text to encode. It should return
222 the text to encode. If not set, then the module will encode using
223 its custom encoding routine.
224 xml:base will set an "xml:base" property as per
226 http://www.w3.org/TR/xmlbase/
228 Note that in order to encode properly, you need to handle "CDATA"
230 sections properly. Look at XML::RSS::Private::Output::Base's
231 "_default_encode()" method for how to do it properly.
232 add_item (title=>$title, link=>$link, description=>$desc, mode=>$mode)
234 Adds an item to the XML::RSS object. mode and description are
235 optional. The default mode is append, which adds the item to the
236 end of the list. To insert an item, set the mode to insert.
237 The items are stored in the array @{$obj->{'items'}} where $obj is
239 a reference to an XML::RSS object.
240 as_string;
242 Returns a string containing the RSS for the XML::RSS object. This
243 method will also encode special characters along the way.
244 channel (title=>$title, link=>$link, description=>$desc,
246 language=>$language, rating=>$rating, copyright=>$copyright,
247 pubDate=>$pubDate, lastBuildDate=>$lastBuild, docs=>$docs,
248 managingEditor=>$editor, webMaster=>$webMaster)
249 Channel information is required in RSS. The title cannot be more
250 the 40 characters, the link 500, and the description 500 when
251 outputting RSS 0.9. title, link, and description, are required for
252 RSS 1.0. language is required for RSS 0.91. The other parameters
253 are optional for RSS 0.91 and 1.0.
254 To retreive the values of the channel, pass the name of the value
256 (title, link, or description) as the first and only argument like
257 so:
258 $title = channel('title');
260 image (title=>$title, url=>$url, link=>$link, width=>$width,
262 height=>$height, description=>$desc)
263 Adding an image is not required. url is the URL of the image, link
264 is the URL the image is linked to. title, url, and link parameters
265 are required if you are going to use an image in your RSS file. The
266 remaining image elements are used in RSS 0.91 or optionally
267 imported into RSS 1.0 via the rss091 namespace.
268 The method for retrieving the values for the image is the same as
270 it is for channel().
271 parse ($string, \%options)
273 Parses an RDF Site Summary which is passed into parse() as the
274 first parameter. Returns the instance of the object so one can say
275 "<$rss-"parse($string)->other_method()>>.
276 See the add_module() method for instructions on automatically
278 adding modules as a string is parsed.
279 %options is a list of options that specify how parsing is to be
281 done. The available options are:
282 · allow_multiple
284 Takes an array ref of names which indicates which elements
286 should be allowed to have multiple occurrences. So, for
287 example, to parse feeds with multiple enclosures
288 $rss->parse($xml, { allow_multiple => ['enclosure'] });
290 · hashrefs_instead_of_strings
292 If true, then some items (so far ""description"") will become
294 hash-references instead of strings (with a content key
295 containing their content , if they have XML attributes. Without
296 this key, the attributes will be ignored and there will only be
297 a string. Thus, specifying this option may break compatibility.
298 · modules_as_arrays
300 This option when true, will parse the modules key-value-pairs
302 as an arrayref of "{ el => $key_name, value => $value, }" hash-
303 refs to gracefully handle duplicate items (see below). It will
304 not affect the known modules such as dc ("Dublin Core").
305 parsefile ($file, \%options)
307 Same as parse() except it parses a file rather than a string.
308 See the add_module() method for instructions on automatically
310 adding modules as a string is parsed.
311 save ($file)
313 Saves the RSS to a specified file.
314 skipDays (day => $day)
316 Populates the skipDays element with the day $day.
317 skipHours (hour => $hour)
319 Populates the skipHours element, with the hour $hour.
320 strict ($boolean)
322 If it's set to 1, it will adhere to the lengths as specified by
323 Netscape Netcenter requirements. It's set to 0 by default. Use it
324 if the RSS file you're generating is for Netcenter. strict will
325 only work for RSS 0.9 and 0.91. Do not use it for RSS 1.0.
326 textinput (title=>$title, description=>$desc, name=>$name,
328 link=>$link);
329 This RSS element is also optional. Using it allows users to submit
330 a Query to a program on a Web server via an HTML form. name is the
331 HTML form name and link is the URL to the program. Content is
332 submitted using the GET method.
333 Access to the textinput values is the the same as channel() and
335 image().
336 add_module(prefix=>$prefix, uri=>$uri)
338 Adds a module namespace declaration to the XML::RSS object,
339 allowing you to add modularity outside of the the standard RSS 1.0
340 modules. At present, the standard modules Dublin Core (dc) and
341 Syndication (syn) are predefined for your convenience. The Taxonomy
342 (taxo) module is also internally supported.
343 The modules are stored in the hash %{$obj->{'modules'}} where $obj
345 is a reference to an XML::RSS object.
346 If you want to automatically add modules that the parser finds in
348 namespaces, set the $XML::RSS::AUTO_ADD variable to a true value.
349 By default the value is false. (N.B. AUTO_ADD only updates the
350 %{$obj->{'modules'}} hash. It does not provide the other benefits
351 of using add_module.)
352 RSS 1.0 MODULES
354 XML-Namespace-based modularization affords RSS 1.0 compartmentalized
355 extensibility. The only modules that ship "in the box" with RSS 1.0
356 are Dublin Core (http://purl.org/rss/1.0/modules/dc/), Syndication
357 (http://purl.org/rss/1.0/modules/syndication/), and Taxonomy
358 (http://purl.org/rss/1.0/modules/taxonomy/). Consult the appropriate
359 module's documentation for further information.
360 Adding items from these modules in XML::RSS is as simple as adding
362 other attributes such as title, link, and description. The only
363 difference is the compartmentalization of their key/value paris in a
364 second-level hash.
365 $rss->add_item (title=>$title, link=>$link, dc=>{ subject=>$subject, creator=>$creator, date=>$date });
367 For elements of the Dublin Core module, use the key 'dc'. For elements
369 of the Syndication module, 'syn'. For elements of the Taxonomy module,
370 'taxo'. These are the prefixes used in the RSS XML document itself.
371 They are associated with appropriate URI-based namespaces:
372 syn: http://purl.org/rss/1.0/modules/syndication/
374 dc: http://purl.org/dc/elements/1.1/
375 taxo: http://purl.org/rss/1.0/modules/taxonomy/
376 The Dublin Core ('dc') hash keys may be point to an array reference,
378 which in turn will specify multiple such keys, and render them one
379 after the other. For example:
380 $rss->add_item (
382 title => $title,
383 link => $link,
384 dc => {
385 subject=> ["Jungle", "Desert", "Swamp"],
386 creator=>$creator,
387 date=>$date
388 },
389 );
390 Dublin Core elements may occur in channel, image, item(s), and
392 textinput -- albeit uncomming to find them under image and textinput.
393 Syndication elements are limited to the channel element. Taxonomy
394 elements can occur in the channel or item elements.
395 Access to module elements after parsing an RSS 1.0 document using
397 XML::RSS is via either the prefix or namespace URI for your
398 convenience.
399 print $rss->{items}->[0]->{dc}->{subject};
401 or
403 print $rss->{items}->[0]->{'http://purl.org/dc/elements/1.1/'}->{subject};
405 XML::RSS also has support for "non-standard" RSS 1.0 modularization at
407 the channel, image, item, and textinput levels. Parsing an RSS
408 document grabs any elements of other namespaces which might appear.
409 XML::RSS also allows the inclusion of arbitrary namespaces and
410 associated elements when building RSS documents.
411 For example, to add elements of a made-up "My" module, first declare
413 the namespace by associating a prefix with a URI:
414 $rss->add_module(prefix=>'my', uri=>'http://purl.org/my/rss/module/');
416 Then proceed as usual:
418 $rss->add_item (title=>$title, link=>$link, my=>{ rating=>$rating });
420 You can also set the value of the module's prefix to an array reference
422 of "{ el => , val => }" hash-references, in which case duplicate
423 elements are possible:
424 $rss->add_item(title=>$title, link=>$link, my=> [
426 {el => "rating", value => $rating1, }
427 {el => "rating", value => $rating2, },
428 ]
429 Non-standard namespaces are not, however, currently accessible via a
431 simple prefix; access them via their namespace URL like so:
432 print $rss->{items}->[0]->{'http://purl.org/my/rss/module/'}->{rating};
434 XML::RSS will continue to provide built-in support for standard RSS 1.0
436 modules as they appear.
437
439 $rss->as_rss_0_9()
440 WARNING: this function is not an API function and should not be called
441 directly. It is kept as is for backwards compatibility with legacy
442 code. Use the following code instead:
443 $rss->{output} = "0.9";
445 my $text = $rss->as_string();
446 This function renders the data in the object as an RSS version 0.9
448 feed, and returns the resultant XML as text.
449 $rss->as_rss_0_9_1()
451 WARNING: this function is not an API function and should not be called
452 directly. It is kept as is for backwards compatibility with legacy
453 code. Use the following code instead:
454 $rss->{output} = "0.91";
456 my $text = $rss->as_string();
457 This function renders the data in the object as an RSS version 0.91
459 feed, and returns the resultant XML as text.
460 $rss->as_rss_1_0()
462 WARNING: this function is not an API function and should not be called
463 directly. It is kept as is for backwards compatibility with legacy
464 code. Use the following code instead:
465 $rss->{output} = "1.0";
467 my $text = $rss->as_string();
468 This function renders the data in the object as an RSS version 1.0
470 feed, and returns the resultant XML as text.
471 $rss->as_rss_2_0()
473 WARNING: this function is not an API function and should not be called
474 directly. It is kept as is for backwards compatibility with legacy
475 code. Use the following code instead:
476 $rss->{output} = "2.0";
478 my $text = $rss->as_string();
479 This function renders the data in the object as an RSS version 2.0
481 feed, and returns the resultant XML as text.
482 $rss->handle_char()
484 Needed for XML::Parser. Don't use this directly.
485 $rss->handle_dec()
487 Needed for XML::Parser. Don't use this directly.
488 $rss->handle_start()
490 Needed for XML::Parser. Don't use this directly.
491
493 Please use rt.cpan.org for tracking bugs. The list of current open
494 bugs is at
495 http://rt.cpan.org/Dist/Display.html?Queue=XML-RSS
496 <http://rt.cpan.org/Dist/Display.html?Queue=XML-RSS>.
497 To report a new bug, go to
499 http://rt.cpan.org/Ticket/Create.html?Queue=XML-RSS
500 <http://rt.cpan.org/Ticket/Create.html?Queue=XML-RSS>
501 Please include a failing test in your bug report. I'd much rather have
503 a well written test with the bug report than a patch.
504 When you create diffs (for tests or patches), please use the "-u"
506 parameter to diff.
507
509 The source is available from the perl.org Subversion server:
510 http://svn.perl.org/modules/XML-RSS/ <http://svn.perl.org/modules/XML-
512 RSS/>
513
515 Original code: Jonathan Eisenzopf <eisen@pobox.com>
516 Further changes: Rael Dornfest <rael@oreilly.com>, Ask Bjoern Hansen
518 <ask@develooper.com>
519 Currently: Shlomi Fish <shlomif@cpan.org>
521
523 Copyright (c) 2001 Jonathan Eisenzopf <eisen@pobox.com> and Rael
524 Dornfest <rael@oreilly.com>, Copyright (C) 2006-2007 Ask Bjoern Hansen
525 <ask@develooper.com>.
526
528 XML::RSS is free software. You can redistribute it and/or modify it
529 under the same terms as Perl itself.
530
532 Wojciech Zwiefka <wojtekz@cnt.pl>
533 Chris Nandor <pudge@pobox.com>
534 Jim Hebert <jim@cosource.com>
535 Randal Schwartz <merlyn@stonehenge.com>
536 rjp@browser.org
537 Kellan Elliott-McCrea <kellan@protest.net>
538 Rafe Colburn <rafe@rafe.us>
539 Adam Trickett <adam.trickett@btinternet.com>
540 Aaron Straup Cope <asc@vineyard.net>
541 Ian Davis <iand@internetalchemy.org>
542 rayg@varchars.com
543 Shlomi Fish <shlomif@iglu.org.il>
544
546 perl(1), XML::Parser(3).
547perl v5.12.0 2009-08-05 XML::RSS(3)
