1LibXSLT(3)            User Contributed Perl Documentation           LibXSLT(3)
2
3
4

NAME

6       XML::LibXSLT - Interface to the GNOME libxslt library
7

SYNOPSIS

9         use XML::LibXSLT;
10         use XML::LibXML;
11
12         my $xslt = XML::LibXSLT->new();
13
14         my $source = XML::LibXML->load_xml(location => 'foo.xml');
15         my $style_doc = XML::LibXML->load_xml(location=>'bar.xsl', no_cdata=>1);
16
17         my $stylesheet = $xslt->parse_stylesheet($style_doc);
18
19         my $results = $stylesheet->transform($source);
20
21         print $stylesheet->output_as_bytes($results);
22

DESCRIPTION

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

OPTIONS

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
35       Each of the option methods returns its previous value, and can be
36       called without a parameter to retrieve the current value.
37
38       max_depth
39             XML::LibXSLT->max_depth(1000);
40
41           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
47       max_vars
48             XML::LibXSLT->max_vars(100_000);
49
50           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
55       debug_callback
56             XML::LibXSLT->debug_callback($subref);
57
58           Sets a callback to be used for debug messages. If you don't set
59           this, debug messages will be ignored.
60
61       register_function
62             XML::LibXSLT->register_function($uri, $name, $subref);
63             $stylesheet->register_function($uri, $name, $subref);
64
65           Registers an XSLT extension function mapped to the given URI. For
66           example:
67
68             XML::LibXSLT->register_function("urn:foo", "bar",
69               sub { scalar localtime });
70
71           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
75             <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
83           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
94       register_element
95                   $stylesheet->register_element($uri, $name, $subref)
96
97           Registers an XSLT extension element $name mapped to the given URI.
98           For example:
99
100             $stylesheet->register_element("urn:foo", "hello", sub {
101                     my $name = $_[2]->getAttribute( "name" );
102                     return XML::LibXML::Text->new( "Hello, $name!" );
103             });
104
105           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
110             <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
119           The callback is passed the input document node as $_[1] and the
120           stylesheet node as $_[2]. $_[0] is reserved for future use.
121

API

123       The following methods are available on the new XML::LibXSLT object:
124
125       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
132           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
136             my $stylesheet_doc = XML::LibXML->load_xml(location=>"some.xsl", no_cdata=>1);
137
138       parse_stylesheet_file($filename)
139           Exactly the same as the above, but parses the given filename
140           directly.
141

Input Callbacks

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
147       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

Security Callbacks

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

XML::LibXSLT::Stylesheet

160       The main API is on the stylesheet, though it is fairly minimal.
161
162       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
167       transform(doc, %params)
168             my $results = $stylesheet->transform($doc, foo => "'bar'");
169             print $stylesheet->output_as_bytes($results);
170
171           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
176       transform_file(filename, %params)
177             my $results = $stylesheet->transform_file($filename, bar => "'baz'");
178
179           Note the string parameter caveat, detailed in the section on
180           "Parameters" below.
181
182       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
191       output_as_chars(result)
192           Like "output_as_bytes(result)", but always return the output as
193           (UTF-8 encoded) string of characters.
194
195       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
205       output_fh(result, fh)
206           Outputs the result to the filehandle given in $fh.
207
208       output_file(result, filename)
209           Outputs the result to the file named in $filename.
210
211       output_encoding()
212           Returns the output encoding of the results. Defaults to "UTF-8".
213
214       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
223       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
229       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

Parameters

236       LibXSLT expects parameters in XPath format. That is, if you wish to
237       pass a string to the XSLT engine, you actually have to pass it as a
238       quoted string:
239
240         $stylesheet->transform($doc, param => "'string'");
241
242       Note the quotes within quotes there!
243
244       Obviously this isn't much fun, so you can make it easy on yourself:
245
246         $stylesheet->transform($doc, XML::LibXSLT::xpath_to_string(
247               param => "string"
248               ));
249
250       The utility function does the right thing with respect to strings in
251       XPath, including when you have quotes already embedded within your
252       string.
253

XML::LibXSLT::Security

255       Provides an interface to the libxslt security framework by allowing
256       callbacks to be defined that can restrict access to various resources
257       (files or URLs) during a transformation.
258
259       The libxslt security framework allows callbacks to be defined for
260       certain actions that a stylesheet may attempt during a transformation.
261       It may be desirable to restrict some of these actions (for example,
262       writing a new file using exsl:document). The actions that may be
263       restricted are:
264
265       read_file
266           Called when the stylesheet attempts to open a local file (ie: when
267           using the document() function).
268
269       write_file
270           Called when an attempt is made to write a local file (ie: when
271           using the exsl:document element).
272
273       create_dir
274           Called when a directory needs to be created in order to write a
275           file.
276
277           NOTE: By default, create_dir is not allowed. To enable it a
278           callback must be registered.
279
280       read_net
281           Called when the stylesheet attempts to read from the network.
282
283       write_net
284           Called when the stylesheet attempts to write to the network.
285
286   Using XML::LibXSLT::Security
287       The interface for this module is similar to XML::LibXML::InputCallback.
288       After creating a new instance you may register callbacks for each of
289       the security options listed above. Then you apply the security
290       preferences to the XML::LibXSLT or XML::LibXSLT::Stylesheet object
291       using "security_callbacks()".
292
293         my $security = XML::LibXSLT::Security->new();
294         $security->register_callback( read_file  => $read_cb );
295         $security->register_callback( write_file => $write_cb );
296         $security->register_callback( create_dir => $create_cb );
297         $security->register_callback( read_net   => $read_net_cb );
298         $security->register_callback( write_net  => $write_net_cb );
299
300         $xslt->security_callbacks( $security );
301          -OR-
302         $stylesheet->security_callbacks( $security );
303
304       The registered callback functions are called when access to a resource
305       is requested. If the access should be allowed the callback should
306       return 1, if not it should return 0. The callback functions should
307       accept the following arguments:
308
309       $tctxt
310           This is the transform context (XML::LibXSLT::TransformContext). You
311           can use this to get the current XML::LibXSLT::Stylesheet object by
312           calling "stylesheet()".
313
314             my $stylesheet = $tctxt->stylesheet();
315
316           The stylesheet object can then be used to share contextual
317           information between different calls to the security callbacks.
318
319       $value
320           This is the name of the resource (file or URI) that has been
321           requested.
322
323       If a particular option (except for "create_dir") doesn't have a
324       registered callback, then the stylesheet will have full access for that
325       action.
326
327   Interface
328       new()
329           Creates a new XML::LibXSLT::Security object.
330
331       register_callback( $option, $callback )
332           Registers a callback function for the given security option (listed
333           above).
334
335       unregister_callback( $option )
336           Removes the callback for the given option. This has the effect of
337           allowing all access for the given option (except for "create_dir").
338

BENCHMARK

340       Included in the distribution is a simple benchmark script, which has
341       two drivers - one for LibXSLT and one for Sablotron. The benchmark
342       requires the testcases files from the XSLTMark distribution which you
343       can find at http://www.datapower.com/XSLTMark/
344
345       Put the testcases directory in the directory created by this
346       distribution, and then run:
347
348         perl benchmark.pl -h
349
350       to get a list of options.
351
352       The benchmark requires XML::XPath at the moment, but I hope to factor
353       that out of the equation fairly soon. It also requires Time::HiRes,
354       which I could be persuaded to factor out, replacing it with
355       Benchmark.pm, but I haven't done so yet.
356
357       I would love to get drivers for XML::XSLT and XML::Transformiix, if you
358       would like to contribute them. Also if you get this running on Win32,
359       I'd love to get a driver for MSXSLT via OLE, to see what we can do
360       against those Redmond boys!
361

LIBRARY VERSIONS

363       For debugging purposes, XML::LibXSLT provides version information about
364       the libxslt C library (but do not confuse it with the version number of
365       XML::LibXSLT module itself, i.e. with $XML::LibXSLT::VERSION).
366       XML::LibXSLT issues a warning if the runtime version of the library is
367       less then the compile-time version.
368
369       XML::LibXSLT::LIBXSLT_VERSION()
370           Returns version number of libxslt library which was used to compile
371           XML::LibXSLT as an integer. For example, for libxslt-1.1.18, it
372           will return 10118.
373
374       XML::LibXSLT::LIBXSLT_DOTTED_VERSION()
375           Returns version number of libxslt library which was used to compile
376           XML::LibXSLT as a string, e.g. "1.1.18".
377
378       XML::LibXSLT::LIBXSLT_RUNTIME_VERSION()
379           Returns version number of libxslt library to which XML::LibXSLT is
380           linked at runtime (either dynamically or statically). For example,
381           for example, for libxslt.so.1.1.18, it will return 10118.
382
383       XML::LibXSLT::HAVE_EXLT()
384           Returns 1 if the module was compiled with libexslt, 0 otherwise.
385

LICENSE

387       This is free software, you may use it and distribute it under the same
388       terms as Perl itself.
389
390       Copyright 2001-2009, AxKit.com Ltd.
391

AUTHOR

393       Matt Sergeant, matt@sergeant.org
394
395       Security callbacks implementation contributed by Shane Corgatelli.
396

MAINTAINER

398       Petr Pajas , pajas@matfyz.org
399

BUGS

401       Please report bugs via
402
403         http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-LibXSLT
404

SEE ALSO

406       XML::LibXML
407
408
409
410perl v5.34.0                      2021-07-23                        LibXSLT(3)
Impressum