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