p:error (3.0)

Raises an error.

Summary
Description
Examples
- Basic usage
Additional details
Reference information

Summary

<p:declare-step type="p:error">
  <input port="source" primary="true" content-types="text xml" sequence="true"/>
  <output port="result" primary="true" content-types="any" sequence="true"/>
  <option name="code" as="xs:QName" required="true"/>
</p:declare-step>

The p:error step raises a (dynamic) error, using the value of the code option as the error code. The document(s) on its source port become the error message(s).

Ports:

Type	Port	Primary?	Content types	Seq?	Description
`input`	`source`	`true`	`text xml`	`true`	The contents/message of the error raised.
`output`	`result`	`true`	`any`	`true`	This port is just there for the convenience of pipeline authors. Nothing will ever appear on this port (since `p:error` stops execution of the pipeline by raising an error).

Options:

Name	Type	Req?	Description
`code`	`xs:QName`	`true`	The code for the error raised.

Description

the p:error step raises a dynamic error, breaking the pipeline’s document flow.

An error has a code, which must be provided using the code option. An error code is a QName (a name with an optional namespace part). This code is shown in the resulting error message. You can also use this code for catching this specific error in a p:try/p:catch construction. Using a namespace in an error code raised by p:error is recommended because it then clearly distinguishes itself from errors raised by XProc itself.

The text or XML document(s) on the step’s source port become the error message(s) accompanying the error. They will return as the contents of the c:errors/c:error element(s) in the error report document produced by the error.

The p:error step also has a (primary) output port, but that is just for the convenience of the pipeline author: nothing will ever appear on it (since the flow is broken by the generated error). It makes it easier to insert a p:error in situations where a primary output port is required, for instance inside a p:if that tests whether an error must be raised.

Examples

Basic usage

The following example raises an error using p:error. Please notice that we use a namespace for the error code (which is recommended but not required).

Source document:

<result status="bad"/>

The example pipeline checks the result status. Watch out: the p:try/p:catch construction that surrounds p:error is there for example purposes only (don’t try this at home)! It takes care of showing the resulting error report document as the step’s result.

<p:declare-step xmlns:my="#my-application" xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result"/>

  <p:if test="/*/@status ne 'good'">
    <p:try>
      
      <p:error code="my:error">
        <p:with-input>
          <message>The status is not good but {/*/@status}</message>
        </p:with-input>
      </p:error>
      
      <p:catch name="error-catch">
        <p:identity>
          <p:with-input pipe="error@error-catch"/>
        </p:identity>
      </p:catch>
      
    </p:try>
  </p:if>

</p:declare-step>

The resulting error report document:

<c:errors xmlns:c="http://www.w3.org/ns/xproc-step">
   <c:error xmlns:my="#my-application"
            code="my:error"
            name="!1.1.1.1.1"
            type="p:error"
            href="file:/…/…/error-01.xpl"
            line="12"
            column="32">
      <message>The status is not good but bad</message>
   </c:error>
</c:errors>

Notice that in the example above the error message is inside a <message> element. Usually however, error messages are just text, strings. This can be accomplished by providing the error message on the p:error source port as a text document:

<p:declare-step xmlns:my="#my-application" xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result"/>

  <p:if test="/*/@status ne 'good'">
    <p:try>
      
      <p:error code="my:error">
        <p:with-input>
          <p:inline content-type="text/plain">The status is not good but {/*/@status}</p:inline>
        </p:with-input>
      </p:error>
      
      <p:catch name="error-catch">
        <p:identity>
          <p:with-input pipe="error@error-catch"/>
        </p:identity>
      </p:catch>
      
    </p:try>
  </p:if>

</p:declare-step>

The resulting error report document:

<c:errors xmlns:c="http://www.w3.org/ns/xproc-step">
   <c:error xmlns:my="#my-application"
            code="my:error"
            name="!1.1.1.1.1"
            type="p:error"
            href="file:/…/…/error-02.xpl"
            line="12"
            column="32">The status is not good but bad</c:error>
</c:errors>

Additional details

If more than one document appears on the source port of p:error, all source documents become children of a single <p:error> element.

Reference information

This description of the p:error 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:error step can be found here.

The p:error step is part of categories:

The p:error step is also present in version: 3.1.