The p:input element describes a step input.

The input in Example 2.3, “A pipeline input” has the port name “copyright” and accepts only XML documents. If it’s the only input, it will be primary. The input doesn’t specify sequence="true", so a single document is required.

  |<p:input port="copyright" content-types="xml"/>

The p:output element describes a step output. There are three slightly different forms, depending on where the output is being declared. The pipeline and compound step forms are the same except that on a pipeline, serialization parameters may also be declared.

The output in Example 2.4, “A pipeline output” has the port name “result”. The pipeline result must be a single text document.

The notes about the attributes on p:input apply to p:output. In addition, p:output has a pipe attribute that is a shortcut for p:pipe bindings. On a p:declare-step it may also have a map of serialization parameters.

  |<p:output port="result" content-types="text"/>

On a compound step, no serialization can occur, so it would be pointless to specify them.

On the declaration of an atomic step, you also cannot provide any connections.

The output on the cx:fileset declaration indicates that the step can produce a sequence of XML documents.

  |<p:output port="result" content-types="xml" sequence="true"/>

Options are declared with the p:option element.

Options can be required or have a default value and they can be typed.

The compound step declaration in Example 2.1, “A compound step declaration” declares three options:

  |<p:option name="path" required="true" as="xs:string"/>
  |<p:option name="output-path" required="true" as="xs:anyURI"/>
  |<p:option name="recurse" select="false()" as="xs:boolean"/>

The path and output-path options are required and must be a string and a URI, respectively (there’s no practical reason to make them different types in this case, it’s just to make the example more interesting). The recurse option is not required and will default to “false”.

Options can be declared static:

Options inside a p:library must be declared static.

It must be possible to evaluate a static option without reference to any pipeline input documents. It is evaluated “at compile time”. You may not shadow a static option with another option or p:variable.

Several steps (and static options) can be bundled together in a library.

A collection of step declarations and (static) options can be put inside a p:library so that they can all be imported together.

The notes about the attributes on p:declare-step apply to p:library.

A library (or a single step) can be imported.

The document URI must identify a pipeline or library document.

XML Calabash provides URIs for importing its extension steps. For example, https://xmlcalabash.com/ext/library/fileset.xpl for the cx:fileset extension step. Generally speaking, the specified URI is retrieved and parsed for its declarations. The library URIs that XML Calabash provides for its extension steps are resolved internally, without accessing the internet.

XML Calabash can also import functions defined in XSLT or XQuery.

Importing functions allows them to be used in expressions in the pipeline.

The stylesheet in Example 2.7, “A function library in XSLT” defines two functions, f:is-leap-day with no arguments and f:is-leap-day with a single date argument.

 1 |<?xml version="1.0" encoding="utf-8"?>
   |<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   |                xmlns:xs="http://www.w3.org/2001/XMLSchema"
   |                xmlns:f="http://example.com/ns/functions"
 5 |                exclude-result-prefixes="xs"
   |                version="3.0">
   | 
   |<xsl:function name="f:is-leap-day">
   |  <xsl:sequence select="f:is-leap-day(current-date())"/>
10 |</xsl:function>
   | 
   |<xsl:function name="f:is-leap-day">
   |  <xsl:param name="date"/>
   |  <xsl:choose>
15 |    <xsl:when test="$date instance of xs:date">
   |      <xsl:sequence select="month-from-date($date) = 2
   |                            and day-from-date($date) = 29"/>
   |    </xsl:when>
   |    <xsl:when test="$date instance of xs:dateTime">
20 |      <xsl:sequence select="month-from-dateTime($date) = 2
   |                            and day-from-dateTime($date) = 29"/>
   |    </xsl:when>
   |    <xsl:when test="$date castable as xs:date">
   |      <xsl:variable name="dt" select="$date cast as xs:date"/>
25 |      <xsl:sequence select="month-from-date($dt) = 2
   |                            and day-from-date($dt) = 29"/>
   |    </xsl:when>
   |    <xsl:when test="$date castable as xs:dateTime">
   |      <xsl:variable name="dt" select="$date cast as xs:dateTime"/>
30 |      <xsl:sequence select="month-from-date($dt) = 2
   |                            and day-from-date($dt) = 29"/>
   |    </xsl:when>
   |    <xsl:otherwise>
   |      <xsl:sequence select="false()"/>
35 |    </xsl:otherwise>
   |  </xsl:choose>
   |</xsl:function>
   | 
   |</xsl:stylesheet>

After the library has been imported, the functions that it defines can be used in XPath expressions in the pipeline. The pipeline in Example 2.8, “Using the function library” outputs a single document that answers the questions, “is today a leap day and is 29 February 2028 a leap day?”

 1 |<p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
   |                xmlns:f="http://example.com/ns/functions"
   |                name="main" version="3.1">
   |  <p:documentation>
 5 |    <div xmlns="http://www.w3.org/1999/xhtml">
   |      <p>Example of importing functions. This requires Saxon EE.</p>
   |    </div>
   |  </p:documentation>
   | 
10 |  <p:import-functions href="is-leap-day.xsl"/>
   | 
   |  <p:output port="result" serialization="map{'indent':true()}"/>
   |    
   |  <p:identity>
15 |    <p:with-input exclude-inline-prefixes="#all">
   |      <leap-days>
   |        <today date="{substring(string(current-date()), 1, 10)}"
   |               >{f:is-leap-day()}</today>
   |        <other date="2028-02-29"
20 |               >{f:is-leap-day('2028-02-29')}</other>
   |      </leap-days>
   |    </p:with-input>
   |  </p:identity>
   |</p:declare-step>

If you have Saxon EE and you run the pipeline, the output will be something like:

<leap-days>
   <today date="2025-07-26">false</today>
   <other date="2028-02-29">true</other>
</leap-days>

Note that the p:output element in the pipeline uses the serialization options to pretty-print the output and the p:with-input uses exclude-inline-prefixes to avoid having the namespace declaration for “f” on the output.

The p:document element (or the href attribute on p:with-input) connects an input to document identified with a URI.

The document properties will be applied to the result. The parameters me be used during document access.

The p:inline element connects an input to a document placed into the pipeline directly.

The p:inline element can be omitted in the simple case of a single XML document.

This p:inline element specifies that it is text. Attribute value templates in the body are used to evaluate expressions.

  |<p:inline content-type="text/plain">Processed {$total} files; {f:is-leap-day()}&#10;</p:inline>

The p:pipe element (or the pipe attribute on p:with-input) connects an input to the output from some other step. If step is omitted, the step associated with the default readable port is assumed. If port is omitted, the primary output port of the step is assumed. (Consequently, <p:pipe/> is a connection to the default readable port.) It’s an error to attempt to refer to the default readable port if there isn’t one.

The p:identity step in the viewport users a pipe attribute to make a pipe binding:

  |<p:with-input pipe="copyright@main"/>

The variable declaration for $total uses the p:pipe step to make a pipe binding. In the context of a variable, this establishes the context item used when evaluating the expression.

  |<p:pipe step="listing"/>

The p:empty element explicitly binds the input to an empty sequence of documents.

The p:for-each step loops over sequence of documents, processing each with its subpipeline.

The p:for-each in Example 2.9, “Looping with for-each” loops over the c:file elements from the p:directory-list step, but each one will be in its own document.

  |<p:for-each name="loop">
  |  <p:with-input select="//c:file"/>
  |…
  |</p:for-each>

In principle, a p:for-each can process its inputs in parallel. XML Calabash does not do so at this time.

The p:viewport step replaces sections of a document with the result of processing (a document containing) those sections using the subpipeline.

The p:viewport in Example 2.10, “Matching with viewport” matches each copyright element where the holder is “Someone Random” and replaces that element with the result of its subpipeline, in this case, with the contents of the document on the copyright input port.

1 |<p:viewport match="copyright[. = 'Someone Random']">
  |  <p:identity>
  |    <p:with-input pipe="copyright@main"/>
  |  </p:identity>
5 |</p:viewport>

The p:choose step allows you to select processing among a number of alternatives. At most one alternative will be used: either the first p:when (in document order) for which the test expression is true or the p:otherwise.

The example pipeline in Example 2.11, “An example choice” uses p:choose to select which stylesheet to use when formatting a document based on the document status.

 1 |<p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
   |                xmlns:c="http://www.w3.org/ns/xproc-step"
   |                xmlns:cx="http://xmlcalabash.com/ns/extensions"
   |                xmlns:xs="http://www.w3.org/2001/XMLSchema" 
 5 |                xmlns:ex="http://example.com/ns"
   |                name="main" version="3.1" type="ex:format">
   |  <p:input port="source"/>
   |  <p:output port="result"/>
   | 
10 |  <p:choose>
   |    <p:when test="/*/@status = 'draft'">
   |      <p:xslt>
   |        <p:with-input port="stylesheet" href="draft.xsl"/>
   |      </p:xslt>
15 |    </p:when>
   |    <p:when test="/*/@status = 'final'">
   |      <p:with-input pipe="source"/>
   |      <p:xslt>
   |        <p:with-input port="stylesheet" href="final.xsl"/>
20 |      </p:xslt>
   |    </p:when>
   |    <p:otherwise>
   |      <p:error code="ex:bad-status">
   |        <p:with-input>
25 |          <p:inline content-type="text/plain">Unexpected status</p:inline>
   |        </p:with-input>
   |      </p:error>
   |    </p:otherwise>
   |  </p:choose>
30 |</p:declare-step>

Each alternative is a p:when which contains the subpipeline to run if this alternative is selected.

The first (and only the first) p:when where the test expression evaluates to true is used.

The first p:when selects documents with a status of “draft”:

1 |<p:when test="/*/@status = 'draft'">
  |  <p:xslt>
  |    <p:with-input port="stylesheet" href="draft.xsl"/>
  |  </p:xslt>
5 |</p:when>

The second p:when selects documents with a status of “final”. This example includes an explicit binding for the input that will be used to set the context item for the test expression. It’s unnecessary as it’s the same as the default readable port in this case.

1 |<p:when test="/*/@status = 'final'">
  |  <p:with-input pipe="source"/>
  |  <p:xslt>
  |    <p:with-input port="stylesheet" href="final.xsl"/>
5 |  </p:xslt>
  |</p:when>

The p:otherwise contains the subpipeline to run if no other alternative is selected.

The p:otherwise in this example raises an error if the status is neither draft nor final:

1 |<p:otherwise>
  |  <p:error code="ex:bad-status">
  |    <p:with-input>
  |      <p:inline content-type="text/plain">Unexpected status</p:inline>
5 |    </p:with-input>
  |  </p:error>
  |</p:otherwise>

The p:if is a simplified form of p:choose. If the test expression is true, then the subpipeline is run and that determines the output from the step. If the expression is false, p:if operates as an identity step, passing its input through unchanged.

The notes about the attributes on p:when apply to p:if.

The p:if in Example 2.12, “Using an if instruction” deletes the count attribute if it has the value “0”.

  |<p:if test="xs:integer(/doc/@count) = 0">
  |  <p:delete match="/doc/@count"/>
  |</p:if>

If the attribute has any other value (or isn’t present), the document passes through as if it was an p:identity step.

The p:group step is just a wrapper around a subpipeline.

The p:try step allows a pipeline author to catch errors and recover from them. The subpipeline is run. If no errors occur, the result of the step is the result of that subpipeline. If an error does occur, each p:catch is tested in turn and the result of the step is the result of the first matching p:catch.

The example for p:choose raises an error if the status is neither “draft” nor “final”. We can use p:try to recover from that error and treat any such document as if it had draft status, as shown in Example 2.13, “An example try/catch”.

 1 |<p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
   |                xmlns:c="http://www.w3.org/ns/xproc-step"
   |                xmlns:cx="http://xmlcalabash.com/ns/extensions"
   |                xmlns:xs="http://www.w3.org/2001/XMLSchema" 
 5 |                xmlns:ex="http://example.com/ns"
   |                name="main" version="3.1">
   |  <p:import href="choose.xpl"/>
   | 
   |  <p:input port="source"/>
10 |  <p:output port="result"/>
   | 
   |  <p:try>
   |    <ex:format/>
   |    <p:catch code="ex:bad-status">
15 |      <p:xslt>
   |        <p:with-input port="source" pipe="source@main"/>
   |        <p:with-input port="stylesheet" href="draft.xsl"/>
   |      </p:xslt>
   |    </p:catch>
20 |  </p:try>
   |</p:declare-step>

A p:catch matches an error if the error code is in its code list, or if it does not have a code attribute at all.

If there are no matching catches, the p:try step fails with the error (which may be caught and handled by some p:try among its ancestors, if it has any.)

Note that the default readable port inside the p:catch is the error document produced by the failed pipeline. You have to make an explicit binding if you want something else.

Irrespective of whether the subpipeline succeeds or fails and whether or not a catch is invoked (and whether or not it succeeds or fails), the p:finally subpipeline will be run.

It is very uncommon for this to be useful. One plausible use case is for the finally step to clean up any side effects that might have been introduced by the subpipeline or the catch expressions, for example, deleting a temporary file or closing a database connection.

This is an extension compound step that processes single documents, applying its subpipeline until the test expression is true.

The test attribute specifies an XPath expression. The subpipeline is always run at least once and the condition is only tested at the end of the loop. The result of the subpipeline is provided as the context item. The previous result is provided in the variable cx:previous.

The pipeline Example 2.14, “Looping until a condition is true” demonstrates a horribly inefficient way to add explicit numbers to a list.

 1 |<p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
   |                xmlns:c="http://www.w3.org/ns/xproc-step"
   |                xmlns:cx="http://xmlcalabash.com/ns/extensions"
   |                xmlns:xs="http://www.w3.org/2001/XMLSchema" 
 5 |                exclude-inline-prefixes="#all"
   |                name="main" version="3.1">
   |  <p:output port="result" serialization="map{'indent':true()}"/>
   | 
   |  <p:identity name="identity">
10 |    <p:with-input>
   |      <list>
   |        <item/>
   |        <item/>
   |        <item/>
15 |      </list>
   |    </p:with-input>
   |  </p:identity>
   | 
   |  <cx:until test="deep-equal(., $cx:previous)">
20 |    <p:replace match="/list/item[1]">
   |      <p:with-input port="replacement">
   |        <li number="{p:iteration-position()}"/>
   |      </p:with-input>
   |    </p:replace>
25 |  </cx:until>
   | 
   |</p:declare-step>

The first time through the loop, the first item is replaced. The next time through, the next item is replaced, etc. Looping stops when nothing changes in the document (that is, when all the items have been replaced).

The result of the cx:until step is first document for which the test expression is true. In this case, the result is:

1 |<list>
  |   <li number="1"/>
  |   <li number="2"/>
  |   <li number="3"/>
5 |</list>

It is a dynamic error (err:XD0001) if the source is not a single document.

This is an extension compound step that processes single documents, applying its subpipeline while the test expression is true.

The somewhat contrived example in Example 2.15, “Looping while a condition is true” loops over the document adding a new first child until the count reaches zero.

 1 |<p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
   |                xmlns:c="http://www.w3.org/ns/xproc-step"
   |                xmlns:cx="http://xmlcalabash.com/ns/extensions"
   |                xmlns:xs="http://www.w3.org/2001/XMLSchema" 
 5 |                exclude-inline-prefixes="#all"
   |                name="main" version="3.1">
   |  <p:output port="result" serialization="map{'indent':true()}"/>
   | 
   |  <p:identity name="identity">
10 |    <p:with-input>
   |      <doc count="3"/>
   |    </p:with-input>
   |  </p:identity>
   | 
15 |  <cx:while test="/doc/@count and xs:integer(/doc/@count) gt 0">
   |    <p:insert position="first-child">
   |      <p:with-input port="insertion">
   |        <insertion for="{/doc/@count}"/>
   |      </p:with-input>
20 |    </p:insert>
   | 
   |    <p:add-attribute attribute-name="count" attribute-value="{xs:integer(/doc/@count) - 1}"/>
   | 
   |    <p:if test="xs:integer(/doc/@count) = 0">
25 |      <p:delete match="/doc/@count"/>
   |    </p:if>
   |  </cx:while>
   | 
   |</p:declare-step>

The result of the cx:while step is first document for which the test expression did not have an effective boolean value of true. In this case, the result is:

1 |<doc>
  |   <insertion for="1"/>
  |   <insertion for="2"/>
  |   <insertion for="3"/>
5 |</doc>

It is a dynamic error (err:XD0001) if the source is not a single document.

The test attribute specifies an XPath expression. The document is provided as the context item. If the expression is false, the loop is not run (or run again).