XML::LibXSLT(3pm)

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 $parser = XML::LibXML->new();
13         my $xslt = XML::LibXSLT->new();
14
15         my $source = $parser->parse_file('foo.xml');
16         my $style_doc = $parser->parse_file('bar.xsl');
17
18         my $stylesheet = $xslt->parse_stylesheet($style_doc);
19
20         my $results = $stylesheet->transform($source);
21
22         print $stylesheet->output_string($results);
23

DESCRIPTION

25       This module is an interface to the gnome project's libxslt. This is an
26       extremely good XSLT engine, highly compliant and also very fast. I have
27       tests showing this to be more than twice as fast as Sablotron.
28

OPTIONS

30       XML::LibXSLT has some global options. Note that these are probably not
31       thread or even fork safe - so only set them once per process. Each one
32       of these options can be called either as class methods, or as instance
33       methods. However either way you call them, it still sets global
34       options.
35
36       Each of the option methods returns its previous value, and can be
37       called without a parameter to retrieve the current value.
38
39       max_depth
40
41         XML::LibXSLT->max_depth(1000);
42
43       This option sets the maximum recursion depth for a stylesheet. See the
44       very end of section 5.4 of the XSLT specification for more details on
45       recursion and detecting it. If your stylesheet or XML file requires
46       seriously deep recursion, this is the way to set it. Default value is
47       250.
48
49       debug_callback
50
51         XML::LibXSLT->debug_callback($subref);
52
53       Sets a callback to be used for debug messages. If you don't set this,
54       debug messages will be ignored.
55
56       register_function
57
58         XML::LibXSLT->register_function($uri, $name, $subref);
59
60       Registers an XSLT extension function mapped to the given URI. For exam‐
61       ple:
62
63         XML::LibXSLT->register_function("urn:foo", "bar",
64           sub { scalar localtime });
65
66       Will register a "bar" function in the "urn:foo" namespace (which you
67       have to define in your XSLT using "xmlns:...") that will return the
68       current date and time as a string:
69
70         <xsl:stylesheet version="1.0"
71           xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
72           xmlns:foo="urn:foo">
73         <xsl:template match="/">
74           The time is: <xsl:value-of select="foo:bar()"/>
75         </xsl:template>
76         </xsl:stylesheet>
77
78       Parameters can be in whatever format you like. If you pass in a
79       nodelist it will be a XML::LibXML::NodeList object in your perl code,
80       but ordinary values (strings, numbers and booleans) will be ordinary
81       perl scalars. If you wish them to be "XML::LibXML::Literal",
82       "XML::LibXML::Number" and "XML::LibXML::Number" values respectively
83       then set the variable $XML::LibXSLT::USE_LIBXML_DATA_TYPES to a true
84       value. Return values can be a nodelist or a plain value - the code will
85       just do the right thing.  But only a single return value is supported
86       (a list is not converted to a nodelist).
87

API

89       The following methods are available on the new XML::LibXSLT object:
90
91       parse_stylesheet($doc)
92
93       $doc here is an XML::LibXML::Document object (see XML::LibXML) repre‐
94       senting an XSLT file. This method will return a
95       XML::LibXSLT::Stylesheet object, or undef on failure. If the XSLT is
96       invalid, an exception will be thrown, so wrap the call to
97       parse_stylesheet in an eval{} block to trap this.
98
99       parse_stylesheet_file($filename)
100
101       Exactly the same as the above, but parses the given filename directly.
102
103       Input Callbacks
104
105       To define XML::LibXSLT specific input callbacks, reuse the XML::LibXML
106       input callback API as described in "Input Callbacks" in
107       XML::LibXML::Document(3).
108

XML::LibXSLT::Stylesheet

110       The main API is on the stylesheet, though it is fairly minimal.
111
112       One of the main advantages of XML::LibXSLT is that you have a generic
113       stylesheet object which you call the transform() method passing in a
114       document to transform. This allows you to have multiple transformations
115       happen with one stylesheet without requiring a reparse.
116
117       transform(doc, %params)
118
119         my $results = $stylesheet->transform($doc, foo => "value);
120
121       Transforms the passed in XML::LibXML::Document object, and returns a
122       new XML::LibXML::Document. Extra hash entries are used as parameters.
123
124       transform_file(filename, %params)
125
126         my $results = $stylesheet->transform_file($filename, bar => "value");
127
128       output_string(result)
129
130       Returns a scalar that is the XSLT rendering of the XML::LibXML::Docu‐
131       ment object using the desired output format (specified in the xsl:out‐
132       put tag in the stylesheet). Note that you can also call
133       $result->toString, but that will *always* output the document in XML
134       format, and in UTF8, which may not be what you asked for in the
135       xsl:output tag.
136
137       output_fh(result, fh)
138
139       Outputs the result to the filehandle given in $fh.
140
141       output_file(result, filename)
142
143       Outputs the result to the file named in $filename.
144
145       output_encoding
146
147       Returns the output encoding of the results. Defaults to "UTF-8".
148
149       media_type
150
151       Returns the output media_type of the results. Defaults to "text/html".
152

Parameters

154       LibXSLT expects parameters in XPath format. That is, if you wish to
155       pass a string to the XSLT engine, you actually have to pass it as a
156       quoted string:
157
158         $stylesheet->transform($doc, param => "'string'");
159
160       Note the quotes within quotes there!
161
162       Obviously this isn't much fun, so you can make it easy on yourself:
163
164         $stylesheet->transform($doc, XML::LibXSLT::xpath_to_string(
165               param => "string"
166               ));
167
168       The utility function does the right thing with respect to strings in
169       XPath, including when you have quotes already embedded within your
170       string.
171

BENCHMARK

173       Included in the distribution is a simple benchmark script, which has
174       two drivers - one for LibXSLT and one for Sablotron. The benchmark
175       requires the testcases files from the XSLTMark distribution which you
176       can find at http://www.datapower.com/XSLTMark/
177
178       Put the testcases directory in the directory created by this distribu‐
179       tion, and then run:
180
181         perl benchmark.pl -h
182
183       to get a list of options.
184
185       The benchmark requires XML::XPath at the moment, but I hope to factor
186       that out of the equation fairly soon. It also requires Time::HiRes,
187       which I could be persuaded to factor out, replacing it with Bench‐
188       mark.pm, but I haven't done so yet.
189
190       I would love to get drivers for XML::XSLT and XML::Transformiix, if you
191       would like to contribute them. Also if you get this running on Win32,
192       I'd love to get a driver for MSXSLT via OLE, to see what we can do
193       against those Redmond boys!
194

AUTHOR

196       Matt Sergeant, matt@sergeant.org
197
198       Copyright 2001, AxKit.com Ltd. All rights reserved.
199