| XML::LibXSLT - Interface to the GNOME libxslt library |
XML::LibXSLT - Interface to the GNOME libxslt library
use XML::LibXSLT; use XML::LibXML;
my $xslt = XML::LibXSLT->new();
my $source = XML::LibXML->load_xml(location => 'foo.xml'); my $style_doc = XML::LibXML->load_xml(location=>'bar.xsl', no_cdata=>1);
my $stylesheet = $xslt->parse_stylesheet($style_doc);
my $results = $stylesheet->transform($source);
print $stylesheet->output_as_bytes($results);
This module is an interface to the GNOME project's libxslt. This is an extremely good XSLT engine, highly compliant and also very fast. I have tests showing this to be more than twice as fast as Sablotron.
XML::LibXSLT has some global options. Note that these are probably not thread or even fork safe - so only set them once per process. Each one of these options can be called either as class methods, or as instance methods. However either way you call them, it still sets global options.
Each of the option methods returns its previous value, and can be called without a parameter to retrieve the current value.
XML::LibXSLT->max_depth(1000);
This option sets the maximum recursion depth for a stylesheet. See the very end of section 5.4 of the XSLT specification for more details on recursion and detecting it. If your stylesheet or XML file requires seriously deep recursion, this is the way to set it. Default value is 250.
XML::LibXSLT->max_vars(100_000);
This option sets the maximum number of variables for a stylesheet. If your stylesheet or XML file requires many variables, this is the way to increase their limit. Default value is system-specific and may vary.
XML::LibXSLT->debug_callback($subref);
Sets a callback to be used for debug messages. If you don't set this, debug messages will be ignored.
XML::LibXSLT->register_function($uri, $name, $subref); $stylesheet->register_function($uri, $name, $subref);
Registers an XSLT extension function mapped to the given URI. For example:
XML::LibXSLT->register_function("urn:foo", "bar",
sub { scalar localtime });
Will register a bar function in the urn:foo namespace (which you
have to define in your XSLT using xmlns:...) that will return the
current date and time as a string:
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
xmlns:foo="urn:foo">
<xsl:template match="/">
The time is: <xsl:value-of select="foo:bar()"/>
</xsl:template>
</xsl:stylesheet>
Parameters can be in whatever format you like. If you pass in a nodelist
it will be a XML::LibXML::NodeList object in your perl code, but ordinary
values (strings, numbers and booleans) will be ordinary perl scalars. If
you wish them to be XML::LibXML::Literal, XML::LibXML::Number and
XML::LibXML::Number values respectively then set the variable
$XML::LibXSLT::USE_LIBXML_DATA_TYPES to a true value. Return values can
be a nodelist or a plain value - the code will just do the right thing.
But only a single return value is supported (a list is not converted to
a nodelist).
$stylesheet->register_element($uri, $name, $subref)
Registers an XSLT extension element $name mapped to the given URI. For example:
$stylesheet->register_element("urn:foo", "hello", sub {
my $name = $_[2]->getAttribute( "name" );
return XML::LibXML::Text->new( "Hello, $name!" );
});
Will register a hello element in the urn:foo namespace that returns a ``Hello, X!'' text node. You must define this namespace in your XSLT and include its prefix in the extension-element-prefixes list:
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
xmlns:foo="urn:foo"
extension-element-prefixes="foo">
<xsl:template match="/">
<foo:hello name="bob"/>
</xsl:template>
</xsl:stylesheet>
The callback is passed the input document node as $_[1] and the stylesheet node as $_[2]. $_[0] is reserved for future use.
The following methods are available on the new XML::LibXSLT object:
parse_stylesheet($stylesheet_doc)$stylesheet_doc here is an XML::LibXML::Document object (see the XML::LibXML manpage)
representing an XSLT file. This method will return a
XML::LibXSLT::Stylesheet object, or undef on failure. If the XSLT is
invalid, an exception will be thrown, so wrap the call to
parse_stylesheet in an eval{} block to trap this.
IMPORTANT: $stylesheet_doc should not contain CDATA sections,
otherwise libxslt may misbehave. The best way to assure this is to
load the stylesheet with no_cdata flag, e.g.
my $stylesheet_doc = XML::LibXML->load_xml(location=>"some.xsl", no_cdata=>1);
parse_stylesheet_file($filename)
To define XML::LibXSLT or XML::LibXSLT::Stylesheet specific input callbacks, reuse the XML::LibXML input callback API as described in the XML::LibXML::InputCallback(3) manpage.
input_callbacks($icb)$icb only for this XML::LibXSLT object.
$icb should be a XML::LibXML::InputCallback object. This will
call init_callbacks and cleanup_callbacks automatically during
parsing or transformation.
To create security preferences for the transformation see
the XML::LibXSLT::Security manpage. Once the security preferences have been defined you
can apply them to an XML::LibXSLT or XML::LibXSLT::Stylesheet instance using
the security_callbacks() method.
The main API is on the stylesheet, though it is fairly minimal.
One of the main advantages of XML::LibXSLT is that you have a generic
stylesheet object which you call the transform() method passing in a
document to transform. This allows you to have multiple transformations
happen with one stylesheet without requiring a reparse.
my $results = $stylesheet->transform($doc, foo => "'bar'"); print $stylesheet->output_as_bytes($results);
Transforms the passed in XML::LibXML::Document object, and returns a new XML::LibXML::Document. Extra hash entries are used as parameters. Be sure to keep in mind the caveat with regard to quotes explained in the section on Parameters below.
my $results = $stylesheet->transform_file($filename, bar => "'baz'");
Note the string parameter caveat, detailed in the section on Parameters below.
output_as_bytes(result)output_as_chars(result)output_as_bytes(result), but always return the output as (UTF-8
encoded) string of characters.
output_string(result)output_as_bytes(result) and output_as_bytes(result): The scalar
returned by this function appears to Perl as characters (UTF8 flag is
on) if the output encoding specified in the XSLT stylesheet was UTF-8
and as bytes if no output encoding was specified or if the output
encoding was other than UTF-8. Since the behavior of this function
depends on the particular stylesheet, it is deprecated in favor of
output_as_bytes(result) and output_as_chars(result).
$fh.
$filename.
output_encoding()output_method()method attribute from xsl:output
(usually xml, html or text). If this attribute is
unspecified, the default value is initially xml. If the
transform method is used to produce an HTML document, as per the
XSLT spec, the default value will
change to html. To override this behavior completely, supply an
xsl:output element in the stylesheet source document.
media_type()media-type attribute from
xsl:output. If this attribute is unspecified, the default media
type is initially text/xml. This default changes to text/html
under the same conditions as output_method.
input_callbacks($icb)$icb only for this stylesheet. $icb
should be a XML::LibXML::InputCallback object. This will call
init_callbacks and cleanup_callbacks automatically during
transformation.
LibXSLT expects parameters in XPath format. That is, if you wish to pass a string to the XSLT engine, you actually have to pass it as a quoted string:
$stylesheet->transform($doc, param => "'string'");
Note the quotes within quotes there!
Obviously this isn't much fun, so you can make it easy on yourself:
$stylesheet->transform($doc, XML::LibXSLT::xpath_to_string(
param => "string"
));
The utility function does the right thing with respect to strings in XPath, including when you have quotes already embedded within your string.
Provides an interface to the libxslt security framework by allowing callbacks to be defined that can restrict access to various resources (files or URLs) during a transformation.
The libxslt security framework allows callbacks to be defined for certain actions that a stylesheet may attempt during a transformation. It may be desirable to restrict some of these actions (for example, writing a new file using exsl:document). The actions that may be restricted are:
document() function).
NOTE: By default, create_dir is not allowed. To enable it a callback must be registered.
The interface for this module is similar to XML::LibXML::InputCallback. After
creating a new instance you may register callbacks for each of the security
options listed above. Then you apply the security preferences to the
XML::LibXSLT or XML::LibXSLT::Stylesheet object using security_callbacks().
my $security = XML::LibXSLT::Security->new(); $security->register_callback( read_file => $read_cb ); $security->register_callback( write_file => $write_cb ); $security->register_callback( create_dir => $create_cb ); $security->register_callback( read_net => $read_net_cb ); $security->register_callback( write_net => $write_net_cb );
$xslt->security_callbacks( $security ); -OR- $stylesheet->security_callbacks( $security );
The registered callback functions are called when access to a resource is requested. If the access should be allowed the callback should return 1, if not it should return 0. The callback functions should accept the following arguments:
stylesheet().
my $stylesheet = $tctxt->stylesheet();
The stylesheet object can then be used to share contextual information between different calls to the security callbacks.
If a particular option (except for create_dir) doesn't have a registered
callback, then the stylesheet will have full access for that action.
new()create_dir).
Included in the distribution is a simple benchmark script, which has two drivers - one for LibXSLT and one for Sablotron. The benchmark requires the testcases files from the XSLTMark distribution which you can find at http://www.datapower.com/XSLTMark/
Put the testcases directory in the directory created by this distribution, and then run:
perl benchmark.pl -h
to get a list of options.
The benchmark requires XML::XPath at the moment, but I hope to factor that out of the equation fairly soon. It also requires Time::HiRes, which I could be persuaded to factor out, replacing it with Benchmark.pm, but I haven't done so yet.
I would love to get drivers for XML::XSLT and XML::Transformiix, if you would like to contribute them. Also if you get this running on Win32, I'd love to get a driver for MSXSLT via OLE, to see what we can do against those Redmond boys!
For debugging purposes, XML::LibXSLT provides version information
about the libxslt C library (but do not confuse it with the version
number of XML::LibXSLT module itself, i.e. with
$XML::LibXSLT::VERSION). XML::LibXSLT issues a warning if the
runtime version of the library is less then the compile-time version.
This is free software, you may use it and distribute it under the same terms as Perl itself.
Copyright 2001-2009, AxKit.com Ltd.
Matt Sergeant, matt@sergeant.org
Security callbacks implementation contributed by Shane Corgatelli.
Petr Pajas , pajas@matfyz.org
Please report bugs via
http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-LibXSLT
XML::LibXML
| XML::LibXSLT - Interface to the GNOME libxslt library |