Raises an error.
<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 |
---|---|---|---|---|---|
|
|
|
|
| The contents/message of the error raised. |
|
|
|
|
| This port is just there for the convenience of pipeline authors. Nothing will ever appear on this port (since |
Options:
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.
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>
If more than one document appears on the source
port of p:error
, all source documents become children of a single
<p:error>
element.
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.