xpath

xpath - XML Path Language implementation

API for the XML Path Language implementation XML Path Language implementation XPath is a language for addressing parts of an XML document, designed to be used by both XSLT and XPointer

Author(s): Daniel Veillard

Synopsis

#define xmlXPathNodeSetGetLength(ns);
#define XML_XPATH_CHECKNS;
#define XML_XPATH_NOVAR;
#define xmlXPathNodeSetItem(ns, index);
#define xmlXPathNodeSetIsEmpty(ns);
typedef enum xmlXPathObjectType;
typedef xmlXPathVariable * xmlXPathVariablePtr;
typedef struct _xmlXPathContext xmlXPathContext;
typedef enum xmlXPathError;
typedef struct _xmlXPathFunct xmlXPathFunct;
typedef xmlXPathType * xmlXPathTypePtr;
typedef struct _xmlXPathType xmlXPathType;
typedef xmlNodeSet * xmlNodeSetPtr;
typedef xmlXPathFunct * xmlXPathFuncPtr;
typedef xmlXPathCompExpr * xmlXPathCompExprPtr;
typedef struct _xmlXPathObject xmlXPathObject;
typedef struct _xmlXPathCompExpr xmlXPathCompExpr;
typedef xmlXPathContext * xmlXPathContextPtr;
typedef xmlXPathParserContext * xmlXPathParserContextPtr;
typedef struct _xmlNodeSet xmlNodeSet;
typedef struct _xmlXPathVariable xmlXPathVariable;
typedef xmlXPathObject * xmlXPathObjectPtr;
typedef struct _xmlXPathAxis xmlXPathAxis;
typedef xmlXPathAxis * xmlXPathAxisPtr;
typedef struct _xmlXPathParserContext xmlXPathParserContext;
int	xmlXPathCastNodeSetToBoolean	(xmlNodeSetPtr ns);
typedef xmlXPathFunction xmlXPathFuncLookupFunc	(void * ctxt, 
const xmlChar * name,
const xmlChar * ns_uri); xmlXPathObjectPtr xmlXPathNodeEval (xmlNodePtr node,
const xmlChar * str,
xmlXPathContextPtr ctx); xmlChar * xmlXPathCastNodeToString (xmlNodePtr node); int xmlXPathIsNaN (double val); int xmlXPathContextSetCache (xmlXPathContextPtr ctxt,
int active,
int value,
int options); xmlXPathObjectPtr xmlXPathConvertString (xmlXPathObjectPtr val); int xmlXPathCompiledEvalToBoolean (xmlXPathCompExprPtr comp,
xmlXPathContextPtr ctxt); int xmlXPathIsInf (double val); long xmlXPathOrderDocElems (xmlDocPtr doc); xmlNodeSetPtr xmlXPathNodeSetCreate (xmlNodePtr val); double xmlXPathCastBooleanToNumber (int val); double xmlXPathCastNodeToNumber (xmlNodePtr node); double xmlXPathCastStringToNumber (const xmlChar * val); typedef xmlXPathObjectPtr xmlXPathAxisFunc (xmlXPathParserContextPtr ctxt,
xmlXPathObjectPtr cur); double xmlXPathCastToNumber (xmlXPathObjectPtr val); int xmlXPathCastStringToBoolean (const xmlChar * val); xmlChar * xmlXPathCastNumberToString (double val); typedef xmlXPathObjectPtr xmlXPathVariableLookupFunc (void * ctxt,
const xmlChar * name,
const xmlChar * ns_uri); void xmlXPathFreeObject (xmlXPathObjectPtr obj); int xmlXPathEvalPredicate (xmlXPathContextPtr ctxt,
xmlXPathObjectPtr res); void xmlXPathFreeContext (xmlXPathContextPtr ctxt); xmlXPathObjectPtr xmlXPathObjectCopy (xmlXPathObjectPtr val); void xmlXPathFreeNodeSetList (xmlXPathObjectPtr obj); xmlXPathObjectPtr xmlXPathEval (const xmlChar * str,
xmlXPathContextPtr ctx); xmlChar * xmlXPathCastNodeSetToString (xmlNodeSetPtr ns); xmlXPathObjectPtr xmlXPathCompiledEval (xmlXPathCompExprPtr comp,
xmlXPathContextPtr ctx); xmlXPathObjectPtr xmlXPathEvalExpression (const xmlChar * str,
xmlXPathContextPtr ctxt); void xmlXPathInit (void); xmlXPathObjectPtr xmlXPathConvertBoolean (xmlXPathObjectPtr val); typedef int xmlXPathConvertFunc (xmlXPathObjectPtr obj,
int type); typedef void xmlXPathFunction (xmlXPathParserContextPtr ctxt,
int nargs); int xmlXPathCmpNodes (xmlNodePtr node1,
xmlNodePtr node2); xmlChar * xmlXPathCastToString (xmlXPathObjectPtr val); xmlXPathCompExprPtr xmlXPathCtxtCompile (xmlXPathContextPtr ctxt,
const xmlChar * str); typedef void xmlXPathEvalFunc (xmlXPathParserContextPtr ctxt,
int nargs); xmlChar * xmlXPathCastBooleanToString (int val); int xmlXPathSetContextNode (xmlNodePtr node,
xmlXPathContextPtr ctx); int xmlXPathCastNumberToBoolean (double val); void xmlXPathFreeNodeSet (xmlNodeSetPtr obj); void xmlXPathFreeCompExpr (xmlXPathCompExprPtr comp); xmlXPathContextPtr xmlXPathNewContext (xmlDocPtr doc); xmlXPathObjectPtr xmlXPathConvertNumber (xmlXPathObjectPtr val); xmlXPathCompExprPtr xmlXPathCompile (const xmlChar * str); double xmlXPathCastNodeSetToNumber (xmlNodeSetPtr ns); int xmlXPathCastToBoolean (xmlXPathObjectPtr val);

Description

Details

Macro XML_XPATH_CHECKNS

#define XML_XPATH_CHECKNS;

check namespaces at compilation


Macro XML_XPATH_NOVAR

#define XML_XPATH_NOVAR;

forbid variables in expression


Macro xmlXPathNodeSetGetLength

#define xmlXPathNodeSetGetLength(ns);

Implement a functionality similar to the DOM NodeList.length. Returns the number of nodes in the node-set.

ns:a node-set

Macro xmlXPathNodeSetIsEmpty

#define xmlXPathNodeSetIsEmpty(ns);

Checks whether @ns is empty or not. Returns %TRUE if @ns is an empty node-set.

ns:a node-set

Macro xmlXPathNodeSetItem

#define xmlXPathNodeSetItem(ns, index);

Implements a functionality similar to the DOM NodeList.item(). Returns the xmlNodePtr at the given @index in @ns or NULL if @index is out of range (0 to length-1)

ns:a node-set
index:index of a node in the set

Structure xmlNodeSet

struct _xmlNodeSet {
    int	nodeNr	: number of nodes in the set
    int	nodeMax	: size of the array as allocated
    xmlNodePtr *	nodeTab	: array of nodes in no particular order @@ with_ns to check whether nam
} xmlNodeSet;


Typedef xmlNodeSetPtr

xmlNodeSet * xmlNodeSetPtr;


Structure xmlXPathAxis

struct _xmlXPathAxis {
    const xmlChar *	name	: the axis name
    xmlXPathAxisFunc	func	: the search function
} xmlXPathAxis;


Typedef xmlXPathAxisPtr

xmlXPathAxis * xmlXPathAxisPtr;


Structure xmlXPathCompExpr

struct _xmlXPathCompExpr {
The content of this structure is not made public by the API.
} xmlXPathCompExpr;


Typedef xmlXPathCompExprPtr

xmlXPathCompExpr * xmlXPathCompExprPtr;


Structure xmlXPathContext

struct _xmlXPathContext {
    xmlDocPtr	doc	: The current document
    xmlNodePtr	node	: The current node
    int	nb_variables_unused	: unused (hash table)
    int	max_variables_unused	: unused (hash table)
    xmlHashTablePtr	varHash	: Hash table of defined variables
    int	nb_types	: number of defined types
    int	max_types	: max number of types
    xmlXPathTypePtr	types	: Array of defined types
    int	nb_funcs_unused	: unused (hash table)
    int	max_funcs_unused	: unused (hash table)
    xmlHashTablePtr	funcHash	: Hash table of defined funcs
    int	nb_axis	: number of defined axis
    int	max_axis	: max number of axis
    xmlXPathAxisPtr	axis	: Array of defined axis the namespace nodes of the context node
    xmlNsPtr *	namespaces	: Array of namespaces
    int	nsNr	: number of namespace in scope
    void *	user	: function to free extra variables
    int	contextSize	: the context size
    int	proximityPosition	: the proximity position extra stuff for XPointer
    int	xptr	: is this an XPointer context?
    xmlNodePtr	here	: for here()
    xmlNodePtr	origin	: for origin() the set of namespace declarations in scope for the expre
    xmlHashTablePtr	nsHash	: The namespaces hash table
    xmlXPathVariableLookupFunc	varLookupFunc	: variable lookup func
    void *	varLookupData	: variable lookup data Possibility to link in an extra item
    void *	extra	: needed for XSLT The function name and URI when calling a function
    const xmlChar *	function
    const xmlChar *	functionURI	: function lookup function and data
    xmlXPathFuncLookupFunc	funcLookupFunc	: function lookup func
    void *	funcLookupData	: function lookup data temporary namespace lists kept for walking the n
    xmlNsPtr *	tmpNsList	: Array of namespaces
    int	tmpNsNr	: number of namespaces in scope error reporting mechanism
    void *	userData	: user specific data block
    xmlStructuredErrorFunc	error	: the callback in case of errors
    xmlError	lastError	: the last error
    xmlNodePtr	debugNode	: the source node XSLT dictionary
    xmlDictPtr	dict	: dictionary if any
    int	flags	: flags to control compilation Cache for reusal of XPath objects
    void *	cache	: Resource limits
    unsigned long	opLimit
    unsigned long	opCount
    int	depth
} xmlXPathContext;


Typedef xmlXPathContextPtr

xmlXPathContext * xmlXPathContextPtr;



Typedef xmlXPathFuncPtr

xmlXPathFunct * xmlXPathFuncPtr;


Structure xmlXPathFunct

struct _xmlXPathFunct {
    const xmlChar *	name	: the function name
    xmlXPathEvalFunc	func	: the evaluation function
} xmlXPathFunct;


Structure xmlXPathObject

struct _xmlXPathObject {
    xmlXPathObjectType	type
    xmlNodeSetPtr	nodesetval
    int	boolval
    double	floatval
    xmlChar *	stringval
    void *	user
    int	index
    void *	user2
    int	index2
} xmlXPathObject;


Typedef xmlXPathObjectPtr

xmlXPathObject * xmlXPathObjectPtr;


Enum xmlXPathObjectType

enum xmlXPathObjectType {
    XPATH_UNDEFINED = 0
    XPATH_NODESET = 1
    XPATH_BOOLEAN = 2
    XPATH_NUMBER = 3
    XPATH_STRING = 4
    XPATH_POINT = 5
    XPATH_RANGE = 6
    XPATH_LOCATIONSET = 7
    XPATH_USERS = 8
    XPATH_XSLT_TREE = 9 /*  An XSLT value tree, non modifiable */
};


Structure xmlXPathParserContext

struct _xmlXPathParserContext {
    const xmlChar *	cur	: the current char being parsed
    const xmlChar *	base	: the full expression
    int	error	: error code
    xmlXPathContextPtr	context	: the evaluation context
    xmlXPathObjectPtr	value	: the current value
    int	valueNr	: number of values stacked
    int	valueMax	: max number of values stacked
    xmlXPathObjectPtr *	valueTab	: stack of values
    xmlXPathCompExprPtr	comp	: the precompiled expression
    int	xptr	: it this an XPointer expression
    xmlNodePtr	ancestor	: used for walking preceding axis
    int	valueFrame	: used to limit Pop on the stack
} xmlXPathParserContext;


Typedef xmlXPathParserContextPtr

xmlXPathParserContext * xmlXPathParserContextPtr;


Structure xmlXPathType

struct _xmlXPathType {
    const xmlChar *	name	: the type name
    xmlXPathConvertFunc	func	: the conversion function
} xmlXPathType;


Typedef xmlXPathTypePtr

xmlXPathType * xmlXPathTypePtr;


Structure xmlXPathVariable

struct _xmlXPathVariable {
    const xmlChar *	name	: the variable name
    xmlXPathObjectPtr	value	: the value
} xmlXPathVariable;


Typedef xmlXPathVariablePtr

xmlXPathVariable * xmlXPathVariablePtr;


Function type xmlXPathAxisFunc

xmlXPathObjectPtr	xmlXPathAxisFunc	(xmlXPathParserContextPtr ctxt, 
xmlXPathObjectPtr cur)

An axis traversal function. To traverse an axis, the engine calls the first time with cur == NULL and repeat until the function returns NULL indicating the end of the axis traversal.

ctxt:the XPath interpreter context
cur:the previous node being explored on that axis
Returns:the next node in that axis or NULL if at the end of the axis.

Function type xmlXPathConvertFunc

int	xmlXPathConvertFunc		(xmlXPathObjectPtr obj, 
int type)

A conversion function is associated to a type and used to cast the new type to primitive values.

obj:an XPath object
type:the number of the target type
Returns:-1 in case of error, 0 otherwise

Function type xmlXPathEvalFunc

void	xmlXPathEvalFunc		(xmlXPathParserContextPtr ctxt, 
int nargs)

An XPath evaluation function, the parameters are on the XPath context stack.

ctxt:an XPath parser context
nargs:the number of arguments passed to the function

Function type xmlXPathFuncLookupFunc

xmlXPathFunction	xmlXPathFuncLookupFunc	(void * ctxt, 
const xmlChar * name,
const xmlChar * ns_uri)

Prototype for callbacks used to plug function lookup in the XPath engine.

ctxt:an XPath context
name:name of the function
ns_uri:the namespace name hosting this function
Returns:the XPath function or NULL if not found.

Function type xmlXPathFunction

void	xmlXPathFunction		(xmlXPathParserContextPtr ctxt, 
int nargs)

An XPath function. The arguments (if any) are popped out from the context stack and the result is pushed on the stack.

ctxt:the XPath interprestation context
nargs:the number of arguments

Function type xmlXPathVariableLookupFunc

xmlXPathObjectPtr	xmlXPathVariableLookupFunc	(void * ctxt, 
const xmlChar * name,
const xmlChar * ns_uri)

Prototype for callbacks used to plug variable lookup in the XPath engine.

ctxt:an XPath context
name:name of the variable
ns_uri:the namespace name hosting this variable
Returns:the XPath object value or NULL if not found.

Variable xmlXPathNAN

double xmlXPathNAN;


Variable xmlXPathNINF

double xmlXPathNINF;


Variable xmlXPathPINF

double xmlXPathPINF;



xmlXPathCastBooleanToString ()

xmlChar *	xmlXPathCastBooleanToString	(int val)

Converts a boolean to its string value.

val:a boolean
Returns:a newly allocated string.

xmlXPathCastNodeSetToBoolean ()

int	xmlXPathCastNodeSetToBoolean	(xmlNodeSetPtr ns)

Converts a node-set to its boolean value

ns:a node-set
Returns:the boolean value

xmlXPathCastNodeSetToNumber ()

double	xmlXPathCastNodeSetToNumber	(xmlNodeSetPtr ns)

Converts a node-set to its number value

ns:a node-set
Returns:the number value

xmlXPathCastNodeSetToString ()

xmlChar *	xmlXPathCastNodeSetToString	(xmlNodeSetPtr ns)

Converts a node-set to its string value.

ns:a node-set
Returns:a newly allocated string.

xmlXPathCastNodeToNumber ()

double	xmlXPathCastNodeToNumber	(xmlNodePtr node)

Converts a node to its number value

node:a node
Returns:the number value

xmlXPathCastNodeToString ()

xmlChar *	xmlXPathCastNodeToString	(xmlNodePtr node)

Converts a node to its string value.

node:a node
Returns:a newly allocated string.


xmlXPathCastNumberToString ()

xmlChar *	xmlXPathCastNumberToString	(double val)

Converts a number to its string value.

val:a number
Returns:a newly allocated string.

xmlXPathCastStringToBoolean ()

int	xmlXPathCastStringToBoolean	(const xmlChar * val)

Converts a string to its boolean value

val:a string
Returns:the boolean value

xmlXPathCastStringToNumber ()

double	xmlXPathCastStringToNumber	(const xmlChar * val)

Converts a string to its number value

val:a string
Returns:the number value

xmlXPathCastToBoolean ()

int	xmlXPathCastToBoolean		(xmlXPathObjectPtr val)

Converts an XPath object to its boolean value

val:an XPath object
Returns:the boolean value

xmlXPathCastToNumber ()

double	xmlXPathCastToNumber		(xmlXPathObjectPtr val)

Converts an XPath object to its number value

val:an XPath object
Returns:the number value

xmlXPathCastToString ()

xmlChar *	xmlXPathCastToString	(xmlXPathObjectPtr val)

Converts an existing object to its string() equivalent

val:an XPath object
Returns:the allocated string value of the object, NULL in case of error. It's up to the caller to free the string memory with xmlFree().

xmlXPathCmpNodes ()

int	xmlXPathCmpNodes		(xmlNodePtr node1, 
xmlNodePtr node2)

Compare two nodes w.r.t document order

node1:the first node
node2:the second node
Returns:-2 in case of error 1 if first point < second point, 0 if it's the same node, -1 otherwise

xmlXPathCompile ()

xmlXPathCompExprPtr	xmlXPathCompile	(const xmlChar * str)

Compile an XPath expression

str:the XPath expression
Returns:the xmlXPathCompExprPtr resulting from the compilation or NULL. the caller has to free the object.

xmlXPathCompiledEval ()

xmlXPathObjectPtr	xmlXPathCompiledEval	(xmlXPathCompExprPtr comp, 
xmlXPathContextPtr ctx)

Evaluate the Precompiled XPath expression in the given context.

comp:the compiled XPath expression
ctx:the XPath context
Returns:the xmlXPathObjectPtr resulting from the evaluation or NULL. the caller has to free the object.

xmlXPathCompiledEvalToBoolean ()

int	xmlXPathCompiledEvalToBoolean	(xmlXPathCompExprPtr comp, 
xmlXPathContextPtr ctxt)

Applies the XPath boolean() function on the result of the given compiled expression.

comp:the compiled XPath expression
ctxt:the XPath context
Returns:1 if the expression evaluated to true, 0 if to false and -1 in API and internal errors.

xmlXPathContextSetCache ()

int	xmlXPathContextSetCache		(xmlXPathContextPtr ctxt, 
int active,
int value,
int options)

Creates/frees an object cache on the XPath context. If activates XPath objects (xmlXPathObject) will be cached internally to be reused. @options: 0: This will set the XPath object caching: @value: This will set the maximum number of XPath objects to be cached per slot There are 5 slots for: node-set, string, number, boolean, and misc objects. Use <0 for the default number (100). Other values for @options have currently no effect.

ctxt:the XPath context
active:enables/disables (creates/frees) the cache
value:a value with semantics dependent on @options
options:options (currently only the value 0 is used)
Returns:0 if the setting succeeded, and -1 on API or internal errors.

xmlXPathConvertBoolean ()

xmlXPathObjectPtr	xmlXPathConvertBoolean	(xmlXPathObjectPtr val)

Converts an existing object to its boolean() equivalent

val:an XPath object
Returns:the new object, the old one is freed (or the operation is done directly on @val)

xmlXPathConvertNumber ()

xmlXPathObjectPtr	xmlXPathConvertNumber	(xmlXPathObjectPtr val)

Converts an existing object to its number() equivalent

val:an XPath object
Returns:the new object, the old one is freed (or the operation is done directly on @val)

xmlXPathConvertString ()

xmlXPathObjectPtr	xmlXPathConvertString	(xmlXPathObjectPtr val)

Converts an existing object to its string() equivalent

val:an XPath object
Returns:the new object, the old one is freed (or the operation is done directly on @val)

xmlXPathCtxtCompile ()

xmlXPathCompExprPtr	xmlXPathCtxtCompile	(xmlXPathContextPtr ctxt, 
const xmlChar * str)

Compile an XPath expression

ctxt:an XPath context
str:the XPath expression
Returns:the xmlXPathCompExprPtr resulting from the compilation or NULL. the caller has to free the object.

xmlXPathEval ()

xmlXPathObjectPtr	xmlXPathEval	(const xmlChar * str, 
xmlXPathContextPtr ctx)

Evaluate the XPath Location Path in the given context.

str:the XPath expression
ctx:the XPath context
Returns:the xmlXPathObjectPtr resulting from the evaluation or NULL. the caller has to free the object.

xmlXPathEvalExpression ()

xmlXPathObjectPtr	xmlXPathEvalExpression	(const xmlChar * str, 
xmlXPathContextPtr ctxt)

Alias for xmlXPathEval().

str:the XPath expression
ctxt:the XPath context
Returns:the xmlXPathObjectPtr resulting from the evaluation or NULL. the caller has to free the object.

xmlXPathEvalPredicate ()

int	xmlXPathEvalPredicate		(xmlXPathContextPtr ctxt, 
xmlXPathObjectPtr res)

Evaluate a predicate result for the current node. A PredicateExpr is evaluated by evaluating the Expr and converting the result to a boolean. If the result is a number, the result will be converted to true if the number is equal to the position of the context node in the context node list (as returned by the position function) and will be converted to false otherwise; if the result is not a number, then the result will be converted as if by a call to the boolean function.

ctxt:the XPath context
res:the Predicate Expression evaluation result
Returns:1 if predicate is true, 0 otherwise

xmlXPathFreeCompExpr ()

void	xmlXPathFreeCompExpr		(xmlXPathCompExprPtr comp)

Free up the memory allocated by @comp

comp:an XPATH comp


xmlXPathFreeNodeSet ()

void	xmlXPathFreeNodeSet		(xmlNodeSetPtr obj)

Free the NodeSet compound (not the actual nodes !).

obj:the xmlNodeSetPtr to free

xmlXPathFreeNodeSetList ()

void	xmlXPathFreeNodeSetList		(xmlXPathObjectPtr obj)

Free up the xmlXPathObjectPtr @obj but don't deallocate the objects in the list contrary to xmlXPathFreeObject().

obj:an existing NodeSetList object



xmlXPathIsInf ()

int	xmlXPathIsInf			(double val)

val:a double value
Returns:1 if the value is +Infinite, -1 if -Infinite, 0 otherwise

xmlXPathIsNaN ()

int	xmlXPathIsNaN			(double val)

val:a double value
Returns:1 if the value is a NaN, 0 otherwise

xmlXPathNewContext ()

xmlXPathContextPtr	xmlXPathNewContext	(xmlDocPtr doc)

Create a new xmlXPathContext

doc:the XML document
Returns:the xmlXPathContext just allocated. The caller will need to free it.

xmlXPathNodeEval ()

xmlXPathObjectPtr	xmlXPathNodeEval	(xmlNodePtr node, 
const xmlChar * str,
xmlXPathContextPtr ctx)

Evaluate the XPath Location Path in the given context. The node 'node' is set as the context node. The context node is not restored.

node:the node to to use as the context node
str:the XPath expression
ctx:the XPath context
Returns:the xmlXPathObjectPtr resulting from the evaluation or NULL. the caller has to free the object.

xmlXPathNodeSetCreate ()

xmlNodeSetPtr	xmlXPathNodeSetCreate	(xmlNodePtr val)

Create a new xmlNodeSetPtr of type double and of value @val

val:an initial xmlNodePtr, or NULL
Returns:the newly created object.

xmlXPathObjectCopy ()

xmlXPathObjectPtr	xmlXPathObjectCopy	(xmlXPathObjectPtr val)

allocate a new copy of a given object

val:the original object
Returns:the newly created object.

xmlXPathOrderDocElems ()

long	xmlXPathOrderDocElems		(xmlDocPtr doc)

Call this routine to speed up XPath computation on static documents. This stamps all the element nodes with the document order Like for line information, the order is kept in the element->content field, the value stored is actually - the node number (starting at -1) to be able to differentiate from line numbers.

doc:an input document
Returns:the number of elements found in the document or -1 in case of error.

xmlXPathSetContextNode ()

int	xmlXPathSetContextNode		(xmlNodePtr node, 
xmlXPathContextPtr ctx)

Sets 'node' as the context node. The node must be in the same document as that associated with the context.

node:the node to to use as the context node
ctx:the XPath context
Returns:-1 in case of error or 0 if successful