1XML::RSS(3) User Contributed Perl Documentation XML::RSS(3)
2
6 XML::RSS - creates and updates RSS files
7
9 version 1.62
10
12 # create an RSS 1.0 file (http://purl.org/rss/1.0/)
13 use XML::RSS;
14 my $rss = XML::RSS->new(version => '1.0');
15 $rss->channel(
16 title => "freshmeat.net",
17 link => "http://freshmeat.net",
18 description => "the one-stop-shop for all your Linux software needs",
19 dc => {
20 date => '2000-08-23T07:00+00:00',
21 subject => "Linux Software",
22 creator => 'scoop@freshmeat.net',
23 publisher => 'scoop@freshmeat.net',
24 rights => 'Copyright 1999, Freshmeat.net',
25 language => 'en-us',
26 },
27 syn => {
28 updatePeriod => "hourly",
29 updateFrequency => "1",
30 updateBase => "1901-01-01T00:00+00:00",
31 },
32 taxo => [
33 'http://dmoz.org/Computers/Internet',
34 'http://dmoz.org/Computers/PC'
35 ]
36 );
37 $rss->image(
39 title => "freshmeat.net",
40 url => "http://freshmeat.net/images/fm.mini.jpg",
41 link => "http://freshmeat.net",
42 dc => {
43 creator => "G. Raphics (graphics at freshmeat.net)",
44 },
45 );
46 $rss->add_item(
48 title => "GTKeyboard 0.85",
49 link => "http://freshmeat.net/news/1999/06/21/930003829.html",
50 description => "GTKeyboard is a graphical keyboard that ...",
51 dc => {
52 subject => "X11/Utilities",
53 creator => "David Allen (s2mdalle at titan.vcu.edu)",
54 },
55 taxo => [
56 'http://dmoz.org/Computers/Internet',
57 'http://dmoz.org/Computers/PC'
58 ]
59 );
60 $rss->textinput(
62 title => "quick finder",
63 description => "Use the text input below to search freshmeat",
64 name => "query",
65 link => "http://core.freshmeat.net/search.php3",
66 );
67 # Optionally mixing in elements of a non-standard module/namespace
69 $rss->add_module(prefix=>'my', uri=>'http://purl.org/my/rss/module/');
71 $rss->add_item(
73 title => "xIrc 2.4pre2",
74 link => "http://freshmeat.net/projects/xirc/",
75 description => "xIrc is an X11-based IRC client which ...",
76 my => {
77 rating => "A+",
78 category => "X11/IRC",
79 },
80 );
81 $rss->add_item (title=>$title, link=>$link, slash=>{ topic=>$topic });
83 # create an RSS 2.0 file
85 use XML::RSS;
86 my $rss = XML::RSS->new (version => '2.0');
87 $rss->channel(title => 'freshmeat.net',
88 link => 'http://freshmeat.net',
89 language => 'en',
90 description => 'the one-stop-shop for all your Linux software needs',
91 rating => '(PICS-1.1 "http://www.classify.org/safesurf/" 1 r (SS~~000 1))',
92 copyright => 'Copyright 1999, Freshmeat.net',
93 pubDate => 'Thu, 23 Aug 1999 07:00:00 GMT',
94 lastBuildDate => 'Thu, 23 Aug 1999 16:20:26 GMT',
95 docs => 'http://www.blahblah.org/fm.cdf',
96 managingEditor => 'scoop@freshmeat.net',
97 webMaster => 'scoop@freshmeat.net'
98 );
99 $rss->image(title => 'freshmeat.net',
101 url => 'http://freshmeat.net/images/fm.mini.jpg',
102 link => 'http://freshmeat.net',
103 width => 88,
104 height => 31,
105 description => 'This is the Freshmeat image stupid'
106 );
107 $rss->add_item(title => "GTKeyboard 0.85",
109 # creates a guid field with permaLink=true
110 permaLink => "http://freshmeat.net/news/1999/06/21/930003829.html",
111 # alternately creates a guid field with permaLink=false
112 # guid => "gtkeyboard-0.85"
113 enclosure => { url=>$url, type=>"application/x-bittorrent" },
114 description => 'blah blah'
115 );
116 $rss->textinput(title => "quick finder",
118 description => "Use the text input below to search freshmeat",
119 name => "query",
120 link => "http://core.freshmeat.net/search.php3"
121 );
122 # create an RSS 0.9 file
124 use XML::RSS;
125 my $rss = XML::RSS->new( version => '0.9' );
126 $rss->channel(title => "freshmeat.net",
127 link => "http://freshmeat.net",
128 description => "the one-stop-shop for all your Linux software needs",
129 );
130 $rss->image(title => "freshmeat.net",
132 url => "http://freshmeat.net/images/fm.mini.jpg",
133 link => "http://freshmeat.net"
134 );
135 $rss->add_item(title => "GTKeyboard 0.85",
137 link => "http://freshmeat.net/news/1999/06/21/930003829.html"
138 );
139 $rss->textinput(title => "quick finder",
141 description => "Use the text input below to search freshmeat",
142 name => "query",
143 link => "http://core.freshmeat.net/search.php3"
144 );
145 # print the RSS as a string
147 print $rss->as_string;
148 # or save it to a file
150 $rss->save("fm.rdf");
151 # insert an item into an RSS file and removes the oldest ones if
153 # there are already 15 items or more
154 my $rss = XML::RSS->new;
155 $rss->parsefile("fm.rdf");
156 while (@{$rss->{'items'}} >= 15)
158 {
159 shift (@{ $rss->{'items'} });
160 }
161 $rss->add_item(title => "MpegTV Player (mtv) 1.0.9.7",
163 link => "http://freshmeat.net/news/1999/06/21/930003958.html",
164 mode => 'insert'
165 );
166 # parse a string instead of a file
168 $rss->parse($string);
169 # print the title and link of each RSS item
171 foreach my $item (@{$rss->{'items'}}) {
172 print "title: $item->{'title'}\n";
173 print "link: $item->{'link'}\n\n";
174 }
175 # output the RSS 0.9 or 0.91 file as RSS 1.0
177 $rss->{output} = '1.0';
178 print $rss->as_string;
179
181 This module provides a basic framework for creating and maintaining RDF
182 Site Summary (RSS) files. This distribution also contains many examples
183 that allow you to generate HTML from an RSS, convert between 0.9, 0.91,
184 1.0, and 2.0 version, and other nifty things. This might be helpful if
185 you want to include news feeds on your Web site from sources like
186 Slashdot and Freshmeat or if you want to syndicate your own content.
187 XML::RSS currently supports versions 0.9
189 <http://www.rssboard.org/rss-0-9-0>, 0.91
190 <http://www.rssboard.org/rss-0-9-1>, 1.0
191 <http://web.resource.org/rss/1.0/>, and 2.0
192 <http://www.rssboard.org/rss-2-0> of RSS.
193 RSS was originally developed by Netscape as the format for Netscape
195 Netcenter channels, however, many Web sites have since adopted it as a
196 simple syndication format. With the advent of RSS 1.0, users are now
197 able to syndication many different kinds of content including news
198 headlines, threaded messages, products catalogs, etc.
199 Note: In order to parse and generate dates (such as "pubDate" and
201 "dc:date") it is recommended to use DateTime::Format::Mail and
202 DateTime::Format::W3CDTF , which is what XML::RSS uses internally and
203 requires. It should also be possible to pass DateTime objects which
204 will be formatted accordingly. E.g:
205 use DateTime ();
207 my $dt = DateTime->from_epoch(epoch => 1_500_000_000);
209 $rss->channel(
211 pubDate => $dt,
212 .
213 .
214 .
215 );
216
218 XML::RSS->new(version=>$version, encoding=>$encoding, output=>$output,
219 stylesheet=>$stylesheet_url, 'xml:base'=>$base)
220 Constructor for XML::RSS. It returns a reference to an XML::RSS
221 object. You may also pass the RSS version and the XML encoding to
222 use. The default version is 1.0. The default encoding is UTF-8. You
223 may also specify the output format regardless of the input version.
224 This comes in handy when you want to convert RSS between versions.
225 The XML::RSS modules will convert between any of the formats. If
226 you set <encode_output> XML::RSS will make sure to encode any
227 entities in generated RSS. This is now on by default.
228 You can also pass an optional URL to an XSL stylesheet that can be
230 used to output an "<?xsl-stylesheet ... ?>" meta-tag in the header
231 that will allow some browsers to render the RSS file as HTML.
232 You can also set "encode_cb" to a reference to a subroutine that
234 will encode the output in a custom way. This subroutine accepts two
235 parameters: a reference to the
236 "XML::RSS::Private::Output::Base"-derived object (which should
237 normally not concern you) and the text to encode. It should return
238 the text to encode. If not set, then the module will encode using
239 its custom encoding routine.
240 xml:base will set an "xml:base" property as per
242 http://www.w3.org/TR/xmlbase/
244 Note that in order to encode properly, you need to handle "CDATA"
246 sections properly. Look at XML::RSS::Private::Output::Base's
247 "_default_encode()" method for how to do it properly.
248 add_item (title=>$title, link=>$link, description=>$desc, mode=>$mode)
250 Adds an item to the XML::RSS object. mode and description are
251 optional. The default mode is append, which adds the item to the
252 end of the list. To insert an item, set the mode to insert.
253 The items are stored in the array "@{$obj->{'items'}}" where $obj
255 is a reference to an XML::RSS object.
256 One can specify a category by using the 'category' key. 'category'
258 can point to an array reference of categories:
259 $rss->add_item(
261 title => "Foo&Bar",
262 link => "http://www.my.tld/",
263 category => ["OneCat", "TooCat", "3Kitties"],
264 );
265 as_string;
267 Returns a string containing the RSS for the XML::RSS object. This
268 method will also encode special characters along the way.
269 channel (title=>$title, link=>$link, description=>$desc,
271 language=>$language, rating=>$rating, copyright=>$copyright,
272 pubDate=>$pubDate, lastBuildDate=>$lastBuild, docs=>$docs,
273 managingEditor=>$editor, webMaster=>$webMaster)
274 Channel information is required in RSS. The title cannot be more
275 the 40 characters, the link 500, and the description 500 when
276 outputting RSS 0.9. title, link, and description, are required for
277 RSS 1.0. language is required for RSS 0.91. The other parameters
278 are optional for RSS 0.91 and 1.0.
279 To retrieve the values of the channel, pass the name of the value
281 (title, link, or description) as the first and only argument like
282 so:
283 $title = channel('title');
285 image (title=>$title, url=>$url, link=>$link, width=>$width,
287 height=>$height, description=>$desc)
288 Adding an image is not required. url is the URL of the image, link
289 is the URL the image is linked to. title, url, and link parameters
290 are required if you are going to use an image in your RSS file. The
291 remaining image elements are used in RSS 0.91 or optionally
292 imported into RSS 1.0 via the rss091 namespace.
293 The method for retrieving the values for the image is the same as
295 it is for channel().
296 parse ($string, \%options)
298 Parses an RDF Site Summary which is passed into parse() as the
299 first parameter. Returns the instance of the object so one can say
300 "$rss->parse($string)->other_method()".
301 See the add_module() method for instructions on automatically
303 adding modules as a string is parsed.
304 %options is a list of options that specify how parsing is to be
306 done. The available options are:
307 • allow_multiple
309 Takes an array ref of names which indicates which elements
311 should be allowed to have multiple occurrences. So, for
312 example, to parse feeds with multiple enclosures
313 $rss->parse($xml, { allow_multiple => ['enclosure'] });
315 • hashrefs_instead_of_strings
317 If true, then some items (so far ""description"") will become
319 hash-references instead of strings (with a content key
320 containing their content , if they have XML attributes. Without
321 this key, the attributes will be ignored and there will only be
322 a string. Thus, specifying this option may break compatibility.
323 • modules_as_arrays
325 This option when true, will parse the modules key-value-pairs
327 as an arrayref of "{ el => $key_name, value => $value, }" hash-
328 refs to gracefully handle duplicate items (see below). It will
329 not affect the known modules such as dc ("Dublin Core").
330 parsefile ($file, \%options)
332 Same as parse() except it parses a file rather than a string.
333 See the add_module() method for instructions on automatically
335 adding modules as a string is parsed.
336 save ($file)
338 Saves the RSS to a specified file.
339 skipDays (day => $day)
341 Populates the skipDays element with the day $day.
342 skipHours (hour => $hour)
344 Populates the skipHours element, with the hour $hour.
345 strict ($boolean)
347 If it's set to 1, it will adhere to the lengths as specified by
348 Netscape Netcenter requirements. It's set to 0 by default. Use it
349 if the RSS file you're generating is for Netcenter. strict will
350 only work for RSS 0.9 and 0.91. Do not use it for RSS 1.0.
351 textinput (title=>$title, description=>$desc, name=>$name,
353 link=>$link);
354 This RSS element is also optional. Using it allows users to submit
355 a Query to a program on a Web server via an HTML form. name is the
356 HTML form name and link is the URL to the program. Content is
357 submitted using the GET method.
358 Access to the textinput values is the same as channel() and
360 image().
361 add_module(prefix=>$prefix, uri=>$uri)
363 Adds a module namespace declaration to the XML::RSS object,
364 allowing you to add modularity outside of the standard RSS 1.0
365 modules. At present, the standard modules Dublin Core (dc) and
366 Syndication (syn) are predefined for your convenience. The Taxonomy
367 (taxo) module is also internally supported.
368 The modules are stored in the hash %{$obj->{'modules'}} where $obj
370 is a reference to an XML::RSS object.
371 If you want to automatically add modules that the parser finds in
373 namespaces, set the $XML::RSS::AUTO_ADD variable to a true value.
374 By default the value is false. (N.B. AUTO_ADD only updates the
375 %{$obj->{'modules'}} hash. It does not provide the other benefits
376 of using add_module.)
377 RSS 1.0 MODULES
379 XML-Namespace-based modularization affords RSS 1.0 compartmentalized
380 extensibility. The only modules that ship "in the box" with RSS 1.0
381 are Dublin Core (http://purl.org/rss/1.0/modules/dc/), Syndication
382 (http://purl.org/rss/1.0/modules/syndication/), and Taxonomy
383 (http://purl.org/rss/1.0/modules/taxonomy/). Consult the appropriate
384 module's documentation for further information.
385 Adding items from these modules in XML::RSS is as simple as adding
387 other attributes such as title, link, and description. The only
388 difference is the compartmentalization of their key/value paris in a
389 second-level hash.
390 $rss->add_item (title=>$title, link=>$link, dc=>{ subject=>$subject, creator=>$creator, date=>$date });
392 For elements of the Dublin Core module, use the key 'dc'. For elements
394 of the Syndication module, 'syn'. For elements of the Taxonomy module,
395 'taxo'. These are the prefixes used in the RSS XML document itself.
396 They are associated with appropriate URI-based namespaces:
397 syn: http://purl.org/rss/1.0/modules/syndication/
399 dc: http://purl.org/dc/elements/1.1/
400 taxo: http://purl.org/rss/1.0/modules/taxonomy/
401 The Dublin Core ('dc') hash keys may be point to an array reference,
403 which in turn will specify multiple such keys, and render them one
404 after the other. For example:
405 $rss->add_item (
407 title => $title,
408 link => $link,
409 dc => {
410 subject=> ["Jungle", "Desert", "Swamp"],
411 creator=>$creator,
412 date=>$date
413 },
414 );
415 Dublin Core elements may occur in channel, image, item(s), and
417 textinput -- albeit uncomming to find them under image and textinput.
418 Syndication elements are limited to the channel element. Taxonomy
419 elements can occur in the channel or item elements.
420 Access to module elements after parsing an RSS 1.0 document using
422 XML::RSS is via either the prefix or namespace URI for your
423 convenience.
424 print $rss->{items}->[0]->{dc}->{subject};
426 or
428 print $rss->{items}->[0]->{'http://purl.org/dc/elements/1.1/'}->{subject};
430 XML::RSS also has support for "non-standard" RSS 1.0 modularization at
432 the channel, image, item, and textinput levels. Parsing an RSS
433 document grabs any elements of other namespaces which might appear.
434 XML::RSS also allows the inclusion of arbitrary namespaces and
435 associated elements when building RSS documents.
436 For example, to add elements of a made-up "My" module, first declare
438 the namespace by associating a prefix with a URI:
439 $rss->add_module(prefix=>'my', uri=>'http://purl.org/my/rss/module/');
441 Then proceed as usual:
443 $rss->add_item (title=>$title, link=>$link, my=>{ rating=>$rating });
445 You can also set the value of the module's prefix to an array reference
447 of "{ el => , val => }" hash-references, in which case duplicate
448 elements are possible:
449 $rss->add_item(title=>$title, link=>$link, my=> [
451 {el => "rating", value => $rating1, }
452 {el => "rating", value => $rating2, },
453 ]
454 Non-standard namespaces are not, however, currently accessible via a
456 simple prefix; access them via their namespace URL like so:
457 print $rss->{items}->[0]->{'http://purl.org/my/rss/module/'}->{rating};
459 XML::RSS will continue to provide built-in support for standard RSS 1.0
461 modules as they appear.
462
464 $rss->as_rss_0_9()
465 WARNING: this function is not an API function and should not be called
466 directly. It is kept as is for backwards compatibility with legacy
467 code. Use the following code instead:
468 $rss->{output} = "0.9";
470 my $text = $rss->as_string();
471 This function renders the data in the object as an RSS version 0.9
473 feed, and returns the resultant XML as text.
474 $rss->as_rss_0_9_1()
476 WARNING: this function is not an API function and should not be called
477 directly. It is kept as is for backwards compatibility with legacy
478 code. Use the following code instead:
479 $rss->{output} = "0.91";
481 my $text = $rss->as_string();
482 This function renders the data in the object as an RSS version 0.91
484 feed, and returns the resultant XML as text.
485 $rss->as_rss_1_0()
487 WARNING: this function is not an API function and should not be called
488 directly. It is kept as is for backwards compatibility with legacy
489 code. Use the following code instead:
490 $rss->{output} = "1.0";
492 my $text = $rss->as_string();
493 This function renders the data in the object as an RSS version 1.0
495 feed, and returns the resultant XML as text.
496 $rss->as_rss_2_0()
498 WARNING: this function is not an API function and should not be called
499 directly. It is kept as is for backwards compatibility with legacy
500 code. Use the following code instead:
501 $rss->{output} = "2.0";
503 my $text = $rss->as_string();
504 This function renders the data in the object as an RSS version 2.0
506 feed, and returns the resultant XML as text.
507 $rss->handle_char()
509 Needed for XML::Parser. Don't use this directly.
510 $rss->handle_dec()
512 Needed for XML::Parser. Don't use this directly.
513 $rss->handle_start()
515 Needed for XML::Parser. Don't use this directly.
516
518 Please use rt.cpan.org for tracking bugs. The list of current open
519 bugs is at
520 <http://rt.cpan.org/Dist/Display.html?Queue=XML-RSS>.
521 To report a new bug, go to
523 <http://rt.cpan.org/Ticket/Create.html?Queue=XML-RSS>
524 Please include a failing test in your bug report. I'd much rather have
526 a well written test with the bug report than a patch.
527 When you create diffs (for tests or patches), please use the "-u"
529 parameter to diff.
530
532 The source is available from the GitHub repository:
533 <https://github.com/shlomif/perl-XML-RSS>
535
537 Original code: Jonathan Eisenzopf <eisen@pobox.com>
538 Further changes: Rael Dornfest <rael@oreilly.com>, Ask Bjoern Hansen
540 <ask@develooper.com>
541 Currently: Shlomi Fish <shlomif@cpan.org>
543
545 Copyright (c) 2001 Jonathan Eisenzopf <eisen@pobox.com> and Rael
546 Dornfest <rael@oreilly.com>, Copyright (C) 2006-2007 Ask Bjoern Hansen
547 <ask@develooper.com>.
548
550 XML::RSS is free software. You can redistribute it and/or modify it
551 under the same terms as Perl itself.
552
554 Wojciech Zwiefka <wojtekz@cnt.pl>
555 Chris Nandor <pudge@pobox.com>
556 Jim Hebert <jim@cosource.com>
557 Randal Schwartz <merlyn@stonehenge.com>
558 rjp@browser.org
559 Kellan Elliott-McCrea <kellan@protest.net>
560 Rafe Colburn <rafe@rafe.us>
561 Adam Trickett <atrickett@cpan.org>
562 Aaron Straup Cope <asc@vineyard.net>
563 Ian Davis <iand@internetalchemy.org>
564 rayg@varchars.com
565 Shlomi Fish <shlomif@cpan.org>
566
568 perl(1), XML::Parser(3).
569
571 Websites
572 The following websites have more information about this module, and may
573 be of help to you. As always, in addition to those websites please use
574 your favorite search engine to discover more resources.
575 • MetaCPAN
577 A modern, open-source CPAN search engine, useful to view POD in
579 HTML format.
580 <https://metacpan.org/release/XML-RSS>
582 • RT: CPAN's Bug Tracker
584 The RT ( Request Tracker ) website is the default bug/issue
586 tracking system for CPAN.
587 <https://rt.cpan.org/Public/Dist/Display.html?Name=XML-RSS>
589 • CPANTS
591 The CPANTS is a website that analyzes the Kwalitee ( code metrics )
593 of a distribution.
594 <http://cpants.cpanauthors.org/dist/XML-RSS>
596 • CPAN Testers
598 The CPAN Testers is a network of smoke testers who run automated
600 tests on uploaded CPAN distributions.
601 <http://www.cpantesters.org/distro/X/XML-RSS>
603 • CPAN Testers Matrix
605 The CPAN Testers Matrix is a website that provides a visual
607 overview of the test results for a distribution on various
608 Perls/platforms.
609 <http://matrix.cpantesters.org/?dist=XML-RSS>
611 • CPAN Testers Dependencies
613 The CPAN Testers Dependencies is a website that shows a chart of
615 the test results of all dependencies for a distribution.
616 <http://deps.cpantesters.org/?module=XML::RSS>
618 Bugs / Feature Requests
620 Please report any bugs or feature requests by email to "bug-xml-rss at
621 rt.cpan.org", or through the web interface at
622 <https://rt.cpan.org/Public/Bug/Report.html?Queue=XML-RSS>. You will be
623 automatically notified of any progress on the request by the system.
624 Source Code
626 The code is open to the world, and available for you to hack on. Please
627 feel free to browse it and play with it, or whatever. If you want to
628 contribute patches, please send me a diff or prod me to pull from your
629 repository :)
630 <https://github.com/shlomif/perl-XML-RSS>
632 git clone git://github.com/shlomif/perl-XML-RSS.git
634
636 Shlomi Fish <shlomif@cpan.org>
637
639 Please report any bugs or feature requests on the bugtracker website
640 <https://github.com/shlomif/perl-XML-RSS/issues>
641 When submitting a bug or request, please include a test-file or a patch
643 to an existing test-file that illustrates the bug or desired feature.
644
646 This software is copyright (c) 2001 by Various.
647 This is free software; you can redistribute it and/or modify it under
649 the same terms as the Perl 5 programming language system itself.
650perl v5.32.1 2021-01-27 XML::RSS(3)
