xproc-template 2011-01-25 XML Norman Walsh MarkLogic Corporation norman.walsh@marklogic.com This note describes two new XProc steps designed to make it easier to construct documents within an XProc pipeline using values computed by that pipeline. This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/. This is the first publication of this document as a Working Group Note. This document is a product of the XML Processing Model Working Group as part of the W3C XML Activity. The English version of this specification is the only normative version. However, for translations of this document, see . This Note defines some additional optional steps for use in XProc pipelines. The XML Processing Model Working Group expects that these new steps will be widely implemented and used. Please report errors in this document to the public mailing list public-xml-processing-model-comments@w3.org (public archives are available). Publication as a Working Group Note does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress. This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

It's quite common in 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: ]]> 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. 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: 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.

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

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

This unlikely pipeline demonstrates the behavior of p:in-scope-names: Assuming the values supplied for the username and password options are “user” and “pass”, respectively, the output would be:

The p:template replaces each XPath expression, delimited with curly braces, in the template document with the result of evaluating that expression. 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. The parser begins in regular-mode at the start of each unit of content where expansion may occur. In regular-mode: “{{” is replaced by a single “{”. “}}” is replaced by a single “}”. Note: It is a dynamic error to encounter a single closing curly brace “}” that is not immediately followed by another closing curly brace. A single opening curly brace “{” (not immediately followed by another opening curly brace) is discarded and the parser moves into xpath-mode. The inital expression is empty. All other characters are copied without change. In xpath-mode: It is a dynamic error to encounter an opening curly brace “{”. A closing curly brace “}” is discarded and ends the expression. The expression is evaluated and the result of that evaluation is copied to the output. The parser returns to regular-mode. Note: Braces cannot be escaped by doubling them in xpath-mode. A single quote (') is added to the current expression and the parser moves to single-quote-mode. A double quote (") is added to the current expression and the parser moves to double-quote-mode. All other characters are appended to the current expression. In single-quote-mode: A single quote (') is added to the current expression and the parser moves to xpath-mode. All other characters are appended to the current expression. In double-quote-mode: A double quote (") is added to the current expression and the parser moves to xpath-mode. All other characters are appended to the current expression. It is a dynamic error 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 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 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. Depending on which version of XPath an implementation supports, and possibly on the xpath-version setting on the p:template, some implementations may report errors, or different results, than other implementations in those cases where the interpretation of an XPath expression differs between the versions of XPath. An example of p:document appears in .

RFC 2119 Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. Network Working Group, IETF, Mar 1997. XProc: An XML Pipeline Language XML: An XML Pipeline Language. Norman Walsh, Alex Milowski, and Henry S. Thompson, editors. W3C Recommedation 11 May 2010.

The following dynamic errors are explicitly called out in this note. Other errors may also arise, see for a complete discussion of error codes.