p:replace (3.1)

Replace nodes with a document.

Summary
Description
Examples
- Basic usage
- Alternative approach
Additional details
Errors raised
Reference information

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:

Type	Port	Primary?	Content types	Seq?	Description
`input`	`source`	`true`	`xml html`	`false`	The document in which to replace nodes.
`output`	`result`	`true`	`text xml html`	`false`	The resulting document.
`input`	`replacement`	`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.