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-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
="
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.