Document Templating Steps for XProc 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 < [email protected] This document is also available in these non-normative formats: XML Copyright W3C ® MIT ERCIM Keio liability trademark document use Abstract 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. Status of this Document 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 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 XML Activity http://www.w3.org/2003/03/Translations/byTechnology?technology=xproc-template 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 [email protected] archives 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 public list of any patent disclosures Essential Claim(s) section 6 of the W3C Patent Policy Table of Contents 1 Introduction 2 Terminology 3 p:in-scope-names 4 p:template A References A.1 Normative References B List of Error Codes B.1 Step Errors It's quite common in [ XProc: An XML Pipeline Language p:http-request p:http-request c:request c: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 <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 p:template <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 c:param-set p:parameters The p:template p:template 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 recommended RFC 2119 The p:in-scope-names c:param-set <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 c:param c:param-set result c:param c:param-set implementation-dependent For consistency and user convenience, if any of the variables or options have names that are in a namespace, the namespace c:param must name must The base URI of the output document is the URI of the pipeline document that contains the step. For consistency with the p:parameters result This unlikely pipeline demonstrates the behavior of p:in-scope-names <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> Assuming the values supplied for the username and password options are “ user pass <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> The p:template template <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 “ { {{ single Inside an XPath expression, strings quoted by single ( ' " 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 regular-mode “ {{ { “ }} } Note: dynamic error err:XC0067 } A single opening curly brace “ { xpath-mode All other characters are copied without change. In xpath-mode dynamic error err:XC0067 { A closing curly brace “ } regular-mode Note: Braces cannot be escaped by doubling them in xpath-mode A single quote ( ' single-quote-mode A double quote ( " double-quote-mode All other characters are appended to the current expression. In single-quote-mode A single quote ( ' xpath-mode All other characters are appended to the current expression. In double-quote-mode A double quote ( " xpath-mode All other characters are appended to the current expression. dynamic error err:XC0067 regular-mode The context node used for each expression is the document passed on the source dynamic error err:XC0068 source p:empty source dynamic error err:XC0026 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. Note Depending on which version of XPath an implementation supports, and possibly on the xpath-version p:template An example of p:document Section 1, “Introduction” [ RFC 2119 Key words for use in RFCs to Indicate Requirement Levels [ XProc: An XML Pipeline Language XML: An XML Pipeline Language The following dynamic errors Step Errors err:XC0026 It is a dynamic error if any XPath expression makes reference to the context node, size, or position when the context item is undefined. See: p:template err:XC0067 It is a dynamic error to encounter a single closing curly brace “}” that is not immediately followed by another closing curly brace. See: p:template p:template p:template err:XC0068 It is a dynamic error if more than one document appears on the source port. See: p:template Other errors may also arise, see [ XProc: An XML Pipeline Language