p:insert (3.1)

Inserts one document into another.

Summary
Description
- The position option
Examples
Additional details
Errors raised
Reference information

Summary

<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:

Type	Port	Primary?	Content types	Seq?	Description
`input`	`source`	`true`	`xml html`	`false`	The base document to insert in.
`output`	`result`	`true`	`xml html text`	`false`	The resulting document
`input`	`insertion`	`false`	`xml html text`	`true`	The document(s) to insert.

Options:

Name	Type	Req?	Default	Description
`match`	`xs:string` (XSLT selection pattern)	`false`	`/*`	The XSLT match pattern that indicates where to insert.
`position`	`xs:string`	`false`	`after`	Where to insert, relative to what was matched by the `match` option. See The position option.

Description

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.

The `position` option

The 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
`first-child`	The insertion is made as the first child of what was matched.
`last-child`	The insertion is made as the last child of what was matched.
`before`	The insertion is made directly before what was matched. In other words: the insertion becomes the immediate preceding sibling of the match.
`after`	The insertion is made directly after what was matched. In other words: the insertion becomes the immediate following sibling of the match.

Examples

Basic usage

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>

Inserting multiple times

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>

Inserting text

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>

Additional details

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.

Errors raised

Error code	Description
`XC0023`	It is a dynamic error if the selection pattern matches a wrong type of node.
`XC0024`	It is a dynamic error if the selection pattern matches a document node and the value of the `position` is “`before`” or “`after`”.
`XC0025`	It is a dynamic error if the selection pattern matches anything other than an element or a document node and the value of the `position` option is “`first-child`” or “`last-child`”.

Reference information

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.

p:insert (3.1)

Summary

Description

The position option

Examples

Basic usage

Inserting multiple times

Inserting text

Additional details

Errors raised

Reference information

The `position` option