<html>
<head>
<title>Writing extensions for XSLT C library for Gnome</title>
- <meta name="GENERATOR" content="amaya V4.1">
+ <meta name="GENERATOR" content="amaya V5.0">
<meta http-equiv="Content-Type" content="text/html">
</head>
<h2><a name="Introducti">Introduction</a></h2>
-<p>This document describes the work needed to write extensions to the standard
-XSLT library for use with <a href="http://xmlsoft.org/XSLT/">libxslt</a>, the
-<a href="http://www.w3.org/TR/xslt">XSLT</a> C library developped for the <a
+<p>This document describes the work needed to write extensions to the
+standard XSLT library for use with <a
+href="http://xmlsoft.org/XSLT/">libxslt</a>, the <a
+href="http://www.w3.org/TR/xslt">XSLT</a> C library developped for the <a
href="http://www.gnome.org/">Gnome</a> project.</p>
<p>Before starting reading this document it is highly recommended to get
<h2><a name="Basics">Basics</a></h2>
-<p>The <a href="http://www.w3.org/TR/xslt">XSLT specification</a> provides two
-<a href="http://www.w3.org/TR/xslt">ways to extend an XSLT engine</a>:</p>
+<p>The <a href="http://www.w3.org/TR/xslt">XSLT specification</a> provides
+
two <a href="http://www.w3.org/TR/xslt">ways to extend an XSLT engine</a>:</p>
<ul>
<li>providing <a href="http://www.w3.org/TR/xslt">new extension
functions</a> which can be called from XPath expressions</li>
- <li>providing <a href="http://www.w3.org/TR/xslt">new extension elements</a>
- which can be inserted in stylesheets</li>
+ <li>providing <a href="http://www.w3.org/TR/xslt">new extension
+ elements</a> which can be inserted in stylesheets</li>
</ul>
-<p>In both cases the extensions need to be associated to a new namespace, i.e.
-an URI used as the name for the extension's namespace (there is no need to
-have a resource there for this to work).</p>
+<p>In both cases the extensions need to be associated to a new namespace,
+i.e. an URI used as the name for the extension's namespace (there is no need
+to have a resource there for this to work).</p>
<p>libxslt provides a few extensions itself, either in libxslt namespace
-"http://xmlsoft.org/XSLT/" or in other namepsace for well known extensions
+"http://xmlsoft.org/XSLT/" or in other namespace for well known extensions
provided by other XSLT processors like Saxon, Xalan or XT.</p>
<h2><a name="Keep">Extension modules</a></h2>
namespace (this may be added but is likely to become a portability
nightmare).</p>
-<p>So the current way to register a module is to link the code implementing it
-with the application and to call a registration function:</p>
+<p>So the current way to register a module is to link the code implementing
+it with the application and to call a registration function:</p>
<pre>int xsltRegisterExtModule(const xmlChar *URI,
xsltExtInitFunction initFunc,
xsltExtShutdownFunction shutdownFunc);</pre>
<h2><a name="libxml">Loading a module</a></h2>
<p>Once the module URI has been registered and if the XSLT processor detects
-that a given stylesheet need the functionalities of an extended module, this
+that a given stylesheet needs the functionalities of an extended module, this
one is initialized.</p>
<p>The xsltExtInitFunction type defines the interface for an initialization
typedef void *(*xsltExtInitFunction)(xsltTransformContextPtr ctxt,
const xmlChar *URI);</pre>
-<p>There is 3 things to notice:</p>
+<p>There are 3 things to notice:</p>
<ul>
<li>the function gets passed the namespace name URI as an argument, this
- allow a single function to provide the initialization for multiple logical
- modules</li>
- <li>it also get passed a transformation context, the initialization is done
- at run time before any processing occurs on the stylesheet but it will be
- invoked separately each time for each transformation</li>
+ allow a single function to provide the initialization for multiple
+ logical modules</li>
+ <li>it also gets passed a transformation context, the initialization is
+ done at run time before any processing occurs on the stylesheet but it
+ will be invoked separately each time for each transformation</li>
<li>it returns a pointer, this can be used to store module specific
informations which can be retrieved later when a function or an element
from the extension are used, an obvious example is a connection to a
- database which should be kept and reused along the transformation. NULL is
- a perfectly valid return, there is no way to indicate a failure at this
- level</li>
+ database which should be kept and reused along the transformation. NULL
+ is a perfectly valid return, there is no way to indicate a failure at
+ this level</li>
</ul>
<p>What this function is expected to do is:</p>
<ul>
<li>prepare the context for this module (like opening the database
connection)</li>
- <li>registers the extensions specific to this module</li>
+ <li>register the extensions specific to this module</li>
</ul>
<h2><a name="Registerin1">Registering an extension function</a></h2>
xmlXPathEvalFunc function);</pre>
<p>The registration is bound to a single transformation instance referred by
-ctxt, name is the UTF8 encoded name for the NCName of the function, and URI is
-the namespace name for the extension (no checking is done, a module could
+ctxt, name is the UTF8 encoded name for the NCName of the function, and URI
+is the namespace name for the extension (no checking is done, a module could
register functions or elements from a different namespace, but it is not
recommended).</p>
int nargs);</pre>
<p>The context passed to an XPath function is not an XSLT context but an <a
-href="internals.html#XPath1">XPath context</a>. However it is possible to find
-one from the other:</p>
+href="internals.html#XPath1">XPath context</a>. However it is possible to
+find one from the other:</p>
<ul>
<li>The function xsltXPathGetTransformContext provide this lookup facility:
<pre>xsltTransformContextPtr
</ul>
<p>The first thing an extension function may want to do is to check the
-arguments passed on the stack, the <code>nargs</code> will precise how many of
-them were provided on the XPath expression. The macros valuePop will extract
-them from the XPath stack:</p>
+arguments passed on the stack, the <code>nargs</code> will precise how many
+of them were provided on the XPath expression. The macros valuePop will
+extract them from the XPath stack:</p>
<pre>#include <libxml/xpath.h>
#include <libxml/xpathInternals.h>
obj = valuePop(ctxt);
}</pre>
-<p>Most common XPath function are availbale directly at the C level and are
+<p>Most common XPath functions are available directly at the C level and are
exported either in <code><libxml/xpath.h></code> or in
<code><libxml/xpathInternals.h></code>.</p>
xmlNodePtr inst,
xsltStylePreCompPtr comp);</pre>
-<p>The first argument is the XSLT transformation context. The second and third
-arguments are xmlNodePtr i.e. internal memory <a
+<p>The first argument is the XSLT transformation context. The second and
+
third arguments are xmlNodePtr i.e. internal memory <a
href="internals.html#libxml">representation of XML nodes</a>. They are
respectively <code>node</code> from the the input document being transformed
by the stylesheet and <code>inst</code> the extension element in the
stylesheet. The last argument is <code>comp</code> a pointer to a precompiled
representation of <code>inst</code> but usually for extension function this
-value is <code>NULL</code> by default (it could be added and associated to the
-instruction in <code>inst->_private</code>).</p>
+value is <code>NULL</code> by default (it could be added and associated to
+the instruction in <code>inst->_private</code>).</p>
<p>The same functions are available from a function implementing an extension
element as in an extension function, including
<code>xsltGetExtData()</code>.</p>
-<p>The goal of extension element being usually to enrich the generated output,
-it is expected that they will grow the currently generated output tree, this
-can be done by grabbing ctxt->insert which is the current libxml node being
-generated (Note this can also be the intermediate value tree being built for
-example to initialize a variable, the processing should be similar). The
-functions for libxml tree manipulation from <a
+<p>The goal of extension element being usually to enrich the generated
+output, it is expected that they will grow the currently generated output
+tree, this can be done by grabbing ctxt->insert which is the current
+libxml node being generated (Note this can also be the intermediate value
+tree being built for example to initialize a variable, the processing should
+
be similar). The functions for libxml tree manipulation from <a
href="http://xmlsoft.org/html/libxml-tree.html"><libxml/tree.h></a> can
be employed to extend or modify the tree, but it is required to preserve the
insertion node and its ancestors since there is existing pointers to those
<h2><a name="shutdown">The shutdown of a module</a></h2>
-<p>When the XSLT processor ends a transformation, the shutdown function (if it
-exists) of all the modules initialized are called.The xsltExtShutdownFunction
-type defines the interface for a shutdown function:</p>
+<p>When the XSLT processor ends a transformation, the shutdown function (if
+it exists) of all the modules initialized are called.The
+xsltExtShutdownFunction type defines the interface for a shutdown
+function:</p>
<pre>/**
* xsltExtShutdownFunction:
* @ctxt: an XSLT transformation context
<p>this is really similar to a module initialization function except a third
argument is passed, it's the value that was returned by the initialization
-function. This allow to deallocate resources from the module for example close
-the connection to the database to keep the same example.</p>
+function. This allow to deallocate resources from the module for example
+close the connection to the database to keep the same example.</p>
<h2><a name="Future">Future work</a></h2>
element extensions.</li>
<li>more examples</li>
<li>implementations of the <a href="http://www.exslt.org/">EXSLT</a> common
- extension libraries, I probably won't have the time needed to do this this
- would be a great contribution.
+ extension libraries, I probably won't have the time needed to do this but
+ this would be a great contribution.
<p></p>
</li>
</ul>
projects / platform / upstream / libxslt.git / commitdiff