p:wrap (3.1) 

Grouping

The group-adjacent option of p:wrap allows you to group adjacent matching nodes in a single wrapper element. The value of this option must a valid XPath expression. It is evaluated for every node in the source document. Adjacent nodes with an equal result value are wrapped together in the same wrapper element.

For all nodes in the document on the source port:

• The node becomes the context item (accessible with the dot . operator).

• The expression in the group-adjacent option is evaluated.

• Two values of sibling nodes, computed by the XPath expression, are considered equal if the XPath function fn:deep-equal() returns true for them. In most cases this simply means that values are equal when you intuitively expect them to be.

• All sibling nodes with equal values for the XPath expression, that are adjacent, are wrapped together in a wrapper element, as named by the wrapper option.

For an example see Grouping and wrapping.

Basic usage

The following example wraps every thing element in a <computer-part> element:

Source document:

<things>
   <thing name="laptop"/>
   <thing name="desktop">
      <subthings>
         <thing name="keyboard"/>
         <thing name="mouse"/>
      </subthings>
   </thing>
</things>

Pipeline document:

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

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

  <p:wrap match="thing" wrapper="computer-part"/>

</p:declare-step>

Result document:

<things>
   <computer-part>
      <thing name="laptop"/>
   </computer-part>
   <computer-part>
      <thing name="desktop">
         <subthings>
            <computer-part>
               <thing name="keyboard"/>
            </computer-part>
            <computer-part>
               <thing name="mouse"/>
            </computer-part>
         </subthings>
      </thing>
   </computer-part>
</things>

Please notice that the nested <thing> elements (inside the <subthings> element) are also wrapped. This is because p:wrap performs “deep” wrapping.

Grouping and wrapping

This example shows what happens when you use the group-adjacent option. Here we group fruits by color:

Source document:

<fruits>
   <fruit name="banana" color="yellow"/>
   <fruit name="orange" color="orange"/>
   <fruit name="carrot" color="orange"/>
   <fruit name="lemon" color="yellow"/>
</fruits>

Pipeline document:

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

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

  <p:wrap match="fruit" wrapper="fruits-by-color" group-adjacent="@color"/>

</p:declare-step>

Result document:

<fruits>
   <fruits-by-color>
      <fruit color="yellow" name="banana"/>
   </fruits-by-color>
   <fruits-by-color>
      <fruit color="orange" name="orange"/>
      <fruit color="orange" name="carrot"/>
   </fruits-by-color>
   <fruits-by-color>
      <fruit color="yellow" name="lemon"/>
   </fruits-by-color>
</fruits>

You might have expected that the result would group the fruits together by color, resulting in groups of elements, wrapped in <fruits-by-color> elements: one for banana+lemon and one for orange+carrot. But p:wrap groups sibling nodes that are adjacent to each other only. It does not do what would be called “group by”: all sibling nodes with the same value for the XPath expression together in a single group. If you need this, you will have to sort the document first. But unfortunately, XProc does not have anything on board for that. For more complex grouping, the advice is to use XSLT or XQuery.

Replacing comments by elements

This example shows that you can use p:wrap not only to wrap elements, but also other kinds of nodes. Here we use its functionality, together with the p:string-replace step, to change comments into elements. For this, we first wrap every element in a <comment> element and then turn these comments into text nodes using p:string-replace.

Source document:

<examples>
      <!--Comment 1-->
      <!--Another comment…-->
    </examples>

Pipeline document:

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

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

  <p:wrap match="comment()" wrapper="comment"/>
  <p:string-replace match="comment/comment()" replace="string(.)"/>

</p:declare-step>

Result document:

<examples>
   <comment>Comment 1</comment>
   <comment>Another comment…</comment>
</examples>