Ubuntu Manpage: TclXSLT - XSLT support for Tcl

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:

* readfile

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