1XML::LibXSLT(3) User Contributed Perl Documentation XML::LibXSLT(3)
2
6 XML::LibXSLT - Interface to the GNOME libxslt library
7
9 use XML::LibXSLT;
10 use XML::LibXML;
11 my $xslt = XML::LibXSLT->new();
13 my $source = XML::LibXML->load_xml(location => 'foo.xml');
15 my $style_doc = XML::LibXML->load_xml(location=>'bar.xsl', no_cdata=>1);
16 my $stylesheet = $xslt->parse_stylesheet($style_doc);
18 my $results = $stylesheet->transform($source);
20 print $stylesheet->output_as_bytes($results);
22
24 This module is an interface to the GNOME project's libxslt. This is an
25 extremely good XSLT engine, highly compliant and also very fast. I have
26 tests showing this to be more than twice as fast as Sablotron.
27
29 XML::LibXSLT has some global options. Note that these are probably not
30 thread or even fork safe - so only set them once per process. Each one
31 of these options can be called either as class methods, or as instance
32 methods. However either way you call them, it still sets global
33 options.
34 Each of the option methods returns its previous value, and can be
36 called without a parameter to retrieve the current value.
37 max_depth
39 XML::LibXSLT->max_depth(1000);
40 This option sets the maximum recursion depth for a stylesheet. See
42 the very end of section 5.4 of the XSLT specification for more
43 details on recursion and detecting it. If your stylesheet or XML
44 file requires seriously deep recursion, this is the way to set it.
45 Default value is 250.
46 max_vars
48 XML::LibXSLT->max_vars(100_000);
49 This option sets the maximum number of variables for a stylesheet.
51 If your stylesheet or XML file requires many variables, this is the
52 way to increase their limit. Default value is system-specific and
53 may vary.
54 debug_callback
56 XML::LibXSLT->debug_callback($subref);
57 Sets a callback to be used for debug messages. If you don't set
59 this, debug messages will be ignored.
60 register_function
62 XML::LibXSLT->register_function($uri, $name, $subref);
63 $stylesheet->register_function($uri, $name, $subref);
64 Registers an XSLT extension function mapped to the given URI. For
66 example:
67 XML::LibXSLT->register_function("urn:foo", "bar",
69 sub { scalar localtime });
70 Will register a "bar" function in the "urn:foo" namespace (which
72 you have to define in your XSLT using "xmlns:...") that will return
73 the current date and time as a string:
74 <xsl:stylesheet version="1.0"
76 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
77 xmlns:foo="urn:foo">
78 <xsl:template match="/">
79 The time is: <xsl:value-of select="foo:bar()"/>
80 </xsl:template>
81 </xsl:stylesheet>
82 Parameters can be in whatever format you like. If you pass in a
84 nodelist it will be a XML::LibXML::NodeList object in your perl
85 code, but ordinary values (strings, numbers and booleans) will be
86 ordinary perl scalars. If you wish them to be
87 "XML::LibXML::Literal", "XML::LibXML::Number" and
88 "XML::LibXML::Number" values respectively then set the variable
89 $XML::LibXSLT::USE_LIBXML_DATA_TYPES to a true value. Return values
90 can be a nodelist or a plain value - the code will just do the
91 right thing. But only a single return value is supported (a list
92 is not converted to a nodelist).
93 register_element
95 $stylesheet->register_element($uri, $name, $subref)
96 Registers an XSLT extension element $name mapped to the given URI.
98 For example:
99 $stylesheet->register_element("urn:foo", "hello", sub {
101 my $name = $_[2]->getAttribute( "name" );
102 return XML::LibXML::Text->new( "Hello, $name!" );
103 });
104 Will register a "hello" element in the "urn:foo" namespace that
106 returns a "Hello, X!" text node. You must define this namespace in
107 your XSLT and include its prefix in the
108 "extension-element-prefixes" list:
109 <xsl:stylesheet version="1.0"
111 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
112 xmlns:foo="urn:foo"
113 extension-element-prefixes="foo">
114 <xsl:template match="/">
115 <foo:hello name="bob"/>
116 </xsl:template>
117 </xsl:stylesheet>
118 The callback is passed the input document node as $_[1] and the
120 stylesheet node as $_[2]. $_[0] is reserved for future use.
121
123 The following methods are available on the new XML::LibXSLT object:
124 parse_stylesheet($stylesheet_doc)
126 $stylesheet_doc here is an XML::LibXML::Document object (see
127 XML::LibXML) representing an XSLT file. This method will return a
128 XML::LibXSLT::Stylesheet object, or undef on failure. If the XSLT
129 is invalid, an exception will be thrown, so wrap the call to
130 parse_stylesheet in an eval{} block to trap this.
131 IMPORTANT: $stylesheet_doc should not contain CDATA sections,
133 otherwise libxslt may misbehave. The best way to assure this is to
134 load the stylesheet with no_cdata flag, e.g.
135 my $stylesheet_doc = XML::LibXML->load_xml(location=>"some.xsl", no_cdata=>1);
137 parse_stylesheet_file($filename)
139 Exactly the same as the above, but parses the given filename
140 directly.
141
143 To define XML::LibXSLT or XML::LibXSLT::Stylesheet specific input
144 callbacks, reuse the XML::LibXML input callback API as described in
145 XML::LibXML::InputCallback(3).
146 input_callbacks($icb)
148 Enable the callbacks in $icb only for this XML::LibXSLT object.
149 $icb should be a "XML::LibXML::InputCallback" object. This will
150 call "init_callbacks" and "cleanup_callbacks" automatically during
151 parsing or transformation.
152
154 To create security preferences for the transformation see
155 XML::LibXSLT::Security. Once the security preferences have been defined
156 you can apply them to an XML::LibXSLT or XML::LibXSLT::Stylesheet
157 instance using the "security_callbacks()" method.
158
160 The main API is on the stylesheet, though it is fairly minimal.
161 One of the main advantages of XML::LibXSLT is that you have a generic
163 stylesheet object which you call the transform() method passing in a
164 document to transform. This allows you to have multiple transformations
165 happen with one stylesheet without requiring a reparse.
166 transform(doc, %params)
168 my $results = $stylesheet->transform($doc, foo => "'bar'");
169 print $stylesheet->output_as_bytes($results);
170 Transforms the passed in XML::LibXML::Document object, and returns
172 a new XML::LibXML::Document. Extra hash entries are used as
173 parameters. Be sure to keep in mind the caveat with regard to
174 quotes explained in the section on "Parameters" below.
175 transform_file(filename, %params)
177 my $results = $stylesheet->transform_file($filename, bar => "'baz'");
178 Note the string parameter caveat, detailed in the section on
180 "Parameters" below.
181 output_as_bytes(result)
183 Returns a scalar that is the XSLT rendering of the
184 XML::LibXML::Document object using the desired output format
185 (specified in the xsl:output tag in the stylesheet). Note that you
186 can also call $result->toString, but that will *always* output the
187 document in XML format which may not be what you asked for in the
188 xsl:output tag. The scalar is a byte string encoded in the output
189 encoding specified in the stylesheet.
190 output_as_chars(result)
192 Like "output_as_bytes(result)", but always return the output as
193 (UTF-8 encoded) string of characters.
194 output_string(result)
196 DEPRECATED: This method is something between
197 "output_as_bytes(result)" and "output_as_bytes(result)": The scalar
198 returned by this function appears to Perl as characters (UTF8 flag
199 is on) if the output encoding specified in the XSLT stylesheet was
200 UTF-8 and as bytes if no output encoding was specified or if the
201 output encoding was other than UTF-8. Since the behavior of this
202 function depends on the particular stylesheet, it is deprecated in
203 favor of "output_as_bytes(result)" and "output_as_chars(result)".
204 output_fh(result, fh)
206 Outputs the result to the filehandle given in $fh.
207 output_file(result, filename)
209 Outputs the result to the file named in $filename.
210 output_encoding()
212 Returns the output encoding of the results. Defaults to "UTF-8".
213 output_method()
215 Returns the value of the "method" attribute from "xsl:output"
216 (usually "xml", "html" or "text"). If this attribute is
217 unspecified, the default value is initially "xml". If the transform
218 method is used to produce an HTML document, as per the XSLT spec
219 <http://www.w3.org/TR/xslt#output>, the default value will change
220 to "html". To override this behavior completely, supply an
221 "xsl:output" element in the stylesheet source document.
222 media_type()
224 Returns the value of the "media-type" attribute from "xsl:output".
225 If this attribute is unspecified, the default media type is
226 initially "text/xml". This default changes to "text/html" under the
227 same conditions as output_method.
228 input_callbacks($icb)
230 Enable the callbacks in $icb only for this stylesheet. $icb should
231 be a "XML::LibXML::InputCallback" object. This will call
232 "init_callbacks" and "cleanup_callbacks" automatically during
233 transformation.
234 transform_into_chars(doc, %params)
236 Combines "transform()" and "output_as_chars()".
237 (Added in version 2.0000 .)
239
241 LibXSLT expects parameters in XPath format. That is, if you wish to
242 pass a string to the XSLT engine, you actually have to pass it as a
243 quoted string:
244 $stylesheet->transform($doc, param => "'string'");
246 Note the quotes within quotes there!
248 Obviously this isn't much fun, so you can make it easy on yourself:
250 $stylesheet->transform($doc, XML::LibXSLT::xpath_to_string(
252 param => "string"
253 ));
254 The utility function does the right thing with respect to strings in
256 XPath, including when you have quotes already embedded within your
257 string.
258
260 Provides an interface to the libxslt security framework by allowing
261 callbacks to be defined that can restrict access to various resources
262 (files or URLs) during a transformation.
263 The libxslt security framework allows callbacks to be defined for
265 certain actions that a stylesheet may attempt during a transformation.
266 It may be desirable to restrict some of these actions (for example,
267 writing a new file using exsl:document). The actions that may be
268 restricted are:
269 read_file
271 Called when the stylesheet attempts to open a local file (ie: when
272 using the document() function).
273 write_file
275 Called when an attempt is made to write a local file (ie: when
276 using the exsl:document element).
277 create_dir
279 Called when a directory needs to be created in order to write a
280 file.
281 NOTE: By default, create_dir is not allowed. To enable it a
283 callback must be registered.
284 read_net
286 Called when the stylesheet attempts to read from the network.
287 write_net
289 Called when the stylesheet attempts to write to the network.
290 Using XML::LibXSLT::Security
292 The interface for this module is similar to XML::LibXML::InputCallback.
293 After creating a new instance you may register callbacks for each of
294 the security options listed above. Then you apply the security
295 preferences to the XML::LibXSLT or XML::LibXSLT::Stylesheet object
296 using "security_callbacks()".
297 my $security = XML::LibXSLT::Security->new();
299 $security->register_callback( read_file => $read_cb );
300 $security->register_callback( write_file => $write_cb );
301 $security->register_callback( create_dir => $create_cb );
302 $security->register_callback( read_net => $read_net_cb );
303 $security->register_callback( write_net => $write_net_cb );
304 $xslt->security_callbacks( $security );
306 -OR-
307 $stylesheet->security_callbacks( $security );
308 The registered callback functions are called when access to a resource
310 is requested. If the access should be allowed the callback should
311 return 1, if not it should return 0. The callback functions should
312 accept the following arguments:
313 $tctxt
315 This is the transform context (XML::LibXSLT::TransformContext). You
316 can use this to get the current XML::LibXSLT::Stylesheet object by
317 calling "stylesheet()".
318 my $stylesheet = $tctxt->stylesheet();
320 The stylesheet object can then be used to share contextual
322 information between different calls to the security callbacks.
323 $value
325 This is the name of the resource (file or URI) that has been
326 requested.
327 If a particular option (except for "create_dir") doesn't have a
329 registered callback, then the stylesheet will have full access for that
330 action.
331 Interface
333 new()
334 Creates a new XML::LibXSLT::Security object.
335 register_callback( $option, $callback )
337 Registers a callback function for the given security option (listed
338 above).
339 unregister_callback( $option )
341 Removes the callback for the given option. This has the effect of
342 allowing all access for the given option (except for "create_dir").
343
345 Included in the distribution is a simple benchmark script, which has
346 two drivers - one for LibXSLT and one for Sablotron. The benchmark
347 requires the testcases files from the XSLTMark distribution which you
348 can find at http://www.datapower.com/XSLTMark/
349 Put the testcases directory in the directory created by this
351 distribution, and then run:
352 perl benchmark.pl -h
354 to get a list of options.
356 The benchmark requires XML::XPath at the moment, but I hope to factor
358 that out of the equation fairly soon. It also requires Time::HiRes,
359 which I could be persuaded to factor out, replacing it with
360 Benchmark.pm, but I haven't done so yet.
361 I would love to get drivers for XML::XSLT and XML::Transformiix, if you
363 would like to contribute them. Also if you get this running on Win32,
364 I'd love to get a driver for MSXSLT via OLE, to see what we can do
365 against those Redmond boys!
366
368 For debugging purposes, XML::LibXSLT provides version information about
369 the libxslt C library (but do not confuse it with the version number of
370 XML::LibXSLT module itself, i.e. with $XML::LibXSLT::VERSION).
371 XML::LibXSLT issues a warning if the runtime version of the library is
372 less then the compile-time version.
373 XML::LibXSLT::LIBXSLT_VERSION()
375 Returns version number of libxslt library which was used to compile
376 XML::LibXSLT as an integer. For example, for libxslt-1.1.18, it
377 will return 10118.
378 XML::LibXSLT::LIBXSLT_DOTTED_VERSION()
380 Returns version number of libxslt library which was used to compile
381 XML::LibXSLT as a string, e.g. "1.1.18".
382 XML::LibXSLT::LIBXSLT_RUNTIME_VERSION()
384 Returns version number of libxslt library to which XML::LibXSLT is
385 linked at runtime (either dynamically or statically). For example,
386 for example, for libxslt.so.1.1.18, it will return 10118.
387 XML::LibXSLT::HAVE_EXLT()
389 Returns 1 if the module was compiled with libexslt, 0 otherwise.
390
392 This is free software, you may use it and distribute it under the same
393 terms as Perl itself.
394 Copyright 2001-2009, AxKit.com Ltd.
396
398 Matt Sergeant, matt@sergeant.org
399 Security callbacks implementation contributed by Shane Corgatelli.
401 Petr Pajas , pajas@matfyz.org
403
405 Shlomi Fish, <https://www.shlomifish.org/me/contact-me/> .
406
408 Please report bugs via
409 http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-LibXSLT
411
413 XML::LibXML , XML::LibXSLT::Quick .
414perl v5.36.0 2022-07-22 XML::LibXSLT(3)