XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (147 page)

Content

An optional sequence constructor, which is used only if the item being copied is a document node or an element.

Effect

The action depends on the kind of context item, as follows:

Item kind	Action
atomic value	Adds the atomic value to the result sequence. (Atomic values have no identity, so there is no distinction between the original value and a copy of the value.)
document	A new document node is added to the result sequence. The sequence constructor is evaluated to provide the content for the document node. This works in the same way as the content of an instruction, as described on page 303. The attributes copy-namespaces , inherit-namespaces , and use-attribute-sets are ignored. The type and validation attributes have the same effect as with .
element	An element node is added to the result sequence, as if by a call on . This will have the same name as the context node. The local name and namespace URI are guaranteed to be the same as the original, and the prefix will be the same unless there is a conflict. The namespace nodes associated with the current element node are copied to the new element, unless copy-namespaces=“no” is specified. The namespace nodes are also copied to the new children of the element, unless inherit-namespaces=“no” is specified. The use-attribute-sets attribute and the contained sequence constructor are then evaluated to create the attributes and children of the new element in the same way as for . Namespace fixup is applied to the new element, to ensure that it has all the namespace nodes it needs, in the same way as for the instruction. With a schema-aware processor, the new element may be validated and may acquire a type annotation; this depends on the values of the type and validation attributes, and works exactly as for described on page 306. Note the surprising consequence that validation=“preserve” does not cause the type annotation of the original element to be retained: This is not feasible, because the content of the element is not being copied.
text	A new text node is added to the result sequence, with the same string value as the context node. The attributes of the instruction and the sequence constructor are ignored.
attribute	A new attribute node is added to the result sequence, as if by a call on . This will have the same name and value as the context node. The attributes copy-namespaces , inherit-namespaces , and use-attribute-sets are ignored. The local name, namespace URI, and string value of the output attribute are guaranteed to be the same as the original, and the prefix will be the same unless there is a conflict (for example, if two attributes added to the same element use the same prefix to refer to different namespace URIs). With a schema-aware processor, the new attribute may be validated and may acquire a type annotation: This depends on the values of the type and validation attributes, and works exactly as for described on page 292.
processing instruction	A processing instruction node is added to the result sequence, with the same name and value (target and data in XML terminology) as the context node. The attributes of the instruction and the sequence constructor are ignored.
comment	A comment node is added to the result sequence, with the same content as the context node. The attributes of the instruction and the sequence constructor are ignored.
namespace	The namespace node is copied to the result sequence. The new namespace node will have the same name and value (that is, the same namespace prefix and URI) as the original. The attributes of the instruction and the sequence constructor are ignored.

Usage

The main use of

is when doing an XML-to-XML transformation in which parts of the document are to remain unchanged. It is also useful when the source XML document contains XHTML fragments within it; for example, if the simple HTML formatting elements such as

and

are used within textual data in the source and are to be copied unchanged to an HTML output document.

Although

does a shallow copy, it is easy to construct a deep copy by applying it recursively. The typical manner of use is to write a template rule that effectively calls itself:

This is sometimes referred to as the
identity template
. This template rule matches any node except a namespace or document node. This is because
@*
matches any attribute node, and
node()
, which is short for
child::node()
, matches any node that is allowed to be the child of something (that is, an element node, text node, comment, or processing instruction). Once this template rule is applied to a node, it copies that node, and if it is an element node, it applies itself to its attributes and child nodes—on the assumption that there is no other template rule with
mode=“copy”
that has a higher priority.An easier way of doing a deep copy is to use

. However, the recursive use of

allows modifications to be made to the tree while it is being copied, by adding further template rules. For example, if you want to copy the whole document except for the subtree rooted at a

element, you can achieve this with a stylesheet that contains the identity template as above, together with the rule: