doc/extensions.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
   2 <html>
   3 <head>
   4 <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
   5 <style type="text/css"><!--
   6 TD {font-size: 10pt; font-family: Verdana,Arial,Helvetica}
   7 BODY {font-size: 10pt; font-family: Verdana,Arial,Helvetica; margin-top: 5pt; margin-left: 0pt; margin-right: 0pt}
   8 H1 {font-size: 16pt; font-family: Verdana,Arial,Helvetica}
   9 H2 {font-size: 14pt; font-family: Verdana,Arial,Helvetica}
  10 H3 {font-size: 12pt; font-family: Verdana,Arial,Helvetica}
  11 A:link, A:visited, A:active { text-decoration: underline }
  12 --></style>
  13 <title>Writing extensions</title>
  14 </head>
  15 <body bgcolor="#8b7765" text="#000000" link="#000000" vlink="#000000">
  16 <table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr>
  17 <td width="100">
  18 <a href="http://www.gnome.org/"><img src="smallfootonly.gif" alt="Gnome Logo"></a><a href="http://www.redhat.com"><img src="redhat.gif" alt="Red Hat Logo"></a>
  19 </td>
  20 <td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center">
  21 <h1>The XSLT C library for Gnome</h1>
  22 <h2>Writing extensions</h2>
  23 </td></tr></table></td></tr></table></td>
  24 </tr></table>
  25 <table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr>
  26 <td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td>
  27 <table width="100%" border="0" cellspacing="1" cellpadding="3">
  28 <tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr>
  29 <tr><td bgcolor="#fffacd"><ul style="margin-left: -2pt">
  30 <li><a href="index.html">Home</a></li>
  31 <li><a href="intro.html">Introduction</a></li>
  32 <li><a href="docs.html">Documentation</a></li>
  33 <li><a href="bugs.html">Reporting bugs and getting help</a></li>
  34 <li><a href="help.html">How to help</a></li>
  35 <li><a href="downloads.html">Downloads</a></li>
  36 <li><a href="FAQ.html">FAQ</a></li>
  37 <li><a href="news.html">News</a></li>
  38 <li><a href="xsltproc2.html">The xsltproc tool</a></li>
  39 <li><a href="docbook.html">DocBook</a></li>
  40 <li><a href="API.html">The programming API</a></li>
  41 <li><a href="internals.html">Library internals</a></li>
  42 <li><a href="extensions.html">Writing extensions</a></li>
  43 <li><a href="contribs.html">Contributions</a></li>
  44 <li>
  45 <a href="xslt.html">flat page</a>, <a href="site.xsl">stylesheet</a>
  46 </li>
  47 </ul></td></tr>
  48 </table>
  49 <table width="100%" border="0" cellspacing="1" cellpadding="3">
  50 <tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr>
  51 <tr><td bgcolor="#fffacd"><ul style="margin-left: -2pt">
  52 <li><a href="tutorial/libxslttutorial.html">Tutorial</a></li>
  53 <li><a href="xsltproc.html">Man page for xsltproc</a></li>
  54 <li><a href="http://mail.gnome.org/archives/xslt/">Mail archive</a></li>
  55 <li><a href="http://xmlsoft.org/">XML libxml</a></li>
  56 <li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li>
  57 <li><a href="ftp://xmlsoft.org/">FTP</a></li>
  58 <li><a href="http://www.fh-frankfurt.de/~igor/projects/libxml/">Windows binaries</a></li>
  59 <li><a href="http://garypennington.net/libxml2/">Solaris binaries</a></li>
  60 <li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxslt">Bug Tracker</a></li>
  61 <li><a href="http://xsldbg.sourceforge.net/">Xsldbg Debugger</a></li>
  62 </ul></td></tr>
  63 </table>
  64 </td></tr></table></td>
  65 <td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd">
  66 <h3>Table  of content</h3>
  67 <ul>
  68 <li><a href="extensions.html#Introducti">Introduction</a></li>
  69 <li><a href="extensions.html#Basics">Basics</a></li>
  70 <li><a href="extensions.html#Keep">Extension modules</a></li>
  71 <li><a href="extensions.html#Registerin">Registering a module</a></li>
  72 <li><a href="extensions.html#module">Loading a module</a></li>
  73 <li><a href="extensions.html#Registerin1">Registering an extension
  74     function</a></li>
  75 <li><a href="extensions.html#Implementi">Implementing an extension
  76     function</a></li>
  77 <li><a href="extensions.html#Examples">Examples for extension
  78   functions</a></li>
  79 <li><a href="extensions.html#Registerin2">Registering an extension
  80     element</a></li>
  81 <li><a href="extensions.html#Implementi1">Implementing an extension
  82     element</a></li>
  83 <li><a href="extensions.html#Example">Example for extension
  84   elements</a></li>
  85 <li><a href="extensions.html#shutdown">The shutdown of a module</a></li>
  86 <li><a href="extensions.html#Future">Future work</a></li>
  87 </ul>
  88 <h3><a name="Introducti1">Introduction</a></h3>
  89 <p>This document describes the work needed to write extensions to the
  90 standard XSLT library for use with <a href="http://xmlsoft.org/XSLT/">libxslt</a>, the <a href="http://www.w3.org/TR/xslt">XSLT</a> C library developed for the <a href="http://www.gnome.org/">Gnome</a> project.</p>
  91 <p>Before starting reading this document it is highly recommended to get
  92 familiar with <a href="internals.html">the libxslt internals</a>.</p>
  93 <p>Note: this documentation is by definition incomplete and I am not good at
  94 spelling, grammar, so patches and suggestions are <a href="mailto:veillard@redhat.com">really welcome</a>.</p>
  95 <h3><a name="Basics">Basics</a></h3>
  96 <p>The <a href="http://www.w3.org/TR/xslt">XSLT specification</a> provides
  97 two <a href="http://www.w3.org/TR/xslt">ways to extend an XSLT engine</a>:</p>
  98 <ul>
  99 <li>providing <a href="http://www.w3.org/TR/xslt">new extension
 100     functions</a> which can be called from XPath expressions</li>
 101 <li>providing <a href="http://www.w3.org/TR/xslt">new extension
 102     elements</a> which can be inserted in stylesheets</li>
 103 </ul>
 104 <p>In both cases the extensions need to be associated to a new namespace,
 105 i.e. an URI used as the name for the extension's namespace (there is no need
 106 to have a resource there for this to work).</p>
 107 <p>libxslt provides a few extensions itself, either in libxslt namespace
 108 &quot;http://xmlsoft.org/XSLT/&quot; or in other namespace for well known extensions
 109 provided by other XSLT processors like Saxon, Xalan or XT.</p>
 110 <h3><a name="Keep">Extension modules</a></h3>
 111 <p>Since extensions are bound to a namespace name, usually sets of extensions
 112 coming from a given source are using the same namespace name defining in
 113 practice a group of extensions providing elements, functions or both. From
 114 libxslt point of view those are considered as an &quot;extension module&quot;, and most
 115 of the APIs work at a module point of view.</p>
 116 <p>Registration of new functions or elements are bound to the activation of
 117 the module, this is currently done by declaring the namespace as an extension
 118 by using the attribute  <code>extension-element-prefixes</code> on the
 119 <code><a href="http://www.w3.org/TR/xslt">xsl:stylesheet</a></code>
 120 element.</p>
 121 <p>And extension module is defined by 3 objects:</p>
 122 <ul>
 123 <li>the namespace name associated</li>
 124 <li>an initialization function</li>
 125 <li>a shutdown function</li>
 126 </ul>
 127 <h3><a name="Registerin">Registering a module</a></h3>
 128 <p>Currently a libxslt module has to be compiled within the application using
 129 libxslt, there is no code to load dynamically shared libraries associated to
 130 namespace (this may be added but is likely to become a portability
 131 nightmare).</p>
 132 <p>So the current way to register a module is to link the code implementing
 133 it with the application and to call a registration function:</p>
 134 <pre>int xsltRegisterExtModule(const xmlChar *URI,
 135                           xsltExtInitFunction initFunc,
 136                           xsltExtShutdownFunction shutdownFunc);</pre>
 137 <p>The associated header is read by:</p>
 138 <pre>#include&lt;libxslt/extensions.h&gt;</pre>
 139 <p>which also defines the type for the initialization and shutdown
 140 functions</p>
 141 <h3><a name="module">Loading a module</a></h3>
 142 <p>Once the module URI has been registered and if the XSLT processor detects
 143 that a given stylesheet needs the functionalities of an extended module, this
 144 one is initialized.</p>
 145 <p>The xsltExtInitFunction type defines the interface for an initialization
 146 function:</p>
 147 <pre>/**
 148  * xsltExtInitFunction:
 149  * @ctxt:  an XSLT transformation context
 150  * @URI:  the namespace URI for the extension
 151  *
 152  * A function called at initialization time of an XSLT
 153  * extension module
 154  *
 155  * Returns a pointer to the module specific data for this
 156  * transformation
 157  */
 158 typedef void *(*xsltExtInitFunction)(xsltTransformContextPtr ctxt,
 159                                      const xmlChar *URI);</pre>
 160 <p>There are 3 things to notice:</p>
 161 <ul>
 162 <li>the function gets passed the namespace name URI as an argument, this
 163     allow a single function to provide the initialization for multiple
 164     logical modules</li>
 165 <li>it also gets passed a transformation context, the initialization is
 166     done at run time before any processing occurs on the stylesheet but it
 167     will be invoked separately each time for each transformation</li>
 168 <li>it returns a pointer, this can be used to store module specific
 169     informations which can be retrieved later when a function or an element
 170     from the extension are used, an obvious example is a connection to a
 171     database which should be kept and reused along the transformation. NULL
 172     is a perfectly valid return, there is no way to indicate a failure at
 173     this level</li>
 174 </ul>
 175 <p>What this function is expected to do is:</p>
 176 <ul>
 177 <li>prepare the context for this module (like opening the database
 178     connection)</li>
 179 <li>register the extensions specific to this module</li>
 180 </ul>
 181 <h3><a name="Registerin1">Registering an extension function</a></h3>
 182 <p>There is a single call to do this registration:</p>
 183 <pre>int xsltRegisterExtFunction(xsltTransformContextPtr ctxt,
 184                             const xmlChar *name,
 185                             const xmlChar *URI,
 186                             xmlXPathEvalFunc function);</pre>
 187 <p>The registration is bound to a single transformation instance referred by
 188 ctxt, name is the UTF8 encoded name for the NCName of the function, and URI
 189 is the namespace name for the extension (no checking is done, a module could
 190 register functions or elements from a different namespace, but it is not
 191 recommended).</p>
 192 <h3><a name="Implementi">Implementing an extension function</a></h3>
 193 <p>The implementation of the function must have the signature of a libxml
 194 XPath function:</p>
 195 <pre>/**
 196  * xmlXPathEvalFunc:
 197  * @ctxt: an XPath parser context
 198  * @nargs: the number of arguments passed to the function
 199  *
 200  * an XPath evaluation function, the parameters are on the
 201  * XPath context stack
 202  */
 203
 204 typedef void (*xmlXPathEvalFunc)(xmlXPathParserContextPtr ctxt,
 205                                  int nargs);</pre>
 206 <p>The context passed to an XPath function is not an XSLT context but an <a href="internals.html#XPath1">XPath context</a>. However it is possible to
 207 find one from the other:</p>
 208 <ul>
 209 <li>The function xsltXPathGetTransformContext provide this lookup facility:
 210     <pre>xsltTransformContextPtr
 211          xsltXPathGetTransformContext
 212                           (xmlXPathParserContextPtr ctxt);</pre>
 213 </li>
 214 <li>The <code>xmlXPathContextPtr</code> associated to an
 215     <code>xsltTransformContext</code> is stored in the <code>xpathCtxt</code>
 216     field.</li>
 217 </ul>
 218 <p>The first thing an extension function may want to do is to check the
 219 arguments passed on the stack, the <code>nargs</code> will precise how many
 220 of them were provided on the XPath expression. The macros valuePop will
 221 extract them from the XPath stack:</p>
 222 <pre>#include &lt;libxml/xpath.h&gt;
 223 #include &lt;libxml/xpathInternals.h&gt;
 224
 225 xmlXPathObjectPtr obj = valuePop(ctxt); </pre>
 226 <p>Note that <code>ctxt</code> is the XPath context not the XSLT one. It is
 227 then possible to examine the content of the value. Check <a href="internals.html#Descriptio">the description of XPath objects</a> if
 228 necessary. The following is a common sequcnce checking whether the argument
 229 passed is a string and converting it using the built-in XPath
 230 <code>string()</code> function if this is not the case:</p>
 231 <pre>if (obj-&gt;type != XPATH_STRING) {
 232     valuePush(ctxt, obj);
 233     xmlXPathStringFunction(ctxt, 1);
 234     obj = valuePop(ctxt);
 235 }</pre>
 236 <p>Most common XPath functions are available directly at the C level and are
 237 exported either in <code>&lt;libxml/xpath.h&gt;</code> or in
 238 <code>&lt;libxml/xpathInternals.h&gt;</code>.</p>
 239 <p>The extension function may also need to retrieve the data associated to
 240 this module instance (the database connection in the previous example) this
 241 can be done using the xsltGetExtData:</p>
 242 <pre>void * xsltGetExtData(xsltTransformContextPtr ctxt,
 243                       const xmlChar *URI);</pre>
 244 <p>again the URI to be provided is the one used which was used when
 245 registering the module.</p>
 246 <p>Once the function finishes, don't forget to:</p>
 247 <ul>
 248 <li>push the return value on the stack using <code>valuePush(ctxt,
 249     obj)</code>
 250 </li>
 251 <li>deallocate the parameters passed to the function using
 252     <code>xmlXPathFreeObject(obj)</code>
 253 </li>
 254 </ul>
 255 <h3><a name="Examples">Examples for extension functions</a></h3>
 256 <p>The module libxslt/functions.c containsthe sources of the XSLT built-in
 257 functions, including document(), key(), generate-id(), etc. as well as a full
 258 example module at the end. Here is the test function implementation for the
 259 libxslt:test function:</p>
 260 <pre>/**
 261  * xsltExtFunctionTest:
 262  * @ctxt:  the XPath Parser context
 263  * @nargs:  the number of arguments
 264  *
 265  * function libxslt:test() for testing the extensions support.
 266  */
 267 static void
 268 xsltExtFunctionTest(xmlXPathParserContextPtr ctxt, int nargs)
 269 {
 270     xsltTransformContextPtr tctxt;
 271     void *data;
 272
 273     tctxt = xsltXPathGetTransformContext(ctxt);
 274     if (tctxt == NULL) {
 275         xsltGenericError(xsltGenericErrorContext,
 276             &quot;xsltExtFunctionTest: failed to get the transformation context\n&quot;);
 277         return;
 278     }
 279     data = xsltGetExtData(tctxt, (const xmlChar *) XSLT_DEFAULT_URL);
 280     if (data == NULL) {
 281         xsltGenericError(xsltGenericErrorContext,
 282             &quot;xsltExtFunctionTest: failed to get module data\n&quot;);
 283         return;
 284     }
 285 #ifdef WITH_XSLT_DEBUG_FUNCTION
 286     xsltGenericDebug(xsltGenericDebugContext,
 287                      &quot;libxslt:test() called with %d args\n&quot;, nargs);
 288 #endif
 289 }</pre>
 290 <h3><a name="Registerin2">Registering an extension function</a></h3>
 291 <p>There is a single call to do this registration:</p>
 292 <pre>int xsltRegisterExtElement(xsltTransformContextPtr ctxt,
 293                            const xmlChar *name,
 294                            const xmlChar *URI,
 295                            xsltTransformFunction function);</pre>
 296 <p>It is similar to the mechanism used to register an extension function,
 297 except that the signature of an extension element implementation is
 298 different.</p>
 299 <p>The registration is bound to a single transformation instance referred by
 300 ctxt, name is the UTF8 encoded name for the NCName of the element, and URI is
 301 the namespace name for the extension (no checking is done, a module could
 302 register elements for a different namespace, but it is not recommended).</p>
 303 <h3><a name="Implementi1">Implementing an extension element</a></h3>
 304 <p>The implementation of the element must have the signature of an XSLT
 305 transformation function:</p>
 306 <pre>/**
 307  * xsltTransformFunction:
 308  * @ctxt: the XSLT transformation context
 309  * @node: the input node
 310  * @inst: the stylesheet node
 311  * @comp: the compiled information from the stylesheet
 312  *
 313  * signature of the function associated to elements part of the
 314  * stylesheet language like xsl:if or xsl:apply-templates.
 315  */
 316 typedef void (*xsltTransformFunction)
 317                           (xsltTransformContextPtr ctxt,
 318                            xmlNodePtr node,
 319                            xmlNodePtr inst,
 320                            xsltStylePreCompPtr comp);</pre>
 321 <p>The first argument is the XSLT transformation context. The second and
 322 third arguments are xmlNodePtr i.e. internal memory <a href="internals.html#libxml">representation of  XML nodes</a>. They are
 323 respectively <code>node</code> from the the input document being transformed
 324 by the stylesheet and <code>inst</code> the extension element in the
 325 stylesheet. The last argument is <code>comp</code> a pointer to a precompiled
 326 representation of <code>inst</code> but usually for extension function this
 327 value is <code>NULL</code> by default (it could be added and associated to
 328 the instruction in <code>inst-&gt;_private</code>).</p>
 329 <p>The same functions are available from a function implementing an extension
 330 element as in an extension function, including
 331 <code>xsltGetExtData()</code>.</p>
 332 <p>The goal of extension element being usually to enrich the generated
 333 output, it is expected that they will grow the currently generated output
 334 tree, this can be done by grabbing ctxt-&gt;insert which is the current
 335 libxml node being generated (Note this can also be the intermediate value
 336 tree being built for example to initialize a variable, the processing should
 337 be similar). The functions for libxml tree manipulation from <a href="http://xmlsoft.org/html/libxml-tree.html">&lt;libxml/tree.h&gt;</a> can
 338 be employed to extend or modify the tree, but it is required to preserve the
 339 insertion node and its ancestors since there is existing pointers to those
 340 elements still in use in the XSLT template execution stack.</p>
 341 <h3><a name="Example">Example for extension elements</a></h3>
 342 <p>The module libxslt/transform.c containsthe sources of the XSLT built-in
 343 elements, including xsl:element, xsl:attribute, xsl:if, etc. There is a small
 344 but full example in functions.c providing the implementation for the
 345 libxslt:test element, it will output a comment in the result tree:</p>
 346 <pre>/**
 347  * xsltExtElementTest:
 348  * @ctxt:  an XSLT processing context
 349  * @node:  The current node
 350  * @inst:  the instruction in the stylesheet
 351  * @comp:  precomputed informations
 352  *
 353  * Process a libxslt:test node
 354  */
 355 static void
 356 xsltExtElementTest(xsltTransformContextPtr ctxt, xmlNodePtr node,
 357                    xmlNodePtr inst,
 358                    xsltStylePreCompPtr comp)
 359 {
 360     xmlNodePtr comment;
 361
 362     if (ctxt == NULL) {
 363         xsltGenericError(xsltGenericErrorContext,
 364                          &quot;xsltExtElementTest: no transformation context\n&quot;);
 365         return;
 366     }
 367     if (node == NULL) {
 368         xsltGenericError(xsltGenericErrorContext,
 369                          &quot;xsltExtElementTest: no current node\n&quot;);
 370         return;
 371     }
 372     if (inst == NULL) {
 373         xsltGenericError(xsltGenericErrorContext,
 374                          &quot;xsltExtElementTest: no instruction\n&quot;);
 375         return;
 376     }
 377     if (ctxt-&gt;insert == NULL) {
 378         xsltGenericError(xsltGenericErrorContext,
 379                          &quot;xsltExtElementTest: no insertion point\n&quot;);
 380         return;
 381     }
 382     comment =
 383         xmlNewComment((const xmlChar *)
 384                       &quot;libxslt:test element test worked&quot;);
 385     xmlAddChild(ctxt-&gt;insert, comment);
 386 }</pre>
 387 <h3><a name="shutdown">The shutdown of a module</a></h3>
 388 <p>When the XSLT processor ends a transformation, the shutdown function (if
 389 it exists) of all the modules initialized are called.The
 390 xsltExtShutdownFunction type defines the interface for a shutdown
 391 function:</p>
 392 <pre>/**
 393  * xsltExtShutdownFunction:
 394  * @ctxt:  an XSLT transformation context
 395  * @URI:  the namespace URI for the extension
 396  * @data:  the data associated to this module
 397  *
 398  * A function called at shutdown time of an XSLT extension module
 399  */
 400 typedef void (*xsltExtShutdownFunction) (xsltTransformContextPtr ctxt,
 401                                          const xmlChar *URI,
 402                                          void *data);</pre>
 403 <p>this is really similar to a module initialization function except a third
 404 argument is passed, it's the value that was returned by the initialization
 405 function. This allow to deallocate resources from the module for example
 406 close the connection to the database to keep the same example.</p>
 407 <h3><a name="Future">Future work</a></h3>
 408 <p>Well some of the pieces missing:</p>
 409 <ul>
 410 <li>a way to load shared libraries to instanciate new modules</li>
 411 <li>a better detection of extension function usage and their registration
 412     without having to use the extension prefix which ought to be reserved to
 413     element extensions.</li>
 414 <li>more examples</li>
 415 <li>implementations of the <a href="http://www.exslt.org/">EXSLT</a> common
 416     extension libraries, Thomas Broyer nearly finished implementing them.</li>
 417 </ul>
 418 <p>
 419 <p><a href="mailto:daniel@veillard.com">Daniel Veillard</a></p>
 420 </td></tr></table></td></tr></table></td></tr></table></td>
 421 </tr></table></td></tr></table>
 422 </body>
 423 </html>