NAME¶
XML::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.
OPTIONS¶
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.
- 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.
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".
- media_type()
- Returns the output media_type of the results. Defaults to
"text/html".
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