<?xml version="1.0"?>
<?xml-stylesheet href="http://xslt.fourthought.com/api.xslt" type="text/xsl"?>
<tech:ApiSpec title="4XPointer API"
  xmlns:tech="http://namespaces.fourthought.com/technical"
  xmlns:dc= "http://purl.org/dc/elements/1.1"
  xmlns="http://docbook.org/docbook/xml/4.0/namespace"
>

<dc:Title>4XPointer API</dc:Title>
<dc:Subject>4XPointer</dc:Subject>
<dc:Subject>XPointer</dc:Subject>
<dc:Subject>API</dc:Subject>
<dc:Description>Application Programming Interface for 4XPointer.</dc:Description>


<sect1><title>Usage</title>
<para>
4XPointer provides functions that can be called with a URI to extract the
relevant subset of the document at the base URI.  The URI must conform to
the <ulink url="http://www.w3.org/TR/xptr">XPointer 1.0 Candidate
Recommendation</ulink>, with the exception that 4XPointer does not yet
support points and ranges.  Specifically, any XPointer operation involving
points and ranges will return an empty location set.
</para>
</sect1>

<sect1><title>API</title>

<tech:Module>
  <tech:Name>Ft.XPointer</tech:Name>
  <tech:Desc>The 4XPointer module</tech:Desc>

  <tech:Function>
    <tech:Name>SelectUri</tech:Name>
    <tech:Desc>Returns the complete DOM node that results from selecting gainst a URI with an XPointer fragment.</tech:Desc>
    <tech:Arg><tech:Name>uri</tech:Name><tech:Type>string conforming to the XPointer spec</tech:Type><tech:Desc>The URI (including fragment) to be selected</tech:Desc></tech:Arg>
    <tech:Arg><tech:Name>contextNode</tech:Name><tech:Type>Object with the interface of Ft.Lib.pDomlette.Node</tech:Type><tech:Desc>The node to be taken as context.  Basically used in the here() and origin() functions.  If None, there is no given context and all operations must be absolute.  The default is None.</tech:Desc></tech:Arg>
    <tech:Arg><tech:Name>reader</tech:Name><tech:Type>Object with the interface of xml.dom.ext.reader.Reader</tech:Type><tech:Desc>The object used to create a DOM representation from text.  Defaults according to the BETA_DOMLETTE environment variable.</tech:Desc></tech:Arg>
    <tech:Return><tech:Type>A DOM node.  The precise type (4DOM, pDomlette, cDomlette, DbDom, etc.) depends on the reader passed in.</tech:Type><tech:Desc>The node which was selected by the XPointer expression.</tech:Desc></tech:Return>
    <tech:Exception><tech:Type>Ft.XPointer.XPtrException</tech:Type><tech:Desc>Raised when an invalid URI according to XPointer is provided.</tech:Desc></tech:Exception>
    <tech:Exception><tech:Type>xml.sax.saxlib.SAXException</tech:Type><tech:Desc>Raised if there is a low-level SAX error.</tech:Desc></tech:Exception>
    <tech:Exception><tech:Type>xml.sax.saxlib.SAXException</tech:Type><tech:Desc>Raised if the XML parser reports a well-formedness or validity error.</tech:Desc></tech:Exception>
  </tech:Function>

  <tech:Function>
    <tech:Name>SelectNode</tech:Name>
    <tech:Desc>Returns the complete DOM node that results from selecting against a DOM document and an XPointer fragment.</tech:Desc>
    <tech:Arg><tech:Name>doc</tech:Name><tech:Type>Object with the interface of Ft.Lib.pDomlette.Node</tech:Type><tech:Desc>The root DOM document of the XPointer operations.</tech:Desc></tech:Arg>
    <tech:Arg><tech:Name>fragment</tech:Name><tech:Type>string</tech:Type><tech:Desc>The URI fragment representing the desired XPointer.</tech:Desc></tech:Arg>
    <tech:Arg><tech:Name>contextNode</tech:Name><tech:Type>Object with the interface of Ft.Lib.pDomlette.Node</tech:Type><tech:Desc>The node to be taken as context.  Basically used in the here() and origin() functions.  If None, there is no given context and all operations must be absolute.  The default is None.</tech:Desc></tech:Arg>
    <tech:Return><tech:Type>A DOM node.  The precise type (4DOM, pDomlette, cDomlette, DbDom, etc.) depends on the reader passed in.</tech:Type><tech:Desc>The node which was selected by the XPointer expression.</tech:Desc></tech:Return>
    <tech:Exception><tech:Type>Ft.XPointer.XPtrException</tech:Type><tech:Desc>Raised when an invalid URI according to XPointer is provided.</tech:Desc></tech:Exception>
  </tech:Function>

</tech:Module>

</sect1>

</tech:ApiSpec>
