blob: 87a6118b672e1b79c2fbdb609846e014deeaf89c [file] [log] [blame]
Owen Taylor3473f882001-02-23 17:55:21 +00001/*
2 * xpath.c: interface for XML Path Language implementation
3 *
4 * Reference: W3C Working Draft 5 July 1999
5 * http://www.w3.org/Style/XSL/Group/1999/07/xpath-19990705.html
6 *
7 * See COPYRIGHT for the status of this software
8 *
Daniel Veillardc5d64342001-06-24 12:13:24 +00009 * Author: daniel@veillard.com
Owen Taylor3473f882001-02-23 17:55:21 +000010 */
11
12#ifndef __XML_XPATH_H__
13#define __XML_XPATH_H__
14
15#include <libxml/tree.h>
16#include <libxml/hash.h>
17
18#ifdef __cplusplus
19extern "C" {
20#endif
21
22typedef struct _xmlXPathContext xmlXPathContext;
23typedef xmlXPathContext *xmlXPathContextPtr;
24typedef struct _xmlXPathParserContext xmlXPathParserContext;
25typedef xmlXPathParserContext *xmlXPathParserContextPtr;
26
27/**
28 * The set of XPath error codes
29 */
30
31typedef enum {
32 XPATH_EXPRESSION_OK = 0,
33 XPATH_NUMBER_ERROR,
34 XPATH_UNFINISHED_LITERAL_ERROR,
35 XPATH_START_LITERAL_ERROR,
36 XPATH_VARIABLE_REF_ERROR,
37 XPATH_UNDEF_VARIABLE_ERROR,
38 XPATH_INVALID_PREDICATE_ERROR,
39 XPATH_EXPR_ERROR,
40 XPATH_UNCLOSED_ERROR,
41 XPATH_UNKNOWN_FUNC_ERROR,
42 XPATH_INVALID_OPERAND,
43 XPATH_INVALID_TYPE,
44 XPATH_INVALID_ARITY,
45 XPATH_INVALID_CTXT_SIZE,
46 XPATH_INVALID_CTXT_POSITION,
47 XPATH_MEMORY_ERROR,
48 XPTR_SYNTAX_ERROR,
49 XPTR_RESOURCE_ERROR,
50 XPTR_SUB_RESOURCE_ERROR,
Daniel Veillard61d80a22001-04-27 17:13:01 +000051 XPATH_UNDEF_PREFIX_ERROR,
52 XPATH_ENCODING_ERROR,
53 XPATH_INVALID_CHAR_ERROR
Owen Taylor3473f882001-02-23 17:55:21 +000054} xmlXPathError;
55
56/*
57 * A node-set (an unordered collection of nodes without duplicates)
58 */
59typedef struct _xmlNodeSet xmlNodeSet;
60typedef xmlNodeSet *xmlNodeSetPtr;
61struct _xmlNodeSet {
62 int nodeNr; /* number of nodes in the set */
63 int nodeMax; /* size of the array as allocated */
64 xmlNodePtr *nodeTab; /* array of nodes in no particular order */
65};
66
67/*
68 * An expression is evaluated to yield an object, which
69 * has one of the following four basic types:
70 * - node-set
71 * - boolean
72 * - number
73 * - string
74 *
75 * @@ XPointer will add more types !
76 */
77
78typedef enum {
79 XPATH_UNDEFINED = 0,
80 XPATH_NODESET = 1,
81 XPATH_BOOLEAN = 2,
82 XPATH_NUMBER = 3,
83 XPATH_STRING = 4,
84 XPATH_POINT = 5,
85 XPATH_RANGE = 6,
86 XPATH_LOCATIONSET = 7,
87 XPATH_USERS = 8,
88 XPATH_XSLT_TREE = 9 /* An XSLT value tree, non modifiable */
89} xmlXPathObjectType;
90
91typedef struct _xmlXPathObject xmlXPathObject;
92typedef xmlXPathObject *xmlXPathObjectPtr;
93struct _xmlXPathObject {
94 xmlXPathObjectType type;
95 xmlNodeSetPtr nodesetval;
96 int boolval;
97 double floatval;
98 xmlChar *stringval;
99 void *user;
100 int index;
101 void *user2;
102 int index2;
103};
104
105/*
106 * A conversion function is associated to a type and used to cast
107 * the new type to primitive values.
108 */
109typedef int (*xmlXPathConvertFunc) (xmlXPathObjectPtr obj, int type);
110
111/*
112 * Extra type: a name and a conversion function.
113 */
114
115typedef struct _xmlXPathType xmlXPathType;
116typedef xmlXPathType *xmlXPathTypePtr;
117struct _xmlXPathType {
118 const xmlChar *name; /* the type name */
119 xmlXPathConvertFunc func; /* the conversion function */
120};
121
122/*
123 * Extra variable: a name and a value.
124 */
125
126typedef struct _xmlXPathVariable xmlXPathVariable;
127typedef xmlXPathVariable *xmlXPathVariablePtr;
128struct _xmlXPathVariable {
129 const xmlChar *name; /* the variable name */
130 xmlXPathObjectPtr value; /* the value */
131};
132
Daniel Veillard5168dbf2001-07-07 00:18:23 +0000133/**
134 * xmlXPathEvalFunc:
135 * @ctxt: an XPath parser context
136 * @nargs: the number of arguments passed to the function
137 *
138 * an XPath evaluation function, the parameters are on thei XPath context stack
Owen Taylor3473f882001-02-23 17:55:21 +0000139 */
140
Daniel Veillard5168dbf2001-07-07 00:18:23 +0000141typedef void (*xmlXPathEvalFunc)(xmlXPathParserContextPtr ctxt,
142 int nargs);
Owen Taylor3473f882001-02-23 17:55:21 +0000143
144/*
145 * Extra function: a name and a evaluation function.
146 */
147
148typedef struct _xmlXPathFunct xmlXPathFunct;
149typedef xmlXPathFunct *xmlXPathFuncPtr;
150struct _xmlXPathFunct {
151 const xmlChar *name; /* the function name */
152 xmlXPathEvalFunc func; /* the evaluation function */
153};
154
155/*
156 * An axis traversal function. To traverse an axis, the engine calls
157 * the first time with cur == NULL and repeat until the function returns
158 * NULL indicating the end of the axis traversal.
159 */
160
161typedef xmlXPathObjectPtr (*xmlXPathAxisFunc) (xmlXPathParserContextPtr ctxt,
162 xmlXPathObjectPtr cur);
163
164/*
165 * Extra axis: a name and an axis function.
166 */
167
168typedef struct _xmlXPathAxis xmlXPathAxis;
169typedef xmlXPathAxis *xmlXPathAxisPtr;
170struct _xmlXPathAxis {
171 const xmlChar *name; /* the axis name */
172 xmlXPathAxisFunc func; /* the search function */
173};
174
Daniel Veillardbed7b052001-05-19 14:59:49 +0000175/**
176 * xmlXPathContext:
177 *
Owen Taylor3473f882001-02-23 17:55:21 +0000178 * Expression evaluation occurs with respect to a context.
179 * he context consists of:
180 * - a node (the context node)
181 * - a node list (the context node list)
182 * - a set of variable bindings
183 * - a function library
184 * - the set of namespace declarations in scope for the expression
185 * Following the switch to hash tables, this need to be trimmed up at
186 * the next binary incompatible release.
187 */
188
189struct _xmlXPathContext {
190 xmlDocPtr doc; /* The current document */
191 xmlNodePtr node; /* The current node */
192
193 int nb_variables_unused; /* unused (hash table) */
194 int max_variables_unused; /* unused (hash table) */
195 xmlHashTablePtr varHash; /* Hash table of defined variables */
196
197 int nb_types; /* number of defined types */
198 int max_types; /* max number of types */
199 xmlXPathTypePtr types; /* Array of defined types */
200
201 int nb_funcs_unused; /* unused (hash table) */
202 int max_funcs_unused; /* unused (hash table) */
203 xmlHashTablePtr funcHash; /* Hash table of defined funcs */
204
205 int nb_axis; /* number of defined axis */
206 int max_axis; /* max number of axis */
207 xmlXPathAxisPtr axis; /* Array of defined axis */
208
209 /* the namespace nodes of the context node */
210 xmlNsPtr *namespaces; /* Array of namespaces */
211 int nsNr; /* number of namespace in scope */
212 void *user; /* function to free */
213
214 /* extra variables */
215 int contextSize; /* the context size */
216 int proximityPosition; /* the proximity position */
217
218 /* extra stuff for XPointer */
219 int xptr; /* it this an XPointer context */
220 xmlNodePtr here; /* for here() */
221 xmlNodePtr origin; /* for origin() */
222
223 /* the set of namespace declarations in scope for the expression */
224 xmlHashTablePtr nsHash; /* The namespaces hash table */
225 void *varLookupFunc; /* variable lookup func */
226 void *varLookupData; /* variable lookup data */
227
228 /* Possibility to link in an extra item */
229 void *extra; /* needed for XSLT */
Daniel Veillard42596ad2001-05-22 16:57:14 +0000230
231 /* The function name and URI when calling a function */
232 const xmlChar *function;
233 const xmlChar *functionURI;
Owen Taylor3473f882001-02-23 17:55:21 +0000234};
235
236/*
Daniel Veillard9e7160d2001-03-18 23:17:47 +0000237 * The structure of a compiled expression form is not public
238 */
239
240typedef struct _xmlXPathCompExpr xmlXPathCompExpr;
241typedef xmlXPathCompExpr *xmlXPathCompExprPtr;
242
Daniel Veillardbed7b052001-05-19 14:59:49 +0000243/**
244 * xmlXPathParserContext:
245 *
Owen Taylor3473f882001-02-23 17:55:21 +0000246 * An XPath parser context, it contains pure parsing informations,
247 * an xmlXPathContext, and the stack of objects.
248 */
249struct _xmlXPathParserContext {
250 const xmlChar *cur; /* the current char being parsed */
251 const xmlChar *base; /* the full expression */
252
253 int error; /* error code */
254
Owen Taylor3473f882001-02-23 17:55:21 +0000255 xmlXPathContextPtr context; /* the evaluation context */
256 xmlXPathObjectPtr value; /* the current value */
257 int valueNr; /* number of values stacked */
258 int valueMax; /* max number of values stacked */
259 xmlXPathObjectPtr *valueTab; /* stack of values */
Daniel Veillardd007d6c2001-03-19 00:01:07 +0000260
261 xmlXPathCompExprPtr comp; /* the precompiled expression */
Daniel Veillardfbf8a2d2001-03-19 15:58:54 +0000262 int xptr; /* it this an XPointer expression */
Daniel Veillardf06307e2001-07-03 10:35:50 +0000263 xmlNodePtr ancestor; /* used for walking preceding axis */
Owen Taylor3473f882001-02-23 17:55:21 +0000264};
265
Daniel Veillardbed7b052001-05-19 14:59:49 +0000266/**
267 * xmlXPathFunction:
268 *
Owen Taylor3473f882001-02-23 17:55:21 +0000269 * An XPath function
270 * The arguments (if any) are popped out of the context stack
271 * and the result is pushed on the stack.
272 */
273
274typedef void (*xmlXPathFunction) (xmlXPathParserContextPtr ctxt, int nargs);
275
276/************************************************************************
277 * *
278 * Public API *
279 * *
280 ************************************************************************/
281
282/**
Daniel Veillardafcbe1c2001-03-19 10:57:13 +0000283 * Objects and Nodesets handling
Owen Taylor3473f882001-02-23 17:55:21 +0000284 */
Daniel Veillard790142b2001-05-15 10:51:53 +0000285
Thomas Broyer496be682001-07-15 22:59:18 +0000286LIBXML_DLL_IMPORT extern double xmlXPathNAN;
287LIBXML_DLL_IMPORT extern double xmlXPathPINF;
288LIBXML_DLL_IMPORT extern double xmlXPathNINF;
289
Daniel Veillard790142b2001-05-15 10:51:53 +0000290/* These macros may later turn into functions */
291#define xmlXPathNodeSetGetLength(ns) ((ns) ? (ns)->nodeNr : 0)
292#define xmlXPathNodeSetItem(ns, index) \
293 ((((ns) != NULL) && \
Thomas Broyer496be682001-07-15 22:59:18 +0000294 ((index) >= 0) && ((index) < (ns)->nodeNr)) ? \
Daniel Veillard790142b2001-05-15 10:51:53 +0000295 (ns)->nodeTab[(index)] \
296 : NULL)
297
298
Owen Taylor3473f882001-02-23 17:55:21 +0000299void xmlXPathFreeObject (xmlXPathObjectPtr obj);
Owen Taylor3473f882001-02-23 17:55:21 +0000300xmlNodeSetPtr xmlXPathNodeSetCreate (xmlNodePtr val);
301void xmlXPathFreeNodeSetList (xmlXPathObjectPtr obj);
302void xmlXPathFreeNodeSet (xmlNodeSetPtr obj);
303xmlXPathObjectPtr xmlXPathObjectCopy (xmlXPathObjectPtr val);
304int xmlXPathCmpNodes (xmlNodePtr node1,
305 xmlNodePtr node2);
Daniel Veillardfbf8a2d2001-03-19 15:58:54 +0000306/**
307 * Conversion functions to basic types
308 */
Daniel Veillardba0b8c92001-05-15 09:43:47 +0000309int xmlXPathCastNumberToBoolean (double val);
310int xmlXPathCastStringToBoolean (const xmlChar * val);
Daniel Veillardbed7b052001-05-19 14:59:49 +0000311int xmlXPathCastNodeSetToBoolean (xmlNodeSetPtr ns);
Daniel Veillardba0b8c92001-05-15 09:43:47 +0000312int xmlXPathCastToBoolean (xmlXPathObjectPtr val);
313
314double xmlXPathCastBooleanToNumber (int val);
315double xmlXPathCastStringToNumber (const xmlChar * val);
316double xmlXPathCastNodeToNumber (xmlNodePtr node);
317double xmlXPathCastNodeSetToNumber (xmlNodeSetPtr ns);
318double xmlXPathCastToNumber (xmlXPathObjectPtr val);
319
320xmlChar * xmlXPathCastBooleanToString (int val);
321xmlChar * xmlXPathCastNumberToString (double val);
322xmlChar * xmlXPathCastNodeToString (xmlNodePtr node);
323xmlChar * xmlXPathCastNodeSetToString (xmlNodeSetPtr ns);
324xmlChar * xmlXPathCastToString (xmlXPathObjectPtr val);
325
Daniel Veillardfbf8a2d2001-03-19 15:58:54 +0000326xmlXPathObjectPtr xmlXPathConvertBoolean (xmlXPathObjectPtr val);
327xmlXPathObjectPtr xmlXPathConvertNumber (xmlXPathObjectPtr val);
328xmlXPathObjectPtr xmlXPathConvertString (xmlXPathObjectPtr val);
Owen Taylor3473f882001-02-23 17:55:21 +0000329
Daniel Veillardafcbe1c2001-03-19 10:57:13 +0000330/**
331 * Context handling
332 */
333void xmlXPathInit (void);
334xmlXPathContextPtr xmlXPathNewContext (xmlDocPtr doc);
335void xmlXPathFreeContext (xmlXPathContextPtr ctxt);
336
337/**
338 * Evaluation functions.
339 */
340xmlXPathObjectPtr xmlXPathEval (const xmlChar *str,
341 xmlXPathContextPtr ctxt);
342xmlXPathObjectPtr xmlXPathEvalXPtrExpr (const xmlChar *str,
343 xmlXPathContextPtr ctxt);
344xmlXPathObjectPtr xmlXPathEvalExpression (const xmlChar *str,
345 xmlXPathContextPtr ctxt);
Daniel Veillardfbf8a2d2001-03-19 15:58:54 +0000346int xmlXPathEvalPredicate (xmlXPathContextPtr ctxt,
347 xmlXPathObjectPtr res);
Daniel Veillardafcbe1c2001-03-19 10:57:13 +0000348/**
349 * Separate compilation/evaluation entry points
350 */
351xmlXPathCompExprPtr xmlXPathCompile (const xmlChar *str);
352xmlXPathObjectPtr xmlXPathCompiledEval (xmlXPathCompExprPtr comp,
353 xmlXPathContextPtr ctx);
Daniel Veillardfbf8a2d2001-03-19 15:58:54 +0000354void xmlXPathFreeCompExpr (xmlXPathCompExprPtr comp);
Owen Taylor3473f882001-02-23 17:55:21 +0000355#ifdef __cplusplus
356}
357#endif
358#endif /* ! __XML_XPATH_H__ */