Replace nodes with a document.
<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 |
---|---|---|---|---|---|
|
|
|
|
| The document in which to replace nodes. |
|
|
|
|
| The resulting document. |
|
|
|
|
| The document to replace the nodes with. |
Options:
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.
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>
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>
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.
Error code | Description |
---|---|
It is a dynamic error if the selection pattern matches a wrong type of node. |
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.