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

NAME

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

VERSION

9       version 1.62
10

SYNOPSIS

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
38        $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
47        $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
61        $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
68        # Optionally mixing in elements of a non-standard module/namespace
69
70        $rss->add_module(prefix=>'my', uri=>'http://purl.org/my/rss/module/');
71
72        $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
82         $rss->add_item (title=>$title, link=>$link, slash=>{ topic=>$topic });
83
84        # 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
100        $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
108        $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
117        $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
123        # 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
131        $rss->image(title => "freshmeat.net",
132                    url   => "http://freshmeat.net/images/fm.mini.jpg",
133                    link  => "http://freshmeat.net"
134                    );
135
136        $rss->add_item(title => "GTKeyboard 0.85",
137                       link  => "http://freshmeat.net/news/1999/06/21/930003829.html"
138                       );
139
140        $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
146        # print the RSS as a string
147        print $rss->as_string;
148
149        # or save it to a file
150        $rss->save("fm.rdf");
151
152        # 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
157        while (@{$rss->{'items'}} >= 15)
158        {
159            shift (@{ $rss->{'items'} });
160        }
161
162        $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
167        # parse a string instead of a file
168        $rss->parse($string);
169
170        # 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
176        # output the RSS 0.9 or 0.91 file as RSS 1.0
177        $rss->{output} = '1.0';
178        print $rss->as_string;
179

DESCRIPTION

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
188       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
194       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
200       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
206           use DateTime ();
207
208           my $dt = DateTime->from_epoch(epoch => 1_500_000_000);
209
210           $rss->channel(
211               pubDate => $dt,
212               .
213               .
214               .
215           );
216

METHODS

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
229           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
233           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
241           xml:base will set an "xml:base" property as per
242
243               http://www.w3.org/TR/xmlbase/
244
245           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
249       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
254           The items are stored in the array "@{$obj->{'items'}}" where $obj
255           is a reference to an XML::RSS object.
256
257           One can specify a category by using the 'category' key. 'category'
258           can point to an array reference of categories:
259
260               $rss->add_item(
261                   title => "Foo&Bar",
262                   link => "http://www.my.tld/",
263                   category => ["OneCat", "TooCat", "3Kitties"],
264               );
265
266       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
270       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
280           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
284           $title = channel('title');
285
286       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
294           The method for retrieving the values for the image is the same as
295           it is for channel().
296
297       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
302           See the add_module() method for instructions on automatically
303           adding modules as a string is parsed.
304
305           %options is a list of options that specify how parsing is to be
306           done. The available options are:
307
308           •   allow_multiple
309
310               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
314                  $rss->parse($xml, { allow_multiple => ['enclosure'] });
315
316           •   hashrefs_instead_of_strings
317
318               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
324           •   modules_as_arrays
325
326               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
331       parsefile ($file, \%options)
332           Same as parse() except it parses a file rather than a string.
333
334           See the add_module() method for instructions on automatically
335           adding modules as a string is parsed.
336
337       save ($file)
338           Saves the RSS to a specified file.
339
340       skipDays (day => $day)
341           Populates the skipDays element with the day $day.
342
343       skipHours (hour => $hour)
344           Populates the skipHours element, with the hour $hour.
345
346       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
352       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
359           Access to the textinput values is the same as channel() and
360           image().
361
362       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
369           The modules are stored in the hash %{$obj->{'modules'}} where $obj
370           is a reference to an XML::RSS object.
371
372           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
378   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
386       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
391         $rss->add_item (title=>$title, link=>$link, dc=>{ subject=>$subject, creator=>$creator, date=>$date });
392
393       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
398         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
402       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
406           $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
416       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
421       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
425         print $rss->{items}->[0]->{dc}->{subject};
426
427         or
428
429         print $rss->{items}->[0]->{'http://purl.org/dc/elements/1.1/'}->{subject};
430
431       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
437       For example, to add elements of a made-up "My" module, first declare
438       the namespace by associating a prefix with a URI:
439
440         $rss->add_module(prefix=>'my', uri=>'http://purl.org/my/rss/module/');
441
442       Then proceed as usual:
443
444         $rss->add_item (title=>$title, link=>$link, my=>{ rating=>$rating });
445
446       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
450         $rss->add_item(title=>$title, link=>$link, my=> [
451           {el => "rating", value => $rating1, }
452           {el => "rating", value => $rating2, },
453         ]
454
455       Non-standard namespaces are not, however, currently accessible via a
456       simple prefix; access them via their namespace URL like so:
457
458         print $rss->{items}->[0]->{'http://purl.org/my/rss/module/'}->{rating};
459
460       XML::RSS will continue to provide built-in support for standard RSS 1.0
461       modules as they appear.
462

Non-API Methods

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
469           $rss->{output} = "0.9";
470           my $text = $rss->as_string();
471
472       This function renders the data in the object as an RSS version 0.9
473       feed, and returns the resultant XML as text.
474
475   $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
480           $rss->{output} = "0.91";
481           my $text = $rss->as_string();
482
483       This function renders the data in the object as an RSS version 0.91
484       feed, and returns the resultant XML as text.
485
486   $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
491           $rss->{output} = "1.0";
492           my $text = $rss->as_string();
493
494       This function renders the data in the object as an RSS version 1.0
495       feed, and returns the resultant XML as text.
496
497   $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
502           $rss->{output} = "2.0";
503           my $text = $rss->as_string();
504
505       This function renders the data in the object as an RSS version 2.0
506       feed, and returns the resultant XML as text.
507
508   $rss->handle_char()
509       Needed for XML::Parser. Don't use this directly.
510
511   $rss->handle_dec()
512       Needed for XML::Parser. Don't use this directly.
513
514   $rss->handle_start()
515       Needed for XML::Parser. Don't use this directly.
516

BUGS

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
522       To report a new bug, go to
523           <http://rt.cpan.org/Ticket/Create.html?Queue=XML-RSS>
524
525       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
528       When you create diffs (for tests or patches), please use the "-u"
529       parameter to diff.
530

SOURCE AVAILABILITY

532       The source is available from the GitHub repository:
533
534       <https://github.com/shlomif/perl-XML-RSS>
535

AUTHOR

537       Original code: Jonathan Eisenzopf <eisen@pobox.com>
538
539       Further changes: Rael Dornfest <rael@oreilly.com>, Ask Bjoern Hansen
540       <ask@develooper.com>
541
542       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

LICENSE

550       XML::RSS is free software. You can redistribute it and/or modify it
551       under the same terms as Perl itself.
552

CREDITS

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

SEE ALSO

568       perl(1), XML::Parser(3).
569

SUPPORT

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
576       •   MetaCPAN
577
578           A modern, open-source CPAN search engine, useful to view POD in
579           HTML format.
580
581           <https://metacpan.org/release/XML-RSS>
582
583       •   RT: CPAN's Bug Tracker
584
585           The RT ( Request Tracker ) website is the default bug/issue
586           tracking system for CPAN.
587
588           <https://rt.cpan.org/Public/Dist/Display.html?Name=XML-RSS>
589
590       •   CPANTS
591
592           The CPANTS is a website that analyzes the Kwalitee ( code metrics )
593           of a distribution.
594
595           <http://cpants.cpanauthors.org/dist/XML-RSS>
596
597       •   CPAN Testers
598
599           The CPAN Testers is a network of smoke testers who run automated
600           tests on uploaded CPAN distributions.
601
602           <http://www.cpantesters.org/distro/X/XML-RSS>
603
604       •   CPAN Testers Matrix
605
606           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
610           <http://matrix.cpantesters.org/?dist=XML-RSS>
611
612       •   CPAN Testers Dependencies
613
614           The CPAN Testers Dependencies is a website that shows a chart of
615           the test results of all dependencies for a distribution.
616
617           <http://deps.cpantesters.org/?module=XML::RSS>
618
619   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
625   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
631       <https://github.com/shlomif/perl-XML-RSS>
632
633         git clone git://github.com/shlomif/perl-XML-RSS.git
634

AUTHOR

636       Shlomi Fish <shlomif@cpan.org>
637

BUGS

639       Please report any bugs or feature requests on the bugtracker website
640       <https://github.com/shlomif/perl-XML-RSS/issues>
641
642       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
648       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.
650
651
652
653perl v5.38.0                      2023-07-21                       XML::RSS(3)
Impressum