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 | item()* | ✔ | |
| test | xs:boolean | true() |
Implementation details
| Implementation | Description |
|---|---|
| Defined | Precisely what “made available” means is implementation-defined. |
Declaration
<p:declare-step type="p:message">
<p:input port="source" sequence="true"/>
<p:output port="result" sequence="true"/>
<p:option name="test" as="xs:boolean" select="true()"/>
<p:option name="select" as="item()*" 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 option 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.