Inserts one document into another.
<p:declare-step type="p:insert"> <input port="source" primary="true" content-types="xml html" sequence="false"/> <output port="result" primary="true" content-types="xml html text" sequence="false"/> <input port="insertion" primary="false" content-types="xml html text" sequence="true"/> <option name="match" as="xs:string" required="false" select="'/*'"/> <option name="position" as="xs:string" required="false" select="'after'" values="('first-child','last-child','before','after')"/> </p:declare-step>
The p:insert
step inserts the document(s) appearing on the insertion
port into the document appearing on the source
port.
Ports:
Port | Type | Primary? | Content types | Seq? | Description |
---|---|---|---|---|---|
|
|
|
|
| The base document to insert in. |
|
|
|
|
| The resulting document |
|
|
|
|
| The document(s) to insert. |
Options:
The p:insert
step can be used to insert one or more documents into another. It searches the document appearing on its source
port for matches as indicated by the match
option. It then inserts the document(s) appearing on its insertion
port, as indicated by the position
option. The result of the merge is emitted on the result
port.
position
optionThe position
option tells p:insert
where to insert the document(s) in the insertion
port, relative to what
was matched by the match
option. There are 4 possible values:
Value | Description |
---|---|
| The insertion is made as the first child of what was matched. |
| The insertion is made as the last child of what was matched. |
| The insertion is made directly before what was matched. In other words: the insertion becomes the immediate preceding sibling of the match. |
| The insertion is made directly after what was matched. In other words: the insertion becomes the immediate following sibling of the match. |
This simple example shows how to insert a (for the example, fixed) document into another, as a first child of a match:
Source document:
<things> <thing id="123">USB adapter</thing> <thing id="456">Joystick</thing> <thing id="789">Mouse</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:insert position="first-child"> <p:with-input port="insertion"> <thing id="999">Keyboard</thing> </p:with-input> </p:insert> </p:declare-step>
Result document:
<things> <thing id="999">Keyboard</thing> <thing id="123">USB adapter</thing> <thing id="456">Joystick</thing> <thing id="789">Mouse</thing> </things>
Or, using the same source document, as the its last child:
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0"> <p:input port="source"/> <p:output port="result"/> <p:insert position="last-child"> <p:with-input port="insertion"> <thing id="999">Keyboard</thing> </p:with-input> </p:insert> </p:declare-step>
Result document:
<things> <thing id="123">USB adapter</thing> <thing id="456">Joystick</thing> <thing id="789">Mouse</thing> <thing id="999">Keyboard</thing> </things>
The following example, again using the same source document, inserts a new thing using the before
value of the
position
option:
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0"> <p:input port="source"/> <p:output port="result"/> <p:insert match="/things/thing[@id eq '456']" position="before"> <p:with-input port="insertion"> <thing id="999">Keyboard</thing> </p:with-input> </p:insert> </p:declare-step>
Result document:
<things> <thing id="123">USB adapter</thing> <thing id="999">Keyboard</thing> <thing id="456">Joystick</thing> <thing id="789">Mouse</thing> </things>
The following example shows that when the match
option matches multiple times, the insertion occurs multiple times:
Source document:
<things> <thing id="123"> <name>USB adapter</name> </thing> <thing id="456"> <name>Joystick</name> </thing> <thing id="789"> <name>Mouse</name> </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:insert match="thing" position="last-child"> <p:with-input port="insertion"> <description>TBD</description> </p:with-input> </p:insert> </p:declare-step>
Result document:
<things> <thing id="123"> <name>USB adapter</name> <description>TBD</description> </thing> <thing id="456"> <name>Joystick</name> <description>TBD</description> </thing> <thing id="789"> <name>Mouse</name> <description>TBD</description> </thing> </things>
Starting XProc version 3.1, it is also possible to insert text into a document using the p:insert
step:
Source document:
<things> <thing id="123">USB adapter</thing> <thing id="456">Joystick</thing> <thing id="789">Mouse</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:insert match="/things/thing[@id eq '456']" position="last-child"> <p:with-input port="insertion"> <p:inline content-type="text/plain"> (special!)</p:inline> </p:with-input> </p:insert> </p:declare-step>
Result document:
<things> <thing id="123">USB adapter</thing> <thing id="456">Joystick (special!)</thing> <thing id="789">Mouse</thing> </things>
It must be possible to insert the document(s) at the indicated location(s). For instance, the match
option cannot match an
attribute and you cannot insert something before or after the document node. If this happens, an appropriate error is raised.
p:insert
preserves all document-properties of the document(s) appearing on its source
port.
The document-properties of the document(s) appearing on its insertion
port are not used/preserved.
If the match
option matches multiple times, multiple instances of the document(s) on the insertion
port are
inserted. See Inserting multiple times.
If the insertion
port receives no document(s), nothing happens. The step will act as a p:identity
step.
Error code | Description |
---|---|
It is a dynamic error if the selection pattern matches a wrong type of node. | |
It is a dynamic error if the selection pattern matches a document node and the value of the | |
It is a dynamic error if the selection pattern matches anything other than an element or a document node and the value of the
|
This description of the p:insert
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:insert
step can be found here.
The p:insert
step is part of categories:
The p:insert
step is also present in version:
3.0.