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