<!DOCTYPE refentry [
  <!ENTITY version "@PACKAGE_VERSION@">
]>
<refentry xmlns="http://docbook.org/ns/docbook"
	  xmlns:tcl='http://tclxml.sourceforge.net/doc'>
  <info>
    <author xmlns:xlink="http://www.w3.org/XLink" xlink:href="http://www.explain.com.au/staff/Steve.Ball/">
      <firstname>Steve</firstname>
      <surname>Ball</surname>
    </author>
    <copyright>
      <year>2008</year>
      <year>2007</year>
      <year>2005</year>
      <holder xmlns:xlink="http://www.w3.org/XLink" xlink:href="http://www.explain.com.au/">Explain</holder>
    </copyright>
    <copyright>
      <year>2004</year>
      <year>2003</year>
      <year>2002</year>
      <holder xmlns:xlink="http://www.w3.org/XLink" xlink:href="http://www.zveno.com/">Zveno Pty Ltd</holder>
      <legalnotice>
        <para>See the file <filename>LICENSE</filename> for information on usage and redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.</para>
      </legalnotice>
    </copyright>
  </info>
  <refmeta>
    <refentrytitle>TclXSLT</refentrytitle>
    <manvolnum>n</manvolnum>
  </refmeta>
  <refnamediv>
    <refname>::xslt::compile</refname>
    <refname>::xslt::extension</refname>
    <refname>::xslt::security</refname>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis xmlns="http://tclxml.sourceforge.net/doc">
      <command xmlns="http://docbook.org/ns/docbook">package require xslt</command>
    </cmdsynopsis>
    <pkgsynopsis xmlns="http://tclxml.sourceforge.net/doc">
      <package xmlns="http://docbook.org/ns/docbook">xslt</package>
      <version xmlns="http://docbook.org/ns/docbook">&version;</version>
    </pkgsynopsis>
    <namespacesynopsis xmlns="http://tclxml.sourceforge.net/doc">
      <namespace>::xslt</namespace>
    </namespacesynopsis>
    <cmdsynopsis xmlns="http://tclxml.sourceforge.net/doc">
      <command xmlns="http://docbook.org/ns/docbook">::xslt::compile</command>
      <arg xmlns="http://docbook.org/ns/docbook">
        <replaceable>doc</replaceable>
      </arg>
    </cmdsynopsis>
    <cmdsynopsis xmlns="http://tclxml.sourceforge.net/doc">
      <command xmlns="http://docbook.org/ns/docbook">
        <replaceable>ssheet</replaceable>
      </command>
      <arg xmlns="http://docbook.org/ns/docbook">
        <replaceable>method</replaceable>
      </arg>
      <group xmlns="http://docbook.org/ns/docbook" choice="opt" rep="repeat">
        <arg>option</arg>
        <arg>value</arg>
      </group>
      <group xmlns="http://docbook.org/ns/docbook" choice="opt" rep="repeat">
        <arg>args</arg>
      </group>
    </cmdsynopsis>
    <cmdsynopsis xmlns="http://tclxml.sourceforge.net/doc">
      <command xmlns="http://docbook.org/ns/docbook">::xslt::extension</command>
      <methodname xmlns="http://docbook.org/ns/docbook">add</methodname>
      <arg xmlns="http://docbook.org/ns/docbook">
        <replaceable>nsuri</replaceable>
      </arg>
      <arg xmlns="http://docbook.org/ns/docbook">
        <replaceable>tcl-namespace</replaceable>
      </arg>
    </cmdsynopsis>
    <cmdsynopsis xmlns="http://tclxml.sourceforge.net/doc">
      <command xmlns="http://docbook.org/ns/docbook">::xslt::security</command>
      <methodname xmlns="http://docbook.org/ns/docbook">
        <replaceable>request</replaceable>
      </methodname>
      <arg xmlns="http://docbook.org/ns/docbook">
        <replaceable>detail</replaceable>
      </arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <d:info xmlns:d="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:tcl="http://tclxml.sourceforge.net/doc">
      <d:title>Description</d:title>
    </d:info>
    <para>TclXSLT is a wrapper for the <d:link xmlns:d="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:tcl="http://tclxml.sourceforge.net/doc" xlink:href="http://xmlsoft.org/">Gnome libxslt library</d:link> 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.</para>
    <para>Transformation only works with documents created by TclDOM/libxml2.</para>
    <para>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.</para>
  </refsect1>
  <refsect1>
    <d:info xmlns:d="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:tcl="http://tclxml.sourceforge.net/doc">
      <d:title>Packages and Namespaces</d:title>
    </d:info>
    <para>The TclXSLT package defines the <tcl:package>xslt</tcl:package> package and also a Tcl namespace using that name.</para>
  </refsect1>
  <refsect1>
    <d:info xmlns:d="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:tcl="http://tclxml.sourceforge.net/doc">
      <d:title>Commands</d:title>
    </d:info>
    <refsect2>
      <d:info xmlns:d="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:tcl="http://tclxml.sourceforge.net/doc">
        <d:title>
          <command xmlns="http://tclxml.sourceforge.net/doc">::xslt::compile</command>
        </d:title>
      </d:info>
      <para>The <command xmlns="http://tclxml.sourceforge.net/doc">::xslt::compile</command> 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.</para>
      <example>
        <d:info xmlns:d="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:tcl="http://tclxml.sourceforge.net/doc">
          <d:title>Example</d:title>
        </d:info>
        <programlisting>
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]
</programlisting>
      </example>
      <para>NB.  It is advisable to use the <option>-baseuri</option> option when parsing the source and stylesheet documents to allow external resources to be resolved.</para>
    </refsect2>
    <refsect2>
      <d:info xmlns:d="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:tcl="http://tclxml.sourceforge.net/doc">
        <d:title>Stylesheet Command</d:title>
      </d:info>
      <para>The stylesheet command created by <command xmlns="http://tclxml.sourceforge.net/doc">::xslt::compile</command> command accesses a compiled stylesheet.</para>
      <refsect3>
        <d:info xmlns:d="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:tcl="http://tclxml.sourceforge.net/doc">
          <d:title>Command Methods</d:title>
        </d:info>
        <para>The following command methods may be used:</para>
        <variablelist>
          <varlistentry>
            <term>
              <arg>cget</arg>
              <arg>
                <replaceable>option</replaceable>
              </arg>
            </term>
            <listitem>
              <para>Returns the value of an option.  See below for the list of valid options.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <arg>configure</arg>
              <arg>
                <replaceable>option</replaceable>
                <replaceable>value</replaceable>
              </arg>
            </term>
            <listitem>
              <para>Sets the value of an option.  Available options are as follows:</para>
              <variablelist>
                <varlistentry>
                  <term>
                    <option>-indent</option>
                  </term>
                  <listitem>
                    <para>Specifies whether the output being produced by the stylesheet should be idented (or "pretty-printed").  This is usually set by the styesheet's <tag>xsl:output</tag> element.  The result is a boolean value.</para>
                    <para>This is a read-only option.</para>
                  </listitem>
                </varlistentry>
                <varlistentry>
                  <term>
                    <option>-messagecommand</option>
                    <arg>
                      <replaceable>script</replaceable>
                    </arg>
                  </term>
                  <listitem>
                    <para>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 <tag>xsl:message</tag> element.</para>
                    <para>It is currently not possible to distinguish between an error message and a message produced using <tag>xsl:message</tag>.</para>
                  </listitem>
                </varlistentry>
                <varlistentry>
                  <term>
                    <option>-method</option>
                  </term>
                  <listitem>
                    <para>Specifies the output being produced by the stylesheet.  This is usually set by the styesheet's <tag>xsl:output</tag> element.  May have the value <literal>xml</literal>, <literal>html</literal>, <literal>xhtml</literal>, <literal>text</literal> or an empty string.</para>
                    <para>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 <literal>HTMLdocument</literal>), then the <literal>html</literal> output method should be used.  Otherwise the output method to use is <literal>xml</literal>.</para>
                    <para>This is a read-only option.</para>
                  </listitem>
                </varlistentry>
                <varlistentry>
                  <term>
                    <option>-profilechannel</option>
                  </term>
                  <listitem>
                    <para>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.</para>
                  </listitem>
                </varlistentry>
                <varlistentry>
                  <term>
                    <option>-resulturi</option>
                  </term>
                  <listitem>
                    <para>Specifies the target URI for the transformation, ie. where the result will be written to.  The result document is <emphasis>not</emphasis> written to this URI automatically; the application should write the result document to this URI itself.</para>
                    <para>Some transformation constructs resolve relative URIs against this URI.  For example, a subsidiary result document produced using the <tag>document</tag> element.</para>
                  </listitem>
                </varlistentry>
              </variablelist>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <arg>get</arg>
              <arg>
                <replaceable>what</replaceable>
              </arg>
            </term>
            <listitem>
              <para>Returns information from the stylesheet.  The following values may be used for <arg><replaceable>what</replaceable></arg>:</para>
              <variablelist>
                <varlistentry>
                  <term>
                    <arg>parameters</arg>
                  </term>
                  <listitem>
                    <para>Returns a Tcl list describing the parameters that the stylesheet accepts.  Each member of the list is itself a Tcl list with three members: <literal>{name ns select}</literal>.  <literal>name</literal> is the name of the parameter, <literal>ns</literal> is the XML namespace for the parameter and <literal>select</literal> is the value of the <tag role='attribute'>select</tag> attribute of the <tag>param</tag> 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 <tag>param</tag> element.</para>
                    <para>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.</para>
                  </listitem>
                </varlistentry>
              </variablelist>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <arg>transform</arg>
              <arg>
                <replaceable>source</replaceable>
              </arg>
              <group opt="repeat">
                <arg>
                  <replaceable>name</replaceable>
                </arg>
                <arg>
                  <replaceable>value</replaceable>
                </arg>
              </group>
            </term>
            <listitem>
              <para>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.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect3>
      <refsect3>
        <d:info xmlns:d="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:tcl="http://tclxml.sourceforge.net/doc">
          <d:title>Stylesheet Parameters</d:title>
        </d:info>
        <para>Any number of name-value pairs may be specified as arguments to the <command xmlns="http://tclxml.sourceforge.net/doc"><replaceable xmlns="http://docbook.org/ns/docbook">stylesheet</replaceable> transform</command> method.  These are passed as values for parameters in the stylesheet.  <application>libxslt</application> 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</para>
        <informalexample>
          <programlisting>
set library "Gnome libxslt"
$ssheet transform $source_doc \
	library '$library' \
	author "'Daniel Veillard'" \
	node {/*/Element[3]}
</programlisting>
        </informalexample>
      </refsect3>
      <para>Following is an example of how to use the <command xmlns="http://tclxml.sourceforge.net/doc"><replaceable xmlns="http://docbook.org/ns/docbook">stylesheet</replaceable> transform</command> method.</para>
      <example>
        <d:info xmlns:d="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:tcl="http://tclxml.sourceforge.net/doc">
          <d:title>Example</d:title>
        </d:info>
        <programlisting>
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]]
</programlisting>
      </example>
    </refsect2>
    <refsect2>
      <d:info xmlns:d="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:tcl="http://tclxml.sourceforge.net/doc">
        <d:title>
          <command xmlns="http://tclxml.sourceforge.net/doc">::xslt::extension</command>
        </d:title>
      </d:info>
      <para>The <command xmlns="http://tclxml.sourceforge.net/doc">::xslt::extension</command> command is used to manage extensions of the <application>libxslt</application> library.  The <methodname>add</methodname> is used to register an extension.  The <methodname>remove</methodname> is used to unregister an extension.  See <link>EXTENSIONS</link> for more detail.</para>
    </refsect2>
    <refsect2>
      <d:info xmlns:d="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:tcl="http://tclxml.sourceforge.net/doc">
        <d:title>
          <command xmlns="http://tclxml.sourceforge.net/doc">::xslt::security</command>
        </d:title>
      </d:info>
      <para>The <command xmlns="http://tclxml.sourceforge.net/doc">::xslt::security</command> 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 <command xmlns="http://tclxml.sourceforge.net/doc">::xslt::security</command> command.  It interprets the result of the command as a boolean value, and only if the "true" value is returned will it instruct the <application>libxslt</application> library to continue.</para>
      <para>TclXSLT will invoke the <command xmlns="http://tclxml.sourceforge.net/doc">::xslt::security</command> command in a different fashion depending on whether the current interpreter is safe or unsafe.</para>
      <itemizedlist>
        <listitem>
          <para>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.</para>
        </listitem>
        <listitem>
          <para>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.</para>
        </listitem>
      </itemizedlist>
      <para>When the <command xmlns="http://tclxml.sourceforge.net/doc">::xslt::security</command> command is invoked two arguments are appended:</para>
      <cmdsynopsis xmlns="http://tclxml.sourceforge.net/doc">
        <command xmlns="http://docbook.org/ns/docbook">::xslt::security</command>
        <methodname xmlns="http://docbook.org/ns/docbook">
          <replaceable>request</replaceable>
        </methodname>
        <arg xmlns="http://docbook.org/ns/docbook">
          <replaceable>detail</replaceable>
        </arg>
      </cmdsynopsis>
      <variablelist>
        <varlistentry>
          <term>
            <methodname>
              <replaceable>request</replaceable>
            </methodname>
          </term>
          <listitem>
            <para>This indicates the operation being requested and may have one of the following values:</para>
            <itemizedlist>
              <listitem>
                <para>
                  <literal>readfile</literal>
                </para>
              </listitem>
              <listitem>
                <para>
                  <literal/>
                </para>
              </listitem>
              <listitem>
                <para>
                  <literal/>
                </para>
              </listitem>
              <listitem>
                <para>
                  <literal/>
                </para>
              </listitem>
              <listitem>
                <para>
                  <literal/>
                </para>
              </listitem>
            </itemizedlist>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect2>
  </refsect1>
  <refsect1>
    <d:info xmlns:d="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:tcl="http://tclxml.sourceforge.net/doc">
      <d:title>Extensions</d:title>
    </d:info>
    <para>The TclXSLT package allows an application to bind Tcl scripts to the extension mechanism of <application>libxslt</application>.  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.</para>
    <refsect2>
      <d:info xmlns:d="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:tcl="http://tclxml.sourceforge.net/doc">
        <d:title>Implementing An Extension</d:title>
      </d:info>
      <para>The Tcl application uses the <command xmlns="http://tclxml.sourceforge.net/doc">::xslt::extension add</command> 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,</para>
      <informalexample>
        <programlisting>
::xslt::extension add http://tclxml.sourceforge.net/Example ::example
</programlisting>
      </informalexample>
      <para>Everytime the <command xmlns="http://tclxml.sourceforge.net/doc">::xslt::transform</command> 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,</para>
      <informalexample>
        <programlisting>
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])
}
</programlisting>
      </informalexample>
      <para>"myfunc" is defined as an extension function and "myelement" is defined as an extension element.</para>
      <refsect3>
        <d:info xmlns:d="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:tcl="http://tclxml.sourceforge.net/doc">
          <d:title>Extension Functions</d:title>
        </d:info>
        <para>The arguments to an extension function are converted to a string value and then passed as parameters to the Tcl procedure.</para>
        <para>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.</para>
      </refsect3>
      <refsect3>
        <d:info xmlns:d="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:tcl="http://tclxml.sourceforge.net/doc">
          <d:title>Extension Elements</d:title>
        </d:info>
        <para>Extension elements have not been implemented in TclXSLT v&version;.</para>
      </refsect3>
    </refsect2>
    <refsect2>
      <d:info xmlns:d="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:tcl="http://tclxml.sourceforge.net/doc">
        <d:title>Using An Extension</d:title>
      </d:info>
      <para>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,</para>
      <informalexample>
        <programlisting>
&lt;xsl:stylesheet version='1.0'
	xmlns:xsl='http://www.w3.org/1999/XSL/Transform'
	xmlns:eg='http://tclxml.sourceforge.net/Example'&gt;

  &lt;xsl:template match='/'&gt;
    &lt;xsl:text&gt;Result of calling extension is "&lt;/xsl:text&gt;
    &lt;xsl:value-of select='eg:myfunc("foo")'/&gt;
    &lt;xsl:text&gt;".
&lt;/xsl:text&gt;
  &lt;/xsl:template&gt;

&lt;/xsl:stylesheet&gt;
</programlisting>
      </informalexample>
      <para>This stylesheet would result in the following Tcl script being evaluated:</para>
      <informalexample>
        <programlisting>
::example::myfunc foo
</programlisting>
      </informalexample>
    </refsect2>
  </refsect1>
</refentry>
