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.  For the following
  description, the <code>result</code> namespace prefix maps to the
  <code>http://exslt.org/resource/result</code> URI.</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 SHOULD also have a <code>uri</code> attribute that
  contains the absolute URI that this function retrieved.  If there is an
  error retrieving 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/">
  <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>uri</code>
  attribute should contain the absolute URI that triggered the error.  The
  <code>result:failed</code> element MUST contain an
  <code>result:category</code> element and MAY contain an
  <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", or "XML" to indicate an unsupported
  scheme, problems in the network, problems with a particular document
  exchange protocol, or problems in the resulting document, 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.  <code>result:message</code> is also optional, and
  contains any error message that was provided by the source of the
  error.</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" default="/.." />
</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>)</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.  For the following
  description, the <code>result</code> namespace prefix maps to the
  <code>http://exslt.org/resource/result</code> URI.</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 SHOULD also have a <code>uri</code> attribute that
  contains the absolute URI that this function retrieved.  If there is an
  error retrieving 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/"&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>uri</code>
  attribute should contain the absolute URI that triggered the error.  The
  <code>result:failed</code> element MUST contain an
  <code>result:category</code> element and MAY contain an
  <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", or "XML" to indicate an unsupported
  scheme, problems in the network, problems with a particular document
  exchange protocol, or problems in the resulting document, 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.  <code>result:message</code> is also optional, and
  contains any error message that was provided by the source of the
  error.</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/"&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"&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"&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)

iD8DBQFEBASYjkcskvOyl78RAjk5AJ43dJ4nGynBJ444bkP1Vz5fhlo2IwCfT07p
hveCj3LlhZK/hHiRKqTkfS8=
=melb
-----END PGP SIGNATURE-----