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 item if
150 # there are already 15 items
151 my $rss = new XML::RSS;
152 $rss->parsefile("fm.rdf");
153 pop(@{$rss->{'items'}}) if (@{$rss->{'items'}} == 15);
154 $rss->add_item(title => "MpegTV Player (mtv) 1.0.9.7",
155 link => "http://freshmeat.net/news/1999/06/21/930003958.html",
156 mode => 'insert'
157 );
158 # parse a string instead of a file
160 $rss->parse($string);
161 # print the title and link of each RSS item
163 foreach my $item (@{$rss->{'items'}}) {
164 print "title: $item->{'title'}\n";
165 print "link: $item->{'link'}\n\n";
166 }
167 # output the RSS 0.9 or 0.91 file as RSS 1.0
169 $rss->{output} = '1.0';
170 print $rss->as_string;
171
173 This module provides a basic framework for creating and maintaining RDF
174 Site Summary (RSS) files. This distribution also contains many examples
175 that allow you to generate HTML from an RSS, convert between 0.9, 0.91,
176 and 1.0 version, and other nifty things. This might be helpful if you
177 want to include news feeds on your Web site from sources like Slashot
178 and Freshmeat or if you want to syndicate your own content.
179 XML::RSS currently supports 0.9, 0.91, and 1.0 versions of RSS. See
181 http://my.netscape.com/publish/help/mnn20/quickstart.html for informa‐
182 tion on RSS 0.91. See http://my.netscape.com/publish/help/ for RSS 0.9.
183 See http://purl.org/rss/1.0/ for RSS 1.0.
184 RSS was originally developed by Netscape as the format for Netscape
186 Netcenter channels, however, many Web sites have since adopted it as a
187 simple syndication format. With the advent of RSS 1.0, users are now
188 able to syndication many different kinds of content including news
189 headlines, threaded measages, products catalogs, etc.
190
192 new XML::RSS (version=>$version, encoding=>$encoding, output=>$output,
193 stylesheet=>$stylesheet_url)
194 Constructor for XML::RSS. It returns a reference to an XML::RSS
195 object. You may also pass the RSS version and the XML encoding to
196 use. The default version is 1.0. The default encoding is UTF-8. You
197 may also specify the output format regarless of the input version.
198 This comes in handy when you want to convert RSS between versions.
199 The XML::RSS modules will convert between any of the formats. If
200 you set <encode_output> XML::RSS will make sure to encode any enti‐
201 ties in generated RSS. This is now on by default.
202 You can also pass an optional URL to an XSL stylesheet that can be
204 used to output an "<?xsl-stylesheet ... ?>" meta-tag in the header
205 that will allow some browsers to render the RSS file as HTML.
206 add_item (title=>$title, link=>$link, description=>$desc, mode=>$mode)
208 Adds an item to the XML::RSS object. mode and description are
209 optional. The default mode is append, which adds the item to the
210 end of the list. To insert an item, set the mode to insert.
211 The items are stored in the array @{$obj->{'items'}} where $obj is
213 a reference to an XML::RSS object.
214 as_string;
216 Returns a string containing the RSS for the XML::RSS object. This
217 method will also encode special characters along the way.
218 channel (title=>$title, link=>$link, description=>$desc, lan‐
220 guage=>$language, rating=>$rating, copyright=>$copyright, pub‐
221 Date=>$pubDate, lastBuildDate=>$lastBuild, docs=>$docs, managingEdi‐
222 tor=>$editor, webMaster=>$webMaster)
223 Channel information is required in RSS. The title cannot be more
224 the 40 characters, the link 500, and the description 500 when out‐
225 putting RSS 0.9. title, link, and description, are required for RSS
226 1.0. language is required for RSS 0.91. The other parameters are
227 optional for RSS 0.91 and 1.0.
228 To retreive the values of the channel, pass the name of the value
230 (title, link, or description) as the first and only argument like
231 so:
232 $title = channel('title');
234 image (title=>$title, url=>$url, link=>$link, width=>$width,
236 height=>$height, description=>$desc)
237 Adding an image is not required. url is the URL of the image, link
238 is the URL the image is linked to. title, url, and link parameters
239 are required if you are going to use an image in your RSS file. The
240 remaining image elements are used in RSS 0.91 or optionally
241 imported into RSS 1.0 via the rss091 namespace.
242 The method for retrieving the values for the image is the same as
244 it is for channel().
245 parse ($string)
247 Parses an RDF Site Summary which is passed into parse() as the
248 first parameter.
249 See the add_module() method for instructions on automatically
251 adding modules as a string is parsed.
252 parsefile ($file)
254 Same as parse() except it parses a file rather than a string.
255 See the add_module() method for instructions on automatically
257 adding modules as a string is parsed.
258 save ($file)
260 Saves the RSS to a specified file.
261 strict ($boolean)
263 If it's set to 1, it will adhere to the lengths as specified by
264 Netscape Netcenter requirements. It's set to 0 by default. Use it
265 if the RSS file you're generating is for Netcenter. strict will
266 only work for RSS 0.9 and 0.91. Do not use it for RSS 1.0.
267 textinput (title=>$title, description=>$desc, name=>$name,
269 link=>$link);
270 This RSS element is also optional. Using it allows users to submit
271 a Query to a program on a Web server via an HTML form. name is the
272 HTML form name and link is the URL to the program. Content is sub‐
273 mitted using the GET method.
274 Access to the textinput values is the the same as channel() and
276 image().
277 add_module(prefix=>$prefix, uri=>$uri)
279 Adds a module namespace declaration to the XML::RSS object, allow‐
280 ing you to add modularity outside of the the standard RSS 1.0 mod‐
281 ules. At present, the standard modules Dublin Core (dc) and Syndi‐
282 cation (syn) are predefined for your convenience. The Taxonomy
283 (taxo) module is also internally supported.
284 The modules are stored in the hash %{$obj->{'modules'}} where $obj
286 is a reference to an XML::RSS object.
287 If you want to automatically add modules that the parser finds in
289 namespaces, set the $XML::RSS::AUTO_ADD variable to a true value.
290 By default the value is false. (N.B. AUTO_ADD only updates the
291 %{$obj->{'modules'}} hash. It does not provide the other benefits
292 of using add_module.)
293 append
295 This has never been documented - do you use this? Please email the
296 maintainer a note (Documentation patches welcome too ;-) )
297 RSS 1.0 MODULES
299 XML-Namespace-based modularization affords RSS 1.0 compartmentalized
301 extensibility. The only modules that ship "in the box" with RSS 1.0
302 are Dublin Core (http://purl.org/rss/1.0/modules/dc/), Syndication
303 (http://purl.org/rss/1.0/modules/syndication/), and Taxonomy
304 (http://purl.org/rss/1.0/modules/taxonomy/). Consult the appropriate
305 module's documentation for further information.
306 Adding items from these modules in XML::RSS is as simple as adding
308 other attributes such as title, link, and description. The only dif‐
309 ference is the compartmentalization of their key/value paris in a sec‐
310 ond-level hash.
311 $rss->add_item (title=>$title, link=>$link, dc=>{ subject=>$subject, creator=>$creator });
313 For elements of the Dublin Core module, use the key 'dc'. For elements
315 of the Syndication module, 'syn'. For elements of the Taxonomy module,
316 'taxo'. These are the prefixes used in the RSS XML document itself.
317 They are associated with appropriate URI-based namespaces:
318 syn: http://purl.org/rss/1.0/modules/syndication/
320 dc: http://purl.org/dc/elements/1.1/
321 taxo: http://purl.org/rss/1.0/modules/taxonomy/
322 Dublin Core elements may occur in channel, image, item(s), and textin‐
324 put -- albeit uncomming to find them under image and textinput. Syndi‐
325 cation elements are limited to the channel element. Taxonomy elements
326 can occur in the channel or item elements.
327 Access to module elements after parsing an RSS 1.0 document using
329 XML::RSS is via either the prefix or namespace URI for your conve‐
330 nience.
331 print $rss->{items}->[0]->{dc}->{subject};
333 or
335 print $rss->{items}->[0]->{'http://purl.org/dc/elements/1.1/'}->{subject};
337 XML::RSS also has support for "non-standard" RSS 1.0 modularization at
339 the channel, image, item, and textinput levels. Parsing an RSS docu‐
340 ment grabs any elements of other namespaces which might appear.
341 XML::RSS also allows the inclusion of arbitrary namespaces and associ‐
342 ated elements when building RSS documents.
343 For example, to add elements of a made-up "My" module, first declare
345 the namespace by associating a prefix with a URI:
346 $rss->add_module(prefix=>'my', uri=>'http://purl.org/my/rss/module/');
348 Then proceed as usual:
350 $rss->add_item (title=>$title, link=>$link, my=>{ rating=>$rating });
352 Non-standard namespaces are not, however, currently accessible via a
354 simple prefix; access them via their namespace URL like so:
355 print $rss->{items}->[0]->{'http://purl.org/my/rss/module/'}->{rating};
357 XML::RSS will continue to provide built-in support for standard RSS 1.0
359 modules as they appear.
360
362 Please use rt.cpan.org for tracking bugs. The list of current open
363 bugs is at
364 <http://rt.cpan.org/Dist/Display.html?Queue=XML-RSS>.
365 To report a new bug, go to
367 <http://rt.cpan.org/Ticket/Create.html?Queue=XML-RSS>
368 Please include a failing test in your bug report. I'd much rather have
370 a well written test with the bug report than a patch.
371 When you create diffs (for tests or patches), please use the "-u"
373 parameter to diff.
374
376 The source is available from the perl.org Subversion server:
377 http://svn.perl.org/modules/XML-RSS/
379
381 Original code: Jonathan Eisenzopf <eisen@pobox.com>
382 Further changes: Rael Dornfest <rael@oreilly.com>
383 Currently: Ask Bjoern Hansen <ask@develooper.com>
385
387 Copyright (c) 2001 Jonathan Eisenzopf <eisen@pobox.com> and Rael Dorn‐
388 fest <rael@oreilly.com>, Copyright (C) 2006 Ask Bjoern Hansen
389 <ask@develooper.com>.
390 XML::RSS is free software. You can redistribute it and/or modify it
392 under the same terms as Perl itself.
393
395 Wojciech Zwiefka <wojtekz@cnt.pl>
396 Chris Nandor <pudge@pobox.com>
397 Jim Hebert <jim@cosource.com>
398 Randal Schwartz <merlyn@stonehenge.com>
399 rjp@browser.org
400 Kellan <kellan@protest.net>
401 Rafe Colburn <rafe@rafe.us>
402 Adam Trickett <adam.trickett@btinternet.com>
403 Aaron Straup Cope <asc@vineyard.net>
404 Ian Davis <iand@internetalchemy.org>
405 rayg@varchars.com
406 Kellan Elliott-McCrea <kellan@protest.net>
407 Shlomi Fish <shlomif@iglu.org.il>
408
410 perl(1), XML::Parser(3).
411perl v5.8.8 2006-12-17 XML::RSS(3)
