p:message (3.1)

Produces a message.

Summary
Description
Examples
- Basic usage
Additional details
Reference information

Summary

<p:declare-step type="p:message">
  <input port="source" primary="true" content-types="any" sequence="true"/>
  <output port="result" primary="true" content-types="any" sequence="true"/>
  <option name="select" as="item()*" required="true"/>
  <option name="test" as="xs:boolean" required="false" select="true()"/>
</p:declare-step>

The p:message step produces a message that is, usually, printed on the console. The effect (when the test option is true) is the same as using a message/p:message attribute on a step.

Ports:

Port	Type	Primary?	Content types	Seq?	Description
`source`	`input`	`true`	`any`	`true`	The source document(s)
`result`	`output`	`true`	`any`	`true`	The resulting document(s). These will be exactly the same as what appeared on the `source` port.

Options:

Name	Type	Req?	Default	Description
`select`	`item()*` (XPath expression)	`true`		The message to produce
`test`	`xs:boolean`	`false`	`true`	If `true`, the message in the `select` attribute is produced.

Description

Steps in general can produce messages by using the message (for steps in the XProc namespace) or p:message (for steps in other namespaces) attribute. What “produce” here actually means is implementation-defined and therefore depends on the XProc processor used. However, usually it means “printed on the console” and/or “output through stdout”: a command-line message appears when the processor executes the step.

The p:message step is an alternative way to produce these messages. When the test option is true (default), the expression in the select option is evaluated and the result is produced/shown, as a message. If the test option is false, nothing happens.

The step itself, irrespective of the value of the test option, simply passes what it gets on its source port unaltered to its result port. In other words, it acts as a p:identity step.

Examples

Basic usage

Assume you have a pipeline that does some preliminary things (getting documents, computing variables, etc.) and then starts the real computation of something. In-between you want a message that says the computation has started, but only when enabled by an option. Here is an example of how to do this using the p:message step:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" xmlns:xs="http://www.w3.org/2001/XMLSchema" version="3.0">

  <p:input port="source"/>
  <p:output port="result"/>
  
  <p:option name="debug-messages-on" as="xs:boolean" select="true()"/>
  
  <!-- Some preliminary stuff… -->

  <p:message test="{$debug-messages-on}" select="'Starting computation at ' || current-dateTime()"/>
  
  <!-- Steps that implement the computation… -->

</p:declare-step>

It is certainly possible to implement this without the p:message step, using a p:identity step with a message attribute:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" xmlns:xs="http://www.w3.org/2001/XMLSchema" version="3.0">

  <p:input port="source"/>
  <p:output port="result"/>
  
  <p:option static="true" name="debug-messages-on" as="xs:boolean" select="true()"/>
  
  <!-- Some preliminary stuff… -->

  <p:identity use-when="$debug-messages-on" message="Starting computation at {current-dateTime()}"/>
  
  <!-- Steps that implement the computation… -->

</p:declare-step>

Please notice the differences between the two examples:

In the first example the on/off switch for the message, here the debug-messages-on option, is dynamic. It can be computed/set during run-time, if necessary.
However, in the second example, this on/off switch is referenced in a use-when attribute. All use-when attributes are evaluated during compile-time, and therefore the debug-messages-on option must be static (hence its static="true" attribute). The only time you can change/set this option, and turn messages on/off, is when invoking the pipeline.
The select option of the p:message step is an XPath expression. The value of the message attribute is an AVT (Attribute-Value Template). This results in a very different syntax, while the result is identical.

Additional details

p:message preserves all document-properties of the document(s) appearing on its source port.

Reference information

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

The p:message step is part of categories: