LibXSLT(3) User Contributed Perl Documentation LibXSLT(3)NAMEXML::LibXSLT - Interface to the GNOME libxslt library
SYNOPSIS
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);
DESCRIPTION
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.
OPTIONSXML::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.
max_depth
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.
debug_callback
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.
register_function
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).
register_element
$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.
API
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
XML::LibXML) 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)
Exactly the same as the above, but parses the given filename
directly.
Input Callbacks
To define XML::LibXSLT or XML::LibXSLT::Stylesheet specific input
callbacks, reuse the XML::LibXML input callback API as described in
XML::LibXML::InputCallback(3).
Security Callbacks
To create security preferences for the transformation see
XML::LibXSLT::Security. 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.
XML::LibXSLT::Stylesheet
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.
transform(doc, %params)
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.
transform_file(filename, %params)
my $results = $stylesheet->transform_file($filename, bar => "'baz'");
Note the string parameter caveat, detailed in the section on
"Parameters" below.
output_as_bytes(result)
Returns a scalar that is the XSLT rendering of the
XML::LibXML::Document object using the desired output format
(specified in the xsl:output tag in the stylesheet). Note that you
can also call $result->toString, but that will *always* output the
document in XML format which may not be what you asked for in the
xsl:output tag. The scalar is a byte string encoded in the output
encoding specified in the stylesheet.
output_as_chars(result)
Like "output_as_bytes(result)", but always return the output as
(UTF-8 encoded) string of characters.
output_string(result)
DEPRECATED: This method is something between
"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)".
output_fh(result, fh)
Outputs the result to the filehandle given in $fh.
output_file(result, filename)
Outputs the result to the file named in $filename.
output_encoding()
Returns the output encoding of the results. Defaults to "UTF-8".
output_method()
Returns the value of the "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
<http://www.w3.org/TR/xslt#output>, the default value will change
to "html". To override this behavior completely, supply an
"xsl:output" element in the stylesheet source document.
media_type()
Returns the value of the "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.
Parameters
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.
XML::LibXSLT::Security
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:
read_file
Called when the stylesheet attempts to open a local file (ie: when
using the document() function).
write_file
Called when an attempt is made to write a local file (ie: when
using the exsl:document element).
create_dir
Called when a directory needs to be created in order to write a
file.
NOTE: By default, create_dir is not allowed. To enable it a
callback must be registered.
read_net
Called when the stylesheet attempts to read from the network.
write_net
Called when the stylesheet attempts to write to the network.
Using XML::LibXSLT::Security
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:
$tctxt
This is the transform context (XML::LibXSLT::TransformContext). You
can use this to get the current XML::LibXSLT::Stylesheet object by
calling "stylesheet()".
my $stylesheet = $tctxt->stylesheet();
The stylesheet object can then be used to share contextual
information between different calls to the security callbacks.
$value
This is the name of the resource (file or URI) that has been
requested.
If a particular option (except for "create_dir") doesn't have a
registered callback, then the stylesheet will have full access for that
action.
Interface
new()
Creates a new XML::LibXSLT::Security object.
register_callback( $option, $callback )
Registers a callback function for the given security option (listed
above).
unregister_callback( $option )
Removes the callback for the given option. This has the effect of
allowing all access for the given option (except for "create_dir").
BENCHMARK
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!
LIBRARY VERSIONS
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.
XML::LibXSLT::LIBXSLT_VERSION()
Returns version number of libxslt library which was used to compile
XML::LibXSLT as an integer. For example, for libxslt-1.1.18, it
will return 10118.
XML::LibXSLT::LIBXSLT_DOTTED_VERSION()
Returns version number of libxslt library which was used to compile
XML::LibXSLT as a string, e.g. "1.1.18".
XML::LibXSLT::LIBXSLT_RUNTIME_VERSION()
Returns version number of libxslt library to which XML::LibXSLT is
linked at runtime (either dynamically or statically). For example,
for example, for libxslt.so.1.1.18, it will return 10118.
XML::LibXSLT::HAVE_EXLT()
Returns 1 if the module was compiled with libexslt, 0 otherwised.
LICENSE
This is free software, you may use it and distribute it under the same
terms as Perl itself.
Copyright 2001-2009, AxKit.com Ltd.
AUTHOR
Matt Sergeant, matt@sergeant.org
Security callbacks implementation contributed by Shane Corgatelli.
MAINTAINER
Petr Pajas , pajas@matfyz.org
BUGS
Please report bugs via
http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-LibXSLT
SEE ALSO
XML::LibXML
perl v5.16.2 2012-09-06 LibXSLT(3)
