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