Saxon home page

Saxon Extensions

This page describes the extensions and implementation-defined features provided with the Saxon product.

If you want to implement your own extensions, see extensibility.html.

These extensions have been provided because there are things that are difficult to achieve, or inefficient, using standard XSLT facilities alone. As always, it is best to stick to the standard if you possibly can: and most things are possible, even if it's not obvious at first sight.

All Saxon extensions require a namespace declaration such xmlns:saxon="http://saxon.sf.net/" to appear, typically in the xsl:stylesheet element. If you use extension instructions such as saxon:doctype, it is also necessary to include the attribute extension-element-prefixes="saxon".

Before using a Saxon extension, check whether there is an equivalent EXSLT extension available. EXSLT extensions are more likely to be portable across XSLT processors.

 

Contents
Extension attributes
saxon:assignable
saxon:explain
saxon:memo-function
additional xsl:output attributes
Extension functions
saxon:dayTimeDuration-from-seconds()
saxon:distinct()
saxon:eval()
saxon:evaluate()
saxon:expression()
saxon:getPseudoAttribute()
saxon:hasSameNodes()
saxon:highest()
saxon:leading()
saxon:lineNumber()
saxon:lowest()
saxon:max()
saxon:min()
saxon:parse()
saxon:path()
saxon:serialize()
saxon:sum()
saxon:systemId()
saxon:tokenize()
saxon:typeAnnotation()
saxon:yearMonthDuration-from-months()
Extension instructions
saxon:assign
saxon:call-template
saxon:collation
saxon:doctype
saxon:entity-ref
saxon:import-query
saxon:script
saxon:while

Saxon also provides a set of extension elements providing access to SQL databases. These are described here.

EXSLT

EXSLT is an initiative to define a standardized set of extension functions and extension elements that can be used across different XSLT processors.

Saxon now supports the EXSLT modules Common, Math, Sets, DatesAndTimes, and Functions. The full list of EXSLT extension functions implemented is:

These have considerable overlap with extension function and elements that have previously been provided in the Saxon namespace. In most cases the Saxon versions of the functions remain available, for the time being, but the EXSLT versions are preferred.

There are some known restrictions:

Extension attributes

An extension attribute is an extra attribute on an XSLT-defined element. Following the rules of XSLT, such attributes must be in a non-default namespace. For Saxon extension elements, the namespace must be the Saxon namespace URI "http://saxon.sf.net/"

For example, the saxon:assignable attribute can be set as follows:


<xsl:variable name="counter" saxon:assignable="yes" 
    xmlns:saxon="http://saxon.sf.net/">

The extension attributes supplied with the Saxon product are as follows:

saxon:assignable This attribute may be set on the xsl:variable element. The permitted values are "yes" and "no". If the variable is the subject of a saxon:assign instruction, it must be set to the value "yes". Setting this value to "yes" also ensures that the variable is actually evaluated, which is useful if the select expression calls extension functions with side-effects; without this, a variable that is never reference may never be evaluated.
saxon:explain

This attribute may be set on any instruction in the stylesheet, including a literal result element. The permitted values are "yes" and "no". If the value is "yes", then at compile time Saxon outputs (to the standard error output) an analysis of all XPath expressions appearing on attributes of that instruction. The analysis includes the static type of the expression, and a representation of the expression tree that results from Saxon's parsing and static optimization phases of processing. The tree is represented by indentation. For example, writing:

<xsl:value-of select="count(*/@test)" saxon:explain="yes" xmlns:saxon="http://saxon.sf.net/"/>

produces the output:

Attribute select of element xsl:value-of at line 18:
Static type: xs:integer
Optimized expression tree:
                    function count
                      path
                        child::*
                        @550

(Here 550 is the internal code allocated to test in the name pool).

saxon:memo-function This attribute may be set on the xsl:function element. The permitted values are "yes" and "no". Specifying "yes" indicates that Saxon should remember the results of calling the function in a cache, and if the function is called again with the same arguments, the result is retrieved from the cache rather than being recalculated. Don't use this if the function has side-effects (for example, if it calls saxon:assign, or an extension function with side-effects). Don't use it if the function accesses context information such as the context node or position() or last(). And be careful if the function constructs and returns a temporary tree: the effect will be that the function returns the same tree each time, rather than a copy of the tree (this difference will only show up if you compare the identity of nodes in the two trees).

Additional attributes for xsl:output

A number of additional attributes, or attribute values, are allowed on the xsl:output element, beyond those defined in the XSLT 2.0 specification.

The method attribute

The method attribute of xsl:output can take the standard values "xml", "html", "xhtml", or "text", or a QName.

If a QName is specified, the local name may be:

The prefix of the QName must correspond to a valid namespace URI. It is recommended to use the Saxon URI "http://saxon.sf.net/", but this is not enforced.

The saxon:indent-spaces attribute

When the output is XML or HTML with indent="yes", the saxon:indent-spaces attribute may be used to control the amount of indentation. The value must be an integer.

The saxon:character-representation attribute

This attribute allows greater control over how non-ASCII characters will be represented on output.

With method="xml", two values are supported: "decimal" and "hex". These control whether numeric character references are output in decimal or hexadecimal when the character is not available in the selected encoding.

With HTML, the value may hold two strings, separated by a semicolon. The first string defines how non-ASCII characters within the character encoding will be represented, the values being "native", "entity", "decimal", or "hex". The second string defines how characters outside the encoding will be represented, the values being "entity", "decimal", or "hex". Here "native" means output the character as itself; "entity" means use a defined entity reference (such as "&eacute;") if known; "decimal" and "hex" refer to numeric character references. For example "entity;decimal" (the default) means that with encoding="iso-8859-1", characters in the range 160-255 will be represented using standard HTML entity references, while Unicode characters above 255 will be represented as decimal character references.

The saxon:byte-order-mark attribute

This attribute may take the values "yes" or "no": the default is "no". If set to "yes", a byte order mark (Unicode xFEFF) is output at the start of the output file. This option is available with all output methods and all encodings, though it is most useful when producing XML encoded in UTF-8. Under the rules of XML 1.0 Second Edition, XML parsers are required to accept a byte order mark at the start of the file; however, some parsers written before the Second Edition was published may reject it. In particular, the Crimson parser included as the default XML parser in JDK 1.4 rejects byte order marks.

The saxon:next-in-chain attribute

The saxon:next-in-chain attribute is used to direct the output to another stylesheet. The value is the URL of a stylesheet that should be used to process the output stream. In this case the output stream must always be pure XML, and attributes that control the format of the output (e.g. method, cdata-section-elements, etc) will have no effect. The output of the second stylesheet will be directed to the destination that would have been used for the first stylesheet if no saxon:next-in-chain attribute were not present.

The saxon:require-well-formed attribute

The attribute saxon:require-well-formed is available, with values "yes" or "no". The default is "no". If the value is set to "yes", and a user-written ContentHandler is supplied to receive the results of the transformation, then Saxon will report an error rather than sending a non-well-formed stream of SAX events to the ContentHandler. This attribute is useful when the output of the stylesheet is sent to a component (for example an XSL-FO rendering engine) that is not designed to accept non-well-formed XML result trees.

User defined attributes

Any number of user-defined attributes may be defined on xsl:output. These attributes must have names in a non-null namespace, which must not be either the XSLT or the Saxon namespace. These attributes are interpreted as attribute value templates. The value of the attribute is inserted into the Properties object made available to the Emitter handling the output; they will be ignored by the standard output methods, but can supply arbitrary information to a user-defined output method. The name of the property will be the expanded name of the attribute in JAXP format, for example "{http://my-namespace/uri}local-name", and the value will be the value as given, after evaluation as an attribute value template.


Extension functions

A Saxon extension function is invoked using a name such as saxon:localname().

The saxon prefix (or whatever prefix you choose to use) must be associated with the Saxon namespace URI http://saxon.sf.net/.

For example, to invoke the saxon:evaluate() function, write:

<xsl:variable name="expression"
      select="concat('child::', $param, '[', $index, ']')"/>
..
<xsl:copy-of select="saxon:evaluate($expression)"
     xmlns:saxon="http://saxon.sf.net/"/>

The extension functions supplied with the Saxon product are as follows:

dayTimeDuration-from-seconds(number)

This returns an instance of xdt:dayTimeDuration corresponding to the given number of seconds.

distinct(node-set-1, [stored-expression])

This returns a node-set obtained by eliminating nodes in node-set-1 that have duplicate values for the supplied stored expression, evaluated as a string. A stored expression may be obtained as the result of calling the saxon:expression() function. If no stored expression is supplied, the default is expression('.'), that is, the string-value of the node. If several nodes produce the same string value, the one that is first in document order will be retained.

The stored expression is evaluated for each node in node-set-1 in turn, with that node as the context node, with the context position equal to the position of that node in node-set-1, and with the context size equal to the size of node-set-1.

Example: <xsl:for-each select="saxon:distinct(surname, saxon:expression('substring(.,1,1)')"> will process the first surname starting with each letter of the alphabet in turn.

Note: for the single-argument version, the EXSLT distinct() function should be used in preference, for portability reasons.

eval(stored-expression)

This returns the result of evaluating the supplied stored expression. A stored expression may be obtained as the result of calling the saxon:expression() function.

The stored expression is evaluated in the current context, that is, the context node is the current node, and the context position and context size are the same as the result of calling position() or last() respectively.

The second and subsequent arguments to saxon:eval supply values for the variables $p1, $p2, etc within the stored expression. For details see saxon:expression.

evaluate(string)

The supplied string must contain an XPath expression. The result of the function is the result of evaluating the XPath expression. This is useful where an expression needs to be constructed at run-time or passed to the stylesheet as a parameter, for example where the sort key is determined dynamically.

The function saxon:evaluate(string) is shorthand for saxon:eval(saxon:expression(string)). For the rules governing what may and may not appear in the expression, see saxon:expression. The expression may contain references to variables $p1, $p2, etc., and the values of these variables may be supplied in the second, third, and subsequent arguments to the saxon:evaluate() call.

expression(string)

The supplied string must contain an XPath expression. The result of the function is a stored expression, which may be supplied as an argument to other extension functions such as saxon:eval(), saxon:sum() and saxon:distinct(). The result of the expression will usually depend on the current node. The context for the expression includes the namespaces in scope at this point in the stylesheet. The expression may contain references to the nine variables $p1, $p2, ... $p9 only. It may contain calls on Java extension functions, including Saxon and EXSLT-defined functions (other than those which are restricted to use within stylesheets, for example the saxon:evaluate() function itself). But it does not allow access to stylesheet variables, stylesheet functions, or functions defined in the XSLT specification such as key() or format-number(). If the expression contains namespace prefixes, these are interpreted in terms of the namespace declarations in scope at the point where the saxon:expression() function is called, not those in scope where the stored expression is evaluated.

The stored expression (if it is to be evaluated using saxon:eval()) may contain references to variables named $p1, $p2, ... $p9. The values of these variables can be supplied when the expression is evaluated using saxon:eval. The second argument of saxon:eval supplies the value of $p1, the third argument supplies the value of $p2, and so on.

For example, following <xsl:variable name="add" select="saxon:expression('$p1 + $p2')"/>, the instruction <xsl:value-of select="saxon:eval($add, 6, 7)"/> will output 13.

get-pseudo-attribute(string) This function parses the contents of a processing instruction whose content follows the conventional attribute="value" structure (as defined for the <?xsl-stylesheet?> processing instruction). The context node should be a processing instruction; the function returns the value of the pseudo-attribute named in the first argument if it is present, or an empty string otherwise.
has-same-nodes(node-set-1, node-set-2) This returns a boolean that is true if and only if node-set-1 and node-set-2 contain the same set of nodes. Note this is quite different from the "=" operator, which tests whether there is a pair of nodes with the same string-value.
highest(node-set-1 [, stored-expression])

This returns (as a node-set) the node from node-set-1 that has the highest value of the supplied stored expression, evaluated as a number. If the stored expression is omitted, the expression "number(.)" is evaluated: that is, the string value of the node, converted to a number. A stored expression may be obtained as the result of calling the saxon:expression() function.

The stored expression is evaluated for each node in node-set-1 in turn, with that node as the context node, with the context position equal to the position of that node in node-set-1, and with the context size equal to the size of node-set-1. Any NaN values are ignored. If the node-set is empty, the result is an empty node-set. If several nodes have the highest value, the result node-set contains the one that is first in document order. This differs from the EXSLT highest() function, which returns all the nodes that have the maximum value.

Example: saxon:highest(sale, saxon:expression('@price * @qty')) will evaluate price times quantity for each child <sale> element, and return the node for which this has the highest value.

leading(node-set-1, stored-expression)

This returns a node-set containing all those nodes from node-set-1 up to and excluding the first one (in document order) for which the stored-expression evaluates to false. A stored expression may be obtained as the result of calling the saxon:expression() function.

The stored expression is evaluated for each node in node-set-1 in turn, with that node as the context node, with the context position equal to the position of that node in node-set-1 (taken in document order), and with the context size equal to the size of node-set-1.

Example: saxon:leading(following-sibling::*, saxon:expression('self::para')) will return the <para> elements following the current node, stopping at the first element that is not a </;para>

Note: this function is quite different from the EXSLT leading() function, though both fulfil a similar purpose.

line-number() This returns the line number of the context node in the source document within the entity that contains it. There are no arguments. If line numbers are not maintained for the current document, the function returns -1. (To ensure that line numbers are maintained, use the -l option on the command line)
lowest(node-set-1 [, stored-expression])

This returns (as a node-set) the node from node-set-1 that has the lowest value of the supplied stored expression, evaluated as a number. If the stored expression is omitted, the expression "number(.)" is evaluated: that is, the string value of the node, converted to a number. A stored expression may be obtained as the result of calling the saxon:expression() function.

The stored expression is evaluated for each node in node-set-1 in turn, with that node as the context node, with the context position equal to the position of that node in node-set-1, and with the context size equal to the size of node-set-1. Any NaN values are ignored. If the node-set is empty, the result is an empty node-set. If several nodes have the lowest value, the result node-set contains the one that is first in document order. This differs from the EXSLT lowest() function, which returns all the nodes that have the minimum value.

Example: saxon:lowest(sale, saxon:expression('@price * @qty')) will evaluate price times quantity for each child <sale> element, and return the node for which this has the lowest value.

max(node-set-1 , stored-expression)

This returns the maximimum value of a numeric expression resulting from evaluating the supplied stored expression for each node in node-set-1 in turn, as a number. A stored expression may be obtained as the result of calling the saxon:expression() function.

The stored expression is evaluated for each node in node-set-1 in turn, with that node as the context node, with the context position equal to the position of that node in node-set-1, and with the context size equal to the size of node-set-1. Any NaN values are ignored. If the node-set is empty, the result is negative infinity.

For the single-argument version of this function, use the XPath 2.0 max() function instead, for portability.

Example: saxon:max(sale, saxon:expression('@price * @qty')) will evaluate price times quantity for each child <sale> element, and return the maximum amount.

min(node-set-1 , stored-expression)

This returns the minimum value of a numeric expression resulting from evaluating the supplied stored expression for each node in node-set-1 in turn, as a number. A stored expression may be obtained as the result of calling the saxon:expression() function.

The stored expression is evaluated for each node in node-set-1 in turn, with that node as the context node, with the context position equal to the position of that node in node-set-1, and with the context size equal to the size of node-set-1. Any NaN values are ignored. If the node-set is empty, the result is positive infinity.

For the single-argument version of this function, use the XPath 2.0 min() function instead, for portability.

Example: saxon:min(sale, saxon:expression('@price * @qty')) will evaluate price times quantity for each child <sale> element, and return the minimum amount.

parse(string)

This function takes a single argument, a string containing the source text of a well-formed XML document. It returns the document node (root node) that results from parsing this text. It throws an error if the text is not well-formed XML. Applications should not rely on the identity of the returned document node (at present, if the function is called twice with the same arguments, it returns a new document node each time, but this may change in future).

This function is useful where one XML document is embedded inside another using CDATA, or as an alternative way of passing an XML document as a parameter to a stylesheet.

path() This takes no arguments. It returns a string whose value is an XPath expression identifying the context node in the source tree. This can be useful for diagnostics, or to create an XPointer value, or when generating another stylesheet to process the same document. The resulting string can be used as input to the evaluate() function, provided that any namespace prefixes it uses are declared.
serialize(node, format)

This function takes two arguments: the first is a node (generally a document or element node) to be serialized. The second is the name of an <xsl:output> element in the stylesheet. The second argument must be known at compile time (it will typically be supplied as a string literal.) The function serializes the specified document, or the subtree rooted at the specified element, according to the parameters specified in the named <xsl:output> element, and returns the serialized document as a string.

This function is useful where the XSLT stylesheet wants to manipulate the serialized output, for example by embedding it as CDATA inside another XML document, or prefixing it with a DOCTYPE declaration, or inserting it into a non-XML output file.

sum(node-set-1, stored-expression)

This returns the total resulting from evaluating the supplied stored expression for each node in node-set-1 in turn, as a number. If the result is NaN for any node, the total will be NaN. A stored expression may be obtained as the result of calling the saxon:expression() function.

The stored expression is evaluated for each node in node-set-1 in turn, with that node as the context node, with the context position equal to the position of that node in node-set-1, and with the context size equal to the size of node-set-1.

Example: saxon:sum(sale, saxon:expression('@price * @qty')) will evaluate price times quantity for each child <sale> element, and return the total amount.

systemId() This returns the system identifier (URI) of the entity in the source document that contains the context node. There are no arguments.
tokenize(string-1, string-2?) The first argument is converted to a string and is treated as a list of separated tokens. If the second argument is present, any character in string-2 is taken as a delimiter character, and any sequence of delimiter characters is taken as a token separator. If the second argument is omitted, any sequence of whitespace is taken as a token separator: or to put it another way, the default for string-2 is '&#x09;&#x0A;&#x0D;&#x20;'.
A new sequence is constructed containing one string for each token; if the string is empty or contains a separator only then the result will be empty. For example tokenize("a cup of tea") generates a sequence of four strings: ( "a", "cup", "of", "tea").
typeAnnotation() This takes a node as argument, and returns a string representation of its type. In the case of an anonymous type, this will be a path identifying the type within the schema. The function is intended for diagnostic use, and the actual form of the string result may change in future releases.
yearMonthDuration-from-months(integer)

This returns an instance of xdt:yearMonthDuration corresponding to the given number of months.

The source code of these methods, which in most cases is extremely simple, can be used as an example for writing other user extension functions. It is found in class net.sf.saxon.functions.Extensions.


Extension instructions

A Saxon extension instruction is invoked using a name such as <saxon:localname>.

The saxon prefix (or whatever prefix you choose to use) must be associated with the Saxon namespace URI http://saxon.sf.net/. The prefix must also be designated as an extension element prefix by including it in the extension-element-prefixes attribute on the xsl:stylesheet element, or the xsl:extension-element-prefixes attribute on any enclosing literal result element or extension element.

However, top-level elements such as saxon:collation and saxon:script can be used without designating the prefix as an extension element prefix.


saxon:assign

The saxon:assign element is used to change the value of a local or global variable that has previously been declared using xsl:variable (or xsl:param). The variable or parameter must be marked as assignable by including the extra attribute saxon:assignable="yes"

As with xsl:variable, the name of the variable is given in the mandatory name attribute, and the new value may be given either by an expression in the select attribute, or by expanding the content of the xsl:assign element.

If the xsl:variable element has a type attribute, then the value is converted to the required type of the variable in the usual way.

Example:


<xsl:variable name="i" select="0" saxon:assignable="yes"/>
<saxon:while test="$i &lt; 10">
    The value of i is <xsl:value-of select="$i"/>
    <saxon:assign name="i" select="$i+1"/>
</saxon:while>
    

Note: Using saxon:assign is cheating. XSLT is designed as a language that is free of side-effects, which is why variables are not assignable. Once assignment to variables is allowed, certain optimizations become impossible. At present this doesn't affect Saxon, which generally executes the stylesheet sequentially. However, there are some circumstances in which the order of execution may not be quite what you expect, in which case saxon:assign may show anomalous behavior. In principle the saxon:assignable attribute is designed to stop Saxon doing optimizations that cause such anomalies, but you can't always rely on this.


saxon:call-template

The saxon:call-template instruction is identical to xsl:call-template except that the template name can be written as an attribute value template, allowing the actual template that is called to be selected at run time.

Typical usage is:
<saxon:call-template name="{$tname}"/>

This feature replaces the saxon:allow-avt attribute that was provided on xsl:call-template in earlier releases. The XSLT 2.0 rules on extension attributes have been tightened up, making it clear that the earlier design was non-conformant.

The saxon:call-template instruction allows xsl:fallback as a child element, so that fallback behaviour can be defined for other XSLT processors when they encounter this instruction.


saxon:collation

It is also possible to specify a collation directly by using a URI of the form http://saxon.sf.net/collation?keyword=value;keyword=value;.... For details see Collation URIs.

The saxon:collation element is a top-level element used to define collating sequences that may be used in sort keys and in functions such as compare(). The collation name is a URI (though actually any string can be used), and is defined in the mandatory name attribute. The other attributes control how the collation is defined. There are three ways of setting up a collation:

  1. by class. In this case the class attribute is used to specify the fully qualified name of a Java class that implements the java.util.Comparator interface. Note that if the collation is to be used in functions such as contains() and starts-with(), this class must also be a java.text.RuleBasedCollator. This approach allows a user-defined collation to be implemented in Java.
  2. by rules. In this case the rules attribute is used to specify details of the ordering required, using the syntax of the Java RuleBasedCollator. To give a simplified example, rules="A &lt; B &lt; C"
  3. by locale and tailoring. In this case the lang, strength, and decomposition attributes are used to obtain a collation for a particular locale, and to customize it. The lang attribute follows the rules of the xml:lang attribute, for example specify "en-US" for US English. This is used to find the collation appropriate to a Java locale. The strength attribute sets the strength of the collator. Values are "primary", "secondary", "tertiary", and "identical". The decomposition attribute determines how the collator handles Unicode composed characters. Values are "none", "standard", and "full". See the JDK documentation for full details of these attributes.
The default attribute specifies whether this collation is the default collation. Value is "yes" or "no". The value "yes" indicates that this collation is to be used as the default collation. If more than one collation is specified as the default, the last one wins. If no default collation is specified, Unicode codepoint collation is used.

Sorting and comparison according to Unicode codepoints can be achieved by setting up a collator as <saxon:collation name="unicode" class="net.sf.saxon.sort.CodepointCollator"/>

Note that a stylesheet containing a saxon:collation declaration cannot be compiled at this release, because the underlying Java classes are not serializable.


saxon:doctype

The saxon:doctype instruction is used to insert a document type declaration into the current output file. It should be instantiated before the first element in the output file is written.

The saxon:doctype instruction takes no attributes. The content of the element is a template-body that is instantiated to create an XML document that represents the DTD to be generated; this XML document is then serialized using a special output method that produces DTD syntax rather than XML syntax.

If this element is present the doctype-system and doctype-public attributes of xsl:output should not be present.

The generated XML document uses the following elements, where the namespace prefix "dtd" is used for the namespace URI "http://saxon.sf.net/dtd":

dtd:doctype Represents the document type declaration. This is always the top-level element. The element may contain dtd:element, dtd:attlist, dtd:entity, and dtd:notation elements. It may have the following attributes:
name (mandatory) The name of the document type
system The system ID
public The public ID
dtd:element Represents an element type declaration. This is always a child of dtd:doctype. The element is always empty. It may have the following attributes:
name (mandatory) The name of the element type
content (mandatory) The content model, exactly as it appears in a DTD, for example content="(#PCDATA)" or content="( a | b | c)*"
dtd:attlist Represents an attribute list declaration. This is always a child of dtd:doctype. The element will generally have one or more dtd:attribute children. It may have the following attributes:
element (mandatory) The name of the element type
dtd:attribute Represents an attribute declaration within an attribute list. This is always a child of dtd:attlist. The element will always be empty. It may have the following attributes:
name (mandatory) The name of the attribute
type (mandatory) The type of the attribute, exactly as it appears in a DTD, for example type="ID" or type="( red | green | blue)"
value (mandatory) The default value of the attribute, exactly as it appears in a DTD, for example value="#REQUIRED" or value="#FIXED 'blue'"
dtd:entity Represents an entity declaration. This is always a child of dtd:doctype. The element may be empty, or it may have content. The content is a template body, which is instantiated to define the value of an internal parsed entity. Note that this value includes the delimiting quotes. The xsl:entity element may have the following attributes:
name (mandatory) The name of the entity
system The system identifier
public The public identifier
parameter Set to "yes" for a parameter entity
notation The name of a notation, for an unparsed entity
dtd:notation Represents a notation declaration. This is always a child of dtd:doctype. The element will always be empty. It may have the following attributes:
name (mandatory) The name of the notation
system The system identifier
public The public identifier

Note that Saxon will perform only minimal validation on the DTD being generated; it will output the components requested but will not check that this generates well-formed XML, let alone that the output document instance is valid according to this DTD.

Example:


<xsl:template match="/">
  <saxon:doctype xsl:extension-element-prefixes="saxon">
  <dtd:doctype name="booklist"
        xmlns:dtd="http://saxon.sf.net/dtd" xsl:exclude-result-prefixes="dtd">
    <dtd:element name="booklist" content="(book)*"/>
    <dtd:element name="book" content="EMPTY"/>
    <dtd:attlist element="book">
      <dtd:attribute name="isbn" type="ID" value="#REQUIRED"/>
      <dtd:attribute name="title" type="CDATA" value="#IMPLIED"/>
    </dtd:attlist>
    <dtd:entity name="blurb">'A <i>cool</i> book with &gt; 200 pictures!'</dtd:entity>
    <dtd:entity name="cover" system="cover.gif" notation="GIF"/>
    <dtd:notation name="GIF" system="http://gif.org/"/>
  </dtd:doctype>
  </saxon:doctype>
  <xsl:apply-templates/>
</xsl:template>

Although not shown in this example, there is nothing to stop the DTD being generated as the output of a transformation, using instructions such as xsl:value-of and xsl:call-template. It is also possible to use xsl:text with disable-output-escaping="yes" to output DTD constructs not covered by this syntax, for example conditional sections and references to parameter entities.


saxon:import-query

The saxon:import-query element is a top-level declaration that causes an XQuery library module to be imported into the stylesheet.

The effect is that the functions defined in the library module become available for calling from any XPath expression in the stylesheet, as extension functions. They are available in all modules of the stylesheet.

Only the functions actually defined in the given XQuery module are imported. Functions that the specified module imports from other XQuery modules are not imported. This follows the semantics of XQuery's import module declaration. Variables defined in an imported module are not (currently) imported into the stylesheet.

The imported functions do not have any specific import precedence. If a stylesheet contains two saxon:import-query declarations importing the same namespace, then they are assumed to refer to the same library module, and all but the first are ignored. As with other extension functions, the override="yes|no" attribute on xsl:function can be used to determine whether a stylesheet function overrides an imported XQuery function of the same name.

The saxon:import-xquery function has two optional arguments. The href argument is the (absolute or relative) URI of the XQuery module. The namespace argument identifies the module namespace of the imported module. If href alone is specified, then the module is loaded from the given location. If namespace alone is specified, then the module must already be present in Saxon's Configuration object (you can share a Configuration between multiple stylesheets, which means that imported XQuery modules will not need to be recompiled for each one). If both attributes are specified, then Saxon uses an already-loaded module for the namespace if it can, otherwise it fetches it from the specified location, and checks that the namespace is correct. I would recommend specifying both attributes.


saxon:entity-ref

The saxon:entity-ref element is useful to generate entities such as &nbsp; in HTML output. To do this, write:


        <saxon:entity-ref name="nbsp"/>

Note: the preferred way to produce a non-breaking space character in the output is simply to write &#160; or &#xa0; in the stylesheet. By default, with HTML output, this will be serialized as &nbsp;, though the way it is serialized doesn't actually matter as far as the HTML browser is concerned.


saxon:script

The saxon:script element is a top-level element. It is used to define an implementation for an extension function that will be used by Saxon. With other processors, a different implementation of the same function can be selected, using mechanisms defined by that processor (for example, xalan:script).

The attributes for saxon:script are the same as the attributes of the xsl:script element defined in the (now withdrawn) XSLT 1.1 working draft.

The language attribute is mandatory, and must take the value "java". The values "javascript", "ecmascript", or a QName are also permitted, but in this case Saxon ignores the saxon:script element.

The implements-prefix attribute is mandatory, its value must be a namespace prefix that maps to the same namespace URI as the prefix used in the extension function call.

The src attribute is mandatory for language="java", its value must take the form "java:fully.qualified.class.Name", for example "java:java.util.Date". It defines the class containing the implementation of extension functions that use this prefix.

The archive attribute is optional, its value is a space-separated list of URLs of folders or JAR files that will be searched to find the named class. If the attribute is omitted, the class is sought on the classpath.


saxon:while

The saxon:while element is used to iterate while some condition is true.

The condition is given as a boolean expression in the mandatory test attribute. Because this expression must change its value if the loop is to terminate, the condition will generally reference a variable that is updated somewhere in the loop using an saxon:assign element. Alternatively, it may test a condition that is changed by means of a call on an extension function that has side-effects.

Example:


<xsl:variable name="i" expr="0"/>
<saxon:while test="$i &lt; 10">
    The value of i is <xsl:value-of select="$i"/>
    <saxon:assign name="i" expr="$i+1"/>
</saxon:while>
    

Michael H. Kay
7 March 2004