p:unwrap (3.1) 

Summary

<p:declare-step type="p:unwrap">
  <input port="source" primary="true" content-types="xml html" sequence="false"/>
  <output port="result" primary="true" content-types="text xml html" sequence="false"/>
  <option name="match" as="xs:string" required="false" select="'/*'"/>
</p:declare-step>

The p:unwrap step unwraps element nodes, specified by an XSLT selection pattern, from the document appearing on its source port. Unwrapping means: remove the matched element (including any attributes), but keep all its children.

Ports:

Options:

Description

The p:unwrap step takes the XSLT match pattern in the match option and holds this against the document appearing on its source port. This pattern must match element nodes (or the document-node). Matching elements are unwrapped: removed (including any attributes) but their child nodes remain. The resulting document appear on the result port.

If you want to remove an element including child nodes you need p:delete.

Examples

<person>
   <name>
      <firstname>John</firstname>
      <lastname>Doe</lastname>
      <spouse>
         <name>
            <firstname>Clara</firstname>
            <lastname>Doe</lastname>
         </name>
      </spouse>
   </name>
</person>

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

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

  <p:unwrap match="name"/>

</p:declare-step>

<person>
   <firstname>John</firstname>
   <lastname>Doe</lastname>
   <spouse>
      <firstname>Clara</firstname>
      <lastname>Doe</lastname>
   </spouse>
</person>

Additional details

• In most cases, p:unwrap preserves all document-properties of the document appearing on its source port.

• For documents consisting of just a root-element containing text: if this root-element is unwrapped, the result is a document-node with a single text node child. This changes the result document’s content-type (its content-type property) to text/plain. The serialization document-property, if present, is removed.

• If a document consisting of only an empty root-element is unwrapped, the result will be a document-node without any children. The result document’s content type does not change if you do this.

• If you unwrap the document-node (set the match property to /) nothing will happen.

• It’s possible to produce non well-formed XML using this step. Unwrapping the root-element from the following document (<p:unwrap match="/*"/> or simply <p:unwrap/>) produces a result with just a single comment node, which is not well-formed:

  <!-- Some comment -->
  <root/>

  XProc does not care about this, it keeps calm and carries on. However, writing this result to disk might not be what you expect.

Errors raised

Reference information

This description of the p:unwrap 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:unwrap step can be found here.

The p:unwrap step is part of categories:

• Standard XProc steps

• Basic XML manipulation

The p:unwrap step is also present in version: 3.0.