::xslt::cget, ::xslt::compile, ::xslt::transform, ::xslt::extension
TclXSLT is a wrapper for the Gnome libxslt library that allows an application to perform XSL transformations (XSLT). The package also provides a binding to the XSLT extension mechanism so that XSLT extension may be implemented using Tcl scripts.
Transformation only works with documents created by TclDOM/libxml2.
The TclXSLT package makes extensive use of Tcl objects. Compiled XSL stylesheets are stored as the internal representation of a Tcl object. Source and result documents are accessed via TclDOM's C interface as Tcl objects. This allows the application to cache parsed XML documents and compiled XSL stylesheets for better runtime performance.
The TclXSLT package defines the xslt package and also a Tcl namespace using that name.
The ::xslt::cget command accesses options of a compiled XSL stylesheet object.
The following options may be used:
Returns the output method for the stylesheet. Possible values are xml, html or text. The default is xml.
The ::xslt::compile command pre-compiles a stylesheet document. It returns a compiled stylesheet object that may be used in subsequent invocations of the ::xslt::transform command.
Example 1. Example
set ssheet_doc [::dom::libxml2::parse $XSLstylesheet] set ssheet [::xslt::compile $ssheet_doc] set result [::xslt::transform $ssheet $source_doc]
The ::xslt::transform command performs an XSL transformation using the Gnome libxslt XSLT engine. The result is a new TclDOM/libxml2 document, which is the result document of the transformation.
The following command options may be used:
Specifies a Tcl script to be invoked when the XSL stylesheet uses the xsl:message element. The content of the element is appended as an argment to the Tcl script.
Any number of name-value pairs may be specified as arguments to the ::xslt::transform command. These are passed as values for parameters in the stylesheet. libxslt interprets the values as XPath expressions, where the context node is the root node for the source document. To pass a value as a string it must be XPath-quoted, for example
set library "Gnome libxslt"
::xslt::transform $ssheet $source_doc \
library '$library' \
author "'Daniel Veillard'" \
node {/*/Element[3]}
Following is an example of how to use the ::xslt::transform command.
Example 2. Example
set source_doc [::dom::libxml2::parse $XML] set ssheet_doc [::dom::libxml2::parse $XSLstylesheet] set ssheet [::xslt::compile $ssheet_doc] set result_doc [::xslt::transform $ssheet $source_doc] set result_xml [::dom::libxml2::serialize $result_doc]
The ::xslt::extension command is used to manage extensions of the libxslt library. The add is used to register an extension. The remove is used to unregister an extension. See EXTENSIONS for more detail.
The TclXSLT package allows an application to bind Tcl scripts to the extension mechanism of libxslt. This means that Tcl scripts may provide the implementation of an XSLT extension element or function. The binding is achieved to associating a Tcl namespace with an XML namespace.
The Tcl application uses the ::xslt::extension add command to register an extension. An XML Namespace for the extension is specified as an argument, along with a Tcl namespace that will provide implementations of extension elements and functions. For example,
::xslt::extension add http://www.zveno.com/Example ::example
Everytime the ::xslt::transform command is executed, a newly-created XSLT engine is initialized. For each registered extension, every procedure in the associated Tcl namespace is defined in the XSLT engine as either an extension element or an extension function. The procedure is defined as an extension function if it has a variable argument list, otherwise it is defined as an extension element. The procedure name is used as the local part of the extension name. For example,
namespace eval example {
namespace export myfunc myelement
}
proc example::myfunc {name args} {
global app
return $app($name)
}
proc example::myelement {node} {
global app
return $app([dom::libxml2::node cget $node -nodeName])
}
"myfunc" is defined as an extension function and "myelement" is defined as an extension element.
The arguments to an extension function are converted to a string value and then passed as parameters to the Tcl procedure.
The return result of the Tcl procedure becomes the return value of the extension function. The type of the result is preserved where possible, otherwise it is converted to a string value.
Extension elements have not been implemented in TclXSLT v1.1.
To invoke an extension in an XSL stylesheet, use the normal XSLT extension mechanism. The XML Namespace matches the extension to the registered Tcl namespace (NB. the stylesheet author is free to choose any prefix for the extension namespace). For example,
<xsl:stylesheet version='1.0'
xmlns:xsl='http://www.w3.org/1999/XSL/Transform'
xmlns:eg='http://www.zveno.com/Example'>
<xsl:template match='/'>
<xsl:text>Result of calling extension is "</xsl:text>
<xsl:value-of select='eg:myfunc("foo")'/>
<xsl:text>".
</xsl:text>
</xsl:template>
</xsl:stylesheet>
This stylesheet would result in the following Tcl script being evaluated:
::example::myfunc foo