saxon:update

The saxon:update element is used to create a modified copy of an XML node and its subtree, using child instructions that define the specific changes to be made.

The semantics are based on corresponding primitives in the XQuery Update specification.

Category: instruction
Content: ( saxon:change | saxon:delete | saxon:insert | saxon:rename | saxon:replace | xsl:choose | xsl:for-each | xsl:if | xsl:variable )*
Permitted parent elements: any XSLT element whose content model is sequence-constructor; any literal result element

Attributes

Saxon availability

Requires Saxon-EE. Implemented since Saxon 9.9. Available for all platforms.

Details

For example, you can delete selected attributes using the construct:

The outermost instruction is saxon:update. This has a select attribute to select the nodes whose subtrees will be updated. The default is select=".". The result of the instruction is a sequence of nodes that are modified copies of the selected nodes (unless any of these nodes are deleted, in which case they are omitted from the result). The original tree remains unchanged.

Updating instructions, although they give the impression of modifying data in-situ, are in fact side-effect free. The saxon:update instruction returns a modified copy of its input; the original input tree is unaffected. Within the saxon:update instruction, all path expressions access an unmodified deep copy of the selected source nodes. These instructions return pending update actions, which are applied at the end (in a defined order) to create the modified trees returned by the saxon:update instruction.

Within the saxon:update instruction, the following subsidiary instructions may be evaluated. They are evaluated once for each node selected by the saxon:update instruction, with that node as the context node.

• <saxon:delete select="expression"/>. Deletes the selected node or nodes from the tree.
• <saxon:rename select="expression" to="expression"/>. Renames the (single) selected node to the specified name. The to expression must return either an xs:QName value, or a string in the form of a legal NCName (representing a name in the default namespace for elements and types). To rename multiple nodes, use within xsl:for-each.
• <saxon:insert select="expression" position="before|after|first|last">...</saxon:insert>. Inserts the node(s) constructed by the contained sequence constructor as attributes, as immediately preceding or following siblings, or as the first or last children, of the (single) node selected by the select expression. Specifically, any attributes returned by the contained sequence constructor are copied as attributes of the selected node, while any elements, text nodes, comments, or processing instructions are copied to appear before or after the selected node, or as its first or last children according to the value of the @position attribute; if there are multiple inserted nodes, then their relative ordering is retained.
• <saxon:replace select="expression">...</saxon:replace>. Replace the (single) node selected by the select expression, with the node(s) constructed by the contained sequence constructor.
• <saxon:change select="expression" to="expression"/>. Changes the content of the (single) node selected by the select expression, so that its string value becomes the value computed by the "to" expression.

For all these instructions the select attribute defaults to "." (the context item). In all cases except saxon:delete the select expression must select a single node (or nothing); to apply the same operation to multiple nodes, use the instruction within xsl:for-each (and omit the select attribute).

The semantics of these subsidiary instructions are as defined for the corresponding expressions in the XQuery Update specification. In most cases the correspondence is obvious. The XQuery Update expression corresponding to <saxon:change select="N" to="V"/> is replace value of node N with V.

Within the saxon:update instruction, the xsl:if, xsl:choose, and xsl:for-each instructions (and no others) can be used to achieve conditional or repeated execution of the subsidiary instructions. Local variables may also be declared within saxon:update.

For all expressions contained in subsidiary instructions, the focus for evaluating the expression is the sequence of nodes selected by the containing saxon:update instruction, unless the focus is changed by an intervening instruction such as xsl:for-each.

The update extension for XSLT does not provide any equivalent to updating functions; all update instructions must be contained lexically within the saxon:update instruction.

Examples