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 Registers an XSLT extension function mapped to the given URI. For
57 example:
58 XML::LibXSLT->register_function("urn:foo", "bar",
60 sub { scalar localtime });
61 Will register a "bar" function in the "urn:foo" namespace (which
63 you have to define in your XSLT using "xmlns:...") that will return
64 the current date and time as a string:
65 <xsl:stylesheet version="1.0"
67 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
68 xmlns:foo="urn:foo">
69 <xsl:template match="/">
70 The time is: <xsl:value-of select="foo:bar()"/>
71 </xsl:template>
72 </xsl:stylesheet>
73 Parameters can be in whatever format you like. If you pass in a
75 nodelist it will be a XML::LibXML::NodeList object in your perl
76 code, but ordinary values (strings, numbers and booleans) will be
77 ordinary perl scalars. If you wish them to be
78 "XML::LibXML::Literal", "XML::LibXML::Number" and
79 "XML::LibXML::Number" values respectively then set the variable
80 $XML::LibXSLT::USE_LIBXML_DATA_TYPES to a true value. Return values
81 can be a nodelist or a plain value - the code will just do the
82 right thing. But only a single return value is supported (a list
83 is not converted to a nodelist).
84
86 The following methods are available on the new XML::LibXSLT object:
87 parse_stylesheet($stylesheet_doc)
89 $stylesheet_doc here is an XML::LibXML::Document object (see
90 XML::LibXML) representing an XSLT file. This method will return a
91 XML::LibXSLT::Stylesheet object, or undef on failure. If the XSLT
92 is invalid, an exception will be thrown, so wrap the call to
93 parse_stylesheet in an eval{} block to trap this.
94 IMPORTANT: $stylesheet_doc should not contain CDATA sections,
96 otherwise libxslt may misbehave. The best way to assure this is to
97 load the stylesheet with no_cdata flag, e.g.
98 my $stylesheet_doc = XML::LibXML->load_xml(location=>"some.xsl", no_cdata=>1);
100 parse_stylesheet_file($filename)
102 Exactly the same as the above, but parses the given filename
103 directly.
104
106 To define XML::LibXSLT or XML::LibXSLT::Stylesheet specific input
107 callbacks, reuse the XML::LibXML input callback API as described in
108 XML::LibXML::InputCallback(3).
109
111 To create security preferences for the transformation see
112 XML::LibXSLT::Security. Once the security preferences have been defined
113 you can apply them to an XML::LibXSLT or XML::LibXSLT::Stylesheet
114 instance using the "security_callbacks()" method.
115
117 The main API is on the stylesheet, though it is fairly minimal.
118 One of the main advantages of XML::LibXSLT is that you have a generic
120 stylesheet object which you call the transform() method passing in a
121 document to transform. This allows you to have multiple transformations
122 happen with one stylesheet without requiring a reparse.
123 transform(doc, %params)
125 my $results = $stylesheet->transform($doc, foo => "value);
126 print $stylesheet->output_as_bytes($results);
127 Transforms the passed in XML::LibXML::Document object, and returns
129 a new XML::LibXML::Document. Extra hash entries are used as
130 parameters. See output_string
131 transform_file(filename, %params)
133 my $results = $stylesheet->transform_file($filename, bar => "value");
134 output_as_bytes(result)
136 Returns a scalar that is the XSLT rendering of the
137 XML::LibXML::Document object using the desired output format
138 (specified in the xsl:output tag in the stylesheet). Note that you
139 can also call $result->toString, but that will *always* output the
140 document in XML format which may not be what you asked for in the
141 xsl:output tag. The scalar is a byte string encoded in the output
142 encoding specified in the stylesheet.
143 output_as_chars(result)
145 Like "output_as_bytes(result)", but always return the output as
146 (UTF-8 encoded) string of characters.
147 output_string(result)
149 DEPRECATED: This method is something between
150 "output_as_bytes(result)" and "output_as_bytes(result)": The scalar
151 returned by this function appears to Perl as characters (UTF8 flag
152 is on) if the output encoding specified in the XSLT stylesheet was
153 UTF-8 and as bytes if no output encoding was specified or if the
154 output encoding was other than UTF-8. Since the behavior of this
155 function depends on the particular stylesheet, it is deprecated in
156 favor of "output_as_bytes(result)" and "output_as_chars(result)".
157 output_fh(result, fh)
159 Outputs the result to the filehandle given in $fh.
160 output_file(result, filename)
162 Outputs the result to the file named in $filename.
163 output_encoding()
165 Returns the output encoding of the results. Defaults to "UTF-8".
166 media_type()
168 Returns the output media_type of the results. Defaults to
169 "text/html".
170
172 LibXSLT expects parameters in XPath format. That is, if you wish to
173 pass a string to the XSLT engine, you actually have to pass it as a
174 quoted string:
175 $stylesheet->transform($doc, param => "'string'");
177 Note the quotes within quotes there!
179 Obviously this isn't much fun, so you can make it easy on yourself:
181 $stylesheet->transform($doc, XML::LibXSLT::xpath_to_string(
183 param => "string"
184 ));
185 The utility function does the right thing with respect to strings in
187 XPath, including when you have quotes already embedded within your
188 string.
189
191 Provides an interface to the libxslt security framework by allowing
192 callbacks to be defined that can restrict access to various resources
193 (files or URLs) during a transformation.
194 The libxslt security framework allows callbacks to be defined for
196 certain actions that a stylesheet may attempt during a transformation.
197 It may be desirable to restrict some of these actions (for example,
198 writing a new file using exsl:document). The actions that may be
199 restricted are:
200 read_file
202 Called when the stylesheet attempts to open a local file (ie: when
203 using the document() function).
204 write_file
206 Called when an attempt is made to write a local file (ie: when
207 using the exsl:document element).
208 create_dir
210 Called when a directory needs to be created in order to write a
211 file.
212 NOTE: By default, create_dir is not allowed. To enable it a
214 callback must be registered.
215 read_net
217 Called when the stylesheet attempts to read from the network.
218 write_net
220 Called when the stylesheet attempts to write to the network.
221 Using XML::LibXSLT::Security
223 The interface for this module is similar to XML::LibXML::InputCallback.
224 After creating a new instance you may register callbacks for each of
225 the security options listed above. Then you apply the security
226 preferences to the XML::LibXSLT or XML::LibXSLT::Stylesheet object
227 using "security_callbacks()".
228 my $security = XML::LibXSLT::Security->new();
230 $security->register_callback( read_file => $read_cb );
231 $security->register_callback( write_file => $write_cb );
232 $security->register_callback( create_dir => $create_cb );
233 $security->register_callback( read_net => $read_net_cb );
234 $security->register_callback( write_net => $write_net_cb );
235 $xslt->security_callbacks( $security );
237 -OR-
238 $stylesheet->security_callbacks( $security );
239 The registered callback functions are called when access to a resource
241 is requested. If the access should be allowed the callback should
242 return 1, if not it should return 0. The callback functions should
243 accept the following arguments:
244 $tctxt
246 This is the transform context (XML::LibXSLT::TransformContext). You
247 can use this to get the current XML::LibXSLT::Stylesheet object by
248 calling "stylesheet()".
249 my $stylesheet = $tctxt->stylesheet();
251 The stylesheet object can then be used to share contextual
253 information between different calls to the security callbacks.
254 $value
256 This is the name of the resource (file or URI) that has been
257 requested.
258 If a particular option (except for "create_dir") doesn't have a
260 registered callback, then the stylesheet will have full access for that
261 action.
262 Interface
264 new()
265 Creates a new XML::LibXSLT::Security object.
266 register_callback( $option, $callback )
268 Registers a callback function for the given security option (listed
269 above).
270 unregister_callback( $option )
272 Removes the callback for the given option. This has the effect of
273 allowing all access for the given option (except for "create_dir").
274
276 Included in the distribution is a simple benchmark script, which has
277 two drivers - one for LibXSLT and one for Sablotron. The benchmark
278 requires the testcases files from the XSLTMark distribution which you
279 can find at http://www.datapower.com/XSLTMark/
280 Put the testcases directory in the directory created by this
282 distribution, and then run:
283 perl benchmark.pl -h
285 to get a list of options.
287 The benchmark requires XML::XPath at the moment, but I hope to factor
289 that out of the equation fairly soon. It also requires Time::HiRes,
290 which I could be persuaded to factor out, replacing it with
291 Benchmark.pm, but I haven't done so yet.
292 I would love to get drivers for XML::XSLT and XML::Transformiix, if you
294 would like to contribute them. Also if you get this running on Win32,
295 I'd love to get a driver for MSXSLT via OLE, to see what we can do
296 against those Redmond boys!
297
299 For debugging purposes, XML::LibXSLT provides version information about
300 the libxslt C library (but do not confuse it with the version number of
301 XML::LibXSLT module itself, i.e. with $XML::LibXSLT::VERSION).
302 XML::LibXSLT issues a warning if the runtime version of the library is
303 less then the compile-time version.
304 XML::LibXSLT::LIBXSLT_VERSION()
306 Returns version number of libxslt library which was used to compile
307 XML::LibXSLT as an integer. For example, for libxslt-1.1.18, it
308 will return 10118.
309 XML::LibXSLT::LIBXSLT_DOTTED_VERSION()
311 Returns version number of libxslt library which was used to compile
312 XML::LibXSLT as a string, e.g. "1.1.18".
313 XML::LibXSLT::LIBXSLT_RUNTIME_VERSION()
315 Returns version number of libxslt library to which XML::LibXSLT is
316 linked at runtime (either dynamically or statically). For example,
317 for example, for libxslt.so.1.1.18, it will return 10118.
318 XML::LibXSLT::HAVE_EXLT()
320 Returns 1 if the module was compiled with libexslt, 0 otherwised.
321
323 This is free software, you may use it and distribute it under the same
324 terms as Perl itself.
325 Copyright 2001-2009, AxKit.com Ltd.
327
329 Matt Sergeant, matt@sergeant.org
330 Security callbacks implementation contributed by Shane Corgatelli.
332
334 Petr Pajas , pajas@matfyz.org
335
337 Please report bugs via
338 http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-LibXSLT
340
342 XML::LibXML
343perl v5.12.0 2009-10-07 LibXSLT(3)