From 63396bd87db785408eba67d4c5ccc2212b7d6a3a Mon Sep 17 00:00:00 2001
From: "William M. Brack"
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).
libxslt provides a few extensions itself, either in libxslt namespace -"http://xmlsoft.org/XSLT/" or in other namespace for well known extensions +to have a resource there for this to work).
libxslt provides a few extensions itself, either in the libxslt namespace +"http://xmlsoft.org/XSLT/namespace" or in namespaces for other well known extensions provided by other XSLT processors like Saxon, Xalan or XT.
Since extensions are bound to a namespace name, usually sets of extensions coming from a given source are using the same namespace name defining in -practice a group of extensions providing elements, functions or both. From +practice a group of extensions providing elements, functions or both. From the libxslt point of view those are considered as an "extension module", and most of the APIs work at a module point of view.
Registration of new functions or elements are bound to the activation of
-the module, this is currently done by declaring the namespace as an extension
+the module. This is currently done by declaring the namespace as an extension
by using the attribute extension-element-prefixes
on the
xsl:stylesheet
-element.
And extension module is defined by 3 objects:
An extension module is defined by 3 objects:
Currently a libxslt module has to be compiled within the application using -libxslt, there is no code to load dynamically shared libraries associated to +libxslt. There is no code to load dynamically shared libraries associated to a namespace (this may be added but is likely to become a portability -nightmare).
So the current way to register a module is to link the code implementing +nightmare).
The current way to register a module is to link the code implementing it with the application and to call a registration function:
int xsltRegisterExtModule(const xmlChar *URI, xsltExtInitFunction initFunc, xsltExtShutdownFunction shutdownFunc);
The associated header is read by:
#include<libxslt/extensions.h>
which also defines the type for the initialization and shutdown @@ -71,17 +71,17 @@ function:
/** * transformation */ typedef void *(*xsltExtInitFunction)(xsltTransformContextPtr ctxt, - const xmlChar *URI);
There are 3 things to notice:
There are 3 things to notice:
What this function is expected to do is:
/** typedef void (*xmlXPathEvalFunc)(xmlXPathParserContextPtr ctxt, int nargs);
The context passed to an XPath function is not an XSLT context but an XPath context. However it is possible to -find one from the other:
xsltTransformContextPtr xsltXPathGetTransformContext (xmlXPathParserContextPtr ctxt);@@ -114,14 +114,14 @@ find one from the other:
xsltTransformContext
is stored in the xpathCtxt
field.The first thing an extension function may want to do is to check the
-arguments passed on the stack, the nargs
will precise how many
-of them were provided on the XPath expression. The macros valuePop will
+arguments passed on the stack, the nargs
parameter will tell how many
+of them were provided on the XPath expression. The macro valuePop will
extract them from the XPath stack:
#include <libxml/xpath.h> #include <libxml/xpathInternals.h> xmlXPathObjectPtr obj = valuePop(ctxt);
Note that ctxt
is the XPath context not the XSLT one. It is
then possible to examine the content of the value. Check the description of XPath objects if
-necessary. The following is a common sequcnce checking whether the argument
+necessary. The following is a common sequence checking whether the argument
passed is a string and converting it using the built-in XPath
string()
function if this is not the case:
if (obj->type != XPATH_STRING) { valuePush(ctxt, obj); @@ -132,12 +132,12 @@ exported either in<libxml/xpath.h>
or in<libxml/xpathInternals.h>
.The extension function may also need to retrieve the data associated to this module instance (the database connection in the previous example) this can be done using the xsltGetExtData:
void * xsltGetExtData(xsltTransformContextPtr ctxt, - const xmlChar *URI);again the URI to be provided is the one used which was used when + const xmlChar *URI);
Again the URI to be provided is the one which was used when registering the module.
Once the function finishes, don't forget to:
valuePush(ctxt,
obj)
xmlXPathFreeObject(obj)
The module libxslt/functions.c containsthe sources of the XSLT built-in +
The module libxslt/functions.c contains the sources of the XSLT built-in functions, including document(), key(), generate-id(), etc. as well as a full example module at the end. Here is the test function implementation for the libxslt:test function:
/** @@ -174,7 +174,7 @@ xsltExtFunctionTest(xmlXPathParserContextPtr ctxt, int nargs) const xmlChar *URI, xsltTransformFunction function);
It is similar to the mechanism used to register an extension function, except that the signature of an extension element implementation is -different.
The registration is bound to a single transformation instance referred by +different.
The registration is bound to a single transformation instance referred to by ctxt, name is the UTF8 encoded name for the NCName of the element, and URI is the namespace name for the extension (no checking is done, a module could register elements for a different namespace, but it is not recommended).
The implementation of the element must have the signature of an XSLT @@ -197,19 +197,19 @@ third arguments are xmlNodePtr i.e. internal memory <libxml/tree.h> 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 -elements still in use in the XSLT template execution stack.
The module libxslt/transform.c containsthe sources of the XSLT built-in +insertion node and its ancestors since there are existing pointers to those +elements still in use in the XSLT template execution stack.
The module libxslt/transform.c contains the sources of the XSLT built-in elements, including xsl:element, xsl:attribute, xsl:if, etc. There is a small but full example in functions.c providing the implementation for the libxslt:test element, it will output a comment in the result tree:
/** @@ -253,7 +253,7 @@ xsltExtElementTest(xsltTransformContextPtr ctxt, xmlNodePtr node, "libxslt:test element test worked"); xmlAddChild(ctxt->insert, comment); }
When the XSLT processor ends a transformation, the shutdown function (if -it exists) of all the modules initialized are called.The +it exists) for each of the modules initialized is called. The xsltExtShutdownFunction type defines the interface for a shutdown function:
/** * xsltExtShutdownFunction: @@ -265,11 +265,11 @@ function:/** */ typedef void (*xsltExtShutdownFunction) (xsltTransformContextPtr ctxt, const xmlChar *URI, - void *data);this is really similar to a module initialization function except a third + void *data);
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.
Well some of the pieces missing:
Well, some of the pieces missing:
libxslt provides a few extensions itself, either in libxslt namespace -"http://xmlsoft.org/XSLT/" or in other namespace for well known extensions +
libxslt provides a few extensions itself, either in the libxslt namespace +"http://xmlsoft.org/XSLT/namespace" or in namespaces for other well known extensions provided by other XSLT processors like Saxon, Xalan or XT.
Since extensions are bound to a namespace name, usually sets of extensions coming from a given source are using the same namespace name defining in -practice a group of extensions providing elements, functions or both. From +practice a group of extensions providing elements, functions or both. From the libxslt point of view those are considered as an "extension module", and most of the APIs work at a module point of view.
Registration of new functions or elements are bound to the activation of
-the module, this is currently done by declaring the namespace as an extension
+the module. This is currently done by declaring the namespace as an extension
by using the attribute extension-element-prefixes
on the
xsl:stylesheet
element.
And extension module is defined by 3 objects:
+An extension module is defined by 3 objects:
Currently a libxslt module has to be compiled within the application using -libxslt, there is no code to load dynamically shared libraries associated to +libxslt. There is no code to load dynamically shared libraries associated to a namespace (this may be added but is likely to become a portability nightmare).
-So the current way to register a module is to link the code implementing +
The current way to register a module is to link the code implementing it with the application and to call a registration function:
int xsltRegisterExtModule(const xmlChar *URI, xsltExtInitFunction initFunc, @@ -1901,17 +1901,17 @@ typedef void *(*xsltExtInitFunction)(xsltTransformContextPtr ctxt,There are 3 things to notice:
xsltTransformContextPtr xsltXPathGetTransformContext (xmlXPathParserContextPtr ctxt);@@ -1967,8 +1967,8 @@ find one from the other:
The first thing an extension function may want to do is to check the
-arguments passed on the stack, the nargs
will precise how many
-of them were provided on the XPath expression. The macros valuePop will
+arguments passed on the stack, the nargs
parameter will tell how many
+of them were provided on the XPath expression. The macro valuePop will
extract them from the XPath stack:
#include <libxml/xpath.h> #include <libxml/xpathInternals.h> @@ -1978,7 +1978,7 @@ xmlXPathObjectPtr obj = valuePop(ctxt);
Note that ctxt
is the XPath context not the XSLT one. It is
then possible to examine the content of the value. Check the description of XPath objects if
-necessary. The following is a common sequcnce checking whether the argument
+necessary. The following is a common sequence checking whether the argument
passed is a string and converting it using the built-in XPath
string()
function if this is not the case:
if (obj->type != XPATH_STRING) { @@ -1997,7 +1997,7 @@ can be done using the xsltGetExtData:void * xsltGetExtData(xsltTransformContextPtr ctxt, const xmlChar *URI);-again the URI to be provided is the one used which was used when +
Again the URI to be provided is the one which was used when registering the module.
Once the function finishes, don't forget to:
@@ -2010,7 +2010,7 @@ registering the module.Examples for extension functions
-The module libxslt/functions.c containsthe sources of the XSLT built-in +
The module libxslt/functions.c contains the sources of the XSLT built-in functions, including document(), key(), generate-id(), etc. as well as a full example module at the end. Here is the test function implementation for the libxslt:test function:
@@ -2057,7 +2057,7 @@ xsltExtFunctionTest(xmlXPathParserContextPtr ctxt, int nargs) except that the signature of an extension element implementation is different. -The registration is bound to a single transformation instance referred by +
The registration is bound to a single transformation instance referred to by ctxt, name is the UTF8 encoded name for the NCName of the element, and URI is the namespace name for the extension (no checking is done, a module could register elements for a different namespace, but it is not recommended).
@@ -2088,7 +2088,7 @@ href="internals.html#libxml">representation of XML nodes. They are respectivelynode
from the the input document being transformed by the stylesheet andinst
the extension element in the stylesheet. The last argument iscomp
a pointer to a precompiled -representation ofinst
but usually for extension function this +representation ofinst
but usually for an extension function this value isNULL
by default (it could be added and associated to the instruction ininst->_private
). @@ -2096,20 +2096,20 @@ the instruction ininst->_private
). element as in an extension function, includingxsltGetExtData()
. -The goal of extension element being usually to enrich the generated +
The goal of an 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 +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 <libxml/tree.h> 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 +insertion node and its ancestors since there are existing pointers to those elements still in use in the XSLT template execution stack.
Example for extension elements
-The module libxslt/transform.c containsthe sources of the XSLT built-in +
The module libxslt/transform.c contains the sources of the XSLT built-in elements, including xsl:element, xsl:attribute, xsl:if, etc. There is a small but full example in functions.c providing the implementation for the libxslt:test element, it will output a comment in the result tree:
@@ -2158,7 +2158,7 @@ xsltExtElementTest(xsltTransformContextPtr ctxt, xmlNodePtr node,The shutdown of a module
When the XSLT processor ends a transformation, the shutdown function (if -it exists) of all the modules initialized are called.The +it exists) for each of the modules initialized is called. The xsltExtShutdownFunction type defines the interface for a shutdown function:
/** @@ -2173,17 +2173,17 @@ typedef void (*xsltExtShutdownFunction) (xsltTransformContextPtr ctxt, const xmlChar *URI, void *data);-this is really similar to a module initialization function except a third +
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 +function. This allows the routine to deallocate resources from the module for example close the connection to the database to keep the same example.
Future work
-Well some of the pieces missing:
+Well, some of the pieces missing: