xpath.h revision 42596ad20cdf1925dd79ea801cbe598b6e7b7aec 
1/*
2 * xpath.c: interface for XML Path Language implementation
3 *
4 * Reference: W3C Working Draft 5 July 1999
5 *            http://www.w3.org/Style/XSL/Group/1999/07/xpath-19990705.html
6 *
7 * See COPYRIGHT for the status of this software
8 *
9 * Author: Daniel.Veillard@w3.org
10 */
11
12#ifndef __XML_XPATH_H__
13#define __XML_XPATH_H__
14
15#include <libxml/tree.h>
16#include <libxml/hash.h>
17
18#ifdef __cplusplus
19extern "C" {
20#endif
21
22typedef struct _xmlXPathContext xmlXPathContext;
23typedef xmlXPathContext *xmlXPathContextPtr;
24typedef struct _xmlXPathParserContext xmlXPathParserContext;
25typedef xmlXPathParserContext *xmlXPathParserContextPtr;
26
27/**
28 * The set of XPath error codes
29 */
30
31typedef enum {
32    XPATH_EXPRESSION_OK = 0,
33    XPATH_NUMBER_ERROR,
34    XPATH_UNFINISHED_LITERAL_ERROR,
35    XPATH_START_LITERAL_ERROR,
36    XPATH_VARIABLE_REF_ERROR,
37    XPATH_UNDEF_VARIABLE_ERROR,
38    XPATH_INVALID_PREDICATE_ERROR,
39    XPATH_EXPR_ERROR,
40    XPATH_UNCLOSED_ERROR,
41    XPATH_UNKNOWN_FUNC_ERROR,
42    XPATH_INVALID_OPERAND,
43    XPATH_INVALID_TYPE,
44    XPATH_INVALID_ARITY,
45    XPATH_INVALID_CTXT_SIZE,
46    XPATH_INVALID_CTXT_POSITION,
47    XPATH_MEMORY_ERROR,
48    XPTR_SYNTAX_ERROR,
49    XPTR_RESOURCE_ERROR,
50    XPTR_SUB_RESOURCE_ERROR,
51    XPATH_UNDEF_PREFIX_ERROR,
52    XPATH_ENCODING_ERROR,
53    XPATH_INVALID_CHAR_ERROR
54} xmlXPathError;
55
56/*
57 * A node-set (an unordered collection of nodes without duplicates)
58 */
59typedef struct _xmlNodeSet xmlNodeSet;
60typedef xmlNodeSet *xmlNodeSetPtr;
61struct _xmlNodeSet {
62    int nodeNr;			/* number of nodes in the set */
63    int nodeMax;		/* size of the array as allocated */
64    xmlNodePtr *nodeTab;	/* array of nodes in no particular order */
65};
66
67/*
68 * An expression is evaluated to yield an object, which
69 * has one of the following four basic types:
70 *   - node-set
71 *   - boolean
72 *   - number
73 *   - string
74 *
75 * @@ XPointer will add more types !
76 */
77
78typedef enum {
79    XPATH_UNDEFINED = 0,
80    XPATH_NODESET = 1,
81    XPATH_BOOLEAN = 2,
82    XPATH_NUMBER = 3,
83    XPATH_STRING = 4,
84    XPATH_POINT = 5,
85    XPATH_RANGE = 6,
86    XPATH_LOCATIONSET = 7,
87    XPATH_USERS = 8,
88    XPATH_XSLT_TREE = 9  /* An XSLT value tree, non modifiable */
89} xmlXPathObjectType;
90
91typedef struct _xmlXPathObject xmlXPathObject;
92typedef xmlXPathObject *xmlXPathObjectPtr;
93struct _xmlXPathObject {
94    xmlXPathObjectType type;
95    xmlNodeSetPtr nodesetval;
96    int boolval;
97    double floatval;
98    xmlChar *stringval;
99    void *user;
100    int index;
101    void *user2;
102    int index2;
103};
104
105/*
106 * A conversion function is associated to a type and used to cast
107 * the new type to primitive values.
108 */
109typedef int (*xmlXPathConvertFunc) (xmlXPathObjectPtr obj, int type);
110
111/*
112 * Extra type: a name and a conversion function.
113 */
114
115typedef struct _xmlXPathType xmlXPathType;
116typedef xmlXPathType *xmlXPathTypePtr;
117struct _xmlXPathType {
118    const xmlChar         *name;		/* the type name */
119    xmlXPathConvertFunc func;		/* the conversion function */
120};
121
122/*
123 * Extra variable: a name and a value.
124 */
125
126typedef struct _xmlXPathVariable xmlXPathVariable;
127typedef xmlXPathVariable *xmlXPathVariablePtr;
128struct _xmlXPathVariable {
129    const xmlChar       *name;		/* the variable name */
130    xmlXPathObjectPtr value;		/* the value */
131};
132
133/*
134 * an evaluation function, the parameters are on the context stack
135 */
136
137typedef void (*xmlXPathEvalFunc)(xmlXPathParserContextPtr ctxt, int nargs);
138
139/*
140 * Extra function: a name and a evaluation function.
141 */
142
143typedef struct _xmlXPathFunct xmlXPathFunct;
144typedef xmlXPathFunct *xmlXPathFuncPtr;
145struct _xmlXPathFunct {
146    const xmlChar      *name;		/* the function name */
147    xmlXPathEvalFunc func;		/* the evaluation function */
148};
149
150/*
151 * An axis traversal function. To traverse an axis, the engine calls
152 * the first time with cur == NULL and repeat until the function returns
153 * NULL indicating the end of the axis traversal.
154 */
155
156typedef xmlXPathObjectPtr (*xmlXPathAxisFunc)	(xmlXPathParserContextPtr ctxt,
157						 xmlXPathObjectPtr cur);
158
159/*
160 * Extra axis: a name and an axis function.
161 */
162
163typedef struct _xmlXPathAxis xmlXPathAxis;
164typedef xmlXPathAxis *xmlXPathAxisPtr;
165struct _xmlXPathAxis {
166    const xmlChar      *name;		/* the axis name */
167    xmlXPathAxisFunc func;		/* the search function */
168};
169
170/**
171 * xmlXPathContext:
172 *
173 * Expression evaluation occurs with respect to a context.
174 * he context consists of:
175 *    - a node (the context node)
176 *    - a node list (the context node list)
177 *    - a set of variable bindings
178 *    - a function library
179 *    - the set of namespace declarations in scope for the expression
180 * Following the switch to hash tables, this need to be trimmed up at
181 * the next binary incompatible release.
182 */
183
184struct _xmlXPathContext {
185    xmlDocPtr doc;			/* The current document */
186    xmlNodePtr node;			/* The current node */
187
188    int nb_variables_unused;		/* unused (hash table) */
189    int max_variables_unused;		/* unused (hash table) */
190    xmlHashTablePtr varHash;		/* Hash table of defined variables */
191
192    int nb_types;			/* number of defined types */
193    int max_types;			/* max number of types */
194    xmlXPathTypePtr types;		/* Array of defined types */
195
196    int nb_funcs_unused;		/* unused (hash table) */
197    int max_funcs_unused;		/* unused (hash table) */
198    xmlHashTablePtr funcHash;		/* Hash table of defined funcs */
199
200    int nb_axis;			/* number of defined axis */
201    int max_axis;			/* max number of axis */
202    xmlXPathAxisPtr axis;		/* Array of defined axis */
203
204    /* the namespace nodes of the context node */
205    xmlNsPtr *namespaces;		/* Array of namespaces */
206    int nsNr;				/* number of namespace in scope */
207    void *user;				/* function to free */
208
209    /* extra variables */
210    int contextSize;			/* the context size */
211    int proximityPosition;		/* the proximity position */
212
213    /* extra stuff for XPointer */
214    int xptr;				/* it this an XPointer context */
215    xmlNodePtr here;			/* for here() */
216    xmlNodePtr origin;			/* for origin() */
217
218    /* the set of namespace declarations in scope for the expression */
219    xmlHashTablePtr nsHash;		/* The namespaces hash table */
220    void *varLookupFunc;		/* variable lookup func */
221    void *varLookupData;		/* variable lookup data */
222
223    /* Possibility to link in an extra item */
224    void *extra;                        /* needed for XSLT */
225
226    /* The function name and URI when calling a function */
227    const xmlChar *function;
228    const xmlChar *functionURI;
229};
230
231/*
232 * The structure of a compiled expression form is not public
233 */
234
235typedef struct _xmlXPathCompExpr xmlXPathCompExpr;
236typedef xmlXPathCompExpr *xmlXPathCompExprPtr;
237
238/**
239 * xmlXPathParserContext:
240 *
241 * An XPath parser context, it contains pure parsing informations,
242 * an xmlXPathContext, and the stack of objects.
243 */
244struct _xmlXPathParserContext {
245    const xmlChar *cur;			/* the current char being parsed */
246    const xmlChar *base;			/* the full expression */
247
248    int error;				/* error code */
249
250    xmlXPathContextPtr  context;	/* the evaluation context */
251    xmlXPathObjectPtr     value;	/* the current value */
252    int                 valueNr;	/* number of values stacked */
253    int                valueMax;	/* max number of values stacked */
254    xmlXPathObjectPtr *valueTab;	/* stack of values */
255
256    xmlXPathCompExprPtr comp;		/* the precompiled expression */
257    int xptr;				/* it this an XPointer expression */
258};
259
260/**
261 * xmlXPathFunction:
262 *
263 * An XPath function
264 * The arguments (if any) are popped out of the context stack
265 * and the result is pushed on the stack.
266 */
267
268typedef void (*xmlXPathFunction) (xmlXPathParserContextPtr ctxt, int nargs);
269
270/************************************************************************
271 *									*
272 *			Public API					*
273 *									*
274 ************************************************************************/
275
276/**
277 * Objects and Nodesets handling
278 */
279
280/* These macros may later turn into functions */
281#define xmlXPathNodeSetGetLength(ns) ((ns) ? (ns)->nodeNr : 0)
282#define xmlXPathNodeSetItem(ns, index)				\
283		((((ns) != NULL) && 				\
284		  ((index) > 0) && ((index) <= (ns)->nodeNr)) ?	\
285		 (ns)->nodeTab[(index)]				\
286		 : NULL)
287
288
289void		   xmlXPathFreeObject		(xmlXPathObjectPtr obj);
290xmlNodeSetPtr	   xmlXPathNodeSetCreate	(xmlNodePtr val);
291void		   xmlXPathFreeNodeSetList	(xmlXPathObjectPtr obj);
292void		   xmlXPathFreeNodeSet		(xmlNodeSetPtr obj);
293xmlXPathObjectPtr  xmlXPathObjectCopy		(xmlXPathObjectPtr val);
294int		   xmlXPathCmpNodes		(xmlNodePtr node1,
295						 xmlNodePtr node2);
296/**
297 * Conversion functions to basic types
298 */
299int		   xmlXPathCastNumberToBoolean	(double val);
300int		   xmlXPathCastStringToBoolean	(const xmlChar * val);
301int		   xmlXPathCastNodeSetToBoolean	(xmlNodeSetPtr ns);
302int		   xmlXPathCastToBoolean	(xmlXPathObjectPtr val);
303
304double		   xmlXPathCastBooleanToNumber	(int val);
305double		   xmlXPathCastStringToNumber	(const xmlChar * val);
306double		   xmlXPathCastNodeToNumber	(xmlNodePtr node);
307double		   xmlXPathCastNodeSetToNumber	(xmlNodeSetPtr ns);
308double		   xmlXPathCastToNumber		(xmlXPathObjectPtr val);
309
310xmlChar *	   xmlXPathCastBooleanToString	(int val);
311xmlChar *	   xmlXPathCastNumberToString	(double val);
312xmlChar *	   xmlXPathCastNodeToString	(xmlNodePtr node);
313xmlChar *	   xmlXPathCastNodeSetToString	(xmlNodeSetPtr ns);
314xmlChar *	   xmlXPathCastToString		(xmlXPathObjectPtr val);
315
316xmlXPathObjectPtr  xmlXPathConvertBoolean	(xmlXPathObjectPtr val);
317xmlXPathObjectPtr  xmlXPathConvertNumber	(xmlXPathObjectPtr val);
318xmlXPathObjectPtr  xmlXPathConvertString	(xmlXPathObjectPtr val);
319
320/**
321 * Context handling
322 */
323void		   xmlXPathInit			(void);
324xmlXPathContextPtr xmlXPathNewContext		(xmlDocPtr doc);
325void		   xmlXPathFreeContext		(xmlXPathContextPtr ctxt);
326
327/**
328 * Evaluation functions.
329 */
330xmlXPathObjectPtr  xmlXPathEval			(const xmlChar *str,
331						 xmlXPathContextPtr ctxt);
332xmlXPathObjectPtr  xmlXPathEvalXPtrExpr		(const xmlChar *str,
333						 xmlXPathContextPtr ctxt);
334xmlXPathObjectPtr  xmlXPathEvalExpression	(const xmlChar *str,
335						 xmlXPathContextPtr ctxt);
336int                xmlXPathEvalPredicate	(xmlXPathContextPtr ctxt,
337						 xmlXPathObjectPtr res);
338/**
339 * Separate compilation/evaluation entry points
340 */
341xmlXPathCompExprPtr xmlXPathCompile		(const xmlChar *str);
342xmlXPathObjectPtr   xmlXPathCompiledEval	(xmlXPathCompExprPtr comp,
343						 xmlXPathContextPtr ctx);
344void                xmlXPathFreeCompExpr	(xmlXPathCompExprPtr comp);
345#ifdef __cplusplus
346}
347#endif
348#endif /* ! __XML_XPATH_H__ */
349