NAME¶
TclXSLT - XSLT support for Tcl
SYNOPSIS¶
package require xslt
::xslt::compile doc
ssheet method ?
option value ... ?
? args ... ?
::xslt::extensionadd nsuri
tcl-namespace
::xslt::securityrequest detail
DESCRIPTION¶
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.
PACKAGES AND NAMESPACES¶
The TclXSLT package defines the
xslt package and also a Tcl namespace
using that name.
COMMANDS¶
::xslt::compile¶
The
::xslt::compile command compiles a stylesheet document. It returns a
compiled stylesheet object and also defines a Tcl command to access the
stylesheet. This Tcl command may be used to transform XML documents.
Example.PP
set source_doc [::dom::libxml2::parse $XML] set ssheet_doc
[::dom::libxml2::parse $XSLstylesheet] set ssheet [::xslt::compile
$ssheet_doc] set result [$ssheet transform $source_doc]
NB. It is advisable to use the
-baseuri option when parsing the source
and stylesheet documents to allow external resources to be resolved.
Stylesheet Command¶
The stylesheet command created by
::xslt::compile command accesses a
compiled stylesheet.
Command Methods¶
The following command methods may be used:
- cget option
-
Returns the value of an option. See below for the list of valid options.
- configure
optionvalue
-
Sets the value of an option. Available options are as follows:
- -indent
-
Specifies whether the output being produced by the stylesheet should be idented
(or "pretty-printed"). This is usually set by the styesheet's
xsl:output element. The result is a boolean value.
This is a read-only option.
- -messagecommand
script
-
This option specifies a Tcl command to be evaluated when a message is produced
by the stylesheet. Messages may be produced when the stylesheet detects an
error during processing, or when the stylesheet uses the
xsl:message
element.
It is currently not possible to distinguish between an error message and a
message produced using
xsl:message.
- -method
-
Specifies the output being produced by the stylesheet. This is usually set by
the styesheet's
xsl:output element. May have the value
xml,
html,
xhtml,
text or an empty string.
If the result is an empty string, then the output method used depends on the
type of the result document. If the result document is of type
"HTML" (ie. if [dom::node cget $resultdoc -nodeType] returns
HTMLdocument), then the
html output method should be used.
Otherwise the output method to use is
xml.
This is a read-only option.
- -profilechannel
-
Specifies the name of a channel into which profiling information is written. The
channel must have been opened for writing, or an error will be returned when
attempting a transformation. Only file channels may be used and only on Unix
systems.
- -resulturi
-
Specifies the target URI for the transformation, ie. where the result will be
written to. The result document is
not written to this URI
automatically; the application should write the result document to this URI
itself.
Some transformation constructs resolve relative URIs against this URI. For
example, a subsidiary result document produced using the
document
element.
- get what
-
Returns information from the stylesheet. The following values may be used for
what:
- parameters
-
Returns a Tcl list describing the parameters that the stylesheet accepts. Each
member of the list is itself a Tcl list with three members:
{name ns
select}.
name is the name of the parameter,
ns is the XML
namespace for the parameter and
select is the value of the
select attribute of the
param element, if any (ie. the default
value of the parameter). This implementation is not able to return a default
value set using the content of the
param element.
All stylesheet parameters are returned by this method, including those in
included/imported stylesheets. Where more than one parameter is defined with
the same name, only the parameter with the highest import precedence is
included in the returned list.
- transform source
name value
-
Performs an XSL transformation on the given source document. Stylesheet
parameters may be specified as name-value pairs. The return result is the DOM
token for the result document.
Stylesheet Parameters¶
Any number of name-value pairs may be specified as arguments to the
stylesheet transform method. 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" $ssheet transform $source_doc library
'$library' author "'Daniel Veillard'" node {/*/Element[3]}
Following is an example of how to use the
stylesheet transform
method.
Example.PP
set source_doc [::dom::libxml2::parse $XML] set ssheet_doc
[::dom::libxml2::parse $XSLstylesheet] set ssheet [::xslt::compile
$ssheet_doc] set result_doc [$ssheet transform $source_doc] set result_xml
[::dom::libxml2::serialize $result_doc -method [$ssheet cget -method]]
::xslt::extension¶
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.
::xslt::security¶
The
::xslt::security command is a "call-in" used to manage the
security of a stylesheet performing a transformation. The TclXSLT package does
not create this command. A stylesheet may need to perform an operation on an
external resource, such as reading or writing a file, or opening a network
connection. Before performing such an operation, TclXSLT will invoke the
::xslt::security command. It interprets the result of the command as a
boolean value, and only if the "true" value is returned will it
instruct the
libxslt library to continue.
TclXSLT will invoke the
::xslt::security command in a different fashion
depending on whether the current interpreter is safe or unsafe.
* If the current interpeter is unsafe (ie. it is a trusted interpreter) then the
command is invoked in the usual manner (see below for arguments). If the
command does not exist then the value "true" is the default, ie. the
operation will be permitted.
* If the current interpreter is safe then the command is invoked as a hidden
command. This is to ensure that the untrusted script cannot intercept the
invocation of the command. If the hidden command does not exist then the value
"false" is the default, ie. the operation will not be
permitted.
When the
::xslt::security command is invoked two arguments are appended:
::xslt::securityrequest detail
- request
-
This indicates the operation being requested and may have one of the following
values:
EXTENSIONS¶
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.
Implementing An Extension¶
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://tclxml.sourceforge.net/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 {content node inst avts} {
global app
puts $app([dom::libxml2::node cget $node -nodeName])
return {} }
"myfunc" is defined as an extension function and "myelement"
is defined as an extension element.
Extension Functions¶
The arguments to an extension function are passed as parameters to the Tcl
procedure. Each argument may be passed as a string or as a nodeset. Nodesets
are presented as TclDOM nodes.
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¶
When an extension element associated with a registered namespace is instantiated
all attributes of the extension element are evaluated as Attribute Value
Templates and the content of the extension element is evaluated as a sequence
constructor. The Tcl procedure associated with the extension element is then
invoked. The Tcl procedure is passed four parameters:
* The first parameter is a DOM document, an RVT, that is the result of the
sequence constructor.
* The second parameter is the current node in the source document.
* The third parameter is the extension element in the stylesheet document.
* The fourth parameter is a list. Each element in the list represents an
attribute of the extension element. The list elements are each a sublist that
has three values:
* Attribute name
* Attribute XML namespace
* Attribute value after evaluation as an AVT
Any result returned by the Tcl procedure is discarded (in the current
implementation).
If the Tcl procedure raises an error then this is passed through to the XSL
stylesheet as an XSLT exception condition.
Using An Extension¶
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://tclxml.sourceforge.net/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