Re: No-fail `document` Function Spec

<?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 a retry
  index.  The retry 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 retrieved by this function
  are identified by the same URI and are retrieved with the same retry
  index.  As a result, a processor can obtain new representations of a given
  URI for different values of the retry 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"))=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 retry 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 define the
  encapsulated node-set to be 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 retry 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 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 retry index of this call and the
  <code>uri</code> attribute SHOULD contain the absolute URI 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 "scheme",
  "connection", "protocol", "XML", or "fragment" to indicate 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 "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>

<?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><title>EXSLT - res:document</title><link href="http://exslt.org/base.css" rel="stylesheet"/></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">&#8220;res:xml&#8221;</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 a retry
  index.  The retry 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 retrieved by this function
  are identified by the same URI and are retrieved with the same retry
  index.  As a result, a processor can obtain new representations of a given
  URI for different values of the retry 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"))=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 retry 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 define the
  encapsulated node-set to be 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 retry 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 retriving the resource, then this
  function returns the node-set containing the root of a tree of the
  following form:</p><pre>&lt;result:error xmlns:result="http://exslt.org/resource/result"
              uri="http://www.example.org/"
              attempt="2"&gt;
  &lt;result:failed&gt;
    &lt;result:category&gt;protocol&lt;/result:category&gt;
    &lt;result:item&gt;http&lt;/result:item&gt;
  &lt;/result:failed&gt;
  &lt;result:code&gt;404&lt;/result:code&gt;
  &lt;result:message&gt;Not Found&lt;/result:message&gt;
&lt;/result:error&gt;</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 retry index of this call and the
  <code>uri</code> attribute SHOULD contain the absolute URI 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 "scheme",
  "connection", "protocol", "XML", or "fragment" to indicate 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 "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>&lt;doc&gt;
   &lt;result-from uri="http://www.example.org/" /&gt;
   &lt;result-from uri="data.xml" /&gt;
   &lt;p&gt;Note that "data.xml" refers to this document.&lt;/p&gt;
   &lt;result-from uri="http://www.microsoft.com/license/GPL" /&gt;
&lt;/doc&gt;</pre><h4>Stylesheet</h4><pre>&lt;xsl:template match="/doc"&gt;
   &lt;output&gt;
      &lt;xsl:copy-of select="res:document(result-from[1]/@uri)" /&gt;
      &lt;xsl:copy-of select="res:document(result-from[2]/@uri)" /&gt;
      &lt;xsl:copy-of select="res:document(result-from[3]/@uri)" /&gt;
   &lt;/output&gt;
&lt;/xsl:template&gt;</pre><h4>Result</h4><pre>&lt;output xmlns:result="http://exslt.org/resource/result"&gt;
   &lt;result:error uri="http://www.example.org/"
                 attempt="1"&gt;
      &lt;result:uri&gt;http://www.example.org/&lt;/result:uri&gt;
      &lt;result:failed&gt;
         &lt;result:category&gt;connection&lt;/result:category&gt;
      &lt;/result:failed&gt;
      &lt;result:message&gt;Connection refused&lt;/result:message&gt;
   &lt;/result:error&gt;
   &lt;result:success uri="file:///some/path/to/data.xml"
                   attempt="1"&gt;
      &lt;doc&gt;
         &lt;result-from uri="http://www.example.org/" /&gt;
         &lt;result-from uri="data.xml" /&gt;
         &lt;p&gt;Note that "data.xml" refers to this document.&lt;/p&gt;
         &lt;result-from uri="http://www.microsoft.com/license/GPL" /&gt;
      &lt;/doc&gt;
   &lt;/result:success&gt;
   &lt;result:error uri="http://www.microsoft.com/license/GPL"
                 attempt="1"&gt;
      &lt;result:failed&gt;
         &lt;result:category&gt;protocol&lt;/result:category&gt;
         &lt;result:item&gt;http&lt;/result:item&gt;
      &lt;/result:failed&gt;
      &lt;result:code&gt;404&lt;/result:code&gt;
      &lt;result:message&gt;Not Found&lt;/result:message&gt;
   &lt;/result:error&gt;
&lt;/output&gt;</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>

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.7 (GNU/Linux)

iD8DBQFEEK4LjkcskvOyl78RAu9UAJkBjYV1qeOT1jWLXt+0XB+hNUAKMgCgy8l7
UV4bv4BisrqMSqEIZG72H/k=
=ixC1
-----END PGP SIGNATURE-----