Google

SXP Reference

Building General

Description

All declarations described in this document, if not specified otherwise, are to be found in the Sablotron header file sxpath.h. When building an executable using the SXP, include sxpath.h and link the Sablotron library (-lsablot).

See Also

Groups [ General ]

Errors General

Description

On error, most SXP interface functions output a Sablotron error message and return an error code which can be passed to functions like SablotGetErrorMsg (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

Groups [ General ]

Overview General

Description

The 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

Groups [ General ]
Entries [ .Building | .Errors | .Usage ]

Usage General

Description

To work with SXP, the user needs to instantiate a SablotSituation, 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);

Notes

For clarity, error checking has been omitted from the above excerpt.

See Also

Groups [ General ]
Entries [ SXP_createQueryContext | SXP_registerDOMHandler | SablotSituation ]

DOMHandler Callbacks

Description

A 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

Groups [ Callbacks ]
Entries [ compareNodes | getAttributeCount | getAttributeNo | getChildCount | getChildNo | getNamespaceCount | getNamespaceNo | getNextAttrNS | getNextSibling | getNodeName | getNodeNameLocal | getNodeNameURI | getNodeType | getNodeValue | getOwnerDocument | getParent | getPreviousAttrNS | getPreviousSibling | retrieveDocument ]

QueryContext Types

Description

A type representing the context of a query, which can hold (1) namespace declarations for the next call to SXP_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

Groups [ Types ]
Entries [ SXP_addNamespaceDeclaration | SXP_addVariableBinding | SXP_addVariableString | SXP_createQueryContext | SXP_destroyQueryContext | SXP_getResultString | SXP_query ]

SXP_Document Types

Description

A 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

Groups [ Types ]
Entries [ SXP_Node ]

SXP_ExpressionType Enums

Description

The type for expressions in the SXP. Possible values include SXP_NONE (unknown type), SXP_NUMBER, SXP_STRING, SXP_BOOLEAN and SXP_NODESET.

See Also

Groups [ Enums ]
Entries [ SXP_getResultType ]

SXP_Node Types

Description

A generic node type.

See Also

Groups [ Types ]

SXP_NodeList Types

Description

A node list type. Node lists are returned by SXP_getResultNodeset and are manipulated using SXP_getNodeListLength and SXP_getNodeListItem.

See Also

Groups [ Types ]
Entries [ SXP_getNodeListItem | SXP_getNodeListLength | SXP_getResultNodeset ]

SXP_NodeType Enums

Description

The type for nodes in the SXP. Possible values include:
  • ELEMENT_NODE,
  • ATTRIBUTE_NODE,
  • TEXT_NODE,
  • PROCESSING_INSTRUCTION_NODE,
  • COMMENT_NODE,
  • DOCUMENT_NODE,
  • NAMESPACE_NODE.

See Also

Groups [ Enums ]

SXP_addNamespaceDeclaration Functions

Syntax

     SXP_addNamespaceDeclaration(Q, prefix, uri)
NameTypeDescription
QQueryContextThe current query context.
prefixconst SXP_char*The namespace prefix.
uriconst SXP_char*The namespace URI.
(RET)intThe error code.

Description

Declares a new namespace with the given prefix and URI. The declaration will only be in effect for the next SXP_query.

See Also

Groups [ Functions ]
Entries [ QueryContext | SXP_addVariableBinding | SXP_query ]

SXP_addVariableBinding Functions

Syntax

     SXP_addVariableBinding(Q, name, source)
NameTypeDescription
QQueryContextThe current query context.
nameconst SXP_char*The name of the variable.
sourceQueryContextAnother QueryContext which has been evaluated already. The variable will be bound to its result expression.
(RET)intThe error code.

Description

Binds a variable to the result expression of another QueryContext. 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

Groups [ Functions ]
Entries [ QueryContext | SXP_addVariableBoolean | SXP_addVariableNumber | SXP_addVariableString | SXP_query ]

SXP_addVariableBoolean Functions

Syntax

     SXP_addVariableBoolean(Q, name, value)
NameTypeDescription
QQueryContextThe current query context.
nameconst SXP_char*The name of the variable.
valueintThe boolean value to bind the variable to.
(RET)intThe error code.

Description

Binds a variable to a boolean. The binding will only be in effect for the next SXP_query.

See Also

Groups [ Functions ]
Entries [ QueryContext | SXP_addVariableBinding | SXP_addVariableNumber | SXP_addVariableString | SXP_query ]

SXP_addVariableNumber Functions

Syntax

     SXP_addVariableNumber(Q, name, value)
NameTypeDescription
QQueryContextThe current query context.
nameconst SXP_char*The name of the variable.
valuedoubleThe number to bind the variable to.
(RET)intThe error code.

Description

Binds a variable to a number. The binding will only be in effect for the next SXP_query.

See Also

Groups [ Functions ]
Entries [ QueryContext | SXP_addVariableBinding | SXP_addVariableBoolean | SXP_addVariableString | SXP_query ]

SXP_addVariableString Functions

Syntax

     SXP_addVariableString(Q, name, value)
NameTypeDescription
QQueryContextThe current query context.
nameconst SXP_char*The name of the variable.
valueconst SXP_char*The string to bind the variable to.
(RET)intThe error code.

Description

Binds a variable to a string. The binding will only be in effect for the next SXP_query.

See Also

Groups [ Functions ]
Entries [ QueryContext | SXP_addVariableBinding | SXP_addVariableBoolean | SXP_addVariableNumber | SXP_query ]

SXP_char Types

Description

SXP character type. Currently just UTF-8 encoded char.

See Also

Groups [ Types ]

SXP_createQueryContext Functions

Syntax

     SXP_createQueryContext(S, Qptr)
NameTypeDescription
SSablotSituationThe current situation.
QptrQueryContext *Pointer to where to store the query context.
(RET)intThe error code.

Description

Creates a QueryContext.

See Also

Groups [ Functions ]
Entries [ QueryContext | SablotSituation ]

SXP_destroyQueryContext Functions

Syntax

     SXP_destroyQueryContext(Q)
NameTypeDescription
QQueryContextThe query context to be deleted.
(RET)intThe error code.

Description

Destroys a QueryContext, freeing all the memory it used, including any SXP_query result and the pending variable bindings and namespace declaration lists.

See Also

Groups [ Functions ]
Entries [ QueryContext | SXP_query ]

SXP_getNodeListItem Functions

Syntax

     SXP_getNodeListItem(list, index)
NameTypeDescription
listSXP_NodeListA node list.
indexintA zero-based index into the list.
(RET)intThe error code.

Description

Returns the item at the given (zero-based) position in the node list.

See Also

Groups [ Functions ]
Entries [ SXP_NodeList | SXP_getNodeListLength ]

SXP_getNodeListLength Functions

Syntax

     SXP_getNodeListLength(list)
NameTypeDescription
listSXP_NodeListA node list.
(RET)intThe error code.

Description

Returns the number of items in a node list.

See Also

Groups [ Functions ]
Entries [ SXP_NodeList | SXP_getNodeListItem ]

SXP_getResultBool Functions

Syntax

     SXP_getResultBool(Q, resultPtr)
NameTypeDescription
QQueryContextThe current query context.
resultPtrint*The pointer to store the result at.
(RET)intThe error code.

Description

Retrieves the result of a SXP_query as a boolean, performing a type conversion if necessary.

See Also

Groups [ Functions ]
Entries [ QueryContext | SXP_getResultNodeset | SXP_getResultNumber | SXP_getResultString | SXP_getResultType | SXP_query ]

SXP_getResultNodeset Functions

Syntax

     SXP_getResultNodeset(Q, resultPtr)
NameTypeDescription
QQueryContextThe current query context.
resultPtrSXP_NodeList*The pointer to store the result at.
(RET)intThe error code.

Description

Retrieves the result of a SXP_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

Groups [ Functions ]
Entries [ QueryContext | SXP_getNodeListItem | SXP_getNodeListLength | SXP_getResultBool | SXP_getResultNumber | SXP_getResultString | SXP_getResultType | SXP_query ]

SXP_getResultNumber Functions

Syntax

     SXP_getResultNumber(Q, resultPtr)
NameTypeDescription
QQueryContextThe current query context.
resultPtrdouble*The pointer to store the result at.
(RET)intThe error code.

Description

Retrieves the result of a SXP_query as a double, performing a type conversion if necessary.

See Also

Groups [ Functions ]
Entries [ QueryContext | SXP_getResultBool | SXP_getResultNodeset | SXP_getResultString | SXP_getResultType | SXP_query ]

SXP_getResultString Functions

Syntax

     SXP_getResultString(Q, resultPtr)
NameTypeDescription
QQueryContextThe current query context.
resultPtrconst char**The pointer to store the result at.
(RET)intThe error code.

Description

Retrieves the result of a SXP_query as a string, performing a type conversion if necessary.

See Also

Groups [ Functions ]
Entries [ QueryContext | SXP_getResultBool | SXP_getResultNodeset | SXP_getResultNumber | SXP_getResultType | SXP_query ]

SXP_getResultType Functions

Syntax

     SXP_getResultType(Q, typePtr)
NameTypeDescription
QQueryContextThe current query context.
typePtrSXP_ExpressionType*The pointer to store the result type at.
(RET)intThe error code.

Description

Retrieves the type of a result expression (SXP_ExpressionType) held in QueryContext after SXP_query has been called.

See Also

Groups [ Functions ]
Entries [ QueryContext | SXP_ExpressionType | SXP_getResultBool | SXP_getResultNodeset | SXP_getResultNumber | SXP_getResultString | SXP_query ]

SXP_query Functions

Syntax

     SXP_query(Q, query, node, position, size)
NameTypeDescription
QQueryContextThe current query context.
queryconst SXP_char*The text of the query.
nodeSXP_NodeThe current node for the query.
positionintThe position of the current node in the evaluation context.
sizeintThe size of the evaluation context.
(RET)intThe error code.

Description

Evaluates a query (given as text) based on the current node, the context position and the context size. Any namespaces declared using SXP_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

Groups [ Functions ]
Entries [ QueryContext | SXP_Node | SXP_addNamespaceDeclaration | SXP_addVariableString | SXP_getResultString | SXP_getResultType ]

SXP_registerDOMHandler Functions

Syntax

     SXP_registerDOMHandler(S, domh);
NameTypeDescription
SSablotSituationThe current situation.
domhDOMHandler *Pointer to the new DOM handler.

Description

Registers a new DOMHandler 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

Groups [ Functions ]
Entries [ DOMHandler | SXP_unregisterDOMHandler | SablotSituation ]

SXP_unregisterDOMHandler Functions

Syntax

     SXP_unregisterDOMHandler(S)
NameTypeDescription
SSablotSituationThe current situation.

Description

Unregisters the DOMHandler registered with the given SablotSituation. All DOM requests will be processed in the default way.

See Also

Groups [ Functions ]
Entries [ DOMHandler | SablotSituation ]

SablotCreateSituation Functions

Syntax

     SablotCreateSituation(sPtr)
NameTypeDescription
sPtrSablotSituation *Pointer to where the result is to be stored.
(RET)intThe error code.

Description

Creates a SablotSituation which is passed to many Sablotron functions and can be later destroyed by a call to SablotDestroySituation.

Notes

SablotCreateSituation is declared in sablot.h.

See Also

Groups [ Functions ]
Entries [ SablotDestroySituation | SablotSituation ]

SablotDestroySituation Functions

Syntax

     SablotDestroySituation(S)
NameTypeDescription
SSablotSituationThe situation to be freed.
(RET)intThe error code.

Description

Frees a SablotSituation.

Notes

SablotDestroySituation is declared in sablot.h.

See Also

Groups [ Functions ]
Entries [ SablotSituation ]

SablotSituation Types

Description

The type representing a general "context" for Sablotron. Mainly used for error reporting. An object of this type can be created using SablotCreateSituation.

Notes

SablotSituation is declared in sablot.h.

See Also

Groups [ Types ]
Entries [ SablotCreateSituation ]

compareNodes Callbacks

Syntax

     compareNodes(node1,node2)
NameTypeDescription
node1SXP_NodeThe first node to be compared.
node2SXP_NodeThe second node to be compared.
(RET)intThe result of the comparison.

Description

Compares 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

Groups [ Callbacks ]
Entries [ SXP_Node ]

getAttributeCount Callbacks

Syntax

     getAttributeCount(node)
NameTypeDescription
nodeSXP_NodeThe node to operate on.
(RET)intThe number of attributes of the node.

Description

Returns the number of attributes of the node. In particular, if the node is not an element, 0 is returned.

See Also

Groups [ Callbacks ]
Entries [ SXP_Node ]

getAttributeNo Callbacks

Syntax

     getAttributeNo(node, index)
NameTypeDescription
nodeSXP_NodeThe node to operate on.
indexintIndex of an attribute.
(RET)SXP_NodeThe node's attribute with the given index.

Description

Returns 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

Groups [ Callbacks ]
Entries [ SXP_Node ]

getChildCount Callbacks

Syntax

     getChildCount(node)
NameTypeDescription
nodeSXP_NodeThe node to operate on.
(RET)intThe number of children of the node.

Description

Returns 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

Groups [ Callbacks ]
Entries [ SXP_Node ]

getChildNo Callbacks

Syntax

     getChildNo(node, index)
NameTypeDescription
nodeSXP_NodeThe node to operate on.
indexintIndex of a child.
(RET)SXP_NodeThe node's child with the given index.

Description

Returns 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

Groups [ Callbacks ]
Entries [ SXP_Node ]

getNamespaceCount Callbacks

Syntax

     getNamespaceCount(node)
NameTypeDescription
nodeSXP_NodeThe node to operate on.
(RET)intThe number of namespace declarations belonging to the node.

Description

Returns the number of namespace declarations belonging to the node. In particular, if the node is not an element, 0 is returned.

See Also

Groups [ Callbacks ]
Entries [ SXP_Node ]

getNamespaceNo Callbacks

Syntax

     getNamespaceNo(node, index)
NameTypeDescription
nodeSXP_NodeThe node to operate on.
indexintIndex of a namespace node.
(RET)SXP_NodeThe namespace node with the given index among those belonging to the given node.

Description

Returns 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

Groups [ Callbacks ]
Entries [ SXP_Node ]

getNextAttrNS Callbacks

Syntax

     getNextAttrNS(node)
NameTypeDescription
nodeSXP_NodeThe node to operate on.
(RET)SXP_NodeThe attribute/namespace node after the given one.

Description

If 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

Groups [ Callbacks ]
Entries [ SXP_Node ]

getNextSibling Callbacks

Syntax

     getNextSibling(node)
NameTypeDescription
nodeSXP_NodeThe node to operate on.
(RET)SXP_NodeThe next sibling of the node.

Description

Returns 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.

Notes

In the early versions of the SXP, getNextSibling acted like getNextAttrNS when used on attributes and namespace nodes.

See Also

Groups [ Callbacks ]
Entries [ SXP_Node | getNextAttrNS ]

getNodeName Callbacks

Syntax

     getNodeName(node)
NameTypeDescription
nodeSXP_NodeThe node to operate on.
(RET)const SXP_char*The name of the node.

Description

Returns the qualified name of the given node (prefix:local-part). On error, returns NULL.

See Also

Groups [ Callbacks ]
Entries [ SXP_Node ]

getNodeNameLocal Callbacks

Syntax

     getNodeNameLocal(node)
NameTypeDescription
nodeSXP_NodeThe node to operate on.
(RET)const SXP_char*The local name of the node.

Description

Returns the local part of the given node's name. On error, returns NULL.

See Also

Groups [ Callbacks ]
Entries [ SXP_Node ]

getNodeNameURI Callbacks

Syntax

     getNodeNameURI(node)
NameTypeDescription
nodeSXP_NodeThe node to operate on.
(RET)const SXP_char*The URI of the node's namespace.

Description

Returns the namespace URI of the given node. On error, returns NULL.

See Also

Groups [ Callbacks ]
Entries [ SXP_Node ]

getNodeType Callbacks

Syntax

     getNodeType(node)
NameTypeDescription
nodeSXP_NodeThe node to operate on.
(RET)SXP_NodeTypeThe type of the node.

Description

Returns the type of the given node, or SXP_NONE on error.

See Also

Groups [ Callbacks ]
Entries [ SXP_Node | SXP_NodeType ]

getNodeValue Callbacks

Syntax

     getNodeValue(node)
NameTypeDescription
nodeSXP_NodeThe node to operate on.
(RET)const SXP_char*The value of the node.

Description

Returns 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

Groups [ Callbacks ]
Entries [ SXP_Node ]

getOwnerDocument Callbacks

Syntax

     getOwnerDocument(node)
NameTypeDescription
nodeSXP_NodeThe node to operate on.
(RET)SXP_DocumentThe owner document.

Description

Returns the given node's owner document.

See Also

Groups [ Callbacks ]
Entries [ SXP_Document | SXP_Node ]

getParent Callbacks

Syntax

     getParent(node)
NameTypeDescription
nodeSXP_NodeThe node to operate on.
(RET)SXP_NodeThe node's parent.

Description

Returns the given node's parent. If the node has no parent (i.e. is a SXP_Document), NULL is returned.

See Also

Groups [ Callbacks ]
Entries [ SXP_Node ]

getPreviousAttrNS Callbacks

Syntax

     getPreviousAttrNS(node)
NameTypeDescription
nodeSXP_NodeThe node to operate on.
(RET)SXP_NodeThe attribute/namespace node preceding the given one.

Description

If 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

Groups [ Callbacks ]
Entries [ SXP_Node ]

getPreviousSibling Callbacks

Syntax

     getPreviousSibling(node)
NameTypeDescription
nodeSXP_NodeThe node to operate on.
(RET)SXP_NodeThe preceding sibling of the node.

Description

Returns 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.

Notes

In the early versions of the SXP, getPreviousSibling acted like getPreviousAttrNS when used on attributes and namespace nodes.

See Also

Groups [ Callbacks ]
Entries [ SXP_Node | getPreviousAttrNS ]

retrieveDocument Callbacks

Syntax

     retrieveDocument(uri)
NameTypeDescription
uriconst SXP_char*The URI of the document to be retrieved.
(RET)SXP_DocumentThe retrieved document.

Description

Returns the document found at the given URI. If the document could not be retrieved, NULL is returned.

See Also

Groups [ Callbacks ]
Entries [ SXP_Document ]

© 2001 Ginger Alliance
revision 01-12-12
This page was generated by APIDOC