Unwraps elements in a document.
<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 |
---|---|---|---|---|---|
|
|
|
|
| The document to unwrap the matched elements in. |
|
|
|
|
| The resulting document. |
Options:
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
.
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>
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.
Error code | Description |
---|---|
It is a dynamic error if the selection pattern matches a wrong type of node. |
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.