saxon:transform

This function takes as input a compiled XSLT stylesheet, and uses it to transform a source document into a result document. The first argument will generally be the result of calling the saxon:compile-stylesheet() extension function. The second argument can be any node (usually a document node or element node), either read from external filestore using the doc() or document() function, or constructed programmatically.

The function is available both in XQuery and in XSLT. It can thus be used for example in XQuery to pre-process the input using a stylesheet, or to post-process the output using a stylesheet. It can also be used to chain multiple XSLT transformations together.

The compiled stylesheet can be used repeatedly to transform multiple source documents.

If the optional third argument is present, it is used to supply parameters to the transformation. There are two ways to supply parameters:

• The old way: The parameters are supplied as a sequence of nodes. Each node must be an element node, attribute node, or document node; supplying a document node is equivalent to supplying all its element children. The name of the node must match the parameter name declared in an xsl:param element in the stylesheet, and the atomized value of the node is used as the value of the parameter. If this is untypedAtomic then it is converted to the required type declared in the stylesheet.

• The new way (from Saxon 9.5) is as a map. The keys in the map may be strings (representing the name of a parameter in no namespace), or xs:QName values, allowing the parameter name to be in a namespace. The values are the corresponding parameter values. With the new way of supplying parameters, the parameter may take any value (with the old way it is restricted to atomic values.)

The stylesheet may contain calls on xsl:result-document. This allows the output of the stylesheet to be serialized directly to filestore rather than being returned to the calling transformation or query.

If the stylesheet produces no principal output document (typically because it sends all its output to secondary result documents) then the call on saxon:transform() returns an empty sequence.

Here is an example of how to use the function from XQuery:

let $results := <customers>{ //customer[location="Scotland"] }</customers> let $rendition := saxon:compile-stylesheet(doc('show-customers.xsl')) return saxon:transform($rendition, $results)

The following example uses XSLT's ability to create multiple output files:

let $splitter := saxon:compile-stylesheet( <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0"> <xsl:template match="customer"> <xsl:result-document href="{{@id}}.xml"> <xsl:copy-of select="."/> </xsl:result-document> </xsl:template> </xsl:stylesheet>) let $results := document { <customers>{ //customer[location="Scotland"] }</customers> } return saxon:transform($splitter, $results)

Note (a) the need to double the curly braces to ensure that the contained expression is expanded when the stylesheet is executed by XSLT, not when it is created by XQuery, and (b) the fact that the stylesheet and source document are supplied as document nodes, not element nodes.