XML::RSS::LibXML(3pm)

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

NAME

6       XML::RSS::LibXML - XML::RSS with XML::LibXML
7

SYNOPSIS

9         use XML::RSS::LibXML;
10         my $rss = XML::RSS::LibXML->new;
11         $rss->parsefile($file);
12
13         print "channel: $rss->{channel}->{title}\n";
14         foreach my $item (@{ $rss->{items} }) {
15            print "  item: $item->{title} ($item->{link})\n";
16         }
17
18         # Add custom modules
19         $rss->add_module(uri => $uri, prefix => $prefix);
20
21         # See docs for XML::RSS for these
22         $rss->channel(...);
23         $rss->add_item(...);
24         $rss->image(...);
25         $rss->textinput(...);
26         $rss->save(...);
27
28         $rss->as_string($format);
29
30         # XML::RSS::LibXML only methods
31
32         my $version     = $rss->version;
33         my $base        = $rss->base;
34         my $hash        = $rss->namespaces;
35         my $list        = $rss->items;
36         my $encoding    = $rss->encoding;
37         my $modules     = $rss->modules;
38         my $output      = $rss->output;
39         my $stylesheets = $rss->stylesheets;
40         my $num_items   = $rss->num_items;
41

DESCRIPTION

43       XML::RSS::LibXML uses XML::LibXML (libxml2) for parsing RSS instead of
44       XML::RSS' XML::Parser (expat), while trying to keep interface
45       compatibility with XML::RSS.
46
47       XML::RSS is an extremely handy tool, but it is unfortunately not
48       exactly the most lean or efficient RSS parser, especially in a long-
49       running process.  So for a long time I had been using my own version of
50       RSS parser to get the maximum speed and efficiency - this is the re-
51       packaged version of that module, such that it adheres to the XML::RSS
52       interface.
53
54       Use this module when you have severe performance requirements working
55       with RSS files.
56

VERSION 0.3105

58       The original XML::RSS has been evolving in fairly rapid manner lately,
59       and that meant that there were a lot of features to keep up with.  To
60       keep compatibility, I've had to pretty much rewrite the module from
61       ground up.
62
63       Now XML::RSS::LibXML is *almost* compatible with XML::RSS. If there are
64       problems, please send in bug reports (or more preferrably, patches ;)
65

COMPATIBILITY

67       There seems to be a bit of confusion as to how compatible
68       XML::RSS::LibXML is with XML::RSS: XML::RSS::LibXML is NOT 100%
69       compatible with XML::RSS.  For instance XML::RS::LibXML does not do a
70       complete parsing of the XML document because of the way we deal with
71       XPath and libxml's DOM (see CAVEATS below)
72
73       On top of that, I originally wrote XML::RSS::LibXML as sort of a fast
74       replacement for XML::RAI, which looked cool in terms of abstracting the
75       various modules.  And therefore versions prior to 0.02 worked more like
76       XML::RAI rather than XML::RSS. That was a mistake in hind sight, so it
77       has been addressed (Since XML::RSS::LibXML version 0.08, it even
78       supports writing RSS :)
79
80       From now on XML::RSS::LibXML will try to match XML::RSS's functionality
81       as much as possible in terms of parsing RSS feeds. Please send in
82       patches and any tests that may be useful!
83

PARSED STRUCTURE

85       Once parsed the resulting data structure resembles that of XML::RSS.
86       However, as one addition/improvement, XML::RSS::LibXML uses a technique
87       to allow users to access complex data structures that XML::RSS doesn't
88       support as of this writing.
89
90       For example, suppose you have a tag like the following:
91
92         <rss version="2.0" xml:base="http://example.com/">
93         ...
94           <channel>
95             <tag attr1="val1" attr2="val3">foo bar baz</tag>
96           </channel>
97         </rss>
98
99       All of the fields in this construct can be accessed like so:
100
101         $rss->channel->{tag}        # "foo bar baz"
102         $rss->channel->{tag}{attr1} # "val1"
103         $rss->channel->{tag}{attr2} # "val2"
104
105       See XML::RSS::LibXML::MagicElement for details.
106

METHODS

108   new(%args)
109       Creates a new instance of XML::RSS::LibXML. You may specify a version
110       or an XML base in the constructor args to control which output format
111       as_string() will use.
112
113         XML::RSS::LibXML->new(version => '1.0', base => 'http://example.com/');
114
115       The XML base will be included only in RSS 2.0 output. You can also
116       specify the encoding that you expect this RSS object to use when
117       creating an RSS string
118
119         XML::RSS::LiBXML->new(encoding => 'euc-jp');
120
121   parse($string)
122       Parse a string containing RSS.
123
124   parsefile($filename)
125       Parse an RSS file specified by $filename
126
127   channel(%args)
128   add_item(%args)
129   image(%args)
130   textinput(%args)
131       These methods are used to generate RSS. See the documentation for
132       XML::RSS for details. Currently RSS version 0.9, 1.0, and 2.0 are
133       supported.
134
135       Additionally, add_item takes an extra parameter, "mode", which allows
136       you to add items either in front of the list or at the end of the list:
137
138          $rss->add_item(
139             mode => "append",
140             title => "...",
141             link  => "...",
142          );
143
144          $rss->add_item(
145             mode => "insert",
146             title => "...",
147             link  => "...",
148          );
149
150       By default, items are appended to the end of the list
151
152   as_string($format)
153       Return the string representation of the parsed RSS. If $format is true,
154       this flag is passed to the underlying XML::LibXML object's toString()
155       method.
156
157       By default, $format is true.
158
159   add_module(uri => $uri, prefix => $prefix)
160       Adds a new module. You should do this before parsing the RSS.
161       XML::RSS::LibXML understands a few modules by default:
162
163           rdf     => "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
164           dc      => "http://purl.org/dc/elements/1.1/",
165           syn     => "http://purl.org/rss/1.0/modules/syndication/",
166           admin   => "http://webns.net/mvcb/",
167           content => "http://purl.org/rss/1.0/modules/content/",
168           cc      => "http://web.resource.org/cc/",
169           taxo    => "http://purl.org/rss/1.0/modules/taxonomy/",
170
171       So you do not need to add these explicitly.
172
173   save($file)
174       Saves the RSS to a file
175
176   items()
177       Syntactic sugar to allow statement like this:
178
179         foreach my $item ($rss->items) {
180           ...
181         }
182
183       Instead of
184
185         foreach my $item (@{$rss->{items}}) {
186           ...
187         }
188
189       In scalar context, returns the reference to the list of items.
190
191   create_libxml()
192       Creates, configures, and returns an XML::LibXML object. Used by
193       "parse()" to instantiate the parser used to parse the feed.
194

PERFORMANCE

196       Here's a simple benchmark using benchmark.pl in this distribution,
197       using XML::RSS 1.29_02 and XML::RSS::LibXML 0.30
198
199         daisuke@beefcake XML-RSS-LibXML$ perl -Mblib tools/benchmark.pl t/data/rss20.xml
200         XML::RSS -> 1.29_02
201         XML::RSS::LibXML -> 0.30
202                      Rate        rss rss_libxml
203         rss        25.6/s         --       -67%
204         rss_libxml 78.1/s       205%         --
205

CAVEATS

207       - Only first level data under <channel> and <item> tags are examined.
208       So if you have complex data, this module will not pick it up.  For most
209       of the cases, this will suffice, though.
210
211       - Namespace for namespaced attributes aren't properly parsed as part of
212       the structure.  Hopefully your RSS doesn't do something like this:
213
214         <foo bar:baz="whee">
215
216       You won't be able to get at "bar" in this case:
217
218         $xml->{foo}{baz}; # "whee"
219         $xml->{foo}{bar}{baz}; # nope
220
221       - Some of the structures will need to be handled via
222       XML::RSS::LibXML::MagicElement. For example, XML::RSS's SYNOPSIS shows
223       a snippet like this:
224
225         $rss->add_item(title => "GTKeyboard 0.85",
226            # creates a guid field with permaLink=true
227            permaLink  => "http://freshmeat.net/news/1999/06/21/930003829.html",
228            # alternately creates a guid field with permaLink=false
229            # guid     => "gtkeyboard-0.85
230            enclosure   => { url=> 'http://example.com/torrent', type=>"application/x-bittorrent" },
231            description => 'blah blah'
232         );
233
234       However, the enclosure element will need to be an object:
235
236         enclosure => XML::RSS::LibXML::MagicElement->new(
237           attributes => {
238              url => 'http://example.com/torrent',
239              type=>"application/x-bittorrent"
240           },
241         );
242
243       - Some elements such as permaLink elements are not really parsed such
244       that it can be serialized and parsed back and force. I could fix this,
245       but that would break some compatibility with XML::RSS
246

TODO

248       Tests. Currently tests are simply stolen from XML::RSS. It would be
249       nice to have tests that do more extensive testing for correctness
250

COPYRIGHT AND LICENSE

255       Copyright (c) 2005-2007 Daisuke Maki <dmaki@cpan.org>, Tatsuhiko
256       Miyagawa <miyagawa@bulknews.net>. All rights reserved.
257
258       Many tests were shamelessly borrowed from XML::RSS 1.29_02
259
260       Development partially funded by Brazil, Ltd. <http://b.razil.jp>
261
262       This library is free software; you can redistribute it and/or modify it
263       under the same terms as Perl itself.
264
265
266
267perl v5.30.1                      2020-01-30               XML::RSS::LibXML(3)