p:rename (3.1) 

Renames nodes in a document.

Summary

<p:declare-step type="p:rename">
  <input port="source" primary="true" content-types="xml html" sequence="false"/>
  <output port="result" primary="true" content-types="xml html" sequence="false"/>
  <option name="new-name" as="xs:QName" required="true"/>
  <option name="match" as="xs:string" required="false" select="'/*'"/>
</p:declare-step>

The p:rename step renames elements, attributes, or processing-instruction nodes, specified by an XSLT selection pattern, in the document appearing on its source port.

Ports:

Port

Type

Primary?

Content types

Seq?

Description

source

input

true

xml html

false

The document to rename the nodes in.

result

output

true

xml html

false

The resulting document.

Options:

Name

Type

Req?

Default

Description

new-name

xs:QName

true

 

The new name for the matched nodes.

match

xs:string (XSLT selection pattern)

false

/*

The XSLT match pattern for the nodes to rename, as a string.

Description

Using p:rename, it becomes easy to rename elements, attributes, or processing-instructions in your document. The step takes the XSLT match pattern in the match option and holds this against the document appearing on its source port. Any matching nodes are renamed to the name provided in the new-name option. Matched nodes must be elements, attributes, or processing-instructions (any other match results in error XC0023).

Examples

Basic usage

The following example renames an element, an attribute and a processing-instruction in the source document:

Source document:

<things>
   <thing name="screw" id="A123"/>
   <thing name="bolt" id="A789"/>
   <?convert debug="true"?>
</things>

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result"/>

  <p:rename match="/*/thing" new-name="Thing"/>
  <p:rename match="@name" new-name="thing-name"/>
  <p:rename match="processing-instruction(convert)" new-name="debug-processing"/>

</p:declare-step>

Result document:

<things>
   <Thing thing-name="screw" id="A123"/>
   <Thing thing-name="bolt" id="A789"/>
   <?debug-processing debug="true"?>
</things>

Renaming to an existing attribute

This example shows that when an attribute is renamed to one that is already present, the existing attribute is deleted:

Source document:

<things>
   <thing name="screw" id="A123" thing-name="something else"/>
</things>

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result"/>

  <p:rename match="@name" new-name="thing-name"/>

</p:declare-step>

Result document:

<things>
   <thing thing-name="screw" id="A123"/>
</things>

Additional details

  • p:rename preserves all document-properties of the document(s) appearing on its source port.

  • If an attribute is renamed to an attribute that already exists on this element, this existing attribute is deleted. See the Renaming to an existing attribute example.

  • If an xml:base attribute is renamed to something else, the underlying base URI of the element is not changed.

    If an attribute is renamed to xml:base, the base URI of the underlying element is changed to the value of this attribute.

Errors raised

Error code

Description

XC0013

It is a dynamic error if the pattern matches a processing instruction and the new name has a non-null namespace.

XC0023

It is a dynamic error if the selection pattern matches a wrong type of node.

Reference information

This description of the p:rename step is for XProc version: 3.1. This is a required step (an XProc 3.1 processor must support this).

The formal specification for the p:rename step can be found here.

The p:rename step is part of categories:

The p:rename step is also present in version: 3.0.