| ||
DescriptionAll declarations described in this document, if not specified otherwise, are to be found in the Sablotron header filesxpath.h. When building an executable using the SXP,
include sxpath.h and link the Sablotron library (-lsablot).
| ||
See Also
|
| ||
DescriptionOn error, most SXP interface functions output a Sablotron error message and return an error code which can be passed to functions likeSablotGetErrorMsg (declared in sablot.h).
In the callbacks, in contrast, error handling has been kept to a minimum. Typically, in case of an error, a callback just returns a special value such as NULL. | ||
See Also
|
| ||||
DescriptionThe Sablotron XPath processor (SXP) enables the user to evaluate an XPath query on a DOM document accessed via callback functions provided by the user. The interface to SXP is written in C. SXP is a part of Sablotron, an XSLT processor by Ginger Alliance. | ||||
See Also
|
| ||||
DescriptionTo work with SXP, the user needs to instantiate aSablotSituation, register a DOM handler (a set of DOM-like
callback functions) using SXP_registerDOMHandler, and create a
query context using SXP_createQueryContext.
| ||||
Example SablotSituation S;
SXP_QueryContext Q;
DOMHandler my_domhandler=
{
&getNodeType,
/* ... more callbacks follow ... */
};
/* let us say the root is 123 */
SXP_Node root = (SXP_Node) 123;
SXP_char *result;
SablotCreateSituation(&S);
SXP_registerDOMHandler(S, &my_domhandler);
SXP_createQueryContext(S, &Q);
/* perform the query with the root as the context node */
SXP_query(Q, "//*", root, 1, 1);
SXP_getResultString(Q, &result);
puts(result);
SXP_destroyQueryContext(Q);
SablotDestroySituation(S);
| ||||
NotesFor clarity, error checking has been omitted from the above excerpt. | ||||
See Also
|
| ||||
DescriptionA structure holding the addresses of all the callback functions that reveal the DOM document to the SXP. It contains the following callbacks (in the given order):
| ||||
See Also
|
| ||||
DescriptionA type representing the context of a query, which can hold (1) namespace declarations for the next call toSXP_query, (2)
variable bindings for the same, (3) the result of a
SXP_query. An object of this type is created using
SXP_createQueryContext and freed using
SXP_destroyQueryContext. The evaluation result may be
retrieved using functions like SXP_getResultString.
| ||||
See Also
|
| ||||
DescriptionA document type.SXP_Document can be used in place of any
SXP_Node, in which case it represents the document root
node. A synonym for SXP_Node is NodeHandle.
| ||||
See Also
|
| ||||
DescriptionThe type for expressions in the SXP. Possible values includeSXP_NONE (unknown type), SXP_NUMBER,
SXP_STRING, SXP_BOOLEAN and SXP_NODESET.
| ||||
See Also
|
| ||
DescriptionA generic node type. | ||
See Also
|
| ||||
DescriptionA node list type. Node lists are returned bySXP_getResultNodeset and are manipulated using
SXP_getNodeListLength and SXP_getNodeListItem.
| ||||
See Also
|
| ||
DescriptionThe type for nodes in the SXP. Possible values include:
| ||
See Also
|
| |||||||||||||||
SyntaxSXP_addNamespaceDeclaration(Q, prefix, uri)
| |||||||||||||||
DescriptionDeclares a new namespace with the given prefix and URI. The declaration will only be in effect for the nextSXP_query.
| |||||||||||||||
See Also
|
| |||||||||||||||
SyntaxSXP_addVariableBinding(Q, name, source)
| |||||||||||||||
DescriptionBinds a variable to the result expression of anotherQueryContext. The binding will only be in effect for the
next SXP_query. SXP_addVariableBinding provides the
only way to bind the variable to a node set.
| |||||||||||||||
See Also
|
| |||||||||||||||
SyntaxSXP_addVariableBoolean(Q, name, value)
| |||||||||||||||
DescriptionBinds a variable to a boolean. The binding will only be in effect for the nextSXP_query.
| |||||||||||||||
See Also
|
| |||||||||||||||
SyntaxSXP_addVariableNumber(Q, name, value)
| |||||||||||||||
DescriptionBinds a variable to a number. The binding will only be in effect for the nextSXP_query.
| |||||||||||||||
See Also
|
| |||||||||||||||
SyntaxSXP_addVariableString(Q, name, value)
| |||||||||||||||
DescriptionBinds a variable to a string. The binding will only be in effect for the nextSXP_query.
| |||||||||||||||
See Also
|
| ||
DescriptionSXP character type. Currently just UTF-8 encodedchar.
| ||
See Also
|
| ||||||||||||
SyntaxSXP_createQueryContext(S, Qptr)
| ||||||||||||
DescriptionCreates aQueryContext.
| ||||||||||||
See Also
|
| |||||||||
SyntaxSXP_destroyQueryContext(Q)
| |||||||||
DescriptionDestroys aQueryContext, freeing all the memory it used,
including any SXP_query result and the pending variable
bindings and namespace declaration lists.
| |||||||||
See Also
|
| ||||||||||||
SyntaxSXP_getNodeListItem(list, index)
| ||||||||||||
DescriptionReturns the item at the given (zero-based) position in the node list. | ||||||||||||
See Also
|
| |||||||||
SyntaxSXP_getNodeListLength(list)
| |||||||||
DescriptionReturns the number of items in a node list. | |||||||||
See Also
|
| ||||||||||||
SyntaxSXP_getResultBool(Q, resultPtr)
| ||||||||||||
DescriptionRetrieves the result of aSXP_query as a boolean, performing
a type conversion if necessary.
| ||||||||||||
See Also
|
| ||||||||||||
SyntaxSXP_getResultNodeset(Q, resultPtr)
| ||||||||||||
DescriptionRetrieves the result of aSXP_query as a nodeset. This can
be subsequently manipulated using SXP_getNodeListItem and
SXP_getNodeListLength. If the result is not of type
nodeset, then XPath does not allow its conversion to a nodeset,
and SXP_ getResultNodeset returns NULL in *resultPtr.
| ||||||||||||
See Also
|
| ||||||||||||
SyntaxSXP_getResultNumber(Q, resultPtr)
| ||||||||||||
DescriptionRetrieves the result of aSXP_query as a double, performing
a type conversion if necessary.
| ||||||||||||
See Also
|
| ||||||||||||
SyntaxSXP_getResultString(Q, resultPtr)
| ||||||||||||
DescriptionRetrieves the result of aSXP_query as a string, performing
a type conversion if necessary.
| ||||||||||||
See Also
|
| ||||||||||||
SyntaxSXP_getResultType(Q, typePtr)
| ||||||||||||
DescriptionRetrieves the type of a result expression (SXP_ExpressionType) held in
QueryContext after SXP_query has been called.
| ||||||||||||
See Also
|
| |||||||||||||||||||||
SyntaxSXP_query(Q, query, node, position, size)
| |||||||||||||||||||||
DescriptionEvaluates a query (given as text) based on the current node, the context position and the context size. Any namespaces declared usingSXP_addNamespaceDeclaration are used for the
evaluation, as are the variable bindings made using functions like
SXP_addVariableString. Upon completion of the query, the
pending namespace declarations and variable bindings are cleared.
| |||||||||||||||||||||
See Also
|
| |||||||||
SyntaxSXP_registerDOMHandler(S, domh);
| |||||||||
DescriptionRegisters a newDOMHandler with the given
SablotSituation. There may only be one DOM handler per
situation. The DOM handler will receive all DOM requests made
during evaluation with the situation S. To unregister the handler,
use SXP_unregisterDOMHandler.
| |||||||||
See Also
|
| ||||||
SyntaxSXP_unregisterDOMHandler(S)
| ||||||
DescriptionUnregisters theDOMHandler registered with the given
SablotSituation. All DOM requests will be processed in the
default way.
| ||||||
See Also
|
| |||||||||
SyntaxSablotCreateSituation(sPtr)
| |||||||||
DescriptionCreates aSablotSituation which is passed to many Sablotron
functions and can be later destroyed by a call to SablotDestroySituation.
| |||||||||
NotesSablotCreateSituation is declared in sablot.h.
| |||||||||
See Also
|
| |||||||||
SyntaxSablotDestroySituation(S)
| |||||||||
DescriptionFrees aSablotSituation.
| |||||||||
NotesSablotDestroySituation is declared in sablot.h.
| |||||||||
See Also
|
| ||||
DescriptionThe type representing a general "context" for Sablotron. Mainly used for error reporting. An object of this type can be created usingSablotCreateSituation.
| ||||
NotesSablotSituation is declared in sablot.h.
| ||||
See Also
|
| ||||||||||||
SyntaxcompareNodes(node1,node2)
| ||||||||||||
DescriptionCompares two nodes based on the document order. Returns -1 if node1 < node2 in this order, +1 if node1 > node2, and 0 if the nodes are identical. Any other value signifies an error. | ||||||||||||
See Also
|
| |||||||||
SyntaxgetAttributeCount(node)
| |||||||||
DescriptionReturns the number of attributes of the node. In particular, if the node is not an element, 0 is returned. | |||||||||
See Also
|
| ||||||||||||
SyntaxgetAttributeNo(node, index)
| ||||||||||||
DescriptionReturns the node's attribute at the given index. If the index is out of bounds, or if the node has no attributes, NULL is returned. | ||||||||||||
See Also
|
| |||||||||
SyntaxgetChildCount(node)
| |||||||||
DescriptionReturns the number of children of the node. In particular, if the node is neither an element nor a document node, 0 is returned. | |||||||||
See Also
|
| ||||||||||||
SyntaxgetChildNo(node, index)
| ||||||||||||
DescriptionReturns the node's child at the given index. If the index is out of bounds, or if the node has no children, NULL is returned. | ||||||||||||
See Also
|
| |||||||||
SyntaxgetNamespaceCount(node)
| |||||||||
DescriptionReturns the number of namespace declarations belonging to the node. In particular, if the node is not an element, 0 is returned. | |||||||||
See Also
|
| ||||||||||||
SyntaxgetNamespaceNo(node, index)
| ||||||||||||
DescriptionReturns the namespace node which appears at the given position among those belonging to the given node. If the index is out of bounds, or if the node has no namespace nodes, NULL is returned. | ||||||||||||
See Also
|
| |||||||||
SyntaxgetNextAttrNS(node)
| |||||||||
DescriptionIf the given node is an attribute, the following attribute is returned; if it is a namespace node, the following namespace node is returned. If the node is not of these two types, or if there is no following node of the same type, the callback returns NULL. | |||||||||
See Also
|
| |||||||||
SyntaxgetNextSibling(node)
| |||||||||
DescriptionReturns the following sibling of the node, in document order. If there is no such sibling, returns NULL. If the node is an attribute or a namespace node, NULL is returned. | |||||||||
NotesIn the early versions of the SXP,getNextSibling acted
like getNextAttrNS when used on attributes and namespace
nodes.
| |||||||||
See Also
|
| |||||||||
SyntaxgetNodeName(node)
| |||||||||
DescriptionReturns the qualified name of the given node (prefix:local-part). On error, returns NULL. | |||||||||
See Also
|
| |||||||||
SyntaxgetNodeNameLocal(node)
| |||||||||
DescriptionReturns the local part of the given node's name. On error, returns NULL. | |||||||||
See Also
|
| |||||||||
SyntaxgetNodeNameURI(node)
| |||||||||
DescriptionReturns the namespace URI of the given node. On error, returns NULL. | |||||||||
See Also
|
| |||||||||
SyntaxgetNodeType(node)
| |||||||||
DescriptionReturns the type of the given node, or SXP_NONE on error. | |||||||||
See Also
|
| |||||||||
SyntaxgetNodeValue(node)
| |||||||||
DescriptionReturns the value of the given node, or NULL on error. The node values are as specified in the DOM Level 1 Core specification, with the addition that the value of a namespace node is the namespace URI. | |||||||||
See Also
|
| |||||||||
SyntaxgetOwnerDocument(node)
| |||||||||
DescriptionReturns the given node's owner document. | |||||||||
See Also
|
| |||||||||
SyntaxgetParent(node)
| |||||||||
DescriptionReturns the given node's parent. If the node has no parent (i.e. is a SXP_Document), NULL is returned. | |||||||||
See Also
|
| |||||||||
SyntaxgetPreviousAttrNS(node)
| |||||||||
DescriptionIf the given node is an attribute, the preceding attribute is returned; if it is a namespace node, the preceding namespace node is returned. If the node is not of these two types, or if there is no preceding node of the same type, the callback returns NULL. | |||||||||
See Also
|
| |||||||||
SyntaxgetPreviousSibling(node)
| |||||||||
DescriptionReturns the preceding sibling of the node, in document order. If there is no such sibling, returns NULL. If the node is an attribute or a namespace node, NULL is returned. | |||||||||
NotesIn the early versions of the SXP,getPreviousSibling acted
like getPreviousAttrNS when used on attributes and namespace
nodes.
| |||||||||
See Also
|
| |||||||||
SyntaxretrieveDocument(uri)
| |||||||||
DescriptionReturns the document found at the given URI. If the document could not be retrieved, NULL is returned. | |||||||||
See Also
|