1XML::RSS(3)           User Contributed Perl Documentation          XML::RSS(3)
2
3
4

NAME

6       XML::RSS - creates and updates RSS files
7

SYNOPSIS

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
35        $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
44        $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
58        $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
65        # Optionally mixing in elements of a non-standard module/namespace
66
67        $rss->add_module(prefix=>'my', uri=>'http://purl.org/my/rss/module/');
68
69        $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
79         $rss->add_item (title=>$title, link=>$link, slash=>{ topic=>$topic });
80
81        # 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
97        $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
105        $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
114        $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
120        # 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
128        $rss->image(title => "freshmeat.net",
129                    url   => "http://freshmeat.net/images/fm.mini.jpg",
130                    link  => "http://freshmeat.net"
131                    );
132
133        $rss->add_item(title => "GTKeyboard 0.85",
134                       link  => "http://freshmeat.net/news/1999/06/21/930003829.html"
135                       );
136
137        $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
143        # print the RSS as a string
144        print $rss->as_string;
145
146        # or save it to a file
147        $rss->save("fm.rdf");
148
149        # 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
154        while (@{$rss->{'items'}} >= 15)
155        {
156            pop(@{$rss->{'items'});
157        }
158
159        $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
164        # parse a string instead of a file
165        $rss->parse($string);
166
167        # 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
173        # output the RSS 0.9 or 0.91 file as RSS 1.0
174        $rss->{output} = '1.0';
175        print $rss->as_string;
176

DESCRIPTION

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
185       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
190       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
196       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

METHODS

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
213           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
217           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
225           xml:base will set an "xml:base" property as per
226
227               http://www.w3.org/TR/xmlbase/
228
229           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
233       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
238           The items are stored in the array @{$obj->{'items'}} where $obj is
239           a reference to an XML::RSS object.
240
241       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
245       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
255           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
259           $title = channel('title');
260
261       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
269           The method for retrieving the values for the image is the same as
270           it is for channel().
271
272       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
277           See the add_module() method for instructions on automatically
278           adding modules as a string is parsed.
279
280           %options is a list of options that specify how parsing is to be
281           done. The available options are:
282
283           ·   allow_multiple
284
285               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
289                  $rss->parse($xml, { allow_multiple => ['enclosure'] });
290
291           ·   hashrefs_instead_of_strings
292
293               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
299           ·   modules_as_arrays
300
301               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
306       parsefile ($file, \%options)
307           Same as parse() except it parses a file rather than a string.
308
309           See the add_module() method for instructions on automatically
310           adding modules as a string is parsed.
311
312       save ($file)
313           Saves the RSS to a specified file.
314
315       skipDays (day => $day)
316           Populates the skipDays element with the day $day.
317
318       skipHours (hour => $hour)
319           Populates the skipHours element, with the hour $hour.
320
321       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
327       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
334           Access to the textinput values is the the same as channel() and
335           image().
336
337       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
344           The modules are stored in the hash %{$obj->{'modules'}} where $obj
345           is a reference to an XML::RSS object.
346
347           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
353   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
361       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
366         $rss->add_item (title=>$title, link=>$link, dc=>{ subject=>$subject, creator=>$creator, date=>$date });
367
368       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
373         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
377       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
381           $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
391       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
396       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
400         print $rss->{items}->[0]->{dc}->{subject};
401
402         or
403
404         print $rss->{items}->[0]->{'http://purl.org/dc/elements/1.1/'}->{subject};
405
406       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
412       For example, to add elements of a made-up "My" module, first declare
413       the namespace by associating a prefix with a URI:
414
415         $rss->add_module(prefix=>'my', uri=>'http://purl.org/my/rss/module/');
416
417       Then proceed as usual:
418
419         $rss->add_item (title=>$title, link=>$link, my=>{ rating=>$rating });
420
421       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
425         $rss->add_item(title=>$title, link=>$link, my=> [
426           {el => "rating", value => $rating1, }
427           {el => "rating", value => $rating2, },
428         ]
429
430       Non-standard namespaces are not, however, currently accessible via a
431       simple prefix; access them via their namespace URL like so:
432
433         print $rss->{items}->[0]->{'http://purl.org/my/rss/module/'}->{rating};
434
435       XML::RSS will continue to provide built-in support for standard RSS 1.0
436       modules as they appear.
437

Non-API Methods

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
444           $rss->{output} = "0.9";
445           my $text = $rss->as_string();
446
447       This function renders the data in the object as an RSS version 0.9
448       feed, and returns the resultant XML as text.
449
450   $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
455           $rss->{output} = "0.91";
456           my $text = $rss->as_string();
457
458       This function renders the data in the object as an RSS version 0.91
459       feed, and returns the resultant XML as text.
460
461   $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
466           $rss->{output} = "1.0";
467           my $text = $rss->as_string();
468
469       This function renders the data in the object as an RSS version 1.0
470       feed, and returns the resultant XML as text.
471
472   $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
477           $rss->{output} = "2.0";
478           my $text = $rss->as_string();
479
480       This function renders the data in the object as an RSS version 2.0
481       feed, and returns the resultant XML as text.
482
483   $rss->handle_char()
484       Needed for XML::Parser. Don't use this directly.
485
486   $rss->handle_dec()
487       Needed for XML::Parser. Don't use this directly.
488
489   $rss->handle_start()
490       Needed for XML::Parser. Don't use this directly.
491

BUGS

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
498       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
502       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
505       When you create diffs (for tests or patches), please use the "-u"
506       parameter to diff.
507

SOURCE AVAILABILITY

509       The source is available from the perl.org Subversion server:
510
511       http://svn.perl.org/modules/XML-RSS/ <http://svn.perl.org/modules/XML-
512       RSS/>
513

AUTHOR

515       Original code: Jonathan Eisenzopf <eisen@pobox.com>
516
517       Further changes: Rael Dornfest <rael@oreilly.com>, Ask Bjoern Hansen
518       <ask@develooper.com>
519
520       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

LICENSE

528       XML::RSS is free software. You can redistribute it and/or modify it
529       under the same terms as Perl itself.
530

CREDITS

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

SEE ALSO

546       perl(1), XML::Parser(3).
547
548
549
550perl v5.12.0                      2009-08-05                       XML::RSS(3)
Impressum