NAME
XML::RSS::Tools - A toolkit providing a wrapper around an HTTP client, an RSS parser, and a XSLT engine.
SYNOPSIS
use XML::RSS::Tools;
my $rss_feed = XML::RSS::Tools->new;
$rss_feed->rss_uri('http:://foo/bar.rdf');
$rss_feed->xsl_file('/my/rss_transformation.xsl');
$rss_feed->transform;
print $rss_feed->as_string;DESCRIPTION
RSS/RDF feeds are commonly available ways of distributing or syndicating the latest news about a given web site. This module provides a VERY high level way of manipulating them. You can easily use LWP, the XML::RSS and XML::LibXSLT do to this yourself, but this module is a wrapper around these modules, allowing for the simple creation of a RSS client.
When working with XML if the file is invalid for some reason this module will craok bringing your application down. When calling methods that deal with XML manipulation you should enclose them in an eval statemanet should you wish your program to fail gracefully.
Otherwise method calls will return true on success, and false on failure. For example after loading a URI via HTTP, you may wish to check the error status before proceeding with your code:
unless ($rss_feed->rss_uri('http://this.goes.nowhere/')) {
print "Unable to obtain file via HTTP", $rss_feed->as_string(error);
# Do what else
# you have to.
} else {
# carry on...
}CONSTRUCTOR
my $rss_object = XML::RSS::Tools->new;Or with optional parameters.
my $rss_object = XML::RSS::Tools->new(
version => 0.91,
http_client => "lwp",
auto_wash => 1,
debug => 1);The module will die if it's created with invalid parameters.
METHODS
Source RSS feed
$rss_object->rss_file('/my/file.rss');
$rss_object->rss_uri('http://my.server.com/index.rss');
$rss_object->rss_uri('file:/my/file.rss');
$rss_object->rss_string($xml_file);
$rss_object->rss_fh($file_handle);All return true on success, false on failure. If an XML file was provided but was invalid XML the parser will fail fataly at this time. The input RSS feed will automatically be normalised to the prefered RSS version at this time. Chose your version before you load it!
Source XSL Template
$rss_object->xsl_file('/my/file.xsl');
$rss_object->xsl_uri('http://my.server.com/index.xsl');
$rss_object->xsl_uri('file:/my/file.xsl');
$rss_object->xsl_string($xml_file);
$rss_object->xsl_fh($file_handle);All return true on success, false on failure. The XSLT file is NOT parsed or verified at this time.
Other Methods
transform
$rss_object->transform();Performs the XSL transformation on the source RSS file with the loaded XSLT file.
as_string
$rss_object->as_string;Returns the RSS file after it's been though the XSLT process. Optionally you can pass this method one additional parameter to obtain the source RSS, XSL Tempate and any error message:
$rss_object->as_string(xsl);
$rss_object->as_string(rss);
$rss_object->as_string(error);If there is nothing to stringify you will get nothing.
debug
$rss_object->debug(1);A simple switch that control the debug status of the module. By default debug is off. Returns the current status.
set_auto_wash and get_auto_wash
$rss_object->set_auto_wash(1);
$rss_object->get_auto_wash;
If auto_wash is true, then all RSS files are cleaned before RSS normaisation to replace known entities by their numeric value, and fix known invalid XML constructs. By default auto_wash to true.
set_version and get_version
$rss_object->set_version(0.92);
$rss_object->get_version;All incoming RSS feeds are automatically converted to one default RSS version. If RSS version is set to 0 then normalisation is not performed. The default RSS version is 0.91.
set_http_client and get_http_client
$rss_object->set_http_client('lwp');
$rss_object->get_http_client;These methods set the HTTP client to use, and get back the one selected. Acceptable values are: auto; ghttp; Lite and lwp. If set to auto the module will first try GHTTP then Lite then LWP to retrieve files on the internet. Though GHTTP is much faster than LWP it is far less common and doesn't work reliably on Windows Apache 1.3.x/mod_Perl, so this method allows you to specify which client to use if you need to.
XML Catalog
To speed up large scale XML processing it is advised to create an XML Catalog (sic) so that the XML parser does not have to make slow and expensive requests to files on the internet. The catalogue contains details of the DTD and enternal entities so that they can be retrieved from the local file system quicker and at lower load that from the internet. If XML processing is being carried out on a system not connected to the internet, the libxml2 parser will still attempt to connect to the internet which will add a delay of about 60 seconds per XML file. If an catalogue is created then the process will be much quicker as the libxml2 parser will use the local information stored in the catalogue.
$rss_object->set_xml_catalog( $xml_catalog_file);This will pass the specified file to the XML parsers to use as a local XML Catalog.
$rss_object->get_xml_catalog;This will return the file name of the XML Catalog in use.
Depending upon how your core libxml2 library is compiled, you should also be able to use pre-configured XML Catalog files stored in your /etc/xml/catalog.
PREREQUISITES
To function you must have URI installed. If you plan to normalise your RSS before transforming you must also have XML::RSS installed. To transform any RSS files to HTML you will also need to use XML::LibXSLT and XML::LibXML.
One of HTTP::GHTTP, HTTP::Lite or LWP will bring this module to full functionality. GHTTP is much faster than LWP, but is it not as widely available as LWP. By default GHTTP will be used if it is available. If you have both it is possible to choose which to use.
Any OS able to run the core requirments.
EXPORT
None by default.
HISTORY
0.10 Initial XML Catalog support. HTTP client selection.
0.09 Started to test with XML::RSS 1.x family. Now accepts FileHandle objects as inputs.
0.08 Removed Diagnostics pragma. Minor changes. Documentatoin additions and corrections.
0.07 POD corrections. More changes to HTML documentation. Now uses URI for URI processing.
0.06 Changes to HTML Documentation. Tests fixed. No change to module code.
0.05 More minor stuff. Change to entities routine - still not ideal. Test suite upgraded and expanded again.
0.04 Removed un-used test files, other minor changes. Defect in Test script corrected, tested module on Linux.
0.03 Minor code changes and defect corrections. Example script included.
0.02 Some code changes, POD expanded, and test suite more developed.
0.01 Initial Build. Shown to the public on PerlMonks May 2002, for feedback.
See Changes file for more detail
Defects and Limitations
If an RSS or XSLT file is passed into LibXML and it contains references to external files, such as a DTD or external entites, LibXML will automatically attempt to obtain the files, before performing the transformation. If the files refered to are on the public INTERNET, and you do not have a connection when this happens you may find that the process waits around for several minutes until LibXML gives up. If you plan to use this module in an asyncronous manner, you should setup an XML Catalog for LibXML using the xmlcatalog command. See: http://www.xmlsoft.org/catalog.html for more details. You can pass your catalog into the module, and a local copy will then be used rather than the one on the internet.
Many commercial RSS feeds are derived from the Content Management System in use at the site. Often the RSS feed is not well formed and is thus invalid. This will prevent the RSS parser and/or XSLT engine from functioning, and you will get no output. The auto_wash option attempts to fix these errors, but it's is neither perfect nor ideal. Some people report good succes with complaining to the site. Mark Pilgrim estimates that about 10% of RSS feeds have defective XML.
XML::RSS upto and including version 0.96 has a number of defects. This module had also been out of active development for some time. As of October 2002 brian d foy has taken over the module, and it is again under active devlopment on http://perl-rss.sourceforge.net/.
Perl pre 5.7.x is not able to handle Unicode properly, strange things happen... Things should get better as 5.8.0 is now available.
Todo
Debug mode doesn't actually do much yet.
Possibly support HTTP::MHTTP module, it seems to be even faster than GHTTP
AUTHOR
Adam Trickett, <atrickett@cpan.org>
This module contains the direct and indirect input of a number of Perlmonks: Ovid, Matts and more...
SEE ALSO
perl, XML::RSS, XML::LibXSLT, XML::LibXML, URI, LWP and HTTP::GHTTP.
COPYRIGHT
XML::RSS::Tools, Copyright iredale Consulting 2002-2003
OSI Certified Open Source Software
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA.
DEDICATION
This module is dedicated to my beloved mother who believed in me, even when I didn't.