/app/libxml2-2.4.28/include/libxml2/libxml/xpath.h
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.com
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
19 extern "C" {
20 #endif
21
22 typedef struct _xmlXPathContext xmlXPathContext;
23 typedef xmlXPathContext *xmlXPathContextPtr;
24 typedef struct _xmlXPathParserContext xmlXPathParserContext;
25 typedef xmlXPathParserContext *xmlXPathParserContextPtr;
26
27 /**
28 * The set of XPath error codes.
29 */
30
31 typedef 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 */
59 typedef struct _xmlNodeSet xmlNodeSet;
60 typedef xmlNodeSet *xmlNodeSetPtr;
61 struct _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 /* @@ with_ns to check wether namespace nodes should be looked at @@ */
66 };
67
68 /*
69 * An expression is evaluated to yield an object, which
70 * has one of the following four basic types:
71 * - node-set
72 * - boolean
73 * - number
74 * - string
75 *
76 * @@ XPointer will add more types !
77 */
78
79 typedef enum {
80 XPATH_UNDEFINED = 0,
81 XPATH_NODESET = 1,
82 XPATH_BOOLEAN = 2,
83 XPATH_NUMBER = 3,
84 XPATH_STRING = 4,
85 XPATH_POINT = 5,
86 XPATH_RANGE = 6,
87 XPATH_LOCATIONSET = 7,
88 XPATH_USERS = 8,
89 XPATH_XSLT_TREE = 9 /* An XSLT value tree, non modifiable */
90 } xmlXPathObjectType;
91
92 typedef struct _xmlXPathObject xmlXPathObject;
93 typedef xmlXPathObject *xmlXPathObjectPtr;
94 struct _xmlXPathObject {
95 xmlXPathObjectType type;
96 xmlNodeSetPtr nodesetval;
97 int boolval;
98 double floatval;
99 xmlChar *stringval;
100 void *user;
101 int index;
102 void *user2;
103 int index2;
104 };
105
106 /**
107 * xmlXPathConvertFunc:
108 * @obj: an XPath object
109 * @type: the number of the target type
110 *
111 * A conversion function is associated to a type and used to cast
112 * the new type to primitive values.
113 *
114 * Returns -1 in case of error, 0 otherwise
115 */
116 typedef int (*xmlXPathConvertFunc) (xmlXPathObjectPtr obj, int type);
117
118 /*
119 * Extra type: a name and a conversion function.
120 */
121
122 typedef struct _xmlXPathType xmlXPathType;
123 typedef xmlXPathType *xmlXPathTypePtr;
124 struct _xmlXPathType {
125 const xmlChar *name; /* the type name */
126 xmlXPathConvertFunc func; /* the conversion function */
127 };
128
129 /*
130 * Extra variable: a name and a value.
131 */
132
133 typedef struct _xmlXPathVariable xmlXPathVariable;
134 typedef xmlXPathVariable *xmlXPathVariablePtr;
135 struct _xmlXPathVariable {
136 const xmlChar *name; /* the variable name */
137 xmlXPathObjectPtr value; /* the value */
138 };
139
140 /**
141 * xmlXPathEvalFunc:
142 * @ctxt: an XPath parser context
143 * @nargs: the number of arguments passed to the function
144 *
145 * An XPath evaluation function, the parameters are on the XPath context stack.
146 */
147
148 typedef void (*xmlXPathEvalFunc)(xmlXPathParserContextPtr ctxt,
149 int nargs);
150
151 /*
152 * Extra function: a name and a evaluation function.
153 */
154
155 typedef struct _xmlXPathFunct xmlXPathFunct;
156 typedef xmlXPathFunct *xmlXPathFuncPtr;
157 struct _xmlXPathFunct {
158 const xmlChar *name; /* the function name */
159 xmlXPathEvalFunc func; /* the evaluation function */
160 };
161
162 /**
163 * xmlXPathAxisFunc:
164 * @ctxt: the XPath interpreter context
165 * @cur: the previous node being explored on that axis
166 *
167 * An axis traversal function. To traverse an axis, the engine calls
168 * the first time with cur == NULL and repeat until the function returns
169 * NULL indicating the end of the axis traversal.
170 *
171 * Returns the next node in that axis or NULL if at the end of the axis.
172 */
173
174 typedef xmlXPathObjectPtr (*xmlXPathAxisFunc) (xmlXPathParserContextPtr ctxt,
175 xmlXPathObjectPtr cur);
176
177 /*
178 * Extra axis: a name and an axis function.
179 */
180
181 typedef struct _xmlXPathAxis xmlXPathAxis;
182 typedef xmlXPathAxis *xmlXPathAxisPtr;
183 struct _xmlXPathAxis {
184 const xmlChar *name; /* the axis name */
185 xmlXPathAxisFunc func; /* the search function */
186 };
187
188 /**
189 * xmlXPathContext:
190 *
191 * Expression evaluation occurs with respect to a context.
192 * he context consists of:
193 * - a node (the context node)
194 * - a node list (the context node list)
195 * - a set of variable bindings
196 * - a function library
197 * - the set of namespace declarations in scope for the expression
198 * Following the switch to hash tables, this need to be trimmed up at
199 * the next binary incompatible release.
200 */
201
202 struct _xmlXPathContext {
203 xmlDocPtr doc; /* The current document */
204 xmlNodePtr node; /* The current node */
205
206 int nb_variables_unused; /* unused (hash table) */
207 int max_variables_unused; /* unused (hash table) */
208 xmlHashTablePtr varHash; /* Hash table of defined variables */
209
210 int nb_types; /* number of defined types */
211 int max_types; /* max number of types */
212 xmlXPathTypePtr types; /* Array of defined types */
213
214 int nb_funcs_unused; /* unused (hash table) */
215 int max_funcs_unused; /* unused (hash table) */
216 xmlHashTablePtr funcHash; /* Hash table of defined funcs */
217
218 int nb_axis; /* number of defined axis */
219 int max_axis; /* max number of axis */
220 xmlXPathAxisPtr axis; /* Array of defined axis */
221
222 /* the namespace nodes of the context node */
223 xmlNsPtr *namespaces; /* Array of namespaces */
224 int nsNr; /* number of namespace in scope */
225 void *user; /* function to free */
226
227 /* extra variables */
228 int contextSize; /* the context size */
229 int proximityPosition; /* the proximity position */
230
231 /* extra stuff for XPointer */
232 int xptr; /* it this an XPointer context */
233 xmlNodePtr here; /* for here() */
234 xmlNodePtr origin; /* for origin() */
235
236 /* the set of namespace declarations in scope for the expression */
237 xmlHashTablePtr nsHash; /* The namespaces hash table */
238 void *varLookupFunc; /* variable lookup func */
239 void *varLookupData; /* variable lookup data */
240
241 /* Possibility to link in an extra item */
242 void *extra; /* needed for XSLT */
243
244 /* The function name and URI when calling a function */
245 const xmlChar *function;
246 const xmlChar *functionURI;
247
248 /* function lookup function and data */
249 void *funcLookupFunc; /* function lookup func */
250 void *funcLookupData; /* function lookup data */
251
252 /* temporary namespace lists kept for walking the namespace axis */
253 xmlNsPtr *tmpNsList; /* Array of namespaces */
254 int tmpNsNr; /* number of namespace in scope */
255 };
256
257 /*
258 * The structure of a compiled expression form is not public.
259 */
260
261 typedef struct _xmlXPathCompExpr xmlXPathCompExpr;
262 typedef xmlXPathCompExpr *xmlXPathCompExprPtr;
263
264 /**
265 * xmlXPathParserContext:
266 *
267 * An XPath parser context. It contains pure parsing informations,
268 * an xmlXPathContext, and the stack of objects.
269 */
270 struct _xmlXPathParserContext {
271 const xmlChar *cur; /* the current char being parsed */
272 const xmlChar *base; /* the full expression */
273
274 int error; /* error code */
275
276 xmlXPathContextPtr context; /* the evaluation context */
277 xmlXPathObjectPtr value; /* the current value */
278 int valueNr; /* number of values stacked */
279 int valueMax; /* max number of values stacked */
280 xmlXPathObjectPtr *valueTab; /* stack of values */
281
282 xmlXPathCompExprPtr comp; /* the precompiled expression */
283 int xptr; /* it this an XPointer expression */
284 xmlNodePtr ancestor; /* used for walking preceding axis */
285 };
286
287 /**
288 * xmlXPathFunction:
289 * @ctxt: the XPath interprestation context
290 * @nargs: the number of arguments
291 *
292 * An XPath function.
293 * The arguments (if any) are popped out from the context stack
294 * and the result is pushed on the stack.
295 */
296
297 typedef void (*xmlXPathFunction) (xmlXPathParserContextPtr ctxt, int nargs);
298
299 /************************************************************************
300 * *
301 * Public API *
302 * *
303 ************************************************************************/
304
305 /**
306 * Objects and Nodesets handling
307 */
308
309 LIBXML_DLL_IMPORT extern double xmlXPathNAN;
310 LIBXML_DLL_IMPORT extern double xmlXPathPINF;
311 LIBXML_DLL_IMPORT extern double xmlXPathNINF;
312
313 int xmlXPathIsNaN (double val);
314 int xmlXPathIsInf (double val);
315
316 /* These macros may later turn into functions */
317 /**
318 * xmlXPathNodeSetGetLength:
319 * @ns: a node-set
320 *
321 * Implement a functionality similar to the DOM NodeList.length.
322 *
323 * Returns the number of nodes in the node-set.
324 */
325 #define xmlXPathNodeSetGetLength(ns) ((ns) ? (ns)->nodeNr : 0)
326 /**
327 * xmlXPathNodeSetItem:
328 * @ns: a node-set
329 * @index: index of a node in the set
330 *
331 * Implements a functionality similar to the DOM NodeList.item().
332 *
333 * Returns the xmlNodePtr at the given @index in @ns or NULL if
334 * @index is out of range (0 to length-1)
335 */
336 #define xmlXPathNodeSetItem(ns, index) \
337 ((((ns) != NULL) && \
338 ((index) >= 0) && ((index) < (ns)->nodeNr)) ? \
339 (ns)->nodeTab[(index)] \
340 : NULL)
341 /**
342 * xmlXPathNodeSetIsEmpty:
343 * @ns: a node-set
344 *
345 * Checks whether @ns is empty or not.
346 *
347 * Returns %TRUE if @ns is an empty node-set.
348 */
349 #define xmlXPathNodeSetIsEmpty(ns) \
350 (((ns) == NULL) || ((ns)->nodeNr == 0) || ((ns)->nodeTab == NULL))
351
352
353 void xmlXPathFreeObject (xmlXPathObjectPtr obj);
354 xmlNodeSetPtr xmlXPathNodeSetCreate (xmlNodePtr val);
355 void xmlXPathFreeNodeSetList (xmlXPathObjectPtr obj);
356 void xmlXPathFreeNodeSet (xmlNodeSetPtr obj);
357 xmlXPathObjectPtr xmlXPathObjectCopy (xmlXPathObjectPtr val);
358 int xmlXPathCmpNodes (xmlNodePtr node1,
359 xmlNodePtr node2);
360 /**
361 * Conversion functions to basic types.
362 */
363 int xmlXPathCastNumberToBoolean (double val);
364 int xmlXPathCastStringToBoolean (const xmlChar * val);
365 int xmlXPathCastNodeSetToBoolean (xmlNodeSetPtr ns);
366 int xmlXPathCastToBoolean (xmlXPathObjectPtr val);
367
368 double xmlXPathCastBooleanToNumber (int val);
369 double xmlXPathCastStringToNumber (const xmlChar * val);
370 double xmlXPathCastNodeToNumber (xmlNodePtr node);
371 double xmlXPathCastNodeSetToNumber (xmlNodeSetPtr ns);
372 double xmlXPathCastToNumber (xmlXPathObjectPtr val);
373
374 xmlChar * xmlXPathCastBooleanToString (int val);
375 xmlChar * xmlXPathCastNumberToString (double val);
376 xmlChar * xmlXPathCastNodeToString (xmlNodePtr node);
377 xmlChar * xmlXPathCastNodeSetToString (xmlNodeSetPtr ns);
378 xmlChar * xmlXPathCastToString (xmlXPathObjectPtr val);
379
380 xmlXPathObjectPtr xmlXPathConvertBoolean (xmlXPathObjectPtr val);
381 xmlXPathObjectPtr xmlXPathConvertNumber (xmlXPathObjectPtr val);
382 xmlXPathObjectPtr xmlXPathConvertString (xmlXPathObjectPtr val);
383
384 /**
385 * Context handling.
386 */
387 void xmlXPathInit (void);
388 xmlXPathContextPtr xmlXPathNewContext (xmlDocPtr doc);
389 void xmlXPathFreeContext (xmlXPathContextPtr ctxt);
390
391 /**
392 * Evaluation functions.
393 */
394 xmlXPathObjectPtr xmlXPathEval (const xmlChar *str,
395 xmlXPathContextPtr ctx);
396 xmlXPathObjectPtr xmlXPathEvalExpression (const xmlChar *str,
397 xmlXPathContextPtr ctxt);
398 int xmlXPathEvalPredicate (xmlXPathContextPtr ctxt,
399 xmlXPathObjectPtr res);
400 /**
401 * Separate compilation/evaluation entry points.
402 */
403 xmlXPathCompExprPtr xmlXPathCompile (const xmlChar *str);
404 xmlXPathObjectPtr xmlXPathCompiledEval (xmlXPathCompExprPtr comp,
405 xmlXPathContextPtr ctx);
406 void xmlXPathFreeCompExpr (xmlXPathCompExprPtr comp);
407 #ifdef __cplusplus
408 }
409 #endif
410 #endif /* ! __XML_XPATH_H__ */