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