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