# XT

## Version 20051206

Copyright (c) 2002, 2003, 2004, 2005 Bill Lindsey, with substantial portions Copyright (c) 1998, 1999 James Clark

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

XT is an implementation of XSLT 1.0.

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

XT continues to be hosted at http://www.blnz.com/xt

### Changes from the previous release

- The namespace axis is now supported
- More complete support and bugfixes for Java's JAXP/TrAX APIs for pluggable transformers
- Additional EXSLT functions

XT Now supports the following EXSLT extension functions and elements:

- common:
  - node-set()
  - object-type()
  - document [element]
- Regular Expressions:
  - test()
  - replace()
  - match()
- String:
  - encode-uri()
  - decode-uri()
  - split()

More information about EXSLT can be found at http://www.exslt.org

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

- 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

XT can be embedded in Java applications and accessed through JAXP/TrAX APIs or may be run standalone from a command line.

To use XT from the command line, 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 `xt20051206.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-sax1-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 JAXP API

XT can be invoked through Java's JAXP (TrAX) APIs. The JAXP TransformerFactory class for XT is `com.jclark.xsl.trax.TransformerFactoryImpl`

## XT Native APIs

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

## Limitations

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
- 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 HTML output method may get confused if you embed namespace-qualified 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.

## 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.

## 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.
`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.