Document Templating Steps for XProc

1 Introduction

It's quite common in [XProc: An XML Pipeline Language] to construct documents using values computed by the pipeline. This is particularly (but not exclusively) the case when the pipeline uses the p:http-request step. The input to p:http-request is a c:request document; attributes on the c:request element control most of the request parameters; the body of the document forms the body of request.

A typical example looks like this:

<c:request method="POST" href="http://example.com/post"
           username="user" password="password">
<c:body>
  <computed-content/>
</c:body>
</c:request>

If we assume that the href value and the computed content come from an input document, and the username and password are options, then a typical pipeline to compute the request becomes quite complex.

<p:pipeline xmlns:p="http://www.w3.org/ns/xproc"
            xmlns:c="http://www.w3.org/ns/xproc-step"
            name="main" version="1.0">
<p:option name="username" required="true"/>
<p:option name="password" required="true"/>

<p:identity>
  <p:input port="source">
    <p:inline>
      <c:request method="POST"/>
    </p:inline>
  </p:input>
</p:identity>

<p:add-attribute match="/c:request" attribute-name="href">
  <p:with-option name="attribute-value" select="/doc/request/@uri">
    <p:pipe step="main" port="source"/>
  </p:with-option>
</p:add-attribute>

<p:add-attribute match="/c:request" attribute-name="username">
  <p:with-option name="attribute-value" select="$username"/>
</p:add-attribute>

<p:add-attribute match="/c:request" attribute-name="password">
  <p:with-option name="attribute-value" select="$password"/>
</p:add-attribute>

<p:insert position="first-child" match="/c:request">
  <p:input port="insertion" select="/doc/request">
    <p:pipe step="main" port="source"/>
  </p:input>
</p:insert>

<p:unwrap match="/c:request/request"/>

</p:pipeline>

There's nothing wrong with this pipeline, but it requires several steps to accomplish with the pipeline author probably considers a single operation. What's more, the result of these steps is not immediately obvious on casual inspection.

In order to make this simple construction case both literally and conceptually simpler, this note introduces two new XProc steps in the XProc namespace. Support for these steps is optional, but we strongly encourage implementors to provide them.

The new steps are p:in-scope-names and p:template. Taken together, they greatly simplify the pipeline:

<p:pipeline xmlns:p="http://www.w3.org/ns/xproc"
            xmlns:c="http://www.w3.org/ns/xproc-step"
            name="main" version="1.0">
<p:option name="username" required="true"/>
<p:option name="password" required="true"/>

<p:in-scope-names name="vars"/>

<p:template>
  <p:input port="template">
    <p:inline>
      <c:request method="POST" href="{/doc/request/@uri}"
                 username="{$username}" password="{$password}">
        { /doc/request/node() }
      </c:request>
    </p:inline>
  </p:input>
  <p:input port="source">
    <p:pipe step="main" port="source"/>
  </p:input>
  <p:input port="parameters">
    <p:pipe step="vars" port="result"/>
  </p:input>
</p:template>

</p:pipeline>

The p:in-scope-names step provides all of the in-scope options and variables in a c:param-set (this operation is exactly analagous to what the p:parameters step does, except that it operates on the options and variables instead of on parameters).

The p:template step searches for XPath expressions, delimited by curly braces, in a template document and replaces each with the result of evaluating the expression. All of the parameters passed to the p:template step are available as in-scope variable names when evaluating each XPath expression.

Where the expressions occur in attribute values, their string value is used. Where they appear in text content, their node values are used.

2 Terminology

In this note the words must, must not, should, should not, may and recommended are to be interpreted as described in [RFC 2119].

3 p:in-scope-names

The p:in-scope-names step exposes all of the in-scope variables and options as a set of parameters in a c:param-set document.

<p:declare-step type="p:in-scope-names">
     <p:output port="result" primary="false"/>
</p:declare-step>

Each in-scope variable and option is converted into a c:param element. The resulting c:param elements are wrapped in a c:param-set and the parameter set document is written to the result port. The order in which c:param elements occur in the c:param-set is implementation-dependent.

For consistency and user convenience, if any of the variables or options have names that are in a namespace, the namespace attribute on the c:param element must be used. Each name must be an NCName.

The base URI of the output document is the URI of the pipeline document that contains the step.

For consistency with the p:parameters step, the result port is not primary.

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
                name="main" version="1.0">
<p:output port="result">
  <p:pipe step="vars" port="result"/>
</p:output>

<p:option name="username" required="true"/>
<p:option name="password" required="true"/>
<p:variable name="host" select="'http://example.com/'"/>

<p:in-scope-names name="vars"/>

</p:declare-step>

<c:param-set xmlns:c="http://www.w3.org/ns/xproc-step">
  <c:param name="username" namespace="" value="user"/>
  <c:param name="host" namespace="" value="http://example.com/"/>
  <c:param name="password" namespace="" value="pass"/>
</c:param-set>

4 p:template

The p:template replaces each XPath expression, delimited with curly braces, in the template document with the result of evaluating that expression.

<p:declare-step type="p:template">
     <p:input port="template"/>
     <p:input port="source" sequence="true" primary="true"/>
     <p:input port="parameters" kind="parameter"/>
     <p:output port="result"/>
</p:declare-step>

While evaluating each expression, the names of any parameters passed to the step are available as variable values in the XPath dynamic context.

The step searches for XPath expressions in attribute values, text content (adjacent text nodes, if they occur in the data model, must be coalesced; this step always processes maximal length text nodes), processing instruction data, and comments. XPath expressions are identified by curly braces, similar to attribute value templates in XSLT or enclosed expressions in XQuery.

In order to allow curly braces to appear literally in content, they can be escaped by doubling them. In other words, where “{” would start an XPath expression, “{{” is simply a single, literal opening curly brace. The same applies for closing curly braces.

Inside an XPath expression, strings quoted by single (') or double (") quotes are treated literally. Outside of quoted text, it is an error for an opening curly brace to occur. A closing curly brace ends the XPath expression (whether or not it is followed immediately by another closing curly brace).

These parsing rules can be described by the following algorithm, though implementations are by no means required to implement the parsing in exactly this way, provided that they achieve the same results.

It is a dynamic error (err:XC0067) if the parser reaches the end of the unit of content and it is not in regular-mode.

The context node used for each expression is the document passed on the source port. It is a dynamic error (err:XC0068) if more than one document appears on the source port. In an XPath 1.0 implementation, if p:empty is given or implied on the source port, an empty document node is used as the context node. In an XPath 2.0 implementation, the context item is undefined. It is a dynamic error (err:XC0026) if any XPath expression makes reference to the context node, size, or position when the context item is undefined.

In an attribute value, processing instruction, or comment, the string value of the XPath expression is used. In text content, an expression that selects nodes will cause those nodes to be copied into the template document.

An example of p:document appears in Section 1, “Introduction”.