p:replace (3.1) 

Replace nodes with a document.

Summary

<p:declare-step type="p:replace">
  <input port="source" primary="true" content-types="xml html" sequence="false"/>
  <output port="result" primary="true" content-types="text xml html" sequence="false"/>
  <input port="replacement" primary="false" content-types="text xml html" sequence="false"/>
  <option name="match" as="xs:string" required="true"/>
</p:declare-step>

The p:replace step takes the document appearing on its source port and replaces nodes matching the match option with the document appearing on the replacement port.

Ports:

Port

Type

Primary?

Content types

Seq?

Description

source

input

true

xml html

false

The document in which to replace nodes.

result

output

true

text xml html

false

The resulting document.

replacement

input

false

text xml html

false

The document to replace the nodes with.

Options:

Name

Type

Req?

Description

match

xs:string (XSLT selection pattern)

true

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

Description

The p:replace 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 replaced by the document on the replacement port. The resulting document is emitted on the result port.

This step replaces matched nodes with a complete document. If you need to replace matched nodes with (just) strings, have a look at the p:string-replace step.

Examples

Basic usage

The following example replaces all <thing> elements with <another-thing/> elements.

Source document:

<things>
   <thing>
      <contents/>
   </thing>
   <thing/>
</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:replace match="thing">
    <p:with-input port="replacement">
      <another-thing/>
    </p:with-input>
  </p:replace>

</p:declare-step>

Result document:

<things>
   <another-thing/>
   <another-thing/>
</things>

Alternative approach

What the p:replace step does is similar to what a simple p:viewport instruction does: it takes a matched node and replaces it with something. This pipeline has the same functionality as the one in Basic usage:

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

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

  <p:viewport match="thing">
    <p:identity>
      <p:with-input>
        <another-thing/>
      </p:with-input>
    </p:identity>
  </p:viewport>

</p:declare-step>

Result document (using the same input document as in Basic usage):

<things>
   <another-thing/>
   <another-thing/>
</things>

Additional details

  • For obvious reasons, you cannot replace attributes and namespace nodes.

  • Replacing by p:replace is not recursive. In other words: there are no replacements in a replacement.

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

    There is one exception: if the resulting document contains only text, the content-type document-property is changed to text/plain and the serialization document-property is removed.

Errors raised

Error code

Description

XC0023

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

Reference information

This description of the p:replace 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:replace step can be found here.

The p:replace step is part of categories:

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