p:filter (3.0)

Selects parts of a document.

Summary
Description
Examples
- Basic usage
- Using a dynamic select expression
Additional details
Reference information

Summary

<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:

Type	Port	Primary?	Content types	Seq?	Description
`input`	`source`	`true`	`xml html`	`false`	The source document to select the parts from.
`output`	`result`	`true`	`text xml html`	`true`	The selected parts, as separate documents.

Options:

Name	Type	Req?	Description
`select`	`xs:string` (XPath expression)	`true`	The XPath expression that selects the parts.

Description

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.

Examples

Basic usage

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>

Using a dynamic select expression

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.

Additional details

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.

Reference information

This description of the p:filter step is for XProc version: 3.0. This is a required step (an XProc 3.0 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.1.