XT

Version 20020426a

See the files copying.txt and copyingjc.txt for copying permission.

XT is an implementation of XSLT 1.0. This release is a minor reworking of the code of XT Version 19991105.

This is a beta release. Any bugs are most likely the fault of Bill Lindsey, and should be reported to bill@blnz.com

Changes from the previous release

support for "keys" element and function
support for "node()" node type test in match patterns
lots more comments in the code

XT also has a new home at http://www.blnz.com/xt

As was the case with the earlier release, this version has support for the following:

an xt:node-set extension function that converts a result tree fragment to a node-set
an xt:intersection extension function that returns the intersection of two node-sets
an xt:difference extension function that returns the difference of two node-sets
a simple, purely DOM API

To use XT, you need:

the XT distribution
an XML parser in Java that supports SAX 1 API, such as XP (which is, for your convenience, included in the distribution); you should choose a SAX parser that provides Locator information, otherwise you won't get any line numbers in error messages

Put XT.jar in your CLASSPATH, together with whatever is needed for your XML parser and with xml-apis.jar if the SAX API definitions aren't included with your XML parser. Then use the command:

java -Dcom.jclark.xsl.sax.parser=your-sax-driver com.jclark.sax.Driver source stylesheet [result] [name=value][...]

The name=value arguments are optional and specify parameter names and values; they can occur in any order with respect to the other arguments. They will be ignored unless the stylesheet contains a corresponding top-level xsl:param element. The value of the parameter will be of type string.

To find a SAX parser, XT first uses the value of the system property com.jclark.xsl.sax.parser; if this is not set it uses the value of the system property org.xml.sax.parser; if this is not set it uses the class com.jclark.xml.sax.CommentDriver

XT API

Javadocs of the APIs and implementing classes can be found at: doc/api/index.html

Limitations

This release of XT inherits most of the limitations of its predecessor. The following features of the XSLT 1.0 recommendation are not yet implemented:

the element extension mechanism (the extension-element-prefixes and xsl:extension-element-prefixes attributes, the xsl:fallback element
the xsl:decimal-format element and the optional third argument on the format-number() function
the namespace axis
forwards-compatible processing
the xsl:exclude-result-prefixes attribute on literal result elements (the exclude-result-prefixes attribute on xsl:stylesheet is implemented)

There are also some known bugs, notably:

Many errors that the XSLT specification requires to be reported are silently ignored.
Comments and processing instructions occurring in the DTD are not excluded from the data model.
The document() function does not pay attention to the HTTP content-type header.
The xsl:import element does not conform to the requirement that when xsl:include is used to include a stylesheet, any xsl:import elements in the included document are moved up in the including document to after any existing xsl:import elements in the including document.
The HTML output method may get confused if you embed namespace-qualfied XML elements with the HTML.

Apart from missing features and bugs, the implementation is in need of improvement in several areas, including:

The xml output method ignores the encoding and cdata-section-elements attributes on xsl:output.
Error reporting is often not as helpful as it might be.
No error recovery is attempted after an error is reported.
The document() function does not support fragment identifiers in URIs for any media types.
No support yet for TrAX and SAX 2 APIs.
No support yet for EXSLT common extensions.

Extension Functions

A call to a function ns:foo where ns is bound to a namespace of the form http://www.jclark.com/xt/java/className is treated as a call of the static method foo of the class with fully-qualified name className. Hyphens in method names are removed with the character following the hyphen being upper-cased. Overloading based on number of parameters is supported; overloading based on parameter types is not. A non-static method is treated like a static method with the this object as an additional first argument. A constructor is treated like a static method named new. Extension functions can return objects of arbitrary types which can then be passed as arguments to other extension functions or stored in variables.

For example, the following

<xsl:stylesheet
      version="1.0"
      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
      xmlns:date="http://www.jclark.com/xt/java/java.util.Date">
      
        <xsl:template match="/">
          <html>
            <xsl:if test="function-available('date:to-string') and function-available('date:new')">
                     <p><xsl:value-of select="date:to-string(date:new())"/></p>
            </xsl:if>
          </html>
        </xsl:template>
      
      </xsl:stylesheet>

will print out the current date.

Types are mapped between XSLT and Java as follows:

XSLT type	Java type
string	`java.lang.String`
number	`double`
boolean	`boolean`
node-set	`com.jclark.xsl.om.NodeIterator`
result tree fragment	`com.jclark.xsl.sax.ResultTreeFragment`

On return from an extension function, an object of type com.jclark.xsl.om.Node is also allowed and will be treated as a node-set; also any numeric type is allowed and will be converted to a number.

The demo directory has an examples.

Multiple Output Documents

XT supports an extension element xt:document for creating output documents in addition to the main output document. The prefix xt must be bound to the namespace URI http://www.jclark.com/xt.

XT does not yet properly implement the element extension mechanism, and will recognize the namespace URI http://www.jclark.com/xt as an extension namespace regardless of whether it has been declared using an extension-element-prefixes or xsl:extension-element-prefixes. You should not rely on this and should declare the namespace http://www.jclark.com/xt as an extension namespace in accordance with the XSLT WD. For example,

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:xt="http://www.jclark.com/xt"
                extension-element-prefixes="xt">
...
</xsl:stylesheet>

The xt:document element has a required href attribute, which must be a relative URL. The value of the href attribute is interpreted as an attribute value template. The content of the xt:document element is a template for the result tree to be stored in the location specified by the href attribute. The base URL for resolving the href relative URL is the URL of the parent output document: either the URL of the main output document or the URL in which the parent xt:document element was stored. Thus, the same relative URL specifed by the href attribute can be used in the parent document to reference the document created by the xt:document element.

The xt:document element can also have all the same attributes as the xsl:output element. These attributes are merged with attributes specified on top-level xsl:output elements to determine the output method for this document. The attributes on the xt:document element take precedence over the attributes specified on top-level xsl:output elements.

For example,

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:xt="http://www.jclark.com/xt"
                extension-element-prefixes="xt">

<xsl:variable name="file">out</xsl:variable>

<xsl:template match="/">
  <xt:document method="xml" href="{$file}.xml">
     <xsl:call-template name="out"/>
  </xt:document>
  <xt:document method="html" href="{$file}.html">
     <xsl:call-template name="out"/>
  </xt:document>
  <xt:document method="text" href="{$file}.txt">
     <xsl:call-template name="out"/>
  </xt:document>
</xsl:template>

<xsl:template name="out">
  <html>
   <head><title>Title</title></head>
   <body>
   <p>Line 1<br/>Line 2</p>
   </body>
  </html>
</xsl:template>

</xsl:stylesheet>

The demo directory has a couple more examples.

Non-XML output

XT supports an additional output method of xt:nxml where the prefix xt is bound to the namespace URI http://www.jclark.com/xt. This produces non-XML output from a result document that conforms to the following DTD:

<!ELEMENT nxml (escape*, (control|data)*)>
<!ELEMENT escape (#PCDATA|char)*>
<!ATTLIST escape char CDATA #REQUIRED>
<!ELEMENT control (#PCDATA|char|data|control)*>
<!ELEMENT data (#PCDATA|data|control)*>
<!ELEMENT char EMPTY>
<!ATTLIST char number NMTOKEN #REQUIRED>

The data element contains data. Within a data element control characters get escaped. The escape element specifies how a particular control character gets escaped.

The control element contains control information. Within a control element, all characters are output directly without escaping.

The char element allows the output of a character that is not allowed by XML (such as control-L).

For example, the following stylesheet

<xsl:stylesheet
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="xt:nxml" xmlns:xt="http://www.jclark.com/xt"/>
  <xsl:template match="/">
    <nxml>
      <escape char="\">\\</escape>
      <data>&amp;&lt;&gt;\</data>
      <control>&amp;&lt;&gt;\</control>
    </nxml>
  </xsl:template>
</xsl:stylesheet>

will output

&<>\\&<>\

The encoding attribute on xsl:output applies to the xt:nxml output method.

A result method can also have the form java:class where java is bound to the namespace URI http://www.jclark.com/xt/java and class is the name of a Java class that implements the com.jclark.xsl.sax.OutputDocumentHandler interface (which extends org.xml.sax.DocumentHandler). For example,

      <xsl:output method="java:com.jclark.xsl.sax.NXMLOutputHandler"
      xmlns:java="http://www.jclark.com/xt/java"/>

is equivalent to

<xsl:output method="xt:nxml" xmlns:xt="http://www.jclark.com/xt"/>

Built-in Extension Functions

XT provides the following built-in extension functions. The namespace URI for these is http://www.jclark.com/xt.

xt:node-set: Converts a result tree fragment to the equivalent node-set. The argument must be a node-set or a result tree fragment; the result will be a node-set. See the sort-uniq example in the demo directory.
xt:intersection: Returns the intersection of two node-sets.
xt:difference: Returns the difference of two node-sets (the nodes in the first node-set that are not in the second node-set).

Reporting Bugs

Please report bugs to me, Bill Lindsey. When reporting bugs please be sure to include both a complete stylesheet and complete source document that illustrate the bug.

Bill Lindsey