p:error (3.1) 

Raises an error.

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:

Port

Type

Primary?

Content types

Seq?

Description

source

input

true

text xml

true

The contents/message of the error raised.

result

output

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.1. This is a required step (an XProc 3.1 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.0.