Selects parts of a document.
<p:declare-step type="p:filter"> <input port="source" primary="true" content-types="xml html" sequence="false"/> <output port="result" primary="true" content-types="text xml html" sequence="true"/> <option name="select" as="xs:string" required="true"/> </p:declare-step>
The p:filter
step selects parts of the source document based on a (possibly dynamically constructed) XPath select expression.
Ports:
Port | Type | Primary? | Content types | Seq? | Description |
---|---|---|---|---|---|
|
|
|
|
| The source document to select the parts from. |
|
|
|
|
| The selected parts, as separate documents. |
Options:
The p:filter
step takes the XPath select expression in its select
option, and with this select parts of the document
appearing on the source
port. The resulting document(s) (which might be zero, one or more) appear on the step’s
result
port.
This step behaves just like adding a select
attribute to an input port <p:with-input>
element. What the p:filter
step
adds is the ability to construct the XPath expression dynamically. See Using a dynamic select expression for an example of this.
The following example turns the single source document into a sequence of documents with information about bolts and pipes only.
<parts units="mm"> <screw diameter="4"/> <bolt length="35"/> <pipe diameter="4"/> </parts>
Pipeline document:
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0"> <p:input port="source"/> <p:output port="result" sequence="true"/> <p:filter select="/parts/(bolt | pipe)"/> </p:declare-step>
Result documents:
<bolt length="35"/>
<pipe diameter="4"/>
Since the XPath expression for the select
option is not dynamic, you don’t actually need the p:filter
step for this.
The exact same result is achieved using a select
attribute on a <p:with-input>
element. For instance like below, using the
p:identity
step:
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0"> <p:input port="source"/> <p:output port="result" sequence="true"/> <p:identity> <p:with-input select="/parts/(bolt | pipe)"/> </p:identity> </p:declare-step>
Assume you are only interested in parts with a certain diameter. This diameter is passed to the pipeline using an option (in the
example: required-diameter
). The following pipeline dynamically constructs an XPath expression for this in the p:filter
step
select
option. The input is the same as for the Basic usage example.
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" xmlns:xs="http://www.w3.org/2001/XMLSchema" version="3.0" exclude-inline-prefixes="#all"> <p:input port="source"/> <p:output port="result" sequence="true"/> <p:option name="required-diameter" as="xs:integer" select="4"/> <p:filter select="/parts/*[xs:integer(@diameter) eq {$required-diameter}]"/> </p:declare-step>
Result documents:
<screw diameter="4"/>
<pipe diameter="4"/>
Remark: The exclude-inline-prefixes="#all"
attribute on the pipeline root element is only there to prevent the xs
namespace declaration showing up on the output documents. A superfluous namespace declaration doesn’t matter but is unnecessary and looks
sloppy.
No document-properties from the source document survive.
The base-uri
document-property of the documents appearing on the result
port are the same as the base URI
of their root element in the source document.
This description of the p:filter
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:filter
step can be found here.
The p:filter
step is part of categories:
The p:filter
step is also present in version:
3.0.