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