Name

p:error — The standard p:error step.

Synopsis

The p:error step generates a dynamic error using the input provided to the step.

Input portPrimarySequenceContent types
source✔ ✔ text xml 
Output portPrimarySequenceContent types
result✔ ✔ any 
Option nameTypeRequired
codexs:QName✔ 
Declaration
1 |<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" type="p:error">
  |   <p:input port="source" sequence="true" content-types="text xml"/>
  |   <p:output port="result" sequence="true" content-types="any"/>
  |   <p:option name="code" required="true" as="xs:QName"/>
5 |</p:declare-step>

Description

The p:error step is a standard XProc 3.0 step. It is also described on XProcRef.org.

The code must be a QName. QName values and attribute value templates interact in some perhaps surprising ways.

  • This is an error:

      |<p:error code="Q{http://example.com/}local"/>

    Interpreted as an attribute value template, that’s lexically incorrect.

  • This is either an error or probably an unexpected result:

      |<p:error code="{Q{http://example.com/}local}"/>

    That sets the value of code to the string value of the element that matches the XPath expression “child::Q{http://example.com/}local” in the context document. If there is no context document, or if there are no elements that match the expression, or if multiple elements match the expression, that’s an error. If exactly one element matches the expression, it’s an error unless its string value happens to conform lexically to a QName.

  • This isn’t an error, but the namespace is ignored:

      |<p:error code="{fn:QName('http://example.com/', 'local')}"/>

    The string value (all attribute value templates are resolved to string values) of a QName without a prefix is just the local name, local. So this result is the same as code="local".

  • This may be correct, but it’s also possible for it to raise an error or produce an incorrect code:

      |<p:error code="{fn:QName('http://example.com/', 'ex:local')}"/>

    The string value of the attribute value template is ex:local. If there’s an in-scope namespace binding for the ex: prefix, that will be used regardless of whether or not it is bound to http://example.com/. If there is no in-scope namespace binding for ex:, it is an error.

  • This works:

      |<p:error xmlns:ex="http://example.com/" code="ex:local"/>

    The string value of the attribute value template is ex:local and the in-scope namespace binding for ex: is http://example.com/.

  • This works:

      |<p:error>
  |  <p:with-option name="code" select="QName('http://example.com/', 'local')"/>
  |</p:error>

    The value of the code option is computed without ever passing the result through a string value.

  • This works:

      |<p:error code="Q{{http://example.com/}}local"/>

    The string value is Q{http://example.com/}local which is a lexical representation of a QName.

Generally speaking, an option with a type of xs:QName is best set using p:with-option or using an attribute value template that includes a prefix that is known to be bound to the correct URI.

ⓘ
Note

In the c:errors document produced by p:error, the namespace prefix for the code value is usually, but not necessarily, the same as the prefix used in the pipeline document. (If the code is in a namespace, but no prefix is provided, a unique prefix will be created so that the lexical form in the c:error is always a lexical QName.)