1LibXSLT(3) User Contributed Perl Documentation 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 debug_callback
48 XML::LibXSLT->debug_callback($subref);
49 Sets a callback to be used for debug messages. If you don't set
51 this, debug messages will be ignored.
52 register_function
54 XML::LibXSLT->register_function($uri, $name, $subref);
55 $stylesheet->register_function($uri, $name, $subref);
56 Registers an XSLT extension function mapped to the given URI. For
58 example:
59 XML::LibXSLT->register_function("urn:foo", "bar",
61 sub { scalar localtime });
62 Will register a "bar" function in the "urn:foo" namespace (which
64 you have to define in your XSLT using "xmlns:...") that will return
65 the current date and time as a string:
66 <xsl:stylesheet version="1.0"
68 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
69 xmlns:foo="urn:foo">
70 <xsl:template match="/">
71 The time is: <xsl:value-of select="foo:bar()"/>
72 </xsl:template>
73 </xsl:stylesheet>
74 Parameters can be in whatever format you like. If you pass in a
76 nodelist it will be a XML::LibXML::NodeList object in your perl
77 code, but ordinary values (strings, numbers and booleans) will be
78 ordinary perl scalars. If you wish them to be
79 "XML::LibXML::Literal", "XML::LibXML::Number" and
80 "XML::LibXML::Number" values respectively then set the variable
81 $XML::LibXSLT::USE_LIBXML_DATA_TYPES to a true value. Return values
82 can be a nodelist or a plain value - the code will just do the
83 right thing. But only a single return value is supported (a list
84 is not converted to a nodelist).
85 register_element
87 $stylesheet->register_element($uri, $name, $subref)
88 Registers an XSLT extension element $name mapped to the given URI.
90 For example:
91 $stylesheet->register_element("urn:foo", "hello", sub {
93 my $name = $_[2]->getAttribute( "name" );
94 return XML::LibXML::Text->new( "Hello, $name!" );
95 });
96 Will register a "hello" element in the "urn:foo" namespace that
98 returns a "Hello, X!" text node. You must define this namespace in
99 your XSLT and include its prefix in the
100 "extension-element-prefixes" list:
101 <xsl:stylesheet version="1.0"
103 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
104 xmlns:foo="urn:foo"
105 extension-element-prefixes="foo">
106 <xsl:template match="/">
107 <foo:hello name="bob"/>
108 </xsl:template>
109 </xsl:stylesheet>
110 The callback is passed the input document node as $_[1] and the
112 stylesheet node as $_[2]. $_[0] is reserved for future use.
113
115 The following methods are available on the new XML::LibXSLT object:
116 parse_stylesheet($stylesheet_doc)
118 $stylesheet_doc here is an XML::LibXML::Document object (see
119 XML::LibXML) representing an XSLT file. This method will return a
120 XML::LibXSLT::Stylesheet object, or undef on failure. If the XSLT
121 is invalid, an exception will be thrown, so wrap the call to
122 parse_stylesheet in an eval{} block to trap this.
123 IMPORTANT: $stylesheet_doc should not contain CDATA sections,
125 otherwise libxslt may misbehave. The best way to assure this is to
126 load the stylesheet with no_cdata flag, e.g.
127 my $stylesheet_doc = XML::LibXML->load_xml(location=>"some.xsl", no_cdata=>1);
129 parse_stylesheet_file($filename)
131 Exactly the same as the above, but parses the given filename
132 directly.
133
135 To define XML::LibXSLT or XML::LibXSLT::Stylesheet specific input
136 callbacks, reuse the XML::LibXML input callback API as described in
137 XML::LibXML::InputCallback(3).
138
140 To create security preferences for the transformation see
141 XML::LibXSLT::Security. Once the security preferences have been defined
142 you can apply them to an XML::LibXSLT or XML::LibXSLT::Stylesheet
143 instance using the "security_callbacks()" method.
144
146 The main API is on the stylesheet, though it is fairly minimal.
147 One of the main advantages of XML::LibXSLT is that you have a generic
149 stylesheet object which you call the transform() method passing in a
150 document to transform. This allows you to have multiple transformations
151 happen with one stylesheet without requiring a reparse.
152 transform(doc, %params)
154 my $results = $stylesheet->transform($doc, foo => "'bar'");
155 print $stylesheet->output_as_bytes($results);
156 Transforms the passed in XML::LibXML::Document object, and returns
158 a new XML::LibXML::Document. Extra hash entries are used as
159 parameters. Be sure to keep in mind the caveat with regard to
160 quotes explained in the section on "Parameters" below.
161 transform_file(filename, %params)
163 my $results = $stylesheet->transform_file($filename, bar => "'baz'");
164 Note the string parameter caveat, detailed in the section on
166 "Parameters" below.
167 output_as_bytes(result)
169 Returns a scalar that is the XSLT rendering of the
170 XML::LibXML::Document object using the desired output format
171 (specified in the xsl:output tag in the stylesheet). Note that you
172 can also call $result->toString, but that will *always* output the
173 document in XML format which may not be what you asked for in the
174 xsl:output tag. The scalar is a byte string encoded in the output
175 encoding specified in the stylesheet.
176 output_as_chars(result)
178 Like "output_as_bytes(result)", but always return the output as
179 (UTF-8 encoded) string of characters.
180 output_string(result)
182 DEPRECATED: This method is something between
183 "output_as_bytes(result)" and "output_as_bytes(result)": The scalar
184 returned by this function appears to Perl as characters (UTF8 flag
185 is on) if the output encoding specified in the XSLT stylesheet was
186 UTF-8 and as bytes if no output encoding was specified or if the
187 output encoding was other than UTF-8. Since the behavior of this
188 function depends on the particular stylesheet, it is deprecated in
189 favor of "output_as_bytes(result)" and "output_as_chars(result)".
190 output_fh(result, fh)
192 Outputs the result to the filehandle given in $fh.
193 output_file(result, filename)
195 Outputs the result to the file named in $filename.
196 output_encoding()
198 Returns the output encoding of the results. Defaults to "UTF-8".
199 output_method()
201 Returns the value of the "method" attribute from "xsl:output"
202 (usually "xml", "html" or "text"). If this attribute is
203 unspecified, the default value is initially "xml". If the transform
204 method is used to produce an HTML document, as per the XSLT spec
205 <http://www.w3.org/TR/xslt#output>, the default value will change
206 to "html". To override this behavior completely, supply an
207 "xsl:output" element in the stylesheet source document.
208 media_type()
210 Returns the value of the "media-type" attribute from "xsl:output".
211 If this attribute is unspecified, the default media type is
212 initially "text/xml". This default changes to "text/html" under the
213 same conditions as output_method.
214
216 LibXSLT expects parameters in XPath format. That is, if you wish to
217 pass a string to the XSLT engine, you actually have to pass it as a
218 quoted string:
219 $stylesheet->transform($doc, param => "'string'");
221 Note the quotes within quotes there!
223 Obviously this isn't much fun, so you can make it easy on yourself:
225 $stylesheet->transform($doc, XML::LibXSLT::xpath_to_string(
227 param => "string"
228 ));
229 The utility function does the right thing with respect to strings in
231 XPath, including when you have quotes already embedded within your
232 string.
233
235 Provides an interface to the libxslt security framework by allowing
236 callbacks to be defined that can restrict access to various resources
237 (files or URLs) during a transformation.
238 The libxslt security framework allows callbacks to be defined for
240 certain actions that a stylesheet may attempt during a transformation.
241 It may be desirable to restrict some of these actions (for example,
242 writing a new file using exsl:document). The actions that may be
243 restricted are:
244 read_file
246 Called when the stylesheet attempts to open a local file (ie: when
247 using the document() function).
248 write_file
250 Called when an attempt is made to write a local file (ie: when
251 using the exsl:document element).
252 create_dir
254 Called when a directory needs to be created in order to write a
255 file.
256 NOTE: By default, create_dir is not allowed. To enable it a
258 callback must be registered.
259 read_net
261 Called when the stylesheet attempts to read from the network.
262 write_net
264 Called when the stylesheet attempts to write to the network.
265 Using XML::LibXSLT::Security
267 The interface for this module is similar to XML::LibXML::InputCallback.
268 After creating a new instance you may register callbacks for each of
269 the security options listed above. Then you apply the security
270 preferences to the XML::LibXSLT or XML::LibXSLT::Stylesheet object
271 using "security_callbacks()".
272 my $security = XML::LibXSLT::Security->new();
274 $security->register_callback( read_file => $read_cb );
275 $security->register_callback( write_file => $write_cb );
276 $security->register_callback( create_dir => $create_cb );
277 $security->register_callback( read_net => $read_net_cb );
278 $security->register_callback( write_net => $write_net_cb );
279 $xslt->security_callbacks( $security );
281 -OR-
282 $stylesheet->security_callbacks( $security );
283 The registered callback functions are called when access to a resource
285 is requested. If the access should be allowed the callback should
286 return 1, if not it should return 0. The callback functions should
287 accept the following arguments:
288 $tctxt
290 This is the transform context (XML::LibXSLT::TransformContext). You
291 can use this to get the current XML::LibXSLT::Stylesheet object by
292 calling "stylesheet()".
293 my $stylesheet = $tctxt->stylesheet();
295 The stylesheet object can then be used to share contextual
297 information between different calls to the security callbacks.
298 $value
300 This is the name of the resource (file or URI) that has been
301 requested.
302 If a particular option (except for "create_dir") doesn't have a
304 registered callback, then the stylesheet will have full access for that
305 action.
306 Interface
308 new()
309 Creates a new XML::LibXSLT::Security object.
310 register_callback( $option, $callback )
312 Registers a callback function for the given security option (listed
313 above).
314 unregister_callback( $option )
316 Removes the callback for the given option. This has the effect of
317 allowing all access for the given option (except for "create_dir").
318
320 Included in the distribution is a simple benchmark script, which has
321 two drivers - one for LibXSLT and one for Sablotron. The benchmark
322 requires the testcases files from the XSLTMark distribution which you
323 can find at http://www.datapower.com/XSLTMark/
324 Put the testcases directory in the directory created by this
326 distribution, and then run:
327 perl benchmark.pl -h
329 to get a list of options.
331 The benchmark requires XML::XPath at the moment, but I hope to factor
333 that out of the equation fairly soon. It also requires Time::HiRes,
334 which I could be persuaded to factor out, replacing it with
335 Benchmark.pm, but I haven't done so yet.
336 I would love to get drivers for XML::XSLT and XML::Transformiix, if you
338 would like to contribute them. Also if you get this running on Win32,
339 I'd love to get a driver for MSXSLT via OLE, to see what we can do
340 against those Redmond boys!
341
343 For debugging purposes, XML::LibXSLT provides version information about
344 the libxslt C library (but do not confuse it with the version number of
345 XML::LibXSLT module itself, i.e. with $XML::LibXSLT::VERSION).
346 XML::LibXSLT issues a warning if the runtime version of the library is
347 less then the compile-time version.
348 XML::LibXSLT::LIBXSLT_VERSION()
350 Returns version number of libxslt library which was used to compile
351 XML::LibXSLT as an integer. For example, for libxslt-1.1.18, it
352 will return 10118.
353 XML::LibXSLT::LIBXSLT_DOTTED_VERSION()
355 Returns version number of libxslt library which was used to compile
356 XML::LibXSLT as a string, e.g. "1.1.18".
357 XML::LibXSLT::LIBXSLT_RUNTIME_VERSION()
359 Returns version number of libxslt library to which XML::LibXSLT is
360 linked at runtime (either dynamically or statically). For example,
361 for example, for libxslt.so.1.1.18, it will return 10118.
362 XML::LibXSLT::HAVE_EXLT()
364 Returns 1 if the module was compiled with libexslt, 0 otherwised.
365
367 This is free software, you may use it and distribute it under the same
368 terms as Perl itself.
369 Copyright 2001-2009, AxKit.com Ltd.
371
373 Matt Sergeant, matt@sergeant.org
374 Security callbacks implementation contributed by Shane Corgatelli.
376
378 Petr Pajas , pajas@matfyz.org
379
381 Please report bugs via
382 http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-LibXSLT
384
386 XML::LibXML
387perl v5.16.3 2013-01-23 LibXSLT(3)