Re: No-fail `document` Function Spec
"John L. Clark" <[email protected]>
| Newsgroups | gmane.text.xml.xslt.extensions |
|---|---|
| Message-ID | <20060311214345.GR7127@rejoice> |
On Sat, Mar 11, 2006 at 03:17:57AM -0700, Mike Brown wrote:
> I like the retry index idea, although I would just call it 'attempt'
> since the first try wouldn't be a 're'-try :)
Yeah, that makes sense. :)
> This example has a problem:
>
> generate-id(res:document("foo.xml"))=generate-id(res:document("foo.xml"), ., 1)
>
> The 2nd argument, from which the base URI is derived, defaults to the
> stylesheet node containing the res:document() call. This is not the
> context node (.), so the statement above won't necessarily be true.
Ya know, I knew there was something wrong about this as I wrote it, but
I couldn't quite place my finger on it. Does it bother anyone else that
there is no direct way for the user to actually input the default value
for the second argument explicitly? This is orthogonal, but I think
there ought to be an EXSLT function that allows us to access this value.
Perhaps it would be called something like `uri:caller-base-uri`. Yes, I
plan on working on the URI module after this. :)
> Also in reference to the second argument, the document() function says:
>
> "It is an error if the second argument node-set is empty and the URI
> reference is relative; the XSLT processor may signal the error; if
> it does not signal an error, it must recover by returning an empty
> node-set."
>
> Do you want res:document() to return an empty node-set in this case,
> or a result:error element? If result:error, then what should the uri
> attribute contain?
Good catch; I totally overlooked this case. I think that the `uri`
attribute should contain the relative reference that triggered the error
in this case; I've also expanded the
result:error/result:failed/result:category values to account for this
case. Do you think that's sufficient?
> Finally, just a minor copyedit:
>
> "then define the encapsulated node-set to be" -> "then the encapsulated node-set is"
I've updated the document to account for the above changes. Thanks for
taking the time to provide some critical insight here. I should have
attached the updated spec and an HTML view to this email.
This is almost totally random, but I was doing some recent tests on this
function with my www.example.org stuff, and it turns out there's
actually a page there now! So I don't have a guaranteed example of a
"connection" error. That makes me sad. :-(
Take care,
John L. Clark
_______________________________________________
exslt mailing list
[email protected]
http://www.exslt.org/list
index.html
(text/html, 9.4 KB)
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "/schema/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><title>EXSLT - res:document</title><link rel="stylesheet" href="http://exslt.org/base.css" /></head><body><h1 id="#title"><a href="http://www.exslt.org/">EXSLT</a> - <a href="http://www.exslt.org/res">res</a>:<a href="http://www.exslt.org/res/functions/document">document</a></h1><table><tr><td id="menu"><p class="level1"><a href="res.document.html">Implementer Page</a></p><p class="level1"><a href="../../../howto.html">How To</a></p><p class="level1"><a href="../../../download.html">Downloads</a></p><p class="level1">Modules</p><p class="level2"><a href="../../../date/index.html">Dates and Times</a></p><p class="level2"><a href="../../../dyn/index.html">Dynamic</a></p><p class="level2"><a href="../../../exsl/index.html">Common</a></p><p class="level2"><a href="../../../func/index.html">Functions</a></p><p class="level2"><a href="../../../math/index.html">Math</a></p><p class="level2"><a href="../../../random/index.html">Random</a></p><p class="level2"><a href="../../../regexp/index.html">Regular Expressions</a></p><p class="level2"><a href="../../../res/index.html">Resource</a></p><p class="level3"><a href="../../functions/document/index.html">res:document()</a></p><p class="level3"><a href="../../attributes/no-indent-elements/index.html">res:no-indent-elements=</a></p><p class="level3"><a href="../../value-sets/xml/index.html">“res:xml”</a></p><p class="level2"><a href="../../../set/index.html">Sets</a></p><p class="level2"><a href="../../../str/index.html">Strings</a></p><p class="level2"><a href="../../../sys/index.html">System</a></p><p class="level1"><a href="../../../submissions/">Submissions</a></p><p class="level1"><a href="../../../list">Mailing List</a></p><p class="level1"><a href="../../../contact.html">Contact</a></p></td><td id="content"><p><b>Implementer Page: </b><a href="res.document.html">res.document.html</a><br /><b>Function Package: </b><a href="res.document.zip">res.document.zip</a></p><h4>Function Syntax</h4><pre><var>node-set</var> <b>res:document</b>(<var>object</var>, <var>node-set</var>?, <var>number</var>?)</pre><p>The <code>res:document</code> function has the same behavior as the <a href="http://www.w3.org/TR/xslt#document"><code>document</code></a>
function with the following significant differences. Where the
<code>document</code> function recursively calls itself, the
<code>res:document</code> function follows the same pattern but calls
itself, instead. For this description, the <code>result</code> namespace
prefix maps to the <code>http://exslt.org/resource/result</code> URI.</p><p>Unlike the <code>document</code> function, the
<code>res:document</code> function allows the user to specify an attempt
index. The attempt index is the optional third argument to this function,
and it defaults to 1. Two result documents returned by this function are
treated as the same document if the documents that this function attempts
to retrieve are identified by the same URI reference and are retrieved
with the same attempt index. As a result, a processor can obtain new
representations of a given URI for different values of the attempt index,
but the following expressions will always be true:</p><pre>generate-id(res:document("foo.xml"))=generate-id(res:document("foo.xml"))
generate-id(res:document("foo.xml"), ., 1)=generate-id(res:document("foo.xml"), ., 1)
generate-id(res:document("foo.xml"), ., 2)=generate-id(res:document("foo.xml"), ., 2)</pre><p>Although the following expression will not be true:</p><pre>generate-id(res:document("foo.xml"), ., 1)=generate-id(res:document("foo.xml"), ., 2)</pre><p>For any given value of the attempt index, this function behaves as
follows.</p><p>When the first argument to the <code>res:document</code> function is
not a node-set, this function performs the same processing as the
<code>document</code> function, but instead of returning the constructed
node-set, it returns a result node-set that is defined as follows. If the
constructed node-set contains only a document node, then the encapsulated
node-set is the set of all child nodes of this document node. Otherwise,
the encapsulated node-set is the constructed node-set. The result
node-set, which is returned from this function, consists of a
<code>result:success</code> element with the encapsulated node-set as its
children. This element MUST have an <code>attempt</code> attribute that
contains the attempt index of this call and SHOULD also have a
<code>uri</code> attribute that contains the absolute URI that this
function retrieved. If there is an error processing the arguments or
retriving the resource, then this function returns the node-set containing
the root of a tree of the following form:</p><pre><result:error xmlns:result="http://exslt.org/resource/result"
uri="http://www.example.org/"
attempt="2">
<result:failed>
<result:category>protocol</result:category>
<result:item>http</result:item>
</result:failed>
<result:code>404</result:code>
<result:message>Not Found</result:message>
</result:error></pre><p>The elements contained in this error descriptor are mandatory unless
stated otherwise. In such an error descriptor, the <code>attempt</code>
attribute MUST contain the attempt index of this call and the
<code>uri</code> attribute SHOULD contain the URI reference that triggered
the error. The <code>result:failed</code> element MUST contain a
<code>result:category</code> element and MAY contain a
<code>result:item</code> element. The <code>result:category</code> element
indicates the area of failure. Its value SHOULD be one of
"relative-reference", "scheme", "connection", "protocol", "XML", or
"fragment" to indicate an unresolvable relative URI reference, an
unsupported scheme, problems in the network, problems with a particular
document exchange protocol, problems in the resulting document, or
problems processing the fragment identifier, respectively, or some other
application-specific value to indicate a different type of problem. If the
value of the <code>result:category</code> element is <em>not</em>
"relative-reference", then the <code>uri</code> attribute of the
<code>result:error</code> element MUST contain an absolute URI. If the
value of the <code>result:category</code> element is "protocol", then the
<code>result:item</code> element SHOULD contain the name of the protocol
(as listed in <a href="http://www.iana.org/assignments/port-numbers">the
TCP and UDP Port Numbers list</a>) that failed. The
<code>result:code</code> element is optional, and SHOULD contain the error
code corresponding to the error, if such a code exists. The
<code>result:message</code> element is also optional, and contains any
error message that was provided by the source of the error. Processors
MAY add elements or attributes to the error descriptor with additional
information, but these elements SHOULD be in a namespace other than
<code>http://exslt.org/resource/result</code>.</p><h2>Examples</h2><h3>Function</h3><p>The following example shows how to use the <code>res:document</code> function:</p><h4>Source</h4><pre><doc>
<result-from uri="http://www.example.org/" />
<result-from uri="data.xml" />
<p>Note that "data.xml" refers to this document.</p>
<result-from uri="http://www.microsoft.com/license/GPL" />
</doc></pre><h4>Stylesheet</h4><pre><xsl:template match="/doc">
<output>
<xsl:copy-of select="res:document(result-from[1]/@uri)" />
<xsl:copy-of select="res:document(result-from[2]/@uri)" />
<xsl:copy-of select="res:document(result-from[3]/@uri)" />
</output>
</xsl:template></pre><h4>Result</h4><pre><output xmlns:result="http://exslt.org/resource/result">
<result:error uri="http://www.example.org/"
attempt="1">
<result:uri>http://www.example.org/</result:uri>
<result:failed>
<result:category>connection</result:category>
</result:failed>
<result:message>Connection refused</result:message>
</result:error>
<result:success uri="file:///some/path/to/data.xml"
attempt="1">
<doc>
<result-from uri="http://www.example.org/" />
<result-from uri="data.xml" />
<p>Note that "data.xml" refers to this document.</p>
<result-from uri="http://www.microsoft.com/license/GPL" />
</doc>
</result:success>
<result:error uri="http://www.microsoft.com/license/GPL"
attempt="1">
<result:failed>
<result:category>protocol</result:category>
<result:item>http</result:item>
</result:failed>
<result:code>404</result:code>
<result:message>Not Found</result:message>
</result:error>
</output></pre></td></tr></table><div id="colophon"><p><a href="http://www.exslt.org/res/functions/document/index.html">http://www.exslt.org/res/functions/document/index.html</a> last modified 2006-02-22</p></div></body></html>
res.document.xml
(text/plain, 6.5 KB)
<?xml version="1.0"?>
<exslt:function xmlns:exslt="http://exslt.org/documentation"
version="1" module="res" status="new">
<exslt:name>document</exslt:name>
<rdf:Description xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/elements/1.1/"
ID="res:document">
<dc:subject>EXSLT</dc:subject>
<dc:subject>res</dc:subject>
<dc:subject>document</dc:subject>
<dc:rights>public domain</dc:rights>
<exslt:revision>
<rdf:Description xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/elements/1.1/"
ID="res:document.1">
<exslt:version>1</exslt:version>
<dc:creator email="[email protected]"
url="http://infinitesque.net/">John L. Clark</dc:creator>
<dc:date>2006-02-22</dc:date>
<dc:description>Fetches status-encapsulated documents by URI.</dc:description>
</rdf:Description>
</exslt:revision>
</rdf:Description>
<exslt:doc xmlns="http://www.w3.org/1999/xhtml">
<p>The <code>res:document</code> function has the same behavior as the <a
href="http://www.w3.org/TR/xslt#document"><code>document</code></a>
function with the following significant differences. Where the
<code>document</code> function recursively calls itself, the
<code>res:document</code> function follows the same pattern but calls
itself, instead. For this description, the <code>result</code> namespace
prefix maps to the <code>http://exslt.org/resource/result</code> URI.</p>
<p>Unlike the <code>document</code> function, the
<code>res:document</code> function allows the user to specify an attempt
index. The attempt index is the optional third argument to this function,
and it defaults to 1. Two result documents returned by this function are
treated as the same document if the documents that this function attempts
to retrieve are identified by the same URI reference and are retrieved
with the same attempt index. As a result, a processor can obtain new
representations of a given URI for different values of the attempt index,
but the following expressions will always be true:</p>
<pre>generate-id(res:document("foo.xml"))=generate-id(res:document("foo.xml"))
generate-id(res:document("foo.xml"), ., 1)=generate-id(res:document("foo.xml"), ., 1)
generate-id(res:document("foo.xml"), ., 2)=generate-id(res:document("foo.xml"), ., 2)</pre>
<p>Although the following expression will not be true:</p>
<pre>generate-id(res:document("foo.xml"), ., 1)=generate-id(res:document("foo.xml"), ., 2)</pre>
<p>For any given value of the attempt index, this function behaves as
follows.</p>
<p>When the first argument to the <code>res:document</code> function is
not a node-set, this function performs the same processing as the
<code>document</code> function, but instead of returning the constructed
node-set, it returns a result node-set that is defined as follows. If the
constructed node-set contains only a document node, then the encapsulated
node-set is the set of all child nodes of this document node. Otherwise,
the encapsulated node-set is the constructed node-set. The result
node-set, which is returned from this function, consists of a
<code>result:success</code> element with the encapsulated node-set as its
children. This element MUST have an <code>attempt</code> attribute that
contains the attempt index of this call and SHOULD also have a
<code>uri</code> attribute that contains the absolute URI that this
function retrieved. If there is an error processing the arguments or
retriving the resource, then this function returns the node-set containing
the root of a tree of the following form:</p>
<pre><![CDATA[<result:error xmlns:result="http://exslt.org/resource/result"
uri="http://www.example.org/"
attempt="2">
<result:failed>
<result:category>protocol</result:category>
<result:item>http</result:item>
</result:failed>
<result:code>404</result:code>
<result:message>Not Found</result:message>
</result:error>]]></pre>
<p>The elements contained in this error descriptor are mandatory unless
stated otherwise. In such an error descriptor, the <code>attempt</code>
attribute MUST contain the attempt index of this call and the
<code>uri</code> attribute SHOULD contain the URI reference that triggered
the error. The <code>result:failed</code> element MUST contain a
<code>result:category</code> element and MAY contain a
<code>result:item</code> element. The <code>result:category</code> element
indicates the area of failure. Its value SHOULD be one of
"relative-reference", "scheme", "connection", "protocol", "XML", or
"fragment" to indicate an unresolvable relative URI reference, an
unsupported scheme, problems in the network, problems with a particular
document exchange protocol, problems in the resulting document, or
problems processing the fragment identifier, respectively, or some other
application-specific value to indicate a different type of problem. If the
value of the <code>result:category</code> element is <em>not</em>
"relative-reference", then the <code>uri</code> attribute of the
<code>result:error</code> element MUST contain an absolute URI. If the
value of the <code>result:category</code> element is "protocol", then the
<code>result:item</code> element SHOULD contain the name of the protocol
(as listed in <a href="http://www.iana.org/assignments/port-numbers">the
TCP and UDP Port Numbers list</a>) that failed. The
<code>result:code</code> element is optional, and SHOULD contain the error
code corresponding to the error, if such a code exists. The
<code>result:message</code> element is also optional, and contains any
error message that was provided by the source of the error. Processors
MAY add elements or attributes to the error descriptor with additional
information, but these elements SHOULD be in a namespace other than
<code>http://exslt.org/resource/result</code>.</p>
</exslt:doc>
<exslt:definition>
<exslt:return type="node-set" />
<exslt:arg name="object" type="object" optional="no" />
<exslt:arg name="node-set" type="node-set" optional="yes" default="/.." />
<exslt:arg name="attempt-number" type="number" optional="yes" default="1" />
</exslt:definition>
<exslt:use-cases>
<exslt:use-case type="example" data="use-cases/1/data.xml"
xslt="use-cases/1/script.xsl"
result="use-cases/1/result.xml"/>
</exslt:use-cases>
</exslt:function>
signature.asc
(application/pgp-signature, 189 B)
-----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.7 (GNU/Linux) iD8DBQFEE0SRjkcskvOyl78RAisIAJ4sg/SXzDf1gOLtF85vBuhdCkjUYQCgi9eK jaaSvaTRsioF+XTkz/Wh7jY= =3fam -----END PGP SIGNATURE-----