1XML::RSS(3) User Contributed Perl Documentation XML::RSS(3)
2
6 XML::RSS - creates and updates RSS files
7
9 version 1.60
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 and 1.0 version, and other nifty things. This might be helpful if you
185 want to include news feeds on your Web site from sources like Slashdot
186 and Freshmeat or if you want to syndicate your own content.
187 XML::RSS currently supports 0.9, 0.91, and 1.0 versions of RSS. See
189 http://backend.userland.com/rss091 for information on RSS 0.91. See
190 http://www.purplepages.ie/RSS/netscape/rss0.90.html for RSS 0.9. See
191 http://web.resource.org/rss/1.0/ for RSS 1.0.
192 RSS was originally developed by Netscape as the format for Netscape
194 Netcenter channels, however, many Web sites have since adopted it as a
195 simple syndication format. With the advent of RSS 1.0, users are now
196 able to syndication many different kinds of content including news
197 headlines, threaded messages, products catalogs, etc.
198 Note: In order to parse and generate dates (such as "pubDate" and
200 "dc:date") it is recommended to use DateTime::Format::Mail and
201 DateTime::Format::W3CDTF , which is what XML::RSS uses internally and
202 requires.
203
205 version 1.60
206
208 XML::RSS->new(version=>$version, encoding=>$encoding, output=>$output,
209 stylesheet=>$stylesheet_url, 'xml:base'=>$base)
210 Constructor for XML::RSS. It returns a reference to an XML::RSS
211 object. You may also pass the RSS version and the XML encoding to
212 use. The default version is 1.0. The default encoding is UTF-8. You
213 may also specify the output format regardless of the input version.
214 This comes in handy when you want to convert RSS between versions.
215 The XML::RSS modules will convert between any of the formats. If
216 you set <encode_output> XML::RSS will make sure to encode any
217 entities in generated RSS. This is now on by default.
218 You can also pass an optional URL to an XSL stylesheet that can be
220 used to output an "<?xsl-stylesheet ... ?>" meta-tag in the header
221 that will allow some browsers to render the RSS file as HTML.
222 You can also set "encode_cb" to a reference to a subroutine that
224 will encode the output in a custom way. This subroutine accepts two
225 parameters: a reference to the
226 "XML::RSS::Private::Output::Base"-derived object (which should
227 normally not concern you) and the text to encode. It should return
228 the text to encode. If not set, then the module will encode using
229 its custom encoding routine.
230 xml:base will set an "xml:base" property as per
232 http://www.w3.org/TR/xmlbase/
234 Note that in order to encode properly, you need to handle "CDATA"
236 sections properly. Look at XML::RSS::Private::Output::Base's
237 "_default_encode()" method for how to do it properly.
238 add_item (title=>$title, link=>$link, description=>$desc, mode=>$mode)
240 Adds an item to the XML::RSS object. mode and description are
241 optional. The default mode is append, which adds the item to the
242 end of the list. To insert an item, set the mode to insert.
243 The items are stored in the array "@{$obj->{'items'}}" where $obj
245 is a reference to an XML::RSS object.
246 One can specify a category by using the 'category' key. 'category'
248 can point to an array reference of categories:
249 $rss->add_item(
251 title => "Foo&Bar",
252 link => "http://www.my.tld/",
253 category => ["OneCat", "TooCat", "3Kitties"],
254 );
255 as_string;
257 Returns a string containing the RSS for the XML::RSS object. This
258 method will also encode special characters along the way.
259 channel (title=>$title, link=>$link, description=>$desc,
261 language=>$language, rating=>$rating, copyright=>$copyright,
262 pubDate=>$pubDate, lastBuildDate=>$lastBuild, docs=>$docs,
263 managingEditor=>$editor, webMaster=>$webMaster)
264 Channel information is required in RSS. The title cannot be more
265 the 40 characters, the link 500, and the description 500 when
266 outputting RSS 0.9. title, link, and description, are required for
267 RSS 1.0. language is required for RSS 0.91. The other parameters
268 are optional for RSS 0.91 and 1.0.
269 To retrieve the values of the channel, pass the name of the value
271 (title, link, or description) as the first and only argument like
272 so:
273 $title = channel('title');
275 image (title=>$title, url=>$url, link=>$link, width=>$width,
277 height=>$height, description=>$desc)
278 Adding an image is not required. url is the URL of the image, link
279 is the URL the image is linked to. title, url, and link parameters
280 are required if you are going to use an image in your RSS file. The
281 remaining image elements are used in RSS 0.91 or optionally
282 imported into RSS 1.0 via the rss091 namespace.
283 The method for retrieving the values for the image is the same as
285 it is for channel().
286 parse ($string, \%options)
288 Parses an RDF Site Summary which is passed into parse() as the
289 first parameter. Returns the instance of the object so one can say
290 "$rss->parse($string)->other_method()".
291 See the add_module() method for instructions on automatically
293 adding modules as a string is parsed.
294 %options is a list of options that specify how parsing is to be
296 done. The available options are:
297 · allow_multiple
299 Takes an array ref of names which indicates which elements
301 should be allowed to have multiple occurrences. So, for
302 example, to parse feeds with multiple enclosures
303 $rss->parse($xml, { allow_multiple => ['enclosure'] });
305 · hashrefs_instead_of_strings
307 If true, then some items (so far ""description"") will become
309 hash-references instead of strings (with a content key
310 containing their content , if they have XML attributes. Without
311 this key, the attributes will be ignored and there will only be
312 a string. Thus, specifying this option may break compatibility.
313 · modules_as_arrays
315 This option when true, will parse the modules key-value-pairs
317 as an arrayref of "{ el => $key_name, value => $value, }" hash-
318 refs to gracefully handle duplicate items (see below). It will
319 not affect the known modules such as dc ("Dublin Core").
320 parsefile ($file, \%options)
322 Same as parse() except it parses a file rather than a string.
323 See the add_module() method for instructions on automatically
325 adding modules as a string is parsed.
326 save ($file)
328 Saves the RSS to a specified file.
329 skipDays (day => $day)
331 Populates the skipDays element with the day $day.
332 skipHours (hour => $hour)
334 Populates the skipHours element, with the hour $hour.
335 strict ($boolean)
337 If it's set to 1, it will adhere to the lengths as specified by
338 Netscape Netcenter requirements. It's set to 0 by default. Use it
339 if the RSS file you're generating is for Netcenter. strict will
340 only work for RSS 0.9 and 0.91. Do not use it for RSS 1.0.
341 textinput (title=>$title, description=>$desc, name=>$name,
343 link=>$link);
344 This RSS element is also optional. Using it allows users to submit
345 a Query to a program on a Web server via an HTML form. name is the
346 HTML form name and link is the URL to the program. Content is
347 submitted using the GET method.
348 Access to the textinput values is the same as channel() and
350 image().
351 add_module(prefix=>$prefix, uri=>$uri)
353 Adds a module namespace declaration to the XML::RSS object,
354 allowing you to add modularity outside of the standard RSS 1.0
355 modules. At present, the standard modules Dublin Core (dc) and
356 Syndication (syn) are predefined for your convenience. The Taxonomy
357 (taxo) module is also internally supported.
358 The modules are stored in the hash %{$obj->{'modules'}} where $obj
360 is a reference to an XML::RSS object.
361 If you want to automatically add modules that the parser finds in
363 namespaces, set the $XML::RSS::AUTO_ADD variable to a true value.
364 By default the value is false. (N.B. AUTO_ADD only updates the
365 %{$obj->{'modules'}} hash. It does not provide the other benefits
366 of using add_module.)
367 RSS 1.0 MODULES
369 XML-Namespace-based modularization affords RSS 1.0 compartmentalized
370 extensibility. The only modules that ship "in the box" with RSS 1.0
371 are Dublin Core (http://purl.org/rss/1.0/modules/dc/), Syndication
372 (http://purl.org/rss/1.0/modules/syndication/), and Taxonomy
373 (http://purl.org/rss/1.0/modules/taxonomy/). Consult the appropriate
374 module's documentation for further information.
375 Adding items from these modules in XML::RSS is as simple as adding
377 other attributes such as title, link, and description. The only
378 difference is the compartmentalization of their key/value paris in a
379 second-level hash.
380 $rss->add_item (title=>$title, link=>$link, dc=>{ subject=>$subject, creator=>$creator, date=>$date });
382 For elements of the Dublin Core module, use the key 'dc'. For elements
384 of the Syndication module, 'syn'. For elements of the Taxonomy module,
385 'taxo'. These are the prefixes used in the RSS XML document itself.
386 They are associated with appropriate URI-based namespaces:
387 syn: http://purl.org/rss/1.0/modules/syndication/
389 dc: http://purl.org/dc/elements/1.1/
390 taxo: http://purl.org/rss/1.0/modules/taxonomy/
391 The Dublin Core ('dc') hash keys may be point to an array reference,
393 which in turn will specify multiple such keys, and render them one
394 after the other. For example:
395 $rss->add_item (
397 title => $title,
398 link => $link,
399 dc => {
400 subject=> ["Jungle", "Desert", "Swamp"],
401 creator=>$creator,
402 date=>$date
403 },
404 );
405 Dublin Core elements may occur in channel, image, item(s), and
407 textinput -- albeit uncomming to find them under image and textinput.
408 Syndication elements are limited to the channel element. Taxonomy
409 elements can occur in the channel or item elements.
410 Access to module elements after parsing an RSS 1.0 document using
412 XML::RSS is via either the prefix or namespace URI for your
413 convenience.
414 print $rss->{items}->[0]->{dc}->{subject};
416 or
418 print $rss->{items}->[0]->{'http://purl.org/dc/elements/1.1/'}->{subject};
420 XML::RSS also has support for "non-standard" RSS 1.0 modularization at
422 the channel, image, item, and textinput levels. Parsing an RSS
423 document grabs any elements of other namespaces which might appear.
424 XML::RSS also allows the inclusion of arbitrary namespaces and
425 associated elements when building RSS documents.
426 For example, to add elements of a made-up "My" module, first declare
428 the namespace by associating a prefix with a URI:
429 $rss->add_module(prefix=>'my', uri=>'http://purl.org/my/rss/module/');
431 Then proceed as usual:
433 $rss->add_item (title=>$title, link=>$link, my=>{ rating=>$rating });
435 You can also set the value of the module's prefix to an array reference
437 of "{ el => , val => }" hash-references, in which case duplicate
438 elements are possible:
439 $rss->add_item(title=>$title, link=>$link, my=> [
441 {el => "rating", value => $rating1, }
442 {el => "rating", value => $rating2, },
443 ]
444 Non-standard namespaces are not, however, currently accessible via a
446 simple prefix; access them via their namespace URL like so:
447 print $rss->{items}->[0]->{'http://purl.org/my/rss/module/'}->{rating};
449 XML::RSS will continue to provide built-in support for standard RSS 1.0
451 modules as they appear.
452
454 $rss->as_rss_0_9()
455 WARNING: this function is not an API function and should not be called
456 directly. It is kept as is for backwards compatibility with legacy
457 code. Use the following code instead:
458 $rss->{output} = "0.9";
460 my $text = $rss->as_string();
461 This function renders the data in the object as an RSS version 0.9
463 feed, and returns the resultant XML as text.
464 $rss->as_rss_0_9_1()
466 WARNING: this function is not an API function and should not be called
467 directly. It is kept as is for backwards compatibility with legacy
468 code. Use the following code instead:
469 $rss->{output} = "0.91";
471 my $text = $rss->as_string();
472 This function renders the data in the object as an RSS version 0.91
474 feed, and returns the resultant XML as text.
475 $rss->as_rss_1_0()
477 WARNING: this function is not an API function and should not be called
478 directly. It is kept as is for backwards compatibility with legacy
479 code. Use the following code instead:
480 $rss->{output} = "1.0";
482 my $text = $rss->as_string();
483 This function renders the data in the object as an RSS version 1.0
485 feed, and returns the resultant XML as text.
486 $rss->as_rss_2_0()
488 WARNING: this function is not an API function and should not be called
489 directly. It is kept as is for backwards compatibility with legacy
490 code. Use the following code instead:
491 $rss->{output} = "2.0";
493 my $text = $rss->as_string();
494 This function renders the data in the object as an RSS version 2.0
496 feed, and returns the resultant XML as text.
497 $rss->handle_char()
499 Needed for XML::Parser. Don't use this directly.
500 $rss->handle_dec()
502 Needed for XML::Parser. Don't use this directly.
503 $rss->handle_start()
505 Needed for XML::Parser. Don't use this directly.
506
508 Please use rt.cpan.org for tracking bugs. The list of current open
509 bugs is at
510 <http://rt.cpan.org/Dist/Display.html?Queue=XML-RSS>.
511 To report a new bug, go to
513 <http://rt.cpan.org/Ticket/Create.html?Queue=XML-RSS>
514 Please include a failing test in your bug report. I'd much rather have
516 a well written test with the bug report than a patch.
517 When you create diffs (for tests or patches), please use the "-u"
519 parameter to diff.
520
522 The source is available from the GitHub repository:
523 <https://github.com/shlomif/perl-XML-RSS>
525
527 Original code: Jonathan Eisenzopf <eisen@pobox.com>
528 Further changes: Rael Dornfest <rael@oreilly.com>, Ask Bjoern Hansen
530 <ask@develooper.com>
531 Currently: Shlomi Fish <shlomif@cpan.org>
533
535 Copyright (c) 2001 Jonathan Eisenzopf <eisen@pobox.com> and Rael
536 Dornfest <rael@oreilly.com>, Copyright (C) 2006-2007 Ask Bjoern Hansen
537 <ask@develooper.com>.
538
540 XML::RSS is free software. You can redistribute it and/or modify it
541 under the same terms as Perl itself.
542
544 Wojciech Zwiefka <wojtekz@cnt.pl>
545 Chris Nandor <pudge@pobox.com>
546 Jim Hebert <jim@cosource.com>
547 Randal Schwartz <merlyn@stonehenge.com>
548 rjp@browser.org
549 Kellan Elliott-McCrea <kellan@protest.net>
550 Rafe Colburn <rafe@rafe.us>
551 Adam Trickett <atrickett@cpan.org>
552 Aaron Straup Cope <asc@vineyard.net>
553 Ian Davis <iand@internetalchemy.org>
554 rayg@varchars.com
555 Shlomi Fish <shlomif@cpan.org>
556
558 perl(1), XML::Parser(3).
559
561 Shlomi Fish <shlomif@cpan.org>
562
564 This software is copyright (c) 2001 by Various.
565 This is free software; you can redistribute it and/or modify it under
567 the same terms as the Perl 5 programming language system itself.
568
570 Please report any bugs or feature requests on the bugtracker website
571 <https://github.com/shlomif/perl-XML-RSS/issues>
572 When submitting a bug or request, please include a test-file or a patch
574 to an existing test-file that illustrates the bug or desired feature.
575
577 Perldoc
578 You can find documentation for this module with the perldoc command.
579 perldoc XML::RSS
581 Websites
583 The following websites have more information about this module, and may
584 be of help to you. As always, in addition to those websites please use
585 your favorite search engine to discover more resources.
586 · MetaCPAN
588 A modern, open-source CPAN search engine, useful to view POD in
590 HTML format.
591 <https://metacpan.org/release/XML-RSS>
593 · Search CPAN
595 The default CPAN search engine, useful to view POD in HTML format.
597 <http://search.cpan.org/dist/XML-RSS>
599 · RT: CPAN's Bug Tracker
601 The RT ( Request Tracker ) website is the default bug/issue
603 tracking system for CPAN.
604 <https://rt.cpan.org/Public/Dist/Display.html?Name=XML-RSS>
606 · AnnoCPAN
608 The AnnoCPAN is a website that allows community annotations of Perl
610 module documentation.
611 <http://annocpan.org/dist/XML-RSS>
613 · CPAN Ratings
615 The CPAN Ratings is a website that allows community ratings and
617 reviews of Perl modules.
618 <http://cpanratings.perl.org/d/XML-RSS>
620 · CPANTS
622 The CPANTS is a website that analyzes the Kwalitee ( code metrics )
624 of a distribution.
625 <http://cpants.cpanauthors.org/dist/XML-RSS>
627 · CPAN Testers
629 The CPAN Testers is a network of smoke testers who run automated
631 tests on uploaded CPAN distributions.
632 <http://www.cpantesters.org/distro/X/XML-RSS>
634 · CPAN Testers Matrix
636 The CPAN Testers Matrix is a website that provides a visual
638 overview of the test results for a distribution on various
639 Perls/platforms.
640 <http://matrix.cpantesters.org/?dist=XML-RSS>
642 · CPAN Testers Dependencies
644 The CPAN Testers Dependencies is a website that shows a chart of
646 the test results of all dependencies for a distribution.
647 <http://deps.cpantesters.org/?module=XML::RSS>
649 Bugs / Feature Requests
651 Please report any bugs or feature requests by email to "bug-xml-rss at
652 rt.cpan.org", or through the web interface at
653 <https://rt.cpan.org/Public/Bug/Report.html?Queue=XML-RSS>. You will be
654 automatically notified of any progress on the request by the system.
655 Source Code
657 The code is open to the world, and available for you to hack on. Please
658 feel free to browse it and play with it, or whatever. If you want to
659 contribute patches, please send me a diff or prod me to pull from your
660 repository :)
661 <https://github.com/shlomif/perl-XML-RSS>
663 git clone git://github.com/shlomif/perl-XML-RSS.git
665perl v5.28.0 2018-03-04 XML::RSS(3)
