|
1 /* |
|
2 * Summary: XML Path Language implementation |
|
3 * Description: API for the XML Path Language implementation |
|
4 * |
|
5 * XML Path Language implementation |
|
6 * XPath is a language for addressing parts of an XML document, |
|
7 * designed to be used by both XSLT and XPointer |
|
8 * http://www.w3.org/TR/xpath |
|
9 * |
|
10 * Implements |
|
11 * W3C Recommendation 16 November 1999 |
|
12 * http://www.w3.org/TR/1999/REC-xpath-19991116 |
|
13 * |
|
14 * Copy: See Copyright for the status of this software. |
|
15 * |
|
16 * Author: Daniel Veillard |
|
17 */ |
|
18 |
|
19 #ifndef __XML_XPATH_H__ |
|
20 #define __XML_XPATH_H__ |
|
21 |
|
22 #include <libxml/xmlversion.h> |
|
23 |
|
24 #ifdef LIBXML_XPATH_ENABLED |
|
25 |
|
26 #include <libxml/xmlerror.h> |
|
27 #include <libxml/tree.h> |
|
28 #include <libxml/hash.h> |
|
29 #endif /* LIBXML_XPATH_ENABLED */ |
|
30 |
|
31 #if defined(LIBXML_XPATH_ENABLED) || defined(LIBXML_SCHEMAS_ENABLED) |
|
32 #ifdef __cplusplus |
|
33 extern "C" { |
|
34 #endif |
|
35 #endif /* LIBXML_XPATH_ENABLED or LIBXML_SCHEMAS_ENABLED */ |
|
36 |
|
37 #ifdef LIBXML_XPATH_ENABLED |
|
38 typedef struct _xmlXPathContext xmlXPathContext; |
|
39 typedef xmlXPathContext *xmlXPathContextPtr; |
|
40 typedef struct _xmlXPathParserContext xmlXPathParserContext; |
|
41 typedef xmlXPathParserContext *xmlXPathParserContextPtr; |
|
42 |
|
43 /** |
|
44 * The set of XPath error codes. |
|
45 */ |
|
46 |
|
47 typedef enum { |
|
48 XPATH_EXPRESSION_OK = 0, |
|
49 XPATH_NUMBER_ERROR, |
|
50 XPATH_UNFINISHED_LITERAL_ERROR, |
|
51 XPATH_START_LITERAL_ERROR, |
|
52 XPATH_VARIABLE_REF_ERROR, |
|
53 XPATH_UNDEF_VARIABLE_ERROR, |
|
54 XPATH_INVALID_PREDICATE_ERROR, |
|
55 XPATH_EXPR_ERROR, |
|
56 XPATH_UNCLOSED_ERROR, |
|
57 XPATH_UNKNOWN_FUNC_ERROR, |
|
58 XPATH_INVALID_OPERAND, |
|
59 XPATH_INVALID_TYPE, |
|
60 XPATH_INVALID_ARITY, |
|
61 XPATH_INVALID_CTXT_SIZE, |
|
62 XPATH_INVALID_CTXT_POSITION, |
|
63 XPATH_MEMORY_ERROR, |
|
64 XPTR_SYNTAX_ERROR, |
|
65 XPTR_RESOURCE_ERROR, |
|
66 XPTR_SUB_RESOURCE_ERROR, |
|
67 XPATH_UNDEF_PREFIX_ERROR, |
|
68 XPATH_ENCODING_ERROR, |
|
69 XPATH_INVALID_CHAR_ERROR, |
|
70 XPATH_INVALID_CTXT |
|
71 } xmlXPathError; |
|
72 |
|
73 /* |
|
74 * A node-set (an unordered collection of nodes without duplicates). |
|
75 */ |
|
76 typedef struct _xmlNodeSet xmlNodeSet; |
|
77 typedef xmlNodeSet *xmlNodeSetPtr; |
|
78 struct _xmlNodeSet { |
|
79 int nodeNr; /* number of nodes in the set */ |
|
80 int nodeMax; /* size of the array as allocated */ |
|
81 xmlNodePtr *nodeTab; /* array of nodes in no particular order */ |
|
82 /* @@ with_ns to check wether namespace nodes should be looked at @@ */ |
|
83 }; |
|
84 |
|
85 /* |
|
86 * An expression is evaluated to yield an object, which |
|
87 * has one of the following four basic types: |
|
88 * - node-set |
|
89 * - boolean |
|
90 * - number |
|
91 * - string |
|
92 * |
|
93 * @@ XPointer will add more types ! |
|
94 */ |
|
95 |
|
96 typedef enum { |
|
97 XPATH_UNDEFINED = 0, |
|
98 XPATH_NODESET = 1, |
|
99 XPATH_BOOLEAN = 2, |
|
100 XPATH_NUMBER = 3, |
|
101 XPATH_STRING = 4, |
|
102 XPATH_POINT = 5, |
|
103 XPATH_RANGE = 6, |
|
104 XPATH_LOCATIONSET = 7, |
|
105 XPATH_USERS = 8, |
|
106 XPATH_XSLT_TREE = 9 /* An XSLT value tree, non modifiable */ |
|
107 } xmlXPathObjectType; |
|
108 |
|
109 typedef struct _xmlXPathObject xmlXPathObject; |
|
110 typedef xmlXPathObject *xmlXPathObjectPtr; |
|
111 struct _xmlXPathObject { |
|
112 xmlXPathObjectType type; |
|
113 xmlNodeSetPtr nodesetval; |
|
114 int boolval; |
|
115 double floatval; |
|
116 xmlChar *stringval; |
|
117 void *user; |
|
118 int index; |
|
119 void *user2; |
|
120 int index2; |
|
121 }; |
|
122 |
|
123 /** |
|
124 * xmlXPathConvertFunc: |
|
125 * @obj: an XPath object |
|
126 * @type: the number of the target type |
|
127 * |
|
128 * A conversion function is associated to a type and used to cast |
|
129 * the new type to primitive values. |
|
130 * |
|
131 * Returns -1 in case of error, 0 otherwise |
|
132 */ |
|
133 typedef int (*xmlXPathConvertFunc) (xmlXPathObjectPtr obj, int type); |
|
134 |
|
135 /* |
|
136 * Extra type: a name and a conversion function. |
|
137 */ |
|
138 |
|
139 typedef struct _xmlXPathType xmlXPathType; |
|
140 typedef xmlXPathType *xmlXPathTypePtr; |
|
141 struct _xmlXPathType { |
|
142 const xmlChar *name; /* the type name */ |
|
143 xmlXPathConvertFunc func; /* the conversion function */ |
|
144 }; |
|
145 |
|
146 /* |
|
147 * Extra variable: a name and a value. |
|
148 */ |
|
149 |
|
150 typedef struct _xmlXPathVariable xmlXPathVariable; |
|
151 typedef xmlXPathVariable *xmlXPathVariablePtr; |
|
152 struct _xmlXPathVariable { |
|
153 const xmlChar *name; /* the variable name */ |
|
154 xmlXPathObjectPtr value; /* the value */ |
|
155 }; |
|
156 |
|
157 /** |
|
158 * xmlXPathEvalFunc: |
|
159 * @ctxt: an XPath parser context |
|
160 * @nargs: the number of arguments passed to the function |
|
161 * |
|
162 * An XPath evaluation function, the parameters are on the XPath context stack. |
|
163 */ |
|
164 |
|
165 typedef void (*xmlXPathEvalFunc)(xmlXPathParserContextPtr ctxt, |
|
166 int nargs); |
|
167 |
|
168 /* |
|
169 * Extra function: a name and a evaluation function. |
|
170 */ |
|
171 |
|
172 typedef struct _xmlXPathFunct xmlXPathFunct; |
|
173 typedef xmlXPathFunct *xmlXPathFuncPtr; |
|
174 struct _xmlXPathFunct { |
|
175 const xmlChar *name; /* the function name */ |
|
176 xmlXPathEvalFunc func; /* the evaluation function */ |
|
177 }; |
|
178 |
|
179 /** |
|
180 * xmlXPathAxisFunc: |
|
181 * @ctxt: the XPath interpreter context |
|
182 * @cur: the previous node being explored on that axis |
|
183 * |
|
184 * An axis traversal function. To traverse an axis, the engine calls |
|
185 * the first time with cur == NULL and repeat until the function returns |
|
186 * NULL indicating the end of the axis traversal. |
|
187 * |
|
188 * Returns the next node in that axis or NULL if at the end of the axis. |
|
189 */ |
|
190 |
|
191 typedef xmlXPathObjectPtr (*xmlXPathAxisFunc) (xmlXPathParserContextPtr ctxt, |
|
192 xmlXPathObjectPtr cur); |
|
193 |
|
194 /* |
|
195 * Extra axis: a name and an axis function. |
|
196 */ |
|
197 |
|
198 typedef struct _xmlXPathAxis xmlXPathAxis; |
|
199 typedef xmlXPathAxis *xmlXPathAxisPtr; |
|
200 struct _xmlXPathAxis { |
|
201 const xmlChar *name; /* the axis name */ |
|
202 xmlXPathAxisFunc func; /* the search function */ |
|
203 }; |
|
204 |
|
205 /** |
|
206 * xmlXPathFunction: |
|
207 * @ctxt: the XPath interprestation context |
|
208 * @nargs: the number of arguments |
|
209 * |
|
210 * An XPath function. |
|
211 * The arguments (if any) are popped out from the context stack |
|
212 * and the result is pushed on the stack. |
|
213 */ |
|
214 |
|
215 typedef void (*xmlXPathFunction) (xmlXPathParserContextPtr ctxt, int nargs); |
|
216 |
|
217 /* |
|
218 * Function and Variable Lookup. |
|
219 */ |
|
220 |
|
221 /** |
|
222 * xmlXPathVariableLookupFunc: |
|
223 * @ctxt: an XPath context |
|
224 * @name: name of the variable |
|
225 * @ns_uri: the namespace name hosting this variable |
|
226 * |
|
227 * Prototype for callbacks used to plug variable lookup in the XPath |
|
228 * engine. |
|
229 * |
|
230 * Returns the XPath object value or NULL if not found. |
|
231 */ |
|
232 typedef xmlXPathObjectPtr (*xmlXPathVariableLookupFunc) (void *ctxt, |
|
233 const xmlChar *name, |
|
234 const xmlChar *ns_uri); |
|
235 |
|
236 /** |
|
237 * xmlXPathFuncLookupFunc: |
|
238 * @ctxt: an XPath context |
|
239 * @name: name of the function |
|
240 * @ns_uri: the namespace name hosting this function |
|
241 * |
|
242 * Prototype for callbacks used to plug function lookup in the XPath |
|
243 * engine. |
|
244 * |
|
245 * Returns the XPath function or NULL if not found. |
|
246 */ |
|
247 typedef xmlXPathFunction (*xmlXPathFuncLookupFunc) (void *ctxt, |
|
248 const xmlChar *name, |
|
249 const xmlChar *ns_uri); |
|
250 |
|
251 /** |
|
252 * xmlXPathFlags: |
|
253 * Flags for XPath engine compilation and runtime |
|
254 */ |
|
255 /** |
|
256 * XML_XPATH_CHECKNS: |
|
257 * |
|
258 * check namespaces at compilation |
|
259 */ |
|
260 #define XML_XPATH_CHECKNS (1<<0) |
|
261 /** |
|
262 * XML_XPATH_NOVAR: |
|
263 * |
|
264 * forbid variables in expression |
|
265 */ |
|
266 #define XML_XPATH_NOVAR (1<<1) |
|
267 |
|
268 /** |
|
269 * xmlXPathContext: |
|
270 * |
|
271 * Expression evaluation occurs with respect to a context. |
|
272 * he context consists of: |
|
273 * - a node (the context node) |
|
274 * - a node list (the context node list) |
|
275 * - a set of variable bindings |
|
276 * - a function library |
|
277 * - the set of namespace declarations in scope for the expression |
|
278 * Following the switch to hash tables, this need to be trimmed up at |
|
279 * the next binary incompatible release. |
|
280 */ |
|
281 |
|
282 struct _xmlXPathContext { |
|
283 xmlDocPtr doc; /* The current document */ |
|
284 xmlNodePtr node; /* The current node */ |
|
285 |
|
286 int nb_variables_unused; /* unused (hash table) */ |
|
287 int max_variables_unused; /* unused (hash table) */ |
|
288 xmlHashTablePtr varHash; /* Hash table of defined variables */ |
|
289 |
|
290 int nb_types; /* number of defined types */ |
|
291 int max_types; /* max number of types */ |
|
292 xmlXPathTypePtr types; /* Array of defined types */ |
|
293 |
|
294 int nb_funcs_unused; /* unused (hash table) */ |
|
295 int max_funcs_unused; /* unused (hash table) */ |
|
296 xmlHashTablePtr funcHash; /* Hash table of defined funcs */ |
|
297 |
|
298 int nb_axis; /* number of defined axis */ |
|
299 int max_axis; /* max number of axis */ |
|
300 xmlXPathAxisPtr axis; /* Array of defined axis */ |
|
301 |
|
302 /* the namespace nodes of the context node */ |
|
303 xmlNsPtr *namespaces; /* Array of namespaces */ |
|
304 int nsNr; /* number of namespace in scope */ |
|
305 void *user; /* function to free */ |
|
306 |
|
307 /* extra variables */ |
|
308 int contextSize; /* the context size */ |
|
309 int proximityPosition; /* the proximity position */ |
|
310 |
|
311 /* extra stuff for XPointer */ |
|
312 int xptr; /* it this an XPointer context */ |
|
313 xmlNodePtr here; /* for here() */ |
|
314 xmlNodePtr origin; /* for origin() */ |
|
315 |
|
316 /* the set of namespace declarations in scope for the expression */ |
|
317 xmlHashTablePtr nsHash; /* The namespaces hash table */ |
|
318 xmlXPathVariableLookupFunc varLookupFunc;/* variable lookup func */ |
|
319 void *varLookupData; /* variable lookup data */ |
|
320 |
|
321 /* Possibility to link in an extra item */ |
|
322 void *extra; /* needed for XSLT */ |
|
323 |
|
324 /* The function name and URI when calling a function */ |
|
325 const xmlChar *function; |
|
326 const xmlChar *functionURI; |
|
327 |
|
328 /* function lookup function and data */ |
|
329 xmlXPathFuncLookupFunc funcLookupFunc;/* function lookup func */ |
|
330 void *funcLookupData; /* function lookup data */ |
|
331 |
|
332 /* temporary namespace lists kept for walking the namespace axis */ |
|
333 xmlNsPtr *tmpNsList; /* Array of namespaces */ |
|
334 int tmpNsNr; /* number of namespace in scope */ |
|
335 |
|
336 /* error reporting mechanism */ |
|
337 void *userData; /* user specific data block */ |
|
338 xmlStructuredErrorFunc error; /* the callback in case of errors */ |
|
339 xmlError lastError; /* the last error */ |
|
340 xmlNodePtr debugNode; /* the source node XSLT */ |
|
341 |
|
342 /* dictionnary */ |
|
343 xmlDictPtr dict; /* dictionnary if any */ |
|
344 |
|
345 int flags; /* flags to control compilation */ |
|
346 }; |
|
347 |
|
348 /* |
|
349 * The structure of a compiled expression form is not public. |
|
350 */ |
|
351 |
|
352 typedef struct _xmlXPathCompExpr xmlXPathCompExpr; |
|
353 typedef xmlXPathCompExpr *xmlXPathCompExprPtr; |
|
354 |
|
355 /** |
|
356 * xmlXPathParserContext: |
|
357 * |
|
358 * An XPath parser context. It contains pure parsing informations, |
|
359 * an xmlXPathContext, and the stack of objects. |
|
360 */ |
|
361 struct _xmlXPathParserContext { |
|
362 const xmlChar *cur; /* the current char being parsed */ |
|
363 const xmlChar *base; /* the full expression */ |
|
364 |
|
365 int error; /* error code */ |
|
366 |
|
367 xmlXPathContextPtr context; /* the evaluation context */ |
|
368 xmlXPathObjectPtr value; /* the current value */ |
|
369 int valueNr; /* number of values stacked */ |
|
370 int valueMax; /* max number of values stacked */ |
|
371 xmlXPathObjectPtr *valueTab; /* stack of values */ |
|
372 |
|
373 xmlXPathCompExprPtr comp; /* the precompiled expression */ |
|
374 int xptr; /* it this an XPointer expression */ |
|
375 xmlNodePtr ancestor; /* used for walking preceding axis */ |
|
376 }; |
|
377 |
|
378 /************************************************************************ |
|
379 * * |
|
380 * Public API * |
|
381 * * |
|
382 ************************************************************************/ |
|
383 |
|
384 /** |
|
385 * Objects and Nodesets handling |
|
386 */ |
|
387 |
|
388 XMLPUBVAR double xmlXPathNAN; |
|
389 XMLPUBVAR double xmlXPathPINF; |
|
390 XMLPUBVAR double xmlXPathNINF; |
|
391 |
|
392 /* These macros may later turn into functions */ |
|
393 /** |
|
394 * xmlXPathNodeSetGetLength: |
|
395 * @ns: a node-set |
|
396 * |
|
397 * Implement a functionality similar to the DOM NodeList.length. |
|
398 * |
|
399 * Returns the number of nodes in the node-set. |
|
400 */ |
|
401 #define xmlXPathNodeSetGetLength(ns) ((ns) ? (ns)->nodeNr : 0) |
|
402 /** |
|
403 * xmlXPathNodeSetItem: |
|
404 * @ns: a node-set |
|
405 * @index: index of a node in the set |
|
406 * |
|
407 * Implements a functionality similar to the DOM NodeList.item(). |
|
408 * |
|
409 * Returns the xmlNodePtr at the given @index in @ns or NULL if |
|
410 * @index is out of range (0 to length-1) |
|
411 */ |
|
412 #define xmlXPathNodeSetItem(ns, index) \ |
|
413 ((((ns) != NULL) && \ |
|
414 ((index) >= 0) && ((index) < (ns)->nodeNr)) ? \ |
|
415 (ns)->nodeTab[(index)] \ |
|
416 : NULL) |
|
417 /** |
|
418 * xmlXPathNodeSetIsEmpty: |
|
419 * @ns: a node-set |
|
420 * |
|
421 * Checks whether @ns is empty or not. |
|
422 * |
|
423 * Returns %TRUE if @ns is an empty node-set. |
|
424 */ |
|
425 #define xmlXPathNodeSetIsEmpty(ns) \ |
|
426 (((ns) == NULL) || ((ns)->nodeNr == 0) || ((ns)->nodeTab == NULL)) |
|
427 |
|
428 |
|
429 XMLPUBFUN void XMLCALL |
|
430 xmlXPathFreeObject (xmlXPathObjectPtr obj); |
|
431 XMLPUBFUN xmlNodeSetPtr XMLCALL |
|
432 xmlXPathNodeSetCreate (xmlNodePtr val); |
|
433 XMLPUBFUN void XMLCALL |
|
434 xmlXPathFreeNodeSetList (xmlXPathObjectPtr obj); |
|
435 XMLPUBFUN void XMLCALL |
|
436 xmlXPathFreeNodeSet (xmlNodeSetPtr obj); |
|
437 XMLPUBFUN xmlXPathObjectPtr XMLCALL |
|
438 xmlXPathObjectCopy (xmlXPathObjectPtr val); |
|
439 XMLPUBFUN int XMLCALL |
|
440 xmlXPathCmpNodes (xmlNodePtr node1, |
|
441 xmlNodePtr node2); |
|
442 /** |
|
443 * Conversion functions to basic types. |
|
444 */ |
|
445 XMLPUBFUN int XMLCALL |
|
446 xmlXPathCastNumberToBoolean (double val); |
|
447 XMLPUBFUN int XMLCALL |
|
448 xmlXPathCastStringToBoolean (const xmlChar * val); |
|
449 XMLPUBFUN int XMLCALL |
|
450 xmlXPathCastNodeSetToBoolean(xmlNodeSetPtr ns); |
|
451 XMLPUBFUN int XMLCALL |
|
452 xmlXPathCastToBoolean (xmlXPathObjectPtr val); |
|
453 |
|
454 XMLPUBFUN double XMLCALL |
|
455 xmlXPathCastBooleanToNumber (int val); |
|
456 XMLPUBFUN double XMLCALL |
|
457 xmlXPathCastStringToNumber (const xmlChar * val); |
|
458 XMLPUBFUN double XMLCALL |
|
459 xmlXPathCastNodeToNumber (xmlNodePtr node); |
|
460 XMLPUBFUN double XMLCALL |
|
461 xmlXPathCastNodeSetToNumber (xmlNodeSetPtr ns); |
|
462 XMLPUBFUN double XMLCALL |
|
463 xmlXPathCastToNumber (xmlXPathObjectPtr val); |
|
464 |
|
465 XMLPUBFUN xmlChar * XMLCALL |
|
466 xmlXPathCastBooleanToString (int val); |
|
467 XMLPUBFUN xmlChar * XMLCALL |
|
468 xmlXPathCastNumberToString (double val); |
|
469 XMLPUBFUN xmlChar * XMLCALL |
|
470 xmlXPathCastNodeToString (xmlNodePtr node); |
|
471 XMLPUBFUN xmlChar * XMLCALL |
|
472 xmlXPathCastNodeSetToString (xmlNodeSetPtr ns); |
|
473 XMLPUBFUN xmlChar * XMLCALL |
|
474 xmlXPathCastToString (xmlXPathObjectPtr val); |
|
475 |
|
476 XMLPUBFUN xmlXPathObjectPtr XMLCALL |
|
477 xmlXPathConvertBoolean (xmlXPathObjectPtr val); |
|
478 XMLPUBFUN xmlXPathObjectPtr XMLCALL |
|
479 xmlXPathConvertNumber (xmlXPathObjectPtr val); |
|
480 XMLPUBFUN xmlXPathObjectPtr XMLCALL |
|
481 xmlXPathConvertString (xmlXPathObjectPtr val); |
|
482 |
|
483 /** |
|
484 * Context handling. |
|
485 */ |
|
486 XMLPUBFUN xmlXPathContextPtr XMLCALL |
|
487 xmlXPathNewContext (xmlDocPtr doc); |
|
488 XMLPUBFUN void XMLCALL |
|
489 xmlXPathFreeContext (xmlXPathContextPtr ctxt); |
|
490 |
|
491 /** |
|
492 * Evaluation functions. |
|
493 */ |
|
494 XMLPUBFUN long XMLCALL |
|
495 xmlXPathOrderDocElems (xmlDocPtr doc); |
|
496 XMLPUBFUN xmlXPathObjectPtr XMLCALL |
|
497 xmlXPathEval (const xmlChar *str, |
|
498 xmlXPathContextPtr ctx); |
|
499 XMLPUBFUN xmlXPathObjectPtr XMLCALL |
|
500 xmlXPathEvalExpression (const xmlChar *str, |
|
501 xmlXPathContextPtr ctxt); |
|
502 XMLPUBFUN int XMLCALL |
|
503 xmlXPathEvalPredicate (xmlXPathContextPtr ctxt, |
|
504 xmlXPathObjectPtr res); |
|
505 /** |
|
506 * Separate compilation/evaluation entry points. |
|
507 */ |
|
508 XMLPUBFUN xmlXPathCompExprPtr XMLCALL |
|
509 xmlXPathCompile (const xmlChar *str); |
|
510 XMLPUBFUN xmlXPathCompExprPtr XMLCALL |
|
511 xmlXPathCtxtCompile (xmlXPathContextPtr ctxt, |
|
512 const xmlChar *str); |
|
513 XMLPUBFUN xmlXPathObjectPtr XMLCALL |
|
514 xmlXPathCompiledEval (xmlXPathCompExprPtr comp, |
|
515 xmlXPathContextPtr ctx); |
|
516 XMLPUBFUN void XMLCALL |
|
517 xmlXPathFreeCompExpr (xmlXPathCompExprPtr comp); |
|
518 #endif /* LIBXML_XPATH_ENABLED */ |
|
519 #if defined(LIBXML_XPATH_ENABLED) || defined(LIBXML_SCHEMAS_ENABLED) |
|
520 XMLPUBFUN void XMLCALL |
|
521 xmlXPathInit (void); |
|
522 XMLPUBFUN int XMLCALL |
|
523 xmlXPathIsNaN (double val); |
|
524 XMLPUBFUN int XMLCALL |
|
525 xmlXPathIsInf (double val); |
|
526 |
|
527 #ifdef __cplusplus |
|
528 } |
|
529 #endif |
|
530 |
|
531 #endif /* LIBXML_XPATH_ENABLED or LIBXML_SCHEMAS_ENABLED*/ |
|
532 #endif /* ! __XML_XPATH_H__ */ |