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} xmlXPathError;
73
74/*
75 * A node-set (an unordered collection of nodes without duplicates).
76 */
77typedef struct _xmlNodeSet xmlNodeSet;
78typedef xmlNodeSet *xmlNodeSetPtr;
79struct _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
97typedef 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
110typedef struct _xmlXPathObject xmlXPathObject;
111typedef xmlXPathObject *xmlXPathObjectPtr;
112struct _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 */
134typedef int (*xmlXPathConvertFunc) (xmlXPathObjectPtr obj, int type);
135
136/*
137 * Extra type: a name and a conversion function.
138 */
139
140typedef struct _xmlXPathType xmlXPathType;
141typedef xmlXPathType *xmlXPathTypePtr;
142struct _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
151typedef struct _xmlXPathVariable xmlXPathVariable;
152typedef xmlXPathVariable *xmlXPathVariablePtr;
153struct _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
166typedef void (*xmlXPathEvalFunc)(xmlXPathParserContextPtr ctxt,
167	                         int nargs);
168
169/*
170 * Extra function: a name and a evaluation function.
171 */
172
173typedef struct _xmlXPathFunct xmlXPathFunct;
174typedef xmlXPathFunct *xmlXPathFuncPtr;
175struct _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
192typedef xmlXPathObjectPtr (*xmlXPathAxisFunc) (xmlXPathParserContextPtr ctxt,
193				 xmlXPathObjectPtr cur);
194
195/*
196 * Extra axis: a name and an axis function.
197 */
198
199typedef struct _xmlXPathAxis xmlXPathAxis;
200typedef xmlXPathAxis *xmlXPathAxisPtr;
201struct _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
216typedef 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 */
233typedef 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 */
248typedef 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
286struct _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
359typedef struct _xmlXPathCompExpr xmlXPathCompExpr;
360typedef 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 */
368struct _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
395XMLPUBVAR double xmlXPathNAN;
396XMLPUBVAR double xmlXPathPINF;
397XMLPUBVAR 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
436XMLPUBFUN void XMLCALL
437		    xmlXPathFreeObject		(xmlXPathObjectPtr obj);
438XMLPUBFUN xmlNodeSetPtr XMLCALL
439		    xmlXPathNodeSetCreate	(xmlNodePtr val);
440XMLPUBFUN void XMLCALL
441		    xmlXPathFreeNodeSetList	(xmlXPathObjectPtr obj);
442XMLPUBFUN void XMLCALL
443		    xmlXPathFreeNodeSet		(xmlNodeSetPtr obj);
444XMLPUBFUN xmlXPathObjectPtr XMLCALL
445		    xmlXPathObjectCopy		(xmlXPathObjectPtr val);
446XMLPUBFUN int XMLCALL
447		    xmlXPathCmpNodes		(xmlNodePtr node1,
448						 xmlNodePtr node2);
449/**
450 * Conversion functions to basic types.
451 */
452XMLPUBFUN int XMLCALL
453		    xmlXPathCastNumberToBoolean	(double val);
454XMLPUBFUN int XMLCALL
455		    xmlXPathCastStringToBoolean	(const xmlChar * val);
456XMLPUBFUN int XMLCALL
457		    xmlXPathCastNodeSetToBoolean(xmlNodeSetPtr ns);
458XMLPUBFUN int XMLCALL
459		    xmlXPathCastToBoolean	(xmlXPathObjectPtr val);
460
461XMLPUBFUN double XMLCALL
462		    xmlXPathCastBooleanToNumber	(int val);
463XMLPUBFUN double XMLCALL
464		    xmlXPathCastStringToNumber	(const xmlChar * val);
465XMLPUBFUN double XMLCALL
466		    xmlXPathCastNodeToNumber	(xmlNodePtr node);
467XMLPUBFUN double XMLCALL
468		    xmlXPathCastNodeSetToNumber	(xmlNodeSetPtr ns);
469XMLPUBFUN double XMLCALL
470		    xmlXPathCastToNumber	(xmlXPathObjectPtr val);
471
472XMLPUBFUN xmlChar * XMLCALL
473		    xmlXPathCastBooleanToString	(int val);
474XMLPUBFUN xmlChar * XMLCALL
475		    xmlXPathCastNumberToString	(double val);
476XMLPUBFUN xmlChar * XMLCALL
477		    xmlXPathCastNodeToString	(xmlNodePtr node);
478XMLPUBFUN xmlChar * XMLCALL
479		    xmlXPathCastNodeSetToString	(xmlNodeSetPtr ns);
480XMLPUBFUN xmlChar * XMLCALL
481		    xmlXPathCastToString	(xmlXPathObjectPtr val);
482
483XMLPUBFUN xmlXPathObjectPtr XMLCALL
484		    xmlXPathConvertBoolean	(xmlXPathObjectPtr val);
485XMLPUBFUN xmlXPathObjectPtr XMLCALL
486		    xmlXPathConvertNumber	(xmlXPathObjectPtr val);
487XMLPUBFUN xmlXPathObjectPtr XMLCALL
488		    xmlXPathConvertString	(xmlXPathObjectPtr val);
489
490/**
491 * Context handling.
492 */
493XMLPUBFUN xmlXPathContextPtr XMLCALL
494		    xmlXPathNewContext		(xmlDocPtr doc);
495XMLPUBFUN void XMLCALL
496		    xmlXPathFreeContext		(xmlXPathContextPtr ctxt);
497XMLPUBFUN int XMLCALL
498		    xmlXPathContextSetCache(xmlXPathContextPtr ctxt,
499				            int active,
500					    int value,
501					    int options);
502/**
503 * Evaluation functions.
504 */
505XMLPUBFUN long XMLCALL
506		    xmlXPathOrderDocElems	(xmlDocPtr doc);
507XMLPUBFUN xmlXPathObjectPtr XMLCALL
508		    xmlXPathEval		(const xmlChar *str,
509						 xmlXPathContextPtr ctx);
510XMLPUBFUN xmlXPathObjectPtr XMLCALL
511		    xmlXPathEvalExpression	(const xmlChar *str,
512						 xmlXPathContextPtr ctxt);
513XMLPUBFUN int XMLCALL
514		    xmlXPathEvalPredicate	(xmlXPathContextPtr ctxt,
515						 xmlXPathObjectPtr res);
516/**
517 * Separate compilation/evaluation entry points.
518 */
519XMLPUBFUN xmlXPathCompExprPtr XMLCALL
520		    xmlXPathCompile		(const xmlChar *str);
521XMLPUBFUN xmlXPathCompExprPtr XMLCALL
522		    xmlXPathCtxtCompile		(xmlXPathContextPtr ctxt,
523		    				 const xmlChar *str);
524XMLPUBFUN xmlXPathObjectPtr XMLCALL
525		    xmlXPathCompiledEval	(xmlXPathCompExprPtr comp,
526						 xmlXPathContextPtr ctx);
527XMLPUBFUN int XMLCALL
528		    xmlXPathCompiledEvalToBoolean(xmlXPathCompExprPtr comp,
529						 xmlXPathContextPtr ctxt);
530XMLPUBFUN void XMLCALL
531		    xmlXPathFreeCompExpr	(xmlXPathCompExprPtr comp);
532#endif /* LIBXML_XPATH_ENABLED */
533#if defined(LIBXML_XPATH_ENABLED) || defined(LIBXML_SCHEMAS_ENABLED)
534XMLPUBFUN void XMLCALL
535		    xmlXPathInit		(void);
536XMLPUBFUN int XMLCALL
537		xmlXPathIsNaN	(double val);
538XMLPUBFUN 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