Invokes a transformation using a dynamically-loaded XSLT stylesheet.
fn:transform( $options as map(*)map(*)This function loads an XSLT stylesheet and invokes it to perform a transformation.
The inputs to the transformation are supplied in the form of a map. The option parameter conventions apply to this map; they do not apply to any nested map unless otherwise specified.
The function first identifies the requested XSLT version, as follows:
If the xslt-version
option is present, the requested XSLT version is the value of that option.
Otherwise, the requested XSLT version
is the value of the [xsl:]version attribute of the outermost element in the supplied stylesheet or package.
The function then attempts to locate an XSLT processor that implements the requested XSLT version.
If a processor that implements the requested XSLT version is available, then it is used.
Otherwise, if a processor that implements a version later than the requested version is available, then it is used.
Otherwise, the function fails indicating that no suitable XSLT processor is available.
The phrase locate an XSLT processor includes the possibility of locating a software product and configuring it to act as an XSLT processor that implements the requested XSLT version.
If more than one XSLT processor is available under the above rules, then the one that is chosen may be selected according to the availability of requested features: see below.
Once an XSLT processor has been selected that implements a given version of XSLT, the processor
follows the rules of that version of the XSLT specification. This includes any decision to operate in backwards or forwards
compatibility mode. For example, if an XSLT 2.0 processor is selected, and the stylesheet specifies version="1.0",
then the processor will operate in backwards compatibility mode; if the same processor is selected and the stylesheet
specifies version="3.0", the processor will operate in forwards compatibility mode.
The combinations of options that are relevant to each version of XSLT, other than xslt-version
itself, are listed below. This is followed by a table giving the meaning of each option.
For invocation of an XSLT 1.0 processor (see ), the supplied options must include all of the following (if anything else is present, it is ignored):
The stylesheet, provided by supplying exactly one of the following:
stylesheet-location
stylesheet-node
stylesheet-text
The source tree, provided as the value of the source-node option.
Zero or more of the following additional options:
stylesheet-base-uri
stylesheet-params (defaults to an empty map)
initial-mode (defaults to the unnamed mode)
delivery-format (defaults to document)
serialization-params (defaults to an empty map)
enable-messages (default is implementation-defined)
requested-properties (default is an empty map)
vendor-options (defaults to an empty map)
cache (default is implementation-defined)
For invocation of an XSLT 2.0 processor (see ), the supplied options must include all of the following (if anything else is present, it is ignored):
The stylesheet, provided by supplying exactly one of the following:
stylesheet-location
stylesheet-node
stylesheet-text
Invocation details, as exactly one of the following:
For apply-templates invocation, all of the following:
source-node
Optionally, initial-mode (defaults to the unnamed mode)
For call-template invocation, all of the following:
initial-template
Optionally, source-node
Zero or more of the following additional options:
stylesheet-base-uri
stylesheet-params (defaults to an empty map)
base-output-uri (defaults to absent)
delivery-format (defaults to document)
serialization-params (defaults to an empty map)
enable-messages (default is implementation-defined)
enable-trace (default is implementation-defined)
requested-properties (default is an empty map)
vendor-options (defaults to an empty map)
cache (default is implementation-defined)
For invocation of an XSLT 3.0 processor (see ), the supplied options must include all of the following (if anything else is present, it is ignored):
The stylesheet, provided either by supplying exactly one of the following:
stylesheet-location
stylesheet-node
stylesheet-text
Or by supplying exactly one of the following:
package-location
package-node
package-text
package-name plus optionally package-version
Invocation details, as exactly one of the following combinations:
For apply-templates invocation, all of the following:
Exactly one of source-node or initial-match-selection
Optionally, initial-mode
Optionally, template-params
Optionally, tunnel-params
For call-template invocation using an explicit template name, all of the following:
initial-template
Optionally, template-params
Optionally, tunnel-params
Optionally, source-node
For call-template invocation using the defaulted template name xsl:initial-template, all of the following:
Optionally, template-params
Optionally, tunnel-params
If the source-node option is present and initial-template is absent,
then apply-templates invocation will be used. To use call-template invocation on the template
named xsl:initial-template while also supplying a context item for use when evaluating
global variables, either (a) supply the context item using the global-context-item option,
or (b) supply source-node, and set the initial-template option explicitly to the
QName xsl:initial-template
For call-function invocation, all of the following:
initial-function
function-params
The invocation method can be determined as the first of the following which applies:
If initial-function is present, then call-function invocation.
If initial-template is present, then call-template invocation.
If source-node or initial-match-selection
is present, then apply-templates invocation.
Otherwise, call-template invocation using
the default entry point xsl:initial-template.
Zero or more of the following additional options:
stylesheet-base-uri
static-params (defaults to an empty map)
stylesheet-params (defaults to an empty map)
global-context-item (defaults to absent)
base-output-uri (defaults to absent)
delivery-format
serialization-params (defaults to an empty map)
enable-assertions (default is false)
enable-messages (default is implementation-defined)
enable-trace (default is implementation-defined)
requested-properties (default is an empty map)
vendor-options (defaults to an empty map)
cache (default is implementation-defined)
The meanings of each option are defined in the table below.
1.0, 2.0, 3.0 The URI of the principal result document; also used as the base URI for resolving relative URIs of secondary result documents. If the value is a relative reference, it is resolved against the static base URI of thefn:transform
function call.
xs:string
The effect of not
supplying a base output URI is defined by the XSLT specification; the implementation
may supply a default, for example the directory containing the
stylesheet, or the current working directory.
1.0, 2.0, 3.0
This option has no effect on the result of the transformation but may affect
efficiency. The value true indicates an expectation that the same
stylesheet is likely to be used for more than one transformation; the value
false indicates an expectation that the stylesheet will be used once
only.
xs:boolean
true()
1.0, 2.0, 3.0
The manner in which the transformation results should be delivered. Applies both to the
principal result document and to secondary result documents created using
xsl:result-document.
xs:string
document, unless the relevant
xsl:output or xsl:result-document element specifies
build-tree="no" (applies to XSLT 3.0 only), in which case the default
is raw.
The result is delivered as a
document node.
The result is delivered as
a string, representing the results of serialization. Note that (as with the
fn:serialize function) the final encoding stage of
serialization (which turns a sequence of characters into a sequence of
octets) is either skipped, or reversed by decoding the octet stream back
into a character stream.
The result of the initial
template or function is returned as an arbitrary XDM value (after conversion
to the declared type, but without wrapping in a document node, and without
serialization): when this option is chosen, the returned map contains the
raw result.
3.0
Indicates whether any xsl:assert instructions in the stylesheet
are to be evaluated.
xs:boolean
false()
1.0, 2.0, 3.0
Indicates whether any xsl:message instructions in the stylesheet
are to be evaluated. The destination and formatting of any such messages is
implementation-defined.
xs:boolean
Implementation-defined
2.0, 3.0
Indicates whether any fn:trace functions in the stylesheet are to
generate diagnostic messages. The destination and formatting of any such messages is
implementation-defined.
xs:boolean
Implementation-defined
3.0
An array of values to be used as the arguments to the initial function call.
The value is converted to the required type of the declared parameter using the function
conversion rules.
array(item()*)
Empty array
3.0
The value of the global context item, as defined in XSLT 3.0
item()
The value of source-node
3.0
The name of the initial function to be called for call-function invocation. The
arity of the function is inferred from the length of
function-params.
xs:QName
n/a
3.0
The value of the initial match selection, as defined in XSLT 3.0
item()*
The value of source-node
1.0, 2.0, 3.0
The name of the initial processing mode.
xs:QName
2.0, 3.0
The name of a named template in the stylesheet to act as the initial entry
point.
xs:QName
xsl:initial-template
3.0
The name of the top-level stylesheet package to be invoked (an absolute
URI)
xs:string
n/a
3.0
The location of the top-level stylesheet package, as a relative or absolute
URI
xs:string
n/a
3.0
A document or element node containing the top-level stylesheet
package
node()
n/a
3.0
The top-level stylesheet package in the form of unparsed lexical
XML.
xs:string
n/a
3.0
The version of the top-level stylesheet package to be invoked.
xs:string
"*" (any version)
1.0 2.0 3.0
A function that is used to post-process each result document of
the transformation (both the principal result and secondary results), in whatever
form it would otherwise be delivered (document, serialized, or raw). The first
argument of the function is the key used to identify the result in the map return
by the fn:transform function (for example, this will be the supplied
base output URI in the case of the principal result, or the string "output" if no
base output URI was supplied). The second argument is the
actual value. The value that is returned in the result of the fn:transform
function is the result of applying this post-processing.
If the implementation provides a way of writing or invoking functions
with side-effects, this post-processing function might be used to save
a copy of the result document to persistent storage. For example, if the
implementation provides access to the EXPath File library ,
then a serialized document might be written to filestore by calling the
file:write function. Similar mechanisms might be used to issue
an HTTP POST request that posts the result to an HTTP server, or to send
the document to an email recipient. The semantics of calling functions
with side-effects are entirely implementation-defined.
If the primary purpose of the post-processing function is achieved by
means of such side-effects, and if the actual results are not needed by
the caller of the fn:transform function, then it does not matter what
the post-processing function actually returns (it could be an empty
sequence, for example).
Calls to fn:transform can potentially have side-effects
even in the absence of the post-processing option, because the XSLT
specification allows a stylesheet to invoke extension functions
that have side-effects. The semantics in this case are implementation-defined.
system-property function; the values in the map are the requested
settings of the corresponding property. The boolean values true() and
false() are equivalent to the string values yes and
no. As a special case, setting a value for xsl:version has
no effect, because of the potential for conflict with other options. For example:
Setting xsl:product-name to a particular value requests a
particular XSLT software product.
Setting xsl:product-version requests a specific version of
that product.
Setting xsl:is-schema-aware to true() requests a
schema-aware processor.
Setting xsl:xsd-version to "1.1" requests a
processor that supports XML Schema version 1.1.
xsl:supports-dynamic-evaluation
to false() is interpreted as an explicit request for a processor in which
the value of the property is false. The effect if the requests cannot be precisely met
is implementation-defined. In some cases it may be appropriate to ignore the request or
to provide an alternative (for example, a later version of the product than the one
requested); in other cases it may be more appropriate to raise an error indicating that no suitable XSLT processor
is available.
map(xs:QName, xs:anyAtomicType)
Empty map
1.0, 2.0, 3.0
Serialization parameters for the principal result document. The supplied map
follows the same rules that apply to a map supplied as the second argument of
fn:serialize.
When a parameter is supplied, the corresponding value overrides or augments
the value specified in the unnamed xsl:output declaration (or
its default), following the same rules as when one xsl:output
declaration overrides another with lower import precedence.
When a parameter is supplied and the corresponding value is an empty
sequence (for example, map{"standalone":()}), any value
specified in the unnamed xsl:output declaration is overridden
by the default value.
When a parameter is not supplied in serialization-params (that
is, when the key is absent) the value that applies is the value appearing in
the unnamed xsl:output declaration, or its default.
source-node is supplied then the
global-context-item (the context item for evaluating global variables)
is the root of the tree containing the supplied node. In addition, for apply-templates
invocation, the source-node acts as the
initial-match-selection, that is, stylesheet execution starts by
applying templates to this node.
node()
n/a
3.0
The values of static parameters defined in the stylesheet; the keys are the
names of the parameters, and the associated values are their values. The value is
converted to the required type of the declared parameter using the function conversion
rules.
map(xs:QName, item()*)
Empty map
1.0, 2.0, 3.0
A string intended to be used as the static base URI of the principal stylesheet
module. This value must be used if no other static base URI is
available. If the supplied stylesheet already has a base URI (which will generally be
the case if the stylesheet is supplied using stylesheet-node or
stylesheet-location) then it is implementation-defined whether this
parameter has any effect. If the value is a relative reference, it is resolved against
the static base URI of the fn:transform function call.
xs:string
n/a
1.0, 2.0, 3.0
URI that can be used to locate the principal stylesheet module. If relative, it
is resolved against the static base URI of the fn:transform function call.
The value also acts as the default for stylesheet-base-uri.
xs:string
n/a
1.0, 2.0, 3.0
Root of the tree containing the principal stylesheet module, as a document or
element node. The base URI of the node acts as the default for
stylesheet-base-uri.
node()
n/a
1.0, 2.0, 3.0
A map holding values to be supplied for stylesheet parameters. The keys are the
parameter names; the values are the corresponding parameter values. The values are
converted if necessary to the required type using the function conversion rules. The
default is an empty map.
map(xs:QName, item()*)
Empty map
1.0, 2.0, 3.0
The principal stylesheet module in the form of unparsed lexical
XML.
xs:string
n/a
3.0
The values of non-tunnel parameters to be supplied to the initial template,
used with both apply-templates and call-template invocation. Each value is converted to
the required type of the declared parameter using the function conversion
rules.
map(xs:QName, item()*)
3.0
The values of tunnel parameters to be supplied to the initial template, used
with both apply-templates and call-template invocation. Each value is converted to the
required type of the declared parameter using the function conversion
rules.
map(xs:QName, item()*)
Empty map
1.0, 2.0, 3.0
Values for vendor-defined configuration options for the XSLT processor used to
process the request. The key is the name of an option, expressed as a QName: the
namespace URI of the QName should be a URI controlled by the vendor
of the XSLT processor. The meaning of the associated value is implementation-defined. Implementations
should ignore options whose names are in an unrecognized
namespace. Default is an empty map.
map{xs:QName, item()*}
Empty map
1.0, 2.0, 3.0
The minimum level of the XSLT language that the processor must support.
xs:decimal
The [xsl:]version attribute at the outermost level of the
stylesheet.
The result of the transformation is returned as a map. There is one entry in the map for the principal result document, and one
for each secondary result document. The key is a URI in the form of an xs:string value. The key for the principal
result document is the base output URI if specified, or the string "output" otherwise. The key for secondary
result documents is the URI of the document, as an absolute URI. The associated value in each entry depends on the requested
delivery format. If the delivery format is document, the value is a document node. If the delivery format is
serialized, the value is a string containing the serialized result. If the delivery format is saved,
the value is the absolute URI of the location where the serialized result has been saved. The saved document will not be accessible
at this location within the current execution scope
(this is to prevent any dependency on order of execution).
Where nodes are passed to or from the transformation, for example as the value of a stylesheet parameter or the result of a function, they should if possible retain their node identity, their base URI, their type annotations, and their relationships to all other nodes in the containing tree (including ancestors and siblings). If this is not possible, for example because the only way of passing nodes to the chosen XSLT implementation is by serializing and re-parsing, then a node may be passed in the form of a deep copy, which may lose information about the identity of the node, about its ancestors and siblings, about its base URI, about its type annotation, and about its relationships to other nodes passed across the interface.
It is implementation-defined whether the XSLT transformation is executed within the same execution scope as the calling code.
The function is nondeterministic in that it is
implementation-dependent whether running the function twice against the same
inputs produces identical results. The results of two invocations may differ in the identity of any returned nodes; they may also
differ in other respects, for example because the value of fn:current-dateTime is different for the two invocations,
or because the contents of external documents accessed using fn:doc or xsl:source-document change between
one invocation and the next.
The delivery format saved indicates that the transformation should modify the state of the external environment.
This has two noteworthy consequences:
It creates a potential security risk.
The fn:transform function ceases to be a pure function, because it has side-effects.
Implementations may mitigate these problems in a number of ways, including the following:
Use of the delivery-format=saved option may be disallowed, either
completely or at user option.
The environment that the delivery-format=saved option is allowed to modify may be
sand-boxed in some way. For example: resources that are created using this option may be accessible only
via some special interface; the resource may become available only on completion of the execution scope
in which the fn:transform function is evaluated; or the implementation may prevent the use functions
such as fn:doc and fn:collection to access such resources.
Creating multiple resources with the same URI may be disallowed.
The implementation may define circumstances in which the side-effect of creating external resources is thwarted as a consequence of query optimization (for example, any situation in which a query calls fn:transform but has no functional dependency on the result of the call).
There may be restrictions on the URIs that can be used to identify saved resources
The following example loads a stylesheet from the location render.xsl,
applies it to a document loaded from test.xml, and uses an XPath expression
to examine the result:
A dynamic error is raised if the transformation cannot be invoked because no suitable XSLT processor is available. This includes (but is not limited to) the following cases:
No XSLT processor is available;
No XSLT processor supporting the requested version of XSLT is available;
The XSLT processor API does not support some requested feature (for example, the ability to supply tunnel parameters externally);
A dynamic error is raised if an error is detected in the supplied parameters (for example if two mutually-exclusive parameters are supplied).
If a static or dynamic error is reported by the XSLT processor, this function fails with a dynamic error, retaining the XSLT error code.
A dynamic error is raised if the XSLT transformation invoked by a call on
fn:transform fails with a static or dynamic error, and no more specific error code is available.
XSLT 1.0 does not define any error codes, so this is the likely outcome with an XSLT 1.0 processor. XSLT 2.0 and 3.0 do define error codes, but some APIs do not expose them. If multiple errors are signaled by the transformation (which is most likely to happen with static errors) then the error code should where possible be that of one of these errors, chosen arbitrarily; the processor may make details of additional errors available to the application in an implementation-defined way.
A dynamic error is raised if the use of this function (or of selected options) has been externally disabled, for example for security reasons.
A dynamic error is raised if delivery-format is saved
and the results cannot be saved at the specified location.
A dynamic error is raised if the transformation produces output containing characters available only in XML 1.1, and the calling processor cannot handle such characters.
A dynamic error is raised if the option delivery-format:saved
is used in a way that violates any implementation-defined restrictions on its use.
Recursive use of the fn:transform function may lead to catastrophic failures such as
non-termination or stack overflow. No error code is assigned to such conditions, since they cannot necessarily
be detected by the processor.
As with all other functions in this specification, conformance requirements depend on the host language.
For example, a host language might specify that provision of this function is optional, or that it is excluded entirely,
or that implementations are required to support a particular set of values for the xslt-version
parameter.
Even where support for this function is mandatory, it is recommended for security reasons that implementations should provide a user option to disable its use, or to disable aspects of its functionality such as the ability to write to persistent resources.
