XProc 3.0: dynamic pipeline execution

Draft Community Group Report

Editor's Draft at (build 8)
Latest editor’s draft:
https://spec.xproc.org/master/head/run/
Editors:
Norman Walsh
Achim Berndzen
Gerrit Imsieke
Erik Siegel
Participate:
GitHub xproc/3.0-steps
Report an issue
Changes:
Diff against current “status quo” draft
Commits for this specification

This document is also available in these non-normative formats: XML and HTML with automatic change markup courtesy of DeltaXML.


Abstract

This specification describes the p:run step for XProc 3.0: An XML Pipeline Language.

Status of this Document

This document is an editor's draft that has no official standing.

This specification was published by the XProc Next Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

If you wish to make comments regarding this document, please send them to xproc-dev@w3.org. (subscribe, archives).

1. Introduction

This specification describes the p:run XProc step. A machine-readable description of this step may be found in steps.xpl.

Familarity with the general nature of [XProc 3.0] steps is assumed; for background details, see [XProc 3.0 Steps].

2. p:run

The p:run step runs a dynamically loaded pipeline.

<p:run
  name? = NCName>
    (p:with-input? &
     p:run-input* &
     p:run-option* &
     p:output*)
</p:run>

The p:run step has a single, anonymous input that accepts the pipeline to be run. Otherwise, it functions similar to an atomic step in that you can define input connections and option values for it, albeit not with the usual p:with-input and p:with-option connections.

The p:run step expects a single pipeline document on its anonymous input port (“pipeline port”). Independent of how the pipeline is provided, it must have a version attribute on its root element. It is a dynamic error (err:XC0200) if the pipeline input to the p:run step is not a valid pipeline. The anonymous input port is not primary, although it is the only p:input port of p:run. Therefore it will not automatically connect to the default readable port (see Connections in XProc 3.0: An XML Pipeline Language); it needs to be connected to its pipeline input explicitly.

The pipeline that appears on the pipeline port is evaluated using the inputs and options specified on the p:run step by means of the p:run-input and p:run-option elements, respectively.

The p:run-input element is a special case of the p:with-input element for passing inputs to the pipeline being run.

<p:run-input
  port = NCName
  select? = XPathExpression
  href? = { anyURI }
  pipe? = string
  primary? = boolean
  exclude-inline-prefixes? = ExcludeInlinePrefixes>
    ((p:empty |
       (p:document |
        p:pipe |
        p:inline)*) |
     anyElement*)
</p:run-input>

Similarly, the p:run-option element is a special case of the p:with-option element for passing options to the pipeline being run.

<p:run-option
  name = EQName
  as? = XPathSequenceType
  select = XPathExpression
  collection? = boolean
  href? = { anyURI }
  pipe? = string
  static? = boolean
  exclude-inline-prefixes? = ExcludeInlinePrefixes>
    ((p:empty |
       (p:document |
        p:pipe |
        p:inline)*) |
     anyElement*)
</p:run-option>

In terms of binding inputs and options, these elements have the same syntax and semantics as p:with-input and p:with-option. In addition, the boolean attribute primary can be used on p:run-input to declare whether the respective port of the dynamically executed pipeline is expected to be the primary input port. If the attribute is omitted, it is assumed to be “false” if there are multiple p:run-input connections and “true” if there is exactly one p:run-input connection. It is a dynamic error (err:XC0201) if the dynamically executed pipeline implicitly or explicitly declares a primary input port with a different name than implicitly or explicitly specified in the p:run invocation. Input ports of the dynamically executed pipeline that are not declared with p:run-input on the p:run invocation will receive a p:empty connection. Input ports that are declared in p:run-input but not in the dynamically executed pipeline will be silently ignored.

The context item used to evaluate expressions on p:run-option comes from the default readable port of the p:run step. Additionally, if p:run-input implicitly or explicitly identifies a primary input port, the default readable port will be connected to it if no explicit connection is provided.

Other than p:with-option, p:run-option accepts a boolean attribute static that defaults to “false”. If it is “true”, the option value will be supplied to static analysis of the executed pipeline as a static option with the same name.

Options of the dynamically executed pipeline that are not declared with p:run-option on the p:run invocation will receive an empty sequence as their value. Options that are declared on p:run-option but not in the dynamically executed pipeline will be silently ignored.

Each output port of the pipeline can appear as a same-named output port of the p:run step. In order for this to happen, the port needs to be explicitly declared in the p:run step. In contrast to output declarations of compound steps or of p:declare-pipeline with a subpipeline, such an output declaration may not establish a connection to any port of another step or of the pipeline to be run.

If the pipeline has an output that is not declared on the p:run step, that output is discarded, and the corresponding port on the p:run step does not exist. If the p:run step declares an output port that is not provided by the pipeline, an empty sequence appears on that port.

It is a dynamic error (err:XC0202) if the dynamically executed pipeline implicitly or explicitly declares a primary output port with a different name than implicitly or explicitly specified in the p:run invocation.

2.1. Example

Example 1. Dynamic Execution of a Transformation/Validation Pipeline
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
  xmlns:c="http://www.w3.org/ns/xproc-step"
  xmlns:xs="http://www.w3.org/2001/XMLSchema" version="3.0" 
  name="sample-run-invocation">
  <p:variable name="xsl-params" select="map{'foo': 'bar'}" 
    as="map(xs:QName, item()*)"/>
  <p:variable name="assert-valid" select="false()" as="xs:boolean"/>
  <p:variable name="mode" as="xs:QName?" select="()"/>
  <p:variable name="template" as="xs:QName?" select="()"/>
  <p:run name="runme">
    <p:with-input href="transform-n-validate.xpl"/>
    <p:run-option name="mode" select="$mode"/>
    <p:run-option name="template" select="$template"/>
    <p:run-option name="xslt-parameters" select="$xsl-params"/>
    <p:run-option name="assert-valid" select="$assert-valid"/>
    <p:run-input port="source" href="my.xml" primary="true"/>
    <p:run-input port="stylesheet" href="my.xsl"/>
    <p:run-input port="xsd" href="my.xsd"/>
    <p:output port="result" primary="true"/>
    <p:output port="report"/>
  </p:run>
</p:declare-step>

with this pipeline in transform-n-validate.xpl:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
  xmlns:c="http://www.w3.org/ns/xproc-step"
  xmlns:xs="http://www.w3.org/2001/XMLSchema" version="3.0" 
  name="transform-n-validate">
  <p:input port="source" primary="true" sequence="true"/>
  <p:input port="stylesheet"/>
  <p:input port="xsd"/>
  <p:option name="assert-valid" as="xs:boolean" select="false()"/>
  <p:option name="xslt-parameters" as="map(xs:QName, item()*)?"/>
  <p:option name="mode" as="xs:QName?"/>
  <p:option name="template" as="xs:QName?"/>
  <p:output port="result" primary="true"/>
  <p:output port="report" pipe="report@xsdval"/>
  <p:xslt>
    <p:with-option name="initial-mode" select="$mode"/>
    <p:with-option name="template-name" select="$template"/>
    <p:with-option name="parameters" select="$xslt-parameters"/>
    <p:with-input port="stylesheet" pipe="stylesheet"/>
  </p:xslt>
  <p:validate-with-xml-schema name="xsdval">
    <p:with-option name="assert-valid" select="$assert-valid"/>
    <p:with-input port="schema" pipe="xsd@transform-n-validate"/>
  </p:validate-with-xml-schema>
</p:declare-step>

2.2. Document properties

The extent to which document properties are preserved depends on the steps in the dynamically executed pipeline.

3. Step Errors

This step can raise dynamic errors.

[Definition: A dynamic error is one which occurs while a pipeline is being evaluated.] Examples of dynamic errors include references to URIs that cannot be resolved, steps which fail, and pipelines that exhaust the capacity of an implementation (such as memory or disk space). For a more complete discussion of dynamic errors, see Dynamic Errors in XProc 3.0: An XML Pipeline Language.

If a step fails due to a dynamic error, failure propagates upwards until either a p:try is encountered or the entire pipeline fails. In other words, outside of a p:try, step failure causes the entire pipeline to fail.

The following errors can be raised by this step:

err:XC0200

It is a dynamic error if the pipeline input to the p:run step is not a valid pipeline.

See: p:run

err:XC0201

It is a dynamic error if the dynamically executed pipeline implicitly or explicitly declares a primary input port with a different name than implicitly or explicitly specified in the p:run invocation.

See: p:run

err:XC0202

It is a dynamic error if the dynamically executed pipeline implicitly or explicitly declares a primary output port with a different name than implicitly or explicitly specified in the p:run invocation.

See: p:run

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.]

A.1. Implementation-defined features

The following features are implementation-defined:

    A.2. Implementation-dependent features

    The following features are implementation-dependent:

      B. References

      [XProc 3.0] XProc 3.0: An XML Pipeline Language. Norman Walsh, Achim Berndzen, Gerrit Imsieke and Erik Siegel, editors.

      [XProc 3.0 Steps] XProc 3.0 Steps: An Introduction. Norman Walsh, Achim Berndzen, Gerrit Imsieke and Erik Siegel, editors.

      C. Glossary

      dynamic error

      A dynamic error is one which occurs while a pipeline is being evaluated.

      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.