Splits a sequence of documents.
<p:declare-step type="p:split-sequence"> <input port="source" primary="true" content-types="any" sequence="true"/> <output port="matched" primary="true" content-types="any" sequence="true"/> <output port="not-matched" primary="false" content-types="any" sequence="true"/> <option name="test" as="xs:string" required="true"/> <option name="initial-only" as="xs:boolean" required="false" select="false()"/> </p:declare-step>
The p:split-sequence
step takes a sequence of documents on its source
port and divides this into two sequences, based on the evaluation
expression in the test
option and the value of the initial-only
option.
Ports:
Port | Type | Primary? | Content types | Seq? | Description |
---|---|---|---|---|---|
|
|
|
|
| The incoming sequence of documents to split. |
|
|
|
|
| The documents from the If the |
|
|
|
|
| The documents from the If the |
Options:
The p:split-sequence
step works like a switch in a train marshalling yard. A train with document wagons approaches the switch. The switchman has
instructions to send a wagon in one direction or the other, depending on the contents of the document. In more technical terms:
The p:split-sequence
step takes a sequence of documents on its source
port.
For every document, the XPath boolean expression in the test
option is evaluated. During this evaluation, the document
is the context item (accessible with the dot operator .
).
The position()
and last()
functions are available to get the position of the document in the sequence and the
size of the sequence (see also the Using the position() and last() function example).
If the initial-only
option is false
:
If the result of the test
option evaluation is true
, the document appears on the matched
port.
If the result of the test
option evaluation is false
, the document appears on the
not-matched
port.
If the initial-only
option is true
:
If the result of the test
option evaluation is true
, the document appears on the matched
port, until a document appears for which this expression evaluates to false
.
The first document for which the test
option evaluation is false
and all subsequent
documents are sent to the not-matched
port.
In other words: it only writes the initial series of matched documents (which may be empty) to the matched
port. All other
documents are written to the not-matched
port, irrespective of the outcome of the test
option
evaluation.
This example defines a sequence of <fruit>
documents for the source
port and splits them based on their
color
attribute. The final p:wrap-sequence
step is only there to be able to show the result as a single
document.
Pipeline document:
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0"> <p:input port="source" sequence="true"> <fruit name="banana" color="yellow"/> <fruit name="orange" color="orange"/> <fruit name="lemon" color="yellow"/> <fruit name="cauliflower" color="white"/> </p:input> <p:output port="result"/> <p:split-sequence test="/*/@color eq 'yellow'"/> <p:wrap-sequence wrapper="matched-documents"/> </p:declare-step>
Result document:
<matched-documents> <fruit color="yellow" name="banana"/> <fruit color="yellow" name="lemon"/> </matched-documents>
All the other source documents appear on the not-matched
port, as the following example proofs:
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0"> <p:input port="source" sequence="true"> <fruit name="banana" color="yellow"/> <fruit name="orange" color="orange"/> <fruit name="lemon" color="yellow"/> <fruit name="cauliflower" color="white"/> </p:input> <p:output port="result"/> <p:split-sequence test="/*/@color eq 'yellow'"/> <p:wrap-sequence wrapper="not-matched-documents"> <p:with-input pipe="not-matched"/> </p:wrap-sequence> </p:declare-step>
Result document:
<not-matched-documents> <fruit color="orange" name="orange"/> <fruit color="white" name="cauliflower"/> </not-matched-documents>
This example shows what happens to the Basic usage example when we set the initial-only
option to
true
. The second source document (about oranges) does not match, so this and all
subsequent documents are considered not-matched and sent to the not-matched
port. Only the first source document (about bananas)
appears on the matched
port.
Pipeline document:
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0"> <p:input port="source" sequence="true"> <fruit name="banana" color="yellow"/> <fruit name="orange" color="orange"/> <fruit name="lemon" color="yellow"/> <fruit name="cauliflower" color="white"/> </p:input> <p:output port="result"/> <p:split-sequence test="/*/@color eq 'yellow'" initial-only="true"/> <p:wrap-sequence wrapper="matched-documents"/> </p:declare-step>
Result document:
<matched-documents> <fruit color="yellow" name="banana"/> </matched-documents>
The following example shows that, during evaluation of the test
option, the position()
and last()
functions are available to get the position of the document in the sequence and the size of the sequence. It uses this to match the last
document only.
Pipeline document:
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0"> <p:input port="source" sequence="true"> <fruit name="banana" color="yellow"/> <fruit name="orange" color="orange"/> <fruit name="lemon" color="yellow"/> <fruit name="cauliflower" color="white"/> </p:input> <p:output port="result"/> <p:split-sequence test="position() eq last()"/> <p:wrap-sequence wrapper="matched-documents"/> </p:declare-step>
Result document:
<matched-documents> <fruit color="white" name="cauliflower"/> </matched-documents>
p:split-sequence
preserves all document-properties of the document(s) appearing on its source
port.
Error code | Description |
---|---|
It is a dynamic error if evaluating the XPath expression in option |
This description of the p:split-sequence
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:split-sequence
step can be found here.
The p:split-sequence
step is part of categories:
The p:split-sequence
step is also present in version:
3.0.