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