The p:message step conditionally produces a message.
Summary
| Input port | Primary | Sequence | Content types |
|---|---|---|---|
| source | ✔ | ✔ |
| Output port | Primary | Sequence | Content types |
|---|---|---|---|
| result | ✔ | ✔ |
| Option name | Type | Default value | Required |
|---|---|---|---|
| select | xs:stringitem()* | ✔ | |
| test | xs:boolean | true() |
Implementation details
| Implementation | Description |
|---|---|
| Defined | Precisely what “made available” means is implementation-defined. |
Declaration
<p:declare-steptype="p:message">
<p:inputport="source"sequence="true"/>
<p:outputport="result"sequence="true"/>
<p:optionname="test"as="xs:boolean"select="true()"/>
<p:optionname="select"as="xs:stringitem()*"required="true"/> </p:declare-step>
Steps that produce messages offer one way for an author to keep track of the progress of a pipeline. The [p:]message attribute can be added to any step to display a message when it runs.
Status and debugging messages that are appropriate during pipeline development may be distracting when the pipeline is running “in production”. Existing mechanisms for conditional compilation can be used to mediate between “development” and “production” runs, but they are a bit heavyweight. Adding many steps with [p:]use-when attributes and managing the connections between steps that may be conditionally removed can make pipelines harder to read and understand.
The p:message step can be used to achieve much the same effect and is considerably less verbose.
If the test attribute is “true”, the result of evaluating the select expression is evaluatedoption is serialized and made available. (As with the message attribute, this is intentionally vague. Precisely what “made available” means is implementation-defined. Often it means “printed on the console”.)
Irrespective of the value of the test attribute, the p:message passes all of the documents that appear on its source port through to the result port, unchanged and in the same order.
If exactly one document appears on the source port, it is the context item when the test and select expressions are evaluated. In all other cases, the context item is undefined.
Note
If it can be determined statically that test expression is always “false”, the processor may remove the step from the pipeline entirely, although it must guarantee that all of the connections are preserved.
Document properties
All document properties are preserved.
A. Conformance
Conformant processors must implement all of the features described in this specification except those that are explicitly identified as optional.
Some aspects of processor behavior are not completely specified; those features are either implementation-dependent or implementation-defined.
[Definition: An implementation-dependent feature is one where the implementation has discretion in how it is performed. Implementations are not required to document or explain how implementation-dependent features are performed.]
[Definition: An implementation-defined feature is one where the implementation has discretion in how it is performed. Conformant implementations must document how implementation-defined features are performed.]
The following features are implementation-defined:
- Precisely what “made available” means is implementation-defined. See Section 2.1, “p:message”.
B. References
[XProc 3.1] XProc 3.1: An XML Pipeline Language. Norman Walsh, Achim Berndzen, Gerrit Imsieke and Erik Siegel, editors.
C. Glossary
- implementation-defined
An implementation-defined feature is one where the implementation has discretion in how it is performed. Conformant implementations must document how implementation-defined features are performed.
- implementation-dependent
An implementation-dependent feature is one where the implementation has discretion in how it is performed. Implementations are not required to document or explain how implementation-dependent features are performed.
D. Ancillary files
This specification includes by reference a number of ancillary files.
- steps.xpl
An XProc step library for the declared steps.