p:unwrap (3.1) 

Unwraps elements in a document.

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:

Port

Type

Primary?

Content types

Seq?

Description

source

input

true

xml html

false

The document to unwrap the matched elements in.

result

output

true

text xml html

false

The resulting document.

Options:

Name

Type

Req?

Default

Description

match

xs:string (XSLT selection pattern)

false

/*

The XSLT match pattern for the nodes to unwrap, as a string. This must match element nodes (or the document-node). If any other kind of node is matched, error XC0023 is raised.

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

Basic usage

The following example unwraps all <name> elements. Note that nested <name> elements are also unwrapped.

Source document:

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

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:unwrap match="name"/>

</p:declare-step>

Result document:

<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

Error code

Description

XC0023

It is a dynamic error if the selection pattern matches a wrong type of node.

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:

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