doc/xslt.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   2     "http://www.w3.org/TR/html4/loose.dtd">
   3 <html>
   4 <head>
   5   <title>The XSLT C library for Gnome</title>
   6   <meta name="GENERATOR" content="amaya 5.1">
   7   <meta http-equiv="Content-Type" content="text/html">
   8 </head>
   9
  10 <body bgcolor="#ffffff">
  11 <h1 align="center">The XSLT C library for Gnome</h1>
  12
  13 <h1 style="text-align: center">libxslt</h1>
  14
  15 <p>Libxslt is the <a href="http://www.w3.org/TR/xslt">XSLT</a> C library
  16 developed for the Gnome project. XSLT itself is a an XML language to define
  17 transformation for XML. Libxslt is based on <a
  18 href="http://xmlsoft.org/">libxml2</a> the XML C library developed for the
  19 Gnome project. It also implements most of the EXSLT set of extensions
  20 functions and some of Saxon's evaluate and expressions extensions.</p>
  21
  22 <p>People can either embed the library in their application or use xsltproc
  23 the command line processing tool. This library is free software and can be
  24 reused in commercial applications (see the <a href="intro.html">intro</a>)</p>
  25
  26 <p>External documents:</p>
  27 <ul>
  28   <li>John Fleck wrote <a href="tutorial/libxslttutorial.html">a tutorial for
  29     libxslt</a></li>
  30   <li><a href="xsltproc.html">xsltproc user manual</a></li>
  31   <li><a href="http://xmlsoft.org/">the libxml documentation</a></li>
  32 </ul>
  33
  34 <p></p>
  35
  36 <h2><a name="Introducti">Introduction</a></h2>
  37
  38 <p>This document describes <a href="http://xmlsoft.org/XSLT/">libxslt</a>,
  39 the <a href="http://www.w3.org/TR/xslt">XSLT</a> C library developed for the
  40 <a href="http://www.gnome.org/">Gnome</a> project.</p>
  41
  42 <p>Here are some key points about libxslt:</p>
  43 <ul>
  44   <li>Libxslt is a C implementation</li>
  45   <li>Libxslt is based on libxml for XML parsing, tree manipulation and XPath
  46     support</li>
  47   <li>It is written in plain C, making as few assumptions as possible, and
  48     sticking closely to ANSI C/POSIX for easy embedding. Should works on
  49     Linux/Unix/Windows.</li>
  50   <li>This library is released under the <a
  51     href="http://www.opensource.org/licenses/mit-license.html">MIT
  52   Licence</a></li>
  53   <li>Though not designed primarily with performances in mind, libxslt seems
  54     to be a relatively fast processor.</li>
  55 </ul>
  56
  57 <h2><a name="Documentat">Documentation</a></h2>
  58
  59 <p>There are some on-line resources about using libxslt:</p>
  60 <ol>
  61   <li>Check the <a href="html/libxslt-lib.html#LIBXSLT-LIB">API
  62     documentation</a> automatically extracted from code comments (using <a
  63     href="http://cvs.gnome.org/bonsai/rview.cgi?cvsroot=/cvs/gnome&amp;dir=gtk-doc">gtk
  64     doc</a>).</li>
  65   <li>Look at the <a href="http://mail.gnome.org/archives/xslt/">mailing-list
  66     archive</a>.</li>
  67   <li>Of course since libxslt is based on libxml, it's a good idea to at
  68     least read <a href="http://xmlsoft.org/">libxml description</a></li>
  69 </ol>
  70
  71 <h2><a name="Reporting">Reporting bugs and getting help</a></h2>
  72
  73 <p>If you need help with the XSLT language itself, here are a number of
  74 useful resources:</p>
  75 <ul>
  76   <li>I strongly suggest to subscribe to <a
  77     href="http://www.mulberrytech.com/xsl/xsl-list">XSL-list</a>, check <a
  78     href="http://www.biglist.com/lists/xsl-list/archives/">the XSL-list
  79     archives</a></li>
  80   <li>The <a href="http://www.dpawson.co.uk/xsl/xslfaq.html">XSL FAQ</a>.</li>
  81   <li>The <a
  82     href="http://www.nwalsh.com/docs/tutorials/xsl/xsl/slides.html">tutorial</a>
  83     written by Paul Grosso and Norman Walsh is a very good on-line
  84     introdution to the language.</li>
  85   <li>The <a
  86     href="http://www.zvon.org/xxl/XSLTutorial/Books/Book1/index.html">only
  87     Zvon XSLT tutorial</a> details a lot of constructs with examples.</li>
  88   <li><a href="http://www.jenitennison.com/xslt/index.html">Jeni Tennison's
  89     XSLT</a> pages provide links to a lot of answers</li>
  90   <li>the <a href="http://incrementaldevelopment.com/xsltrick/">Gallery of
  91     XSLT Tricks</a> provides non-standard use case of XSLT</li>
  92   <li>And I suggest to buy Michael Kay "XSLT Programmer's Reference" book
  93     published by <a href="http://www.wrox.com/">Wrox</a> if you plan to work
  94     seriously with XSLT in the future.</li>
  95 </ul>
  96
  97 <p>Well, bugs or missing features are always possible, and I will make a
  98 point of fixing them in a timely fashion. The best way to report a bug is to
  99 use the <a href="http://bugzilla.gnome.org/buglist.cgi?product=libxslt">Gnome
 100 bug tracking database</a> (make sure to use the "libxslt" module name). I
 101 look at reports there regularly and it's good to have a reminder when a bug
 102 is still open. Be sure to specify that the bug is for the package libxslt.</p>
 103
 104 <p>There is also a mailing-list <a
 105 href="mailto:xslt@gnome.org">xslt@gnome.org</a> for libxslt, with an <a
 106 href="http://mail.gnome.org/archives/xslt/">on-line archive</a>. To subscribe
 107 to this list, please visit the <a
 108 href="http://mail.gnome.org/mailman/listinfo/xslt">associated Web</a> page
 109 and follow the instructions.</p>
 110
 111 <p>Alternatively, you can just send the bug to the <a
 112 href="mailto:xslt@gnome.org">xslt@gnome.org</a> list, if it's really libxslt
 113 related I will approve it.. Please do not send me mail directly especially
 114 for portability problem, it makes things really harder to track and in some
 115 cases I'm not the best person to answer a given question, ask the list
 116 instead. <strong>Do not send code, I won't debug it</strong> (but patches are
 117 really appreciated!).</p>
 118
 119 <p>Check the following too before posting:</p>
 120 <ul>
 121   <li>make sure you are <a href="ftp://xmlsoft.org/">using a recent
 122     version</a>, and that the problem still shows up in those</li>
 123   <li>check the <a href="http://mail.gnome.org/archives/xslt/">list
 124     archives</a> to see if the problem was reported already, in this case
 125     there is probably a fix available, similarly check the <a
 126     href="http://bugzilla.gnome.org/buglist.cgi?product=libxslt">registered
 127     open bugs</a></li>
 128   <li>make sure you can reproduce the bug with xsltproc, a very useful thing
 129     to do is run the transformation with -v argument and redirect the
 130     standard error to a file, then search in this file for the transformation
 131     logs just preceding the possible problem</li>
 132   <li>Please send the command showing the error as well as the input and
 133     stylesheet (as an attachment)</li>
 134 </ul>
 135
 136 <p>Of course, bugs reports with a suggested patch for fixing them will
 137 probably be processed faster.</p>
 138
 139 <p>If you're looking for help, a quick look at <a
 140 href="http://mail.gnome.org/archives/xslt/">the list archive</a> may actually
 141 provide the answer, I usually send source samples when answering libxslt
 142 usage questions. The <a
 143 href="html/libxslt-lib.html#LIBXSLT-LIB">auto-generated documentation</a> is
 144 not as polished as I would like (I need to learn more about Docbook), but
 145 it's a good starting point.</p>
 146
 147 <h2><a name="help">How to help</a></h2>
 148
 149 <p>You can help the project in various ways, the best thing to do first is to
 150 subscribe to the mailing-list as explained before, check the <a
 151 href="http://mail.gnome.org/archives/xslt/">archives </a>and the <a
 152 href="http://bugzilla.gnome.org/buglist.cgi?product=libxslt">Gnome bug
 153 database:</a>:</p>
 154 <ol>
 155   <li>provide patches when you find problems</li>
 156   <li>provide the diffs when you port libxslt to a new platform. They may not
 157     be integrated in all cases but help pinpointing portability problems
 158   and</li>
 159   <li>provide documentation fixes (either as patches to the code comments or
 160     as HTML diffs).</li>
 161   <li>provide new documentations pieces (translations, examples, etc ...)</li>
 162   <li>Check the TODO file and try to close one of the items</li>
 163   <li>take one of the points raised in the archive or the bug database and
 164     provide a fix. <a href="mailto:daniel@veillard.com">Get in touch with me
 165     </a>before to avoid synchronization problems and check that the suggested
 166     fix will fit in nicely :-)</li>
 167 </ol>
 168
 169 <h2><a name="Downloads">Downloads</a></h2>
 170
 171 <p>The latest versions of libxslt can be found on <a
 172 href="ftp://xmlsoft.org/">xmlsoft.org</a> (<a
 173 href="ftp://speakeasy.rpmfind.net/pub/libxml/">Seattle</a>, <a
 174 href="ftp://fr.rpmfind.net/pub/libxml/">France</a>) or on the <a
 175 href="ftp://ftp.gnome.org/pub/GNOME/MIRRORS.html">Gnome FTP server</a> either
 176 as a <a href="ftp://ftp.gnome.org/pub/GNOME/stable/sources/libxslt/">source
 177 archive</a> or <a
 178 href="ftp://ftp.gnome.org/pub/GNOME/contrib/redhat/SRPMS/">RPM packages</a>.
 179 (NOTE that you need the <a
 180 href="http://rpmfind.net/linux/RPM/libxml2.html">libxml2</a>, <a
 181 href="http://rpmfind.net/linux/RPM/libxml2-devel.html">libxml2-devel</a>, <a
 182 href="http://rpmfind.net/linux/RPM/libxslt.html">libxslt</a> and <a
 183 href="http://rpmfind.net/linux/RPM/libxslt-devel.html">libxslt-devel</a>
 184 packages installed to compile applications using libxslt.) <a
 185 href="mailto:izlatkovic@daenet.de">Igor  Zlatkovic</a> is now the maintainer
 186 of the Windows port, <a
 187 href="http://www.fh-frankfurt.de/~igor/projects/libxml/index.html">he
 188 provides binaries</a>. <a href="mailto:Gary.Pennington@sun.com">Gary
 189 Pennington</a> provides <a href="http://garypennington.net/libxml2/">Solaris
 190 binaries</a>.</p>
 191
 192 <p><a name="Contribs">Contribs:</a></p>
 193
 194 <p>I do accept external contributions, especially if compiling on another
 195 platform, get in touch with me to upload the package. I will keep them in the
 196 <a href="ftp://xmlsoft.org/contribs/">contrib directory</a></p>
 197
 198 <p>Libxslt is also available from CVS:</p>
 199 <ul>
 200   <li><p>The <a
 201     href="http://cvs.gnome.org/bonsai/rview.cgi?cvsroot=/cvs/gnome&amp;dir=libxslt">Gnome
 202     CVS base</a>. Check the <a
 203     href="http://developer.gnome.org/tools/cvs.html">Gnome CVS Tools</a>
 204     page; the CVS module is <b>libxslt</b>.</p>
 205   </li>
 206   <li><a
 207     href="ftp://xmlsoft.org/XSLT/cvs-snapshot.tar.gzftp://xmlsoft.org/XSLT/cvs-snapshot.tar.gzftp://xmlsoft.org/XSLT/cvs-snapshot.tar.gz">daily
 208     snapshots from CVS</a> are also provided</li>
 209 </ul>
 210
 211 <h2><a name="FAQ">FAQ</a></h2>
 212 <ol>
 213   <li><em>passing parameters on the xsltproc command line doesn't work</em>
 214     <p><em>xsltproc --param test alpha foo.xsl foo.xml</em></p>
 215     <p><em>the param does not get passed and ends up as ""</em></p>
 216     <p>In a nutshell do a double escaping at the shell prompt:</p>
 217     <p>xsltproc --param test "'alpha'" foo.xsl foo.xml</p>
 218     <p>i.e. the string value is surrounded by " and ' then terminated by '
 219     and ". Libxslt interpret the parameter values as XPath expressions, so
 220     the string -&gt;<code>alpha</code>&lt;- is intepreted as the node set
 221     matching this string. You really want -&gt;<code>'alpha'</code>&lt;- to
 222     be passed to the processor. And to allow this you need to escape the
 223     quotes at the shell level using -&gt;<code>"'alpha'"</code>&lt;- .</p>
 224     <p>or use</p>
 225     <p>xsltproc --stringparam test alpha foo.xsl foo.xml</p>
 226   </li>
 227 </ol>
 228
 229 <h2><a name="News">News</a></h2>
 230
 231 <h3>CVS only : check the <a
 232 href="http://cvs.gnome.org/lxr/source/libxslt/ChangeLog">Changelog</a> file
 233 for a really accurate description</h3>
 234
 235 <h3>1.0.14: Mar 18 2002</h3>
 236 <ul>
 237   <li>Improvement in the XPath engine (libxml2-2.4.18)</li>
 238   <li>Nasty bug fix related to exslt:node-set</li>
 239   <li>Fixed the python Makefiles, cleanup of doc comments, Windows
 240     portability fixes</li>
 241 </ul>
 242
 243 <h3>1.0.13: Mar 8 2002</h3>
 244 <ul>
 245   <li>a number of bug fixes including "namespace node have no parents"</li>
 246   <li>Improvement of the Python bindings</li>
 247   <li>Charles Bozeman provided fixes and regression tests for exslt date
 248     functions.</li>
 249 </ul>
 250
 251 <h3>1.0.12: Feb 11 2002</h3>
 252 <ul>
 253   <li>Fixed the makefiles especially the python module ones</li>
 254   <li>half a dozen bugs fixes including 2 old ones</li>
 255 </ul>
 256
 257 <h3>1.0.11: Feb 8 2002</h3>
 258 <ul>
 259   <li>Change of Licence to the <a
 260     href="http://www.opensource.org/licenses/mit-license.html">MIT
 261   Licence</a></li>
 262   <li>Added a beta version of the Python bindings, including support to
 263     extend the engine with functions written in Python</li>
 264   <li>A number of bug fixes</li>
 265   <li>Charlie Bozeman provided more EXSLT functions</li>
 266   <li>Portability fixes</li>
 267 </ul>
 268
 269 <h3>1.0.10: Jan 14 2002</h3>
 270 <ul>
 271   <li>Windows fixes for Win32 from Igor</li>
 272   <li>Fixed the Solaris compilation trouble (Albert)</li>
 273   <li>Documentation changes and updates: John Fleck</li>
 274   <li>Added a stringparam option to avoid escaping hell at the shell
 275   level</li>
 276   <li>A few bug fixes</li>
 277 </ul>
 278
 279 <h3>1.0.9: Dec 7 2001</h3>
 280 <ul>
 281   <li>Makefile patches from Peter Williams</li>
 282   <li>attempt to fix the compilation problem associated to prelinking</li>
 283   <li>obsoleted libxsltbreakpoint now deprecated and frozen to 1.0.8 API</li>
 284   <li>xsltproc return codes are now significant, John Fleck updated the
 285     documentation</li>
 286   <li>patch to allow as much as 40 steps in patterns (Marc Tardif), should be
 287     made dynamic really</li>
 288   <li>fixed a bug raised by Nik Clayton when using doctypes with HTML
 289   output</li>
 290   <li>patches from Keith Isdale to interface with xsltdebugger</li>
 291 </ul>
 292
 293 <h3>1.0.8: Nov 26 2001</h3>
 294 <ul>
 295   <li>fixed an annoying header problem, removed a few bugs and some code
 296     cleanup</li>
 297   <li>patches for Windows and update of Windows Makefiles by Igor</li>
 298   <li>OpenVMS port instructions from John A Fotheringham</li>
 299   <li>fixed some Makefiles annoyance and libraries prelinking
 300   informations</li>
 301 </ul>
 302
 303 <h3>1.0.7: Nov 10 2001</h3>
 304 <ul>
 305   <li>remove a compilation problem with LIBXSLT_PUBLIC</li>
 306   <li>Finishing the integration steps for Keith Isdale debugger</li>
 307   <li>fixes the handling of indent="no" on HTML output</li>
 308   <li>fixes on the configure script and RPM spec file</li>
 309 </ul>
 310
 311 <h3>1.0.6: Oct 30 2001</h3>
 312 <ul>
 313   <li>bug fixes on number formatting (Thomas), date/time functions (Bruce
 314     Miller)</li>
 315   <li>update of the Windows Makefiles (Igor)</li>
 316   <li>fixed DOCTYPE generation rules for HTML output (me)</li>
 317 </ul>
 318
 319 <h3>1.0.5: Oct 10 2001</h3>
 320 <ul>
 321   <li>some portability fixes, including Windows makefile updates from
 322   Igor</li>
 323   <li>fixed a dozen bugs on XSLT and EXSLT (me and Thomas Broyer)</li>
 324   <li>support for Saxon's evaluate and expressions extensions added (initial
 325     contribution from Darren Graves)</li>
 326   <li>better handling of XPath evaluation errors</li>
 327 </ul>
 328
 329 <h3>1.0.4: Sep 12 2001</h3>
 330 <ul>
 331   <li>Documentation updates from John fleck</li>
 332   <li>bug fixes (DocBook  FO generation should be fixed)  and portability
 333     improvements</li>
 334   <li>Thomas Broyer improved the existing EXSLT support and added String,
 335     Time and Date core functions support</li>
 336 </ul>
 337
 338 <h3>1.0.3:  Aug 23 2001</h3>
 339 <ul>
 340   <li>XML Catalog support see the doc</li>
 341   <li>New NaN/Infinity floating point code</li>
 342   <li>A few bug fixes</li>
 343 </ul>
 344
 345 <h3>1.0.2:  Aug 15 2001</h3>
 346 <ul>
 347   <li>lot of bug fixes, increased the testsuite</li>
 348   <li>a large chunk of EXSLT is implemented</li>
 349   <li>improvements on the extension framework</li>
 350   <li>documentation improvements</li>
 351   <li>Windows MSC projects files should be up-to-date</li>
 352   <li>handle attributes inherited from the DTD by default</li>
 353 </ul>
 354
 355 <h3>1.0.1:  July 24 2001</h3>
 356 <ul>
 357   <li>initial EXSLT framework</li>
 358   <li>better error reporting</li>
 359   <li>fixed the profiler on Windows</li>
 360   <li>bug fixes</li>
 361 </ul>
 362
 363 <h3>1.0.0: July 10 2001</h3>
 364 <ul>
 365   <li>a lot of cleanup, a lot of regression tests added or fixed</li>
 366   <li>added a documentation for <a href="extensions.html">writing
 367     extensions</a></li>
 368   <li>fixed some variable evaluation problems (with William)</li>
 369   <li>added profiling of stylesheet execution accessible as the xsltproc
 370     --profile option</li>
 371   <li>fixed element-available() and the implementation of the various
 372     chunking methods present, Norm Walsh provided a lot of feedback</li>
 373   <li>exclude-result-prefixes and namespaces output should now work as
 374     expected</li>
 375   <li>added support of embedded stylesheet as described in section 2.7 of the
 376     spec</li>
 377 </ul>
 378
 379 <h3>0.14.0: July 5 2001</h3>
 380 <ul>
 381   <li>lot of bug fixes, and code cleanup</li>
 382   <li>completion of the little XSLT-1.0 features left unimplemented</li>
 383   <li>Added and implemented the extension API suggested by Thomas Broyer</li>
 384   <li>the Windows MSC environment should be complete</li>
 385   <li>tested and optimized with a really large document (DocBook Definitive
 386     Guide) libxml/libxslt should really be faster on serious workloads</li>
 387 </ul>
 388
 389 <h3>0.13.0: June 26 2001</h3>
 390 <ul>
 391   <li>lots of cleanups</li>
 392   <li>fixed a C++ compilation problem</li>
 393   <li>couple of fixes to xsltSaveTo()</li>
 394   <li>try to fix Docbook-xslt-1.4 and chunking, updated the regression test
 395     with them</li>
 396   <li>fixed pattern compilation and priorities problems</li>
 397   <li>Patches for Windows and MSC project mostly contributed by Yon Derek</li>
 398   <li>update to the Tutorial by John Fleck</li>
 399   <li>William fixed bugs in templates and for-each functions</li>
 400   <li>added a new interface xsltRunStylesheet() for a more flexible output
 401     (incomplete), added -o option to xsltproc</li>
 402 </ul>
 403
 404 <h3>0.12.0: June 18 2001</h3>
 405 <ul>
 406   <li>fixed a dozen of bugs reported</li>
 407   <li>HTML generation should be quite better (requires libxml-2.3.11 upgrade
 408     too)</li>
 409   <li>William fixed some problems with document()</li>
 410   <li>Fix namespace nodes selection and copy (requires libxml-2.3.11 upgrade
 411     too)</li>
 412   <li>John Fleck added a<a href="tutorial/libxslttutorial.html">
 413   tutorial</a></li>
 414   <li>Fixes for namespace handling when evaluating variables</li>
 415   <li>XInclude global flag added to process XInclude on document() if
 416     requested</li>
 417   <li>made xsltproc --version more detailed</li>
 418 </ul>
 419
 420 <h3>0.11.0: June 1 2001</h3>
 421
 422 <p>Mostly a bug fix release.</p>
 423 <ul>
 424   <li>integration of catalogs from xsltproc</li>
 425   <li>added --version to xsltproc for bug reporting</li>
 426   <li>fixed errors when handling ID in external parsed entities</li>
 427   <li>document() should hopefully work correctly but ...</li>
 428   <li>fixed bug with PI and comments processing</li>
 429   <li>William fixed the XPath string functions when using unicode</li>
 430 </ul>
 431
 432 <h3>0.10.0: May 19 2001</h3>
 433 <ul>
 434   <li>cleanups to make stylesheet read-only (not 100% complete)</li>
 435   <li>fixed URI resolution in document()</li>
 436   <li>force all XPath expression to be compiled at stylesheet parsing time,
 437     even if unused ...</li>
 438   <li>Fixed HTML default output detection</li>
 439   <li>Fixed double attribute generation #54446</li>
 440   <li>Fixed {{ handling in attributes #54451</li>
 441   <li>More tests and speedups for DocBook document transformations</li>
 442   <li>Fixed a really bad race like bug in xsltCopyTreeList()</li>
 443   <li>added a documentation on the libxslt internals</li>
 444   <li>William Brack and Bjorn Reese improved format-number()</li>
 445   <li>Fixed multiple sort, it should really work now</li>
 446   <li>added a --docbook option for SGML DocBook input (hackish)</li>
 447   <li>a number of other bug fixes and regression test added as people were
 448     submitting them</li>
 449 </ul>
 450
 451 <h3>0.9.0: May 3 2001</h3>
 452 <ul>
 453   <li>lot of various bugfixes, extended the regression suite</li>
 454   <li>xsltproc should work with multiple params</li>
 455   <li>added an option to use xsltproc with HTML input</li>
 456   <li>improved the stylesheet compilation, processing of complex stylesheets
 457     should be faster</li>
 458   <li>using the same stylesheet for concurrent processing on multithreaded
 459     programs should work now</li>
 460   <li>fixed another batch of namespace handling problems</li>
 461   <li>Implemented multiple level of sorting</li>
 462 </ul>
 463
 464 <h3>0.8.0: Apr 22 2001</h3>
 465 <ul>
 466   <li>fixed ansidecl.h problem</li>
 467   <li>fixed unparsed-entity-uri() and generate-id()</li>
 468   <li>sort semantic fixes and priority prob from William M. Brack</li>
 469   <li>fixed namespace handling problems in XPath expression computations
 470     (requires libxml-2.3.7)</li>
 471   <li>fixes to current() and key()</li>
 472   <li>other, smaller fixes, lots of testing with N Walsh DocBook HTML
 473     stylesheets</li>
 474 </ul>
 475
 476 <h3>0.7.0: Apr 10 2001</h3>
 477 <ul>
 478   <li>cleanup using stricter compiler flags</li>
 479   <li>command line parameter passing</li>
 480   <li>fix to xsltApplyTemplates from William M. Brack</li>
 481   <li>added the XSLTMark in the regression tests as well as document()</li>
 482 </ul>
 483
 484 <h3>0.6.0: Mar 22 2001</h3>
 485 <ul>
 486   <li>another beta</li>
 487   <li>requires 2.3.5, which provide XPath expression compilation support</li>
 488   <li>document() extension should function properly</li>
 489   <li>fixed a number or reported bugs</li>
 490 </ul>
 491
 492 <h3>0.5.0: Mar 10 2001</h3>
 493 <ul>
 494   <li>fifth beta</li>
 495   <li>some optimization work, for the moment 2 XSLT transform cannot use the
 496     same stylesheet at the same time (to be fixed)</li>
 497   <li>fixed problems with handling of tree results</li>
 498   <li>fixed a reported strip-spaces problem</li>
 499   <li>added more reported/fixed bugs to the test suite</li>
 500   <li>incorporated William M. Brack fix for imports and global variables as
 501     well as patch for with-param support in apply-templates</li>
 502   <li>a bug fix on for-each</li>
 503 </ul>
 504
 505 <h3>0.4.0: Mar 1 2001</h3>
 506 <ul>
 507   <li>fourth beta test, released at the same time of libxml2-2.3.3</li>
 508   <li>bug fixes</li>
 509   <li>some optimization</li>
 510   <li>started implement extension support, not finished</li>
 511   <li>implemented but not tested multiple file output</li>
 512 </ul>
 513
 514 <h3>0.3.0: Feb 24 2001</h3>
 515 <ul>
 516   <li>third beta test, released at the same time of libxml2-2.3.2</li>
 517   <li>lot of bug fixes</li>
 518   <li>some optimization</li>
 519   <li>added DocBook XSL based testsuite</li>
 520 </ul>
 521
 522 <h3>0.2.0: Feb 15 2001</h3>
 523 <ul>
 524   <li>second beta version, released at the same time as libxml2-2.3.1</li>
 525   <li>getting close to feature completion, lot of bug fixes, some in the HTML
 526     and XPath support of libxml</li>
 527   <li>start becoming usable for real work. This version can now regenerate
 528     the XML 2e HTML from the original XML sources and the associated
 529     stylesheets (in <a
 530     href="http://www.w3.org/TR/REC-xml#b4d250b6c21">section I of the XML
 531     REC</a>)</li>
 532   <li>Still misses extension element/function/prefixes support. Support of
 533     key() and document() is not complete</li>
 534 </ul>
 535
 536 <h3>0.1.0: Feb 8 2001</h3>
 537 <ul>
 538   <li>first beta version, released at the same time as libxml2-2.3.0</li>
 539   <li>lots of bug fixes, first "testing" version, but incomplete</li>
 540 </ul>
 541
 542 <h3>0.0.1: Jan 25 2001</h3>
 543 <ul>
 544   <li>first alpha version released at the same time as libxml2-2.2.12</li>
 545   <li>Framework in place, should work on simple examples, but far from being
 546     feature complete</li>
 547 </ul>
 548
 549 <h2><a name="xsltproc">The xsltproc tool</a></h2>
 550
 551 <p>This program is the simplest way to use libxslt: from the command line. It
 552 is also used for doing the regression tests of the library.</p>
 553
 554 <p>It takes as first argument the path or URL to an XSLT stylesheet, the next
 555 arguments are filenames or URIs of the inputs to be processed. The output of
 556 the processing is redirected on the standard output. There is actually a few
 557 more options available:</p>
 558 <pre>orchis:~ -&gt; xsltproc
 559 Usage: xsltproc [options] stylesheet file [file ...]
 560    Options:
 561       --version or -V: show the version of libxml and libxslt used
 562       --verbose or -v: show logs of what's happening
 563       --output file or -o file: save to a given file
 564       --timing: display the time used
 565       --repeat: run the transformation 20 times
 566       --debug: dump the tree of the result instead
 567       --novalid: skip the Dtd loading phase
 568       --noout: do not dump the result
 569       --maxdepth val : increase the maximum depth
 570       --html: the input document is(are) an HTML file(s)
 571       --docbook: the input document is SGML docbook
 572       --param name value : pass a (parameter,value) pair
 573       --nonet refuse to fetch DTDs or entities over network
 574       --warnnet warn against fetching over the network
 575       --catalogs : use the catalogs from $SGML_CATALOG_FILES
 576       --xinclude : do XInclude processing on document intput
 577       --profile or --norman : dump profiling informations
 578 orchis:~ -&gt;</pre>
 579
 580 <h2><a name="DocBook">DocBook</a></h2>
 581
 582 <p><a href="http://www.oasis-open.org/committees/docbook/">DocBook</a> is an
 583 XML/SGML vocabulary particularly well suited to books and papers about
 584 computer hardware and software.</p>
 585
 586 <p>xsltproc and libxslt are not specifically dependant on DocBook, but since
 587 a lot of people use xsltproc and libxml2 for DocBook formatting, here are a
 588 few pointers and informations which may be helpful:</p>
 589 <ul>
 590   <li>The <a href="http://www.oasis-open.org/committees/docbook/">DocBook
 591     homepage at Oasis</a> you should find pointers there on all the lastest
 592     versions of the DTDs and XSLT stylesheets</li>
 593   <li><a href="http://www.docbook.org/">DocBook: The Definitive Guide</a> is
 594     the official reference documentation for DocBook.</li>
 595   <li>Here is a <a href="/buildDocBookCatalog">shell script</a> to generate
 596     XML Catalogs for DocBook 4.1.2 . If it can write to the /etc/xml/
 597     directory, it will set-up /etc/xml/catalog and /etc/xml/docbook based on
 598     the resources found on the system. Otherwise it will just create
 599     ~/xmlcatalog and ~/dbkxmlcatalog and doing:
 600     <p><code>export XMLCATALOG=$HOME/xmlcatalog</code></p>
 601     <p>should allow to process DocBook documentations without requiring
 602     network accesses for the DTd or stylesheets</p>
 603   </li>
 604   <li>I have uploaded <a href="ftp://xmlsoft.org/test/dbk412catalog.tar.gz">a
 605     small tarball</a> containing XML Catalogs for DocBook 4.1.2 which seems
 606     to work fine for me too</li>
 607   <li>Informations on installing a <a
 608     href="http://ourworld.compuserve.com/homepages/hoenicka_markus/cygc2057.html">Windows
 609     DocBook processing setup</a> based on Cygwin (using the binaries from the
 610     official Windows port should be possible too)</li>
 611   <li>Alexander Kirillov's page on <a
 612     href="http://www.math.sunysb.edu/~kirillov/dbxml/">Using DocBook XML
 613     4.1.2</a> (RPM packages)</li>
 614   <li>Tim Waugh's <a href="http://cyberelk.net/tim/xmlto/">xmlto front-end
 615     conversion script</a></li>
 616   <li>Linux Documentation Project <a
 617     href="http://www.linuxdoc.org/HOWTO/mini/DocBook-Install/">
 618     DocBook-Install-mini-HOWTO</a></li>
 619   <li>ScrollKeeper the open documentation cataloging project has a <a
 620     href="http://scrollkeeper.sourceforge.net/docbook.shtml">DocBook
 621     section</a></li>
 622 </ul>
 623
 624 <p>Do not use the --docbook option of xsltproc to process XML DocBook
 625 documents, this option is only intended to provide some (limited) support of
 626 the SGML version of DocBook.</p>
 627
 628 <p>Points which are not DocBook specific but still worth mentionning
 629 again:</p>
 630 <ul>
 631   <li>if you think DocBook processing time is too slow, make sure you have
 632     XML Catalogs pointing to a local installation of the DTD of DocBook.
 633     Check the <a href="http://xmlsoft.org/catalog.html">XML Catalog page</a>
 634     to understand more on this subject.</li>
 635   <li>before processing a new document, use the command
 636     <p><code>xmllint --valid --noout path_to_document</code></p>
 637     <p>to make sure that your input is valid DocBook. And fixes the errors
 638     before processing further. Note that XSLT processing may work correctly
 639     with some forms of validity errors left, but in general it can give
 640     troubles on output.</p>
 641   </li>
 642 </ul>
 643
 644 <h2><a name="API">The programming API</a></h2>
 645
 646 <p>Okay this section is clearly incomplete. But integrating libxslt into your
 647 application should be relatively easy. First check the few steps described
 648 below, then for more detailed informations, look at the<a
 649 href="html/libxslt-lib.html"> generated pages</a> for the API and the source
 650 of libxslt/xsltproc.c  and the  <a
 651 href="tutorial/libxslttutorial.html">tutorial</a>.</p>
 652
 653 <p>Basically doing an XSLT transformation can be done in a few steps:</p>
 654 <ol>
 655   <li>configure the parser for XSLT:
 656     <p>xmlSubstituteEntitiesDefault(1);</p>
 657     <p>xmlLoadExtDtdDefaultValue = 1;</p>
 658   </li>
 659   <li>parse the stylesheet with xsltParseStylesheetFile()</li>
 660   <li>parse the document with xmlParseFile()</li>
 661   <li>apply the stylesheet using xsltApplyStylesheet()</li>
 662   <li>save the result using xsltSaveResultToFile() if needed set
 663     xmlIndentTreeOutput to 1</li>
 664 </ol>
 665
 666 <p>Steps 2,3, and 5 will probably need to be changed depending on you
 667 processing needs and environment for example if reading/saving from/to
 668 memory, or if you want to apply XInclude processing to the stylesheet or
 669 input documents.</p>
 670
 671 <h2><a name="Python">Python and bindings</a></h2>
 672
 673 <p>There is a number of language bindings and wrappers available for libxml2,
 674 the list below is not exhaustive. Please contact the <a
 675 href="http://mail.gnome.org/mailman/listinfo/xml-bindings">xml-bindings@gnome.org</a>
 676 (<a href="http://mail.gnome.org/archives/xml-bindings/">archives</a>) in
 677 order to get updates to this list or to discuss the specific topic of libxml2
 678 or libxslt wrappers or bindings:</p>
 679 <ul>
 680   <li><a
 681     href="http://mail.gnome.org/archives/xml/2001-March/msg00014.html">Matt
 682     Sergeant</a> developped <a href="http://axkit.org/download/">XML::LibXML
 683     and XML::LibXSLT</a>, a perl wrapper for libxml2/libxslt as part of the
 684     <a href="http://axkit.com/">AxKit XML application server</a></li>
 685   <li><a href="mailto:dkuhlman@cutter.rexx.com">Dave Kuhlman</a> provides and
 686     earlier version of the libxml/libxslt <a
 687     href="http://www.rexx.com/~dkuhlman">wrappers for Python</a></li>
 688   <li>Petr Kozelka provides <a
 689     href="http://sourceforge.net/projects/libxml2-pas">Pascal units to glue
 690     libxml2</a> with Kylix, Delphi and other Pascal compilers</li>
 691   <li>Wai-Sun "Squidster" Chia provides <a
 692     href="http://www.rubycolor.org/arc/redist/">bindings for Ruby</a>  and
 693     libxml2 bindings are also available in Ruby through the <a
 694     href="http://libgdome-ruby.berlios.de/">libgdome-ruby</a> module
 695     maintained by Tobias Peters.</li>
 696   <li>Steve Ball and contributors maintains <a
 697     href="http://tclxml.sourceforge.net/">libxml2 and libxslt bindings for
 698     Tcl</a></li>
 699 </ul>
 700
 701 <p>The libxslt Python module depends on the <a
 702 href="http://xmlsoft.org/python.html">libxml2 Python</a> module.</p>
 703
 704 <p>The distribution includes a set of Python bindings, which are garanteed to
 705 be maintained as part of the library in the future, though the Python
 706 interface have not yet reached the maturity of the C API.</p>
 707
 708 <p>To install the Python bindings there are 2 options:</p>
 709 <ul>
 710   <li>If you use an RPM based distribution, simply install the <a
 711     href="http://rpmfind.net/linux/rpm2html/search.php?query=libxml2-python">libxml2-python
 712     RPM</a> and the <a
 713     href="http://rpmfind.net/linux/rpm2html/search.php?query=libxslt-python">libxslt-python
 714     RPM</a>.</li>
 715   <li>Otherwise use the <a href="ftp://xmlsoft.org/python/">libxml2-python
 716     module distribution</a> corresponding to your installed version of
 717     libxml2 and libxslt. Note that to install it you will need both libxml2
 718     and libxslt installed and run "python setup.py build install" in the
 719     module tree.</li>
 720 </ul>
 721
 722 <p>The distribution includes a set of examples and regression tests for the
 723 python bindings in the <code>python/tests</code> directory. Here are some
 724 excepts from those tests:</p>
 725
 726 <h3>basic.py:</h3>
 727
 728 <p>This is a basic test of XSLT interfaces: loading a stylesheet and a
 729 document, transforming the document and saving the result.</p>
 730 <pre>import libxml2
 731 import libxslt
 732
 733 styledoc = libxml2.parseFile("test.xsl")
 734 style = libxslt.parseStylesheetDoc(styledoc)
 735 doc = libxml2.parseFile("test.xml")
 736 result = style.applyStylesheet(doc, None)
 737 style.saveResultToFilename("foo", result, 0)
 738 style.freeStylesheet()
 739 doc.freeDoc()
 740 result.freeDoc()</pre>
 741
 742 <p>The Python module is called libxslt, you will also need the libxml2 module
 743 for the operations on XML trees. Let's have a look at the objects manipulated
 744 in that example and how is the processing done:</p>
 745 <ul>
 746   <li><code>styledoc</code> : is a libxml2 document tree. It is obtained by
 747     parsing the XML file "test.xsl" containing the stylesheet.</li>
 748   <li><code>style</code> : this is a precompiled stylesheet ready to be used
 749     by the following transformations (note the plural form, multiple
 750     transformations can resuse the same stylesheet).</li>
 751   <li><code>doc</code> : this is the document to apply the transformation to.
 752     In this case it is simply generated by parsing it from a file but any
 753     other processing is possible as long as one get a libxml2 Doc. Note that
 754     HTML tree are suitable for XSLT processing in libxslt. This is actually
 755     how this page is generated !</li>
 756   <li><code>result</code> : this is a document generated by applying the
 757     stylesheet to the document. Note that some of the stylesheet informations
 758     may be related to the serialization of that document and as in this
 759     example a specific saveResultToFilename() method of the stylesheet should
 760     be used to save it to a file (in that case to "foo").</li>
 761 </ul>
 762
 763 <p>Also note the need to explicitely deallocate documents with freeDoc()
 764 except for the stylesheet document which is freed when its compiled form is
 765 garbage collected.</p>
 766
 767 <h3>extfunc.py:</h3>
 768
 769 <p>This one is a far more complex test. It shows how to modify the behaviour
 770 of an XSLT transformation by passing parameters and how to extend the XSLT
 771 engine with functions defined in python:</p>
 772 <pre>import libxml2
 773 import libxslt
 774 import string
 775
 776 nodeName = None
 777 def f(ctx, str):
 778     global nodeName
 779
 780     #
 781     # Small check to verify the context is correcly accessed
 782     #
 783     try:
 784         pctxt = libxslt.xpathParserContext(_obj=ctx)
 785         ctxt = pctxt.context()
 786         tctxt = ctxt.transformContext()
 787         nodeName = tctxt.insertNode().name
 788     except:
 789         pass
 790
 791     return string.upper(str)
 792
 793 libxslt.registerExtModuleFunction("foo", "http://example.com/foo", f)</pre>
 794
 795 <p>This code defines and register an extension function. Note that the
 796 function can be bound to any name (foo) and how the binding is also
 797 associated to a namespace name "http://example.com/foo". From an XSLT point
 798 of view the function just returns an upper case version of the string passed
 799 as a parameter. But the first part of the function also read some contextual
 800 information from the current XSLT processing environement, in that case it
 801 looks for the current insertion node in the resulting output (either the
 802 resulting document or the Result Value Tree being generated), and saves it to
 803 a global variable for checking that the access actually worked.</p>
 804
 805 <p>For more informations on the xpathParserContext and transformContext
 806 objects check the <a href="internals.html">libray internals description</a>.
 807 The pctxt is actually an object from a class derived from the
 808 libxml2.xpathParserContext() with just a couple more properties including the
 809 possibility to look up the XSLT transformation context from the XPath
 810 context.</p>
 811 <pre>styledoc = libxml2.parseDoc("""
 812 &lt;xsl:stylesheet version='1.0'
 813   xmlns:xsl='http://www.w3.org/1999/XSL/Transform'
 814   xmlns:foo='http://example.com/foo'
 815   xsl:exclude-result-prefixes='foo'&gt;
 816
 817   &lt;xsl:param name='bar'&gt;failure&lt;/xsl:param&gt;
 818   &lt;xsl:template match='/'&gt;
 819     &lt;article&gt;&lt;xsl:value-of select='foo:foo($bar)'/&gt;&lt;/article&gt;
 820   &lt;/xsl:template&gt;
 821 &lt;/xsl:stylesheet&gt;
 822 """)</pre>
 823
 824 <p>Here is a simple example of how to read an XML document from a python
 825 string with libxml2. Note how this stylesheet:</p>
 826 <ul>
 827   <li>Uses a global parameter <code>bar</code></li>
 828   <li>Reference the extension function f</li>
 829   <li>how the Namespace name "http://example.com/foo" has to be bound to a
 830     prefix</li>
 831   <li>how that prefix is excluded from the output</li>
 832   <li>how the function is called from the select</li>
 833 </ul>
 834 <pre>style = libxslt.parseStylesheetDoc(styledoc)
 835 doc = libxml2.parseDoc("&lt;doc/&gt;")
 836 result = style.applyStylesheet(doc, { "bar": "'success'" })
 837 style.freeStylesheet()
 838 doc.freeDoc()</pre>
 839
 840 <p>that part is identical, to the basic example except that the
 841 transformation is passed a dictionnary of parameters. Note that the string
 842 passed "success" had to be quoted, otherwise it is interpreted as an XPath
 843 query for the childs of root named "success".</p>
 844 <pre>root = result.children
 845 if root.name != "article":
 846     print "Unexpected root node name"
 847     sys.exit(1)
 848 if root.content != "SUCCESS":
 849     print "Unexpected root node content, extension function failed"
 850     sys.exit(1)
 851 if nodeName != 'article':
 852     print "The function callback failed to access its context"
 853     sys.exit(1)
 854
 855 result.freeDoc()</pre>
 856
 857 <p>That part just verifies that the transformation worked, that the parameter
 858 got properly passed to the engine, that the function f() got called and that
 859 it properly accessed the context to find the name of the insertion node.</p>
 860
 861 <h3>pyxsltproc.py:</h3>
 862
 863 <p>this module is a bit too long to be described there but it is basically a
 864 rewrite of the xsltproc command line interface of libxslt in Python. It
 865 provides nearly all the functionalities of xsltproc and can be used as a base
 866 module to write Python customized XSLT processors. One of the thing to notice
 867 are:</p>
 868 <pre>libxml2.lineNumbersDefault(1)
 869 libxml2.substituteEntitiesDefault(1)</pre>
 870
 871 <p>those two calls in the main() function are needed to force the libxml2
 872 processor to generate DOM trees compliant with the XPath data model.</p>
 873
 874 <h2><a name="Internals">Library internals</a></h2>
 875
 876 <h3>Table  of contents</h3>
 877 <ul>
 878   <li><a href="internals.html#Introducti">Introduction</a></li>
 879   <li><a href="internals.html#Basics">Basics</a></li>
 880   <li><a href="internals.html#Keep">Keep it simple stupid</a></li>
 881   <li><a href="internals.html#libxml">The libxml nodes</a></li>
 882   <li><a href="internals.html#XSLT">The XSLT processing steps</a></li>
 883   <li><a href="internals.html#XSLT1">The XSLT stylesheet compilation</a></li>
 884   <li><a href="internals.html#XSLT2">The XSLT template compilation</a></li>
 885   <li><a href="internals.html#processing">The processing itself</a></li>
 886   <li><a href="internals.html#XPath">XPath expressions compilation</a></li>
 887   <li><a href="internals.html#XPath1">XPath interpretation</a></li>
 888   <li><a href="internals.html#Descriptio">Description of XPath
 889   Objects</a></li>
 890   <li><a href="internals.html#XPath3">XPath functions</a></li>
 891   <li><a href="internals.html#stack">The variables stack frame</a></li>
 892   <li><a href="internals.html#Extension">Extension support</a></li>
 893   <li><a href="internals.html#Futher">Further reading</a></li>
 894   <li><a href="internals.html#TODOs">TODOs</a></li>
 895 </ul>
 896
 897 <h3><a name="Introducti2">Introduction</a></h3>
 898
 899 <p>This document describes the processing of <a
 900 href="http://xmlsoft.org/XSLT/">libxslt</a>, the <a
 901 href="http://www.w3.org/TR/xslt">XSLT</a> C library developed for the <a
 902 href="http://www.gnome.org/">Gnome</a> project.</p>
 903
 904 <p>Note: this documentation is by definition incomplete and I am not good at
 905 spelling, grammar, so patches and suggestions are <a
 906 href="mailto:veillard@redhat.com">really welcome</a>.</p>
 907
 908 <h3><a name="Basics1">Basics</a></h3>
 909
 910 <p>XSLT is a transformation language. It takes an input document and a
 911 stylesheet document and generates an output document:</p>
 912
 913 <p align="center"><img src="processing.gif"
 914 alt="the XSLT processing model"></p>
 915
 916 <p>Libxslt is written in C. It relies on <a
 917 href="http://www.xmlsoft.org/">libxml</a>, the XML C library for Gnome, for
 918 the following operations:</p>
 919 <ul>
 920   <li>parsing files</li>
 921   <li>building the in-memory DOM structure associated with the documents
 922     handled</li>
 923   <li>the XPath implementation</li>
 924   <li>serializing back the result document to XML and HTML. (Text is handled
 925     directly.)</li>
 926 </ul>
 927
 928 <h3><a name="Keep1">Keep it simple stupid</a></h3>
 929
 930 <p>Libxslt is not very specialized. It is built under the assumption that all
 931 nodes from the source and output document can fit in the virtual memory of
 932 the system. There is a big trade-off there. It is fine for reasonably sized
 933 documents but may not be suitable for large sets of data. The gain is that it
 934 can be used in a relatively versatile way. The input or output may never be
 935 serialized, but the size of documents it can handle are limited by the size
 936 of the memory available.</p>
 937
 938 <p>More specialized memory handling approaches are possible, like building
 939 the input tree from a serialization progressively as it is consumed,
 940 factoring repetitive patterns, or even on-the-fly generation of the output as
 941 the input is parsed but it is possible only for a limited subset of the
 942 stylesheets. In general the implementation of libxslt follows the following
 943 pattern:</p>
 944 <ul>
 945   <li>KISS (keep it simple stupid)</li>
 946   <li>when there is a clear bottleneck optimize on top of this simple
 947     framework and refine only as much as is needed to reach the expected
 948     result</li>
 949 </ul>
 950
 951 <p>The result is not that bad, clearly one can do a better job but more
 952 specialized too. Most optimization like building the tree on-demand would
 953 need serious changes to the libxml XPath framework. An easy step would be to
 954 serialize the output directly (or call a set of SAX-like output handler to
 955 keep this a flexible interface) and hence avoid the memory consumption of the
 956 result.</p>
 957
 958 <h3><a name="libxml">The libxml nodes</a></h3>
 959
 960 <p>DOM-like trees, as used and generated by libxml and libxslt, are
 961 relatively complex. Most node types follow the given structure except a few
 962 variations depending on the node type:</p>
 963
 964 <p align="center"><img src="node.gif" alt="description of a libxml node"></p>
 965
 966 <p>Nodes carry a <strong>name</strong> and the node <strong>type</strong>
 967 indicates the kind of node it represents, the most common ones are:</p>
 968 <ul>
 969   <li>document nodes</li>
 970   <li>element nodes</li>
 971   <li>text nodes</li>
 972 </ul>
 973
 974 <p>For the XSLT processing, entity nodes should not be generated (i.e. they
 975 should be replaced by their content). Most nodes also contains the following
 976 "navigation" informations:</p>
 977 <ul>
 978   <li>the containing <strong>doc</strong>ument</li>
 979   <li>the <strong>parent</strong> node</li>
 980   <li>the first <strong>children</strong> node</li>
 981   <li>the <strong>last</strong> children node</li>
 982   <li>the <strong>prev</strong>ious sibling</li>
 983   <li>the following sibling (<strong>next</strong>)</li>
 984 </ul>
 985
 986 <p>Elements nodes carries the list of attributes in the properties, an
 987 attribute itself holds the navigation pointers and the children list (the
 988 attribute value is not represented as a simple string to allow usage of
 989 entities references).</p>
 990
 991 <p>The <strong>ns</strong> points to the namespace declaration for the
 992 namespace associated to the node, <strong>nsDef</strong> is the linked list
 993 of namespace declaration present on element nodes.</p>
 994
 995 <p>Most nodes also carry an <strong>_private</strong> pointer which can be
 996 used by the application to hold specific data on this node.</p>
 997
 998 <h3><a name="XSLT">The XSLT processing steps</a></h3>
 999
1000 <p>There are a few steps which are clearly decoupled at the interface
1001 level:</p>
1002 <ol>
1003   <li>parse the stylesheet and generate a DOM tree</li>
1004   <li>take the stylesheet tree and build a compiled version of it (the
1005     compilation phase)</li>
1006   <li>take the input and generate a DOM tree</li>
1007   <li>process the stylesheet against the input tree and generate an output
1008     tree</li>
1009   <li>serialize the output tree</li>
1010 </ol>
1011
1012 <p>A few things should be noted here:</p>
1013 <ul>
1014   <li>the steps 1/ 3/ and 5/ are optional</li>
1015   <li>the stylesheet obtained at 2/ can be reused by multiple processing 4/
1016     (and this should also work in threaded programs)</li>
1017   <li>the tree provided in 2/ should never be freed using xmlFreeDoc, but by
1018     freeing the stylesheet.</li>
1019   <li>the input tree 4/ is not modified except the _private field which may
1020     be used for labelling keys if used by the stylesheet</li>
1021 </ul>
1022
1023 <h3><a name="XSLT1">The XSLT stylesheet compilation</a></h3>
1024
1025 <p>This is the second step described. It takes a stylesheet tree, and
1026 "compiles" it. This associates to each node a structure stored in the
1027 _private field and containing information computed in the stylesheet:</p>
1028
1029 <p align="center"><img src="stylesheet.gif"
1030 alt="a compiled XSLT stylesheet"></p>
1031
1032 <p>One xsltStylesheet structure is generated per document parsed for the
1033 stylesheet. XSLT documents allow includes and imports of other documents,
1034 imports are stored in the <strong>imports</strong> list (hence keeping the
1035 tree hierarchy of includes which is very important for a proper XSLT
1036 processing model) and includes are stored in the <strong>doclist</strong>
1037 list. An imported stylesheet has a parent link to allow browsing of the
1038 tree.</p>
1039
1040 <p>The DOM tree associated to the document is stored in <strong>doc</strong>.
1041 It is preprocessed to remove ignorable empty nodes and all the nodes in the
1042 XSLT namespace are subject to precomputing. This usually consist of
1043 extracting all the context information from the context tree (attributes,
1044 namespaces, XPath expressions), and storing them in an xsltStylePreComp
1045 structure associated to the <strong>_private</strong> field of the node.</p>
1046
1047 <p>A couple of notable exceptions to this are XSLT template nodes (more on
1048 this later) and attribute value templates. If they are actually templates,
1049 the value cannot be computed at compilation time. (Some preprocessing could
1050 be done like isolation and preparsing of the XPath subexpressions but it's
1051 not done, yet.)</p>
1052
1053 <p>The xsltStylePreComp structure also allows storing of the precompiled form
1054 of an XPath expression that can be associated to an XSLT element (more on
1055 this later).</p>
1056
1057 <h3><a name="XSLT2">The XSLT template compilation</a></h3>
1058
1059 <p>A proper handling of templates lookup is one of the keys of fast XSLT
1060 processing. (Given a node in the source document this is the process of
1061 finding which templates should be applied to this node.) Libxslt follows the
1062 hint suggested in the <a href="http://www.w3.org/TR/xslt#patterns">5.2
1063 Patterns</a> section of the XSLT Recommendation, i.e. it doesn't evaluate it
1064 as an XPath expression but tokenizes it and compiles it as a set of rules to
1065 be evaluated on a candidate node. There usually is an indication of the node
1066 name in the last step of this evaluation and this is used as a key check for
1067 the match. As a result libxslt builds a relatively more complex set of
1068 structures for the templates:</p>
1069
1070 <p align="center"><img src="templates.gif"
1071 alt="The templates related structure"></p>
1072
1073 <p>Let's describe a bit more closely what is built. First the xsltStylesheet
1074 structure holds a pointer to the template hash table. All the XSLT patterns
1075 compiled in this stylesheet are indexed by the value of the the target
1076 element (or attribute, pi ...) name, so when a element or an attribute "foo"
1077 needs to be processed the lookup is done using the name as a key.</p>
1078
1079 <p>Each of the patterns is compiled into an xsltCompMatch structure. It holds
1080 the set of rules based on the tokenization of the pattern stored in reverse
1081 order (matching is easier this way). It also holds some information about the
1082 previous matches used to speed up the process when one iterates over a set of
1083 siblings. (This optimization may be defeated by trashing when running
1084 threaded computation, it's unclear that this is a big deal in practice.)
1085 Predicate expressions are not compiled at this stage, they may be at run-time
1086 if needed, but in this case they are compiled as full XPath expressions (the
1087 use of some fixed predicate can probably be optimized, they are not yet).</p>
1088
1089 <p>The xsltCompMatch are then stored in the hash table, the clash list is
1090 itself sorted by priority of the template to implement "naturally" the XSLT
1091 priority rules.</p>
1092
1093 <p>Associated to the compiled pattern is the xsltTemplate itself containing
1094 the information required for the processing of the pattern including, of
1095 course, a pointer to the list of elements used for building the pattern
1096 result.</p>
1097
1098 <p>Last but not least a number of patterns do not fit in the hash table
1099 because they are not associated to a name, this is the case for patterns
1100 applying to the root, any element, any attributes, text nodes, pi nodes, keys
1101 etc. Those are stored independently in the stylesheet structure as separate
1102 linked lists of xsltCompMatch.</p>
1103
1104 <h3><a name="processing">The processing itself</a></h3>
1105
1106 <p>The processing is defined by the XSLT specification (the basis of the
1107 algorithm is explained in <a
1108 href="http://www.w3.org/TR/xslt#section-Introduction">the Introduction</a>
1109 section). Basically it works by taking the root of the input document and
1110 applying the following algorithm:</p>
1111 <ol>
1112   <li>Finding the template applying to it. This is a lookup in the template
1113     hash table, walking the hash list until the node satisfies all the steps
1114     of the pattern, then checking the appropriate(s) global templates to see
1115     if there isn't a higher priority rule to apply</li>
1116   <li>If there is no template, apply the default rule (recurse on the
1117     children)</li>
1118   <li>else walk the content list of the selected templates, for each of them:
1119     <ul>
1120       <li>if the node is in the XSLT namespace then the node has a _private
1121         field pointing to the preprocessed values, jump to the specific
1122       code</li>
1123       <li>if the node is in an extension namespace, look up the associated
1124         behavior</li>
1125       <li>otherwise copy the node.</li>
1126     </ul>
1127     <p>The closure is usually done through the XSLT
1128     <strong>apply-templates</strong> construct recursing by applying the
1129     adequate template on the input node children or on the result of an
1130     associated XPath selection lookup.</p>
1131   </li>
1132 </ol>
1133
1134 <p>Note that large parts of the input tree may not be processed by a given
1135 stylesheet and that on the opposite some may be processed multiple times.
1136 (This often is the case when a Table of Contents is built).</p>
1137
1138 <p>The module <code>transform.c</code> is the one implementing most of this
1139 logic. <strong>xsltApplyStylesheet()</strong> is the entry point, it
1140 allocates an xsltTransformContext containing the following:</p>
1141 <ul>
1142   <li>a pointer to the stylesheet being processed</li>
1143   <li>a stack of templates</li>
1144   <li>a stack of variables and parameters</li>
1145   <li>an XPath context</li>
1146   <li>the template mode</li>
1147   <li>current document</li>
1148   <li>current input node</li>
1149   <li>current selected node list</li>
1150   <li>the current insertion points in the output document</li>
1151   <li>a couple of hash tables for extension elements and functions</li>
1152 </ul>
1153
1154 <p>Then a new document gets allocated (HTML or XML depending on the type of
1155 output), the user parameters and global variables and parameters are
1156 evaluated. Then <strong>xsltProcessOneNode()</strong> which implements the
1157 1-2-3 algorithm is called on the root element of the input. Step 1/ is
1158 implemented by calling <strong>xsltGetTemplate()</strong>, step 2/ is
1159 implemented by <strong>xsltDefaultProcessOneNode()</strong> and step 3/ is
1160 implemented by <strong>xsltApplyOneTemplate()</strong>.</p>
1161
1162 <h3><a name="XPath">XPath expression compilation</a></h3>
1163
1164 <p>The XPath support is actually implemented in the libxml module (where it
1165 is reused by the XPointer implementation). XPath is a relatively classic
1166 expression language. The only uncommon feature is that it is working on XML
1167 trees and hence has specific syntax and types to handle them.</p>
1168
1169 <p>XPath expressions are compiled using <strong>xmlXPathCompile()</strong>.
1170 It will take an expression string in input and generate a structure
1171 containing the parsed expression tree, for example the expression:</p>
1172 <pre>/doc/chapter[title='Introduction']</pre>
1173
1174 <p>will be compiled as</p>
1175 <pre>Compiled Expression : 10 elements
1176   SORT
1177     COLLECT  'child' 'name' 'node' chapter
1178       COLLECT  'child' 'name' 'node' doc
1179         ROOT
1180       PREDICATE
1181         SORT
1182           EQUAL =
1183             COLLECT  'child' 'name' 'node' title
1184               NODE
1185             ELEM Object is a string : Introduction
1186               COLLECT  'child' 'name' 'node' title
1187                 NODE</pre>
1188
1189 <p>This can be tested using the  <code>testXPath</code>  command (in the
1190 libxml codebase) using the <code>--tree</code> option.</p>
1191
1192 <p>Again, the KISS approach is used. No optimization is done. This could be
1193 an interesting thing to add. <a
1194 href="http://www-106.ibm.com/developerworks/library/x-xslt2/?dwzone=x?open&amp;l=132%2ct=gr%2c+p=saxon">Michael
1195 Kay describes</a> a lot of possible and interesting optimizations done in
1196 Saxon which would be possible at this level. I'm unsure they would provide
1197 much gain since the expressions tends to be relatively simple in general and
1198 stylesheets are still hand generated. Optimizations at the interpretation
1199 sounds likely to be more efficient.</p>
1200
1201 <h3><a name="XPath1">XPath interpretation</a></h3>
1202
1203 <p>The interpreter is implemented by <strong>xmlXPathCompiledEval()</strong>
1204 which is the front-end to <strong>xmlXPathCompOpEval()</strong> the function
1205 implementing the evaluation of the expression tree. This evaluation follows
1206 the KISS approach again. It's recursive and calls
1207 <strong>xmlXPathNodeCollectAndTest()</strong> to collect nodes set when
1208 evaluating a <code>COLLECT</code> node.</p>
1209
1210 <p>An evaluation is done within the framework of an XPath context stored in
1211 an <strong>xmlXPathContext</strong> structure, in the framework of a
1212 transformation the context is maintained within the XSLT context. Its content
1213 follows the requirements from the XPath specification:</p>
1214 <ul>
1215   <li>the current document</li>
1216   <li>the current node</li>
1217   <li>a hash table of defined variables (but not used by XSLT)</li>
1218   <li>a hash table of defined functions</li>
1219   <li>the proximity position (the place of the node in the current node
1220   list)</li>
1221   <li>the context size (the size of the current node list)</li>
1222   <li>the array of namespace declarations in scope (there also is a namespace
1223     hash table but it is not used in the XSLT transformation).</li>
1224 </ul>
1225
1226 <p>For the purpose of XSLT an <strong>extra</strong> pointer has been added
1227 allowing to retrieve the XSLT transformation context. When an XPath
1228 evaluation is about to be performed, an XPath parser context is allocated
1229 containing and XPath object stack (this is actually an XPath evaluation
1230 context, this is a remain of the time where there was no separate parsing and
1231 evaluation phase in the XPath implementation). Here is an overview of the set
1232 of contexts associated to an XPath evaluation within an XSLT
1233 transformation:</p>
1234
1235 <p align="center"><img src="contexts.gif"
1236 alt="The set of contexts associated "></p>
1237
1238 <p>Clearly this is a bit too complex and confusing and should be refactored
1239 at the next set of binary incompatible releases of libxml. For example the
1240 xmlXPathCtxt has a lot of unused parts and should probably be merged with
1241 xmlXPathParserCtxt.</p>
1242
1243 <h3><a name="Descriptio">Description of XPath Objects</a></h3>
1244
1245 <p>An XPath expression manipulates XPath objects. XPath defines the default
1246 types boolean, numbers, strings and node sets. XSLT adds the result tree
1247 fragment type which is basically an unmodifiable node set.</p>
1248
1249 <p>Implementation-wise, libxml follows again a KISS approach, the
1250 xmlXPathObject is a structure containing a type description and the various
1251 possibilities. (Using an enum could have gained some bytes.) In the case of
1252 node sets (or result tree fragments), it points to a separate xmlNodeSet
1253 object which contains the list of pointers to the document nodes:</p>
1254
1255 <p align="center"><img src="object.gif"
1256 alt="An Node set object pointing to "></p>
1257
1258 <p>The <a href="http://xmlsoft.org/html/libxml-xpath.html">XPath API</a> (and
1259 its <a href="http://xmlsoft.org/html/libxml-xpathinternals.html">'internal'
1260 part</a>) includes a number of functions to create, copy, compare, convert or
1261 free XPath objects.</p>
1262
1263 <h3><a name="XPath3">XPath functions</a></h3>
1264
1265 <p>All the XPath functions available to the interpreter are registered in the
1266 function hash table linked from the XPath context. They all share the same
1267 signature:</p>
1268 <pre>void xmlXPathFunc (xmlXPathParserContextPtr ctxt, int nargs);</pre>
1269
1270 <p>The first argument is the XPath interpretation context, holding the
1271 interpretation stack. The second argument defines the number of objects
1272 passed on the stack for the function to consume (last argument is on top of
1273 the stack).</p>
1274
1275 <p>Basically an XPath function does the following:</p>
1276 <ul>
1277   <li>check <code>nargs</code> for proper handling of errors or functions
1278     with variable numbers of parameters</li>
1279   <li>pop the parameters from the stack using <code>obj =
1280     valuePop(ctxt);</code></li>
1281   <li>do the function specific computation</li>
1282   <li>push the result parameter on the stack using <code>valuePush(ctxt,
1283     res);</code></li>
1284   <li>free up the input parameters with
1285   <code>xmlXPathFreeObject(obj);</code></li>
1286   <li>return</li>
1287 </ul>
1288
1289 <p>Sometime the work can be done directly by modifying in-situ the top object
1290 on the stack <code>ctxt-&gt;value</code>.</p>
1291
1292 <h3><a name="stack">The XSLT variables stack frame</a></h3>
1293
1294 <p>Not to be confused with XPath object stack, this stack holds the XSLT
1295 variables and parameters as they are defined through the recursive calls of
1296 call-template, apply-templates and default templates. This is used to define
1297 the scope of variables being called.</p>
1298
1299 <p>This part seems to be the most urgent attention right now, first it is
1300 done in a very inefficient way since the location of the variables and
1301 parameters within the stylesheet tree is still done at run time (it really
1302 should be done statically at compile time), and I am still unsure that my
1303 understanding of the template variables and parameter scope is actually
1304 right.</p>
1305
1306 <p>This part of the documentation is still to be written once this part of
1307 the code will be stable. <span
1308 style="background-color: #FF0000">TODO</span></p>
1309
1310 <h3><a name="Extension">Extension support</a></h3>
1311
1312 <p>There is a separate document explaining <a href="extensions.html">how the
1313 extension support works</a>.</p>
1314
1315 <h3><a name="Futher">Further reading</a></h3>
1316
1317 <p>Michael Kay wrote <a
1318 href="http://www-106.ibm.com/developerworks/library/x-xslt2/?dwzone=x?open&amp;l=132%2ct=gr%2c+p=saxon">a
1319 really interesting article on Saxon internals</a> and the work he did on
1320 performance issues. I wishes I had read it before starting libxslt design (I
1321 would probably have avoided a few mistakes and progressed faster). A lot of
1322 the ideas in his papers should be implemented or at least tried in
1323 libxslt.</p>
1324
1325 <p>The <a href="http://xmlsoft.org/">libxml documentation</a>, especially <a
1326 href="http://xmlsoft.org/xmlio.html">the I/O interfaces</a> and the <a
1327 href="http://xmlsoft.org/xmlmem.html">memory management</a>.</p>
1328
1329 <h3><a name="TODOs">TODOs</a></h3>
1330
1331 <p>redesign the XSLT stack frame handling. Far too much work is done at
1332 execution time. Similarly for the attribute value templates handling, at
1333 least the embedded subexpressions ought to be precompiled.</p>
1334
1335 <p>Allow output to be saved to a SAX like output (this notion of SAX like API
1336 for output should be added directly to libxml).</p>
1337
1338 <p>Implement and test some of the optimization explained by Michael Kay
1339 especially:</p>
1340 <ul>
1341   <li>static slot allocation on the stack frame</li>
1342   <li>specific boolean interpretation of an XPath expression</li>
1343   <li>some of the sorting optimization</li>
1344   <li>Lazy evaluation of location path. (this may require more changes but
1345     sounds really interesting. XT does this too.)</li>
1346   <li>Optimization of an expression tree (This could be done as a completely
1347     independent module.)</li>
1348 </ul>
1349
1350 <p></p>
1351
1352 <p>Error reporting, there is a lot of case where the XSLT specification
1353 specify that a given construct is an error are not checked adequately by
1354 libxslt. Basically one should do a complete pass on the XSLT spec again and
1355 add all tests to the stylesheet compilation. Using the DTD provided in the
1356 appendix and making direct checks using the libxml validation API sounds a
1357 good idea too (though one should take care of not raising errors for
1358 elements/attributes in different namespaces).</p>
1359
1360 <p>Double check all the places where the stylesheet compiled form might be
1361 modified at run time (extra removal of blanks nodes, hint on the
1362 xsltCompMatch).</p>
1363
1364 <p></p>
1365
1366 <h2><a name="Extensions">Writing extensions</a></h2>
1367
1368 <h3>Table  of content</h3>
1369 <ul>
1370   <li><a href="extensions.html#Introducti">Introduction</a></li>
1371   <li><a href="extensions.html#Basics">Basics</a></li>
1372   <li><a href="extensions.html#Keep">Extension modules</a></li>
1373   <li><a href="extensions.html#Registerin">Registering a module</a></li>
1374   <li><a href="extensions.html#module">Loading a module</a></li>
1375   <li><a href="extensions.html#Registerin1">Registering an extension
1376     function</a></li>
1377   <li><a href="extensions.html#Implementi">Implementing an extension
1378     function</a></li>
1379   <li><a href="extensions.html#Examples">Examples for extension
1380   functions</a></li>
1381   <li><a href="extensions.html#Registerin2">Registering an extension
1382     element</a></li>
1383   <li><a href="extensions.html#Implementi1">Implementing an extension
1384     element</a></li>
1385   <li><a href="extensions.html#Example">Example for extension
1386   elements</a></li>
1387   <li><a href="extensions.html#shutdown">The shutdown of a module</a></li>
1388   <li><a href="extensions.html#Future">Future work</a></li>
1389 </ul>
1390
1391 <h3><a name="Introducti1">Introduction</a></h3>
1392
1393 <p>This document describes the work needed to write extensions to the
1394 standard XSLT library for use with <a
1395 href="http://xmlsoft.org/XSLT/">libxslt</a>, the <a
1396 href="http://www.w3.org/TR/xslt">XSLT</a> C library developed for the <a
1397 href="http://www.gnome.org/">Gnome</a> project.</p>
1398
1399 <p>Before starting reading this document it is highly recommended to get
1400 familiar with <a href="internals.html">the libxslt internals</a>.</p>
1401
1402 <p>Note: this documentation is by definition incomplete and I am not good at
1403 spelling, grammar, so patches and suggestions are <a
1404 href="mailto:veillard@redhat.com">really welcome</a>.</p>
1405
1406 <h3><a name="Basics">Basics</a></h3>
1407
1408 <p>The <a href="http://www.w3.org/TR/xslt">XSLT specification</a> provides
1409 two <a href="http://www.w3.org/TR/xslt">ways to extend an XSLT engine</a>:</p>
1410 <ul>
1411   <li>providing <a href="http://www.w3.org/TR/xslt">new extension
1412     functions</a> which can be called from XPath expressions</li>
1413   <li>providing <a href="http://www.w3.org/TR/xslt">new extension
1414     elements</a> which can be inserted in stylesheets</li>
1415 </ul>
1416
1417 <p>In both cases the extensions need to be associated to a new namespace,
1418 i.e. an URI used as the name for the extension's namespace (there is no need
1419 to have a resource there for this to work).</p>
1420
1421 <p>libxslt provides a few extensions itself, either in libxslt namespace
1422 "http://xmlsoft.org/XSLT/" or in other namespace for well known extensions
1423 provided by other XSLT processors like Saxon, Xalan or XT.</p>
1424
1425 <h3><a name="Keep">Extension modules</a></h3>
1426
1427 <p>Since extensions are bound to a namespace name, usually sets of extensions
1428 coming from a given source are using the same namespace name defining in
1429 practice a group of extensions providing elements, functions or both. From
1430 libxslt point of view those are considered as an "extension module", and most
1431 of the APIs work at a module point of view.</p>
1432
1433 <p>Registration of new functions or elements are bound to the activation of
1434 the module, this is currently done by declaring the namespace as an extension
1435 by using the attribute  <code>extension-element-prefixes</code> on the
1436 <code><a href="http://www.w3.org/TR/xslt">xsl:stylesheet</a></code>
1437 element.</p>
1438
1439 <p>And extension module is defined by 3 objects:</p>
1440 <ul>
1441   <li>the namespace name associated</li>
1442   <li>an initialization function</li>
1443   <li>a shutdown function</li>
1444 </ul>
1445
1446 <h3><a name="Registerin">Registering a module</a></h3>
1447
1448 <p>Currently a libxslt module has to be compiled within the application using
1449 libxslt, there is no code to load dynamically shared libraries associated to
1450 namespace (this may be added but is likely to become a portability
1451 nightmare).</p>
1452
1453 <p>So the current way to register a module is to link the code implementing
1454 it with the application and to call a registration function:</p>
1455 <pre>int xsltRegisterExtModule(const xmlChar *URI,
1456                           xsltExtInitFunction initFunc,
1457                           xsltExtShutdownFunction shutdownFunc);</pre>
1458
1459 <p>The associated header is read by:</p>
1460 <pre>#include&lt;libxslt/extensions.h&gt;</pre>
1461
1462 <p>which also defines the type for the initialization and shutdown
1463 functions</p>
1464
1465 <h3><a name="module">Loading a module</a></h3>
1466
1467 <p>Once the module URI has been registered and if the XSLT processor detects
1468 that a given stylesheet needs the functionalities of an extended module, this
1469 one is initialized.</p>
1470
1471 <p>The xsltExtInitFunction type defines the interface for an initialization
1472 function:</p>
1473 <pre>/**
1474  * xsltExtInitFunction:
1475  * @ctxt:  an XSLT transformation context
1476  * @URI:  the namespace URI for the extension
1477  *
1478  * A function called at initialization time of an XSLT
1479  * extension module
1480  *
1481  * Returns a pointer to the module specific data for this
1482  * transformation
1483  */
1484 typedef void *(*xsltExtInitFunction)(xsltTransformContextPtr ctxt,
1485                                      const xmlChar *URI);</pre>
1486
1487 <p>There are 3 things to notice:</p>
1488 <ul>
1489   <li>the function gets passed the namespace name URI as an argument, this
1490     allow a single function to provide the initialization for multiple
1491     logical modules</li>
1492   <li>it also gets passed a transformation context, the initialization is
1493     done at run time before any processing occurs on the stylesheet but it
1494     will be invoked separately each time for each transformation</li>
1495   <li>it returns a pointer, this can be used to store module specific
1496     informations which can be retrieved later when a function or an element
1497     from the extension are used, an obvious example is a connection to a
1498     database which should be kept and reused along the transformation. NULL
1499     is a perfectly valid return, there is no way to indicate a failure at
1500     this level</li>
1501 </ul>
1502
1503 <p>What this function is expected to do is:</p>
1504 <ul>
1505   <li>prepare the context for this module (like opening the database
1506     connection)</li>
1507   <li>register the extensions specific to this module</li>
1508 </ul>
1509
1510 <h3><a name="Registerin1">Registering an extension function</a></h3>
1511
1512 <p>There is a single call to do this registration:</p>
1513 <pre>int xsltRegisterExtFunction(xsltTransformContextPtr ctxt,
1514                             const xmlChar *name,
1515                             const xmlChar *URI,
1516                             xmlXPathEvalFunc function);</pre>
1517
1518 <p>The registration is bound to a single transformation instance referred by
1519 ctxt, name is the UTF8 encoded name for the NCName of the function, and URI
1520 is the namespace name for the extension (no checking is done, a module could
1521 register functions or elements from a different namespace, but it is not
1522 recommended).</p>
1523
1524 <h3><a name="Implementi">Implementing an extension function</a></h3>
1525
1526 <p>The implementation of the function must have the signature of a libxml
1527 XPath function:</p>
1528 <pre>/**
1529  * xmlXPathEvalFunc:
1530  * @ctxt: an XPath parser context
1531  * @nargs: the number of arguments passed to the function
1532  *
1533  * an XPath evaluation function, the parameters are on the
1534  * XPath context stack
1535  */
1536
1537 typedef void (*xmlXPathEvalFunc)(xmlXPathParserContextPtr ctxt,
1538                                  int nargs);</pre>
1539
1540 <p>The context passed to an XPath function is not an XSLT context but an <a
1541 href="internals.html#XPath1">XPath context</a>. However it is possible to
1542 find one from the other:</p>
1543 <ul>
1544   <li>The function xsltXPathGetTransformContext provide this lookup facility:
1545     <pre>xsltTransformContextPtr
1546          xsltXPathGetTransformContext
1547                           (xmlXPathParserContextPtr ctxt);</pre>
1548   </li>
1549   <li>The <code>xmlXPathContextPtr</code> associated to an
1550     <code>xsltTransformContext</code> is stored in the <code>xpathCtxt</code>
1551     field.</li>
1552 </ul>
1553
1554 <p>The first thing an extension function may want to do is to check the
1555 arguments passed on the stack, the <code>nargs</code> will precise how many
1556 of them were provided on the XPath expression. The macros valuePop will
1557 extract them from the XPath stack:</p>
1558 <pre>#include &lt;libxml/xpath.h&gt;
1559 #include &lt;libxml/xpathInternals.h&gt;
1560
1561 xmlXPathObjectPtr obj = valuePop(ctxt); </pre>
1562
1563 <p>Note that <code>ctxt</code> is the XPath context not the XSLT one. It is
1564 then possible to examine the content of the value. Check <a
1565 href="internals.html#Descriptio">the description of XPath objects</a> if
1566 necessary. The following is a common sequcnce checking whether the argument
1567 passed is a string and converting it using the built-in XPath
1568 <code>string()</code> function if this is not the case:</p>
1569 <pre>if (obj-&gt;type != XPATH_STRING) {
1570     valuePush(ctxt, obj);
1571     xmlXPathStringFunction(ctxt, 1);
1572     obj = valuePop(ctxt);
1573 }</pre>
1574
1575 <p>Most common XPath functions are available directly at the C level and are
1576 exported either in <code>&lt;libxml/xpath.h&gt;</code> or in
1577 <code>&lt;libxml/xpathInternals.h&gt;</code>.</p>
1578
1579 <p>The extension function may also need to retrieve the data associated to
1580 this module instance (the database connection in the previous example) this
1581 can be done using the xsltGetExtData:</p>
1582 <pre>void * xsltGetExtData(xsltTransformContextPtr ctxt,
1583                       const xmlChar *URI);</pre>
1584
1585 <p>again the URI to be provided is the one used which was used when
1586 registering the module.</p>
1587
1588 <p>Once the function finishes, don't forget to:</p>
1589 <ul>
1590   <li>push the return value on the stack using <code>valuePush(ctxt,
1591     obj)</code></li>
1592   <li>deallocate the parameters passed to the function using
1593     <code>xmlXPathFreeObject(obj)</code></li>
1594 </ul>
1595
1596 <h3><a name="Examples">Examples for extension functions</a></h3>
1597
1598 <p>The module libxslt/functions.c containsthe sources of the XSLT built-in
1599 functions, including document(), key(), generate-id(), etc. as well as a full
1600 example module at the end. Here is the test function implementation for the
1601 libxslt:test function:</p>
1602 <pre>/**
1603  * xsltExtFunctionTest:
1604  * @ctxt:  the XPath Parser context
1605  * @nargs:  the number of arguments
1606  *
1607  * function libxslt:test() for testing the extensions support.
1608  */
1609 static void
1610 xsltExtFunctionTest(xmlXPathParserContextPtr ctxt, int nargs)
1611 {
1612     xsltTransformContextPtr tctxt;
1613     void *data;
1614
1615     tctxt = xsltXPathGetTransformContext(ctxt);
1616     if (tctxt == NULL) {
1617         xsltGenericError(xsltGenericErrorContext,
1618             "xsltExtFunctionTest: failed to get the transformation context\n");
1619         return;
1620     }
1621     data = xsltGetExtData(tctxt, (const xmlChar *) XSLT_DEFAULT_URL);
1622     if (data == NULL) {
1623         xsltGenericError(xsltGenericErrorContext,
1624             "xsltExtFunctionTest: failed to get module data\n");
1625         return;
1626     }
1627 #ifdef WITH_XSLT_DEBUG_FUNCTION
1628     xsltGenericDebug(xsltGenericDebugContext,
1629                      "libxslt:test() called with %d args\n", nargs);
1630 #endif
1631 }</pre>
1632
1633 <h3><a name="Registerin2">Registering an extension element</a></h3>
1634
1635 <p>There is a single call to do this registration:</p>
1636 <pre>int xsltRegisterExtElement(xsltTransformContextPtr ctxt,
1637                            const xmlChar *name,
1638                            const xmlChar *URI,
1639                            xsltTransformFunction function);</pre>
1640
1641 <p>It is similar to the mechanism used to register an extension function,
1642 except that the signature of an extension element implementation is
1643 different.</p>
1644
1645 <p>The registration is bound to a single transformation instance referred by
1646 ctxt, name is the UTF8 encoded name for the NCName of the element, and URI is
1647 the namespace name for the extension (no checking is done, a module could
1648 register elements for a different namespace, but it is not recommended).</p>
1649
1650 <h3><a name="Implementi1">Implementing an extension element</a></h3>
1651
1652 <p>The implementation of the element must have the signature of an XSLT
1653 transformation function:</p>
1654 <pre>/**
1655  * xsltTransformFunction:
1656  * @ctxt: the XSLT transformation context
1657  * @node: the input node
1658  * @inst: the stylesheet node
1659  * @comp: the compiled information from the stylesheet
1660  *
1661  * signature of the function associated to elements part of the
1662  * stylesheet language like xsl:if or xsl:apply-templates.
1663  */
1664 typedef void (*xsltTransformFunction)
1665                           (xsltTransformContextPtr ctxt,
1666                            xmlNodePtr node,
1667                            xmlNodePtr inst,
1668                            xsltStylePreCompPtr comp);</pre>
1669
1670 <p>The first argument is the XSLT transformation context. The second and
1671 third arguments are xmlNodePtr i.e. internal memory <a
1672 href="internals.html#libxml">representation of  XML nodes</a>. They are
1673 respectively <code>node</code> from the the input document being transformed
1674 by the stylesheet and <code>inst</code> the extension element in the
1675 stylesheet. The last argument is <code>comp</code> a pointer to a precompiled
1676 representation of <code>inst</code> but usually for extension function this
1677 value is <code>NULL</code> by default (it could be added and associated to
1678 the instruction in <code>inst-&gt;_private</code>).</p>
1679
1680 <p>The same functions are available from a function implementing an extension
1681 element as in an extension function, including
1682 <code>xsltGetExtData()</code>.</p>
1683
1684 <p>The goal of extension element being usually to enrich the generated
1685 output, it is expected that they will grow the currently generated output
1686 tree, this can be done by grabbing ctxt-&gt;insert which is the current
1687 libxml node being generated (Note this can also be the intermediate value
1688 tree being built for example to initialize a variable, the processing should
1689 be similar). The functions for libxml tree manipulation from <a
1690 href="http://xmlsoft.org/html/libxml-tree.html">&lt;libxml/tree.h&gt;</a> can
1691 be employed to extend or modify the tree, but it is required to preserve the
1692 insertion node and its ancestors since there is existing pointers to those
1693 elements still in use in the XSLT template execution stack.</p>
1694
1695 <h3><a name="Example">Example for extension elements</a></h3>
1696
1697 <p>The module libxslt/transform.c containsthe sources of the XSLT built-in
1698 elements, including xsl:element, xsl:attribute, xsl:if, etc. There is a small
1699 but full example in functions.c providing the implementation for the
1700 libxslt:test element, it will output a comment in the result tree:</p>
1701 <pre>/**
1702  * xsltExtElementTest:
1703  * @ctxt:  an XSLT processing context
1704  * @node:  The current node
1705  * @inst:  the instruction in the stylesheet
1706  * @comp:  precomputed informations
1707  *
1708  * Process a libxslt:test node
1709  */
1710 static void
1711 xsltExtElementTest(xsltTransformContextPtr ctxt, xmlNodePtr node,
1712                    xmlNodePtr inst,
1713                    xsltStylePreCompPtr comp)
1714 {
1715     xmlNodePtr comment;
1716
1717     if (ctxt == NULL) {
1718         xsltGenericError(xsltGenericErrorContext,
1719                          "xsltExtElementTest: no transformation context\n");
1720         return;
1721     }
1722     if (node == NULL) {
1723         xsltGenericError(xsltGenericErrorContext,
1724                          "xsltExtElementTest: no current node\n");
1725         return;
1726     }
1727     if (inst == NULL) {
1728         xsltGenericError(xsltGenericErrorContext,
1729                          "xsltExtElementTest: no instruction\n");
1730         return;
1731     }
1732     if (ctxt-&gt;insert == NULL) {
1733         xsltGenericError(xsltGenericErrorContext,
1734                          "xsltExtElementTest: no insertion point\n");
1735         return;
1736     }
1737     comment =
1738         xmlNewComment((const xmlChar *)
1739                       "libxslt:test element test worked");
1740     xmlAddChild(ctxt-&gt;insert, comment);
1741 }</pre>
1742
1743 <h3><a name="shutdown">The shutdown of a module</a></h3>
1744
1745 <p>When the XSLT processor ends a transformation, the shutdown function (if
1746 it exists) of all the modules initialized are called.The
1747 xsltExtShutdownFunction type defines the interface for a shutdown
1748 function:</p>
1749 <pre>/**
1750  * xsltExtShutdownFunction:
1751  * @ctxt:  an XSLT transformation context
1752  * @URI:  the namespace URI for the extension
1753  * @data:  the data associated to this module
1754  *
1755  * A function called at shutdown time of an XSLT extension module
1756  */
1757 typedef void (*xsltExtShutdownFunction) (xsltTransformContextPtr ctxt,
1758                                          const xmlChar *URI,
1759                                          void *data);</pre>
1760
1761 <p>this is really similar to a module initialization function except a third
1762 argument is passed, it's the value that was returned by the initialization
1763 function. This allow to deallocate resources from the module for example
1764 close the connection to the database to keep the same example.</p>
1765
1766 <h3><a name="Future">Future work</a></h3>
1767
1768 <p>Well some of the pieces missing:</p>
1769 <ul>
1770   <li>a way to load shared libraries to instanciate new modules</li>
1771   <li>a better detection of extension function usage and their registration
1772     without having to use the extension prefix which ought to be reserved to
1773     element extensions.</li>
1774   <li>more examples</li>
1775   <li>implementations of the <a href="http://www.exslt.org/">EXSLT</a> common
1776     extension libraries, Thomas Broyer nearly finished implementing them.</li>
1777 </ul>
1778
1779 <p></p>
1780
1781 <h2><a name="Contributi">Contributions</a></h2>
1782 <ul>
1783   <li>Bjorn Reese is the author of the number support and worked on the
1784     XSLTMark support</li>
1785   <li>William Brack was an early adopted, contributed a number of patches and
1786     spent quite some time debugging non-trivial problems in early versions of
1787     libxslt</li>
1788   <li><a href="mailto:izlatkovic@daenet.de">Igor  Zlatkovic</a> is now the
1789     maintainer of the Windows port, <a
1790     href="http://www.fh-frankfurt.de/~igor/projects/libxml/index.html">he
1791     provides binaries</a></li>
1792   <li>Thomas Broyer provided a lot of suggestions, and drafted most of the
1793     extension API</li>
1794   <li>John Fleck maintains <a href="tutorial/libxslttutorial.html">a tutorial
1795     for libxslt</a></li>
1796   <li><a
1797     href="http://mail.gnome.org/archives/xml/2001-March/msg00014.html">Matt
1798     Sergeant</a> developed <a
1799     href="http://axkit.org/download/">XML::LibXSLT</a>, a perl wrapper for
1800     libxml2/libxslt as part of the <a href="http://axkit.com/">AxKit XML
1801     application server</a></li>
1802   <li>there is a module for <a
1803     href="http://acs-misc.sourceforge.net/nsxml.html">libxml/libxslt support
1804     in OpenNSD/AOLServer</a></li>
1805   <li><a href="mailto:dkuhlman@cutter.rexx.com">Dave Kuhlman</a> provides
1806     libxml/libxslt <a href="http://www.rexx.com/~dkuhlman">wrappers for
1807     Python</a></li>
1808   <li>Steve Ball and contributors maintains <a
1809     href="http://tclxml.sourceforge.net/">libxml2 and libxslt bindings for
1810     Tcl</a></li>
1811 </ul>
1812
1813 <p>I'm still waiting for someone to contribute a simple XSLT processing
1814 module for Apache :-)</p>
1815
1816 <p></p>
1817
1818 <p><a href="mailto:daniel@veillard.com">Daniel Veillard</a></p>
1819 </body>
1820 </html>