Document Templating Steps for XProc

W3C Working Group Note 25 January 2011

This Version:

http://www.w3.org/TR/2011/NOTE-xproc-template-20110125/

Latest Version:

http://www.w3.org/TR/xproc-template/

Editor:

Norman Walsh,MarkLogic Corporation<norman.walsh@marklogic.com>

This document is also available in these non-normative formats:XML

Copyright© 2011W3C^® (MIT,ERCIM,Keio), All Rights Reserved.W3Cliability,trademarkanddocumentuse rules apply.

Appendices

1 Introduction

It's quite common in [XProc: An XML Pipeline Language] to constructdocuments using values computed by the pipeline. This isparticularly (but not exclusively) the case when the pipeline usesthep:http-request step. The input top:http-request is ac:request document; attributes on thec:request element control most of the requestparameters; 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 thehref valueand the computed content come from an input document, and theusername and password are options, then a typical pipeline tocompute 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 requiresseveral steps to accomplish with the pipeline author probablyconsiders a single operation. What's more, the result of thesesteps is not immediately obvious on casual inspection.

In order to make this simple construction case both literallyand conceptually simpler, this note introduces two new XProc stepsin the XProc namespace. Support for these steps is optional, but westrongly encourage implementors to provide them.

The new steps arep:in-scope-names andp:template. Takentogether, 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>

Thep:in-scope-names step provides all of thein-scope options and variables in ac:param-set (this operation is exactly analagousto what thep:parameters step does,except that it operates on the options and variables instead of onparameters).

Thep:template step searches for XPathexpressions, delimited by curly braces, in a template document andreplaces each with the result of evaluating the expression. All ofthe parameters passed to thep:template step are available as in-scopevariable names when evaluating each XPath expression.

Where the expressions occur in attribute values, their stringvalue is used. Where they appear in text content, their node valuesare used.

2 Terminology

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

3 p:in-scope-names

Thep:in-scope-names step exposes all ofthe in-scope variables and options as a set of parameters in ac:param-set document.

<p:declare-steptype="p:in-scope-names">
     <p:outputport="result"primary="false"/>
</p:declare-step>

Each in-scope variable and option is converted into ac:param element. The resultingc:param elements are wrapped in ac:param-set and the parameter set document iswritten to theresult port.The order in whichc:param elements occur in thec:param-set isimplementation-dependent.

For consistency and user convenience, if any of the variables oroptions have names that are in a namespace, thenamespace attribute on thec:param elementmust be used. Eachnamemust be anNCName.

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

For consistency with thep:parameters step, theresult 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

Thep:template replaces each XPathexpression, delimited with curly braces, in thetemplate document with the result of evaluating thatexpression.

<p:declare-steptype="p:template">
     <p:inputport="template"/>
     <p:inputport="source"sequence="true"primary="true"/>
     <p:inputport="parameters"kind="parameter"/>
     <p:outputport="result"/>
</p:declare-step>

While evaluating each expression, the names of any parameterspassed to the step are available as variable values in the XPathdynamic 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 textnodes), processing instruction data, and comments. XPathexpressions are identified by curly braces, similar to attributevalue 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 asingle, literalopening curly brace. The same applies for closing curly braces.

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

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

It is adynamic error (err:XC0067) if theparser reaches the end of the unit of content and it is not inregular-mode.

The context node used for each expression is the document passedon thesource port.It is adynamic error (err:XC0068) if morethan one document appears on thesource port.In an XPath 1.0 implementation, ifp:empty is given or implied on thesource port, an empty document node is used as thecontext node. In an XPath 2.0 implementation, the context item isundefined.Itis adynamic error (err:XC0026) if anyXPath expression makes reference to the context node, size, orposition when the context item is undefined.

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

An example ofp:document appears inSection 1,“Introduction”.

A References

B List of ErrorCodes