xpath.h 9.58 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
/*
 * xpath.c: interface for XML Path Language implementation
 *
 * Reference: W3C Working Draft 5 July 1999
 *            http://www.w3.org/Style/XSL/Group/1999/07/xpath-19990705.html
 *
 * See COPYRIGHT for the status of this software
 *
 * Author: Daniel.Veillard@w3.org
 */

#ifndef __XML_XPATH_H__
#define __XML_XPATH_H__

15
#include <libxml/tree.h>
Daniel Veillard's avatar
Daniel Veillard committed
16

17
#ifdef __cplusplus
18
extern "C" {
19
#endif
20

21
22
23
24
typedef struct _xmlXPathContext xmlXPathContext;
typedef xmlXPathContext *xmlXPathContextPtr;
typedef struct _xmlXPathParserContext xmlXPathParserContext;
typedef xmlXPathParserContext *xmlXPathParserContextPtr;
25

26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
/**
 * The set of XPath error codes
 */

typedef enum {
    XPATH_EXPRESSION_OK = 0,
    XPATH_NUMBER_ERROR,
    XPATH_UNFINISHED_LITERAL_ERROR,
    XPATH_START_LITERAL_ERROR,
    XPATH_VARIABLE_REF_ERROR,
    XPATH_UNDEF_VARIABLE_ERROR,
    XPATH_INVALID_PREDICATE_ERROR,
    XPATH_EXPR_ERROR,
    XPATH_UNCLOSED_ERROR,
    XPATH_UNKNOWN_FUNC_ERROR,
    XPATH_INVALID_OPERAND,
    XPATH_INVALID_TYPE,
    XPATH_INVALID_ARITY,
    XPATH_INVALID_CTXT_SIZE,
45
46
47
48
49
    XPATH_INVALID_CTXT_POSITION,
    XPATH_MEMORY_ERROR,
    XPTR_SYNTAX_ERROR,
    XPTR_RESOURCE_ERROR,
    XPTR_SUB_RESOURCE_ERROR
50
51
} xmlXPathError;

52
53
54
/*
 * A node-set (an unordered collection of nodes without duplicates) 
 */
55
56
57
typedef struct _xmlNodeSet xmlNodeSet;
typedef xmlNodeSet *xmlNodeSetPtr;
struct _xmlNodeSet {
58
59
    int nodeNr;			/* number of nodes in the set */
    int nodeMax;		/* size of the array as allocated */
60
    xmlNodePtr *nodeTab;	/* array of nodes in no particular order */
61
};
62
63
64
65
66
67
68
69

/*
 * An expression is evaluated to yield an object, which
 * has one of the following four basic types:
 *   - node-set
 *   - boolean
 *   - number
 *   - string
70
71
 *
 * @@ XPointer will add more types !
72
73
 */

74
75
76
77
78
79
typedef enum {
    XPATH_UNDEFINED = 0,
    XPATH_NODESET = 1,
    XPATH_BOOLEAN = 2,
    XPATH_NUMBER = 3,
    XPATH_STRING = 4,
80
81
82
83
    XPATH_POINT = 5,
    XPATH_RANGE = 6,
    XPATH_LOCATIONSET = 7,
    XPATH_USERS = 8
84
} xmlXPathObjectType;
85

86
87
88
typedef struct _xmlXPathObject xmlXPathObject;
typedef xmlXPathObject *xmlXPathObjectPtr;
struct _xmlXPathObject {
89
    xmlXPathObjectType type;
90
91
    xmlNodeSetPtr nodesetval;
    int boolval;
92
    double floatval;
93
    xmlChar *stringval;
94
    void *user;
95
96
97
    int index;
    void *user2;
    int index2;
98
};
99

100
101
102
103
104
105
106
107
108
109
/*
 * A conversion function is associated to a type and used to cast
 * the new type to primitive values.
 */
typedef int (*xmlXPathConvertFunc) (xmlXPathObjectPtr obj, int type);

/*
 * Extra type: a name and a conversion function.
 */

110
111
112
typedef struct _xmlXPathType xmlXPathType;
typedef xmlXPathType *xmlXPathTypePtr;
struct _xmlXPathType {
113
    const xmlChar         *name;		/* the type name */
114
    xmlXPathConvertFunc func;		/* the conversion function */
115
};
116
117
118
119
120

/*
 * Extra variable: a name and a value.
 */

121
122
123
typedef struct _xmlXPathVariable xmlXPathVariable;
typedef xmlXPathVariable *xmlXPathVariablePtr;
struct _xmlXPathVariable {
124
    const xmlChar       *name;		/* the variable name */
125
    xmlXPathObjectPtr value;		/* the value */
126
};
127
128
129
130
131
132
133
134
135
136
137

/*
 * an evaluation function, the parameters are on the context stack
 */

typedef void (*xmlXPathEvalFunc)(xmlXPathParserContextPtr ctxt, int nargs);

/*
 * Extra function: a name and a evaluation function.
 */

138
139
140
typedef struct _xmlXPathFunct xmlXPathFunct;
typedef xmlXPathFunct *xmlXPathFuncPtr;
struct _xmlXPathFunct {
141
    const xmlChar      *name;		/* the function name */
142
    xmlXPathEvalFunc func;		/* the evaluation function */
143
};
144
145
146
147
148
149
150
151
152
153
154
155
156
157

/*
 * An axis traversal function. To traverse an axis, the engine calls
 * the first time with cur == NULL and repeat until the function returns
 * NULL indicating the end of the axis traversal.
 */

typedef xmlXPathObjectPtr (*xmlXPathAxisFunc)	(xmlXPathParserContextPtr ctxt,
						 xmlXPathObjectPtr cur);

/*
 * Extra axis: a name and an axis function.
 */

158
159
160
typedef struct _xmlXPathAxis xmlXPathAxis;
typedef xmlXPathAxis *xmlXPathAxisPtr;
struct _xmlXPathAxis {
161
    const xmlChar      *name;		/* the axis name */
162
    xmlXPathAxisFunc func;		/* the search function */
163
};
164

165
166
167
168
169
170
171
172
173
174
/* 
 * Expression evaluation occurs with respect to a context.
 * he context consists of:
 *    - a node (the context node) 
 *    - a node list (the context node list) 
 *    - a set of variable bindings 
 *    - a function library 
 *    - the set of namespace declarations in scope for the expression 
 */

175
struct _xmlXPathContext {
176
177
    xmlDocPtr doc;			/* The current document */
    xmlNodePtr node;			/* The current node */
178
179
180

    int nb_variables;			/* number of defined variables */
    int max_variables;			/* max number of variables */
181
    xmlXPathVariablePtr variables;	/* Array of defined variables */
182
183
184

    int nb_types;			/* number of defined types */
    int max_types;			/* max number of types */
185
    xmlXPathTypePtr types;		/* Array of defined types */
186
187
188

    int nb_funcs;			/* number of defined funcs */
    int max_funcs;			/* max number of funcs */
189
    xmlXPathFuncPtr funcs;		/* Array of defined funcs */
190
191
192

    int nb_axis;			/* number of defined axis */
    int max_axis;			/* max number of axis */
193
    xmlXPathAxisPtr axis;		/* Array of defined axis */
194
195

    /* Namespace traversal should be implemented with user */
196
197
    xmlNsPtr *namespaces;		/* The namespaces lookup */
    int nsNr;				/* the current Namespace index */
198
    void *user;				/* user defined extra info */
199
200
201
202

    /* extra variables */
    int contextSize;			/* the context size */
    int proximityPosition;		/* the proximity position */
203
204
205
206
207

    /* extra stuff for XPointer */
    int xptr;				/* it this an XPointer context */
    xmlNodePtr here;			/* for here() */
    xmlNodePtr origin;			/* for origin() */
208
};
209
210
211
212
213

/*
 * An XPath parser context, it contains pure parsing informations,
 * an xmlXPathContext, and the stack of objects.
 */
214
struct _xmlXPathParserContext {
215
216
    const xmlChar *cur;			/* the current char being parsed */
    const xmlChar *base;			/* the full expression */
217
218
219
220
221
222
223
224

    int error;				/* error code */

    xmlXPathContextPtr  context;	/* the evaluation context */
    xmlXPathObjectPtr     value;	/* the current value */
    int                 valueNr;	/* number of values stacked */
    int                valueMax;	/* max number of values stacked */
    xmlXPathObjectPtr *valueTab;	/* stack of values */
225
};
226
227
228
229
230
231
232
233
234

/*
 * An XPath function
 * The arguments (if any) are popped out of the context stack
 * and the result is pushed on the stack.
 */

typedef void (*xmlXPathFunction) (xmlXPathParserContextPtr ctxt, int nargs);

235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
/************************************************************************
 *									*
 *			Helpers						*
 *									*
 ************************************************************************/

#define CHECK_ERROR							\
    if (ctxt->error != XPATH_EXPRESSION_OK) return

#define CHECK_ERROR0							\
    if (ctxt->error != XPATH_EXPRESSION_OK) return(0)

#define XP_ERROR(X)							\
    { xmlXPatherror(ctxt, __FILE__, __LINE__, X);			\
      ctxt->error = (X); return; }

#define XP_ERROR0(X)							\
    { xmlXPatherror(ctxt, __FILE__, __LINE__, X);			\
      ctxt->error = (X); return(0); }

#define CHECK_TYPE(typeval)						\
    if ((ctxt->value == NULL) || (ctxt->value->type != typeval))	\
        XP_ERROR(XPATH_INVALID_TYPE)					\

#define CHECK_ARITY(x)							\
    if (nargs != (x)) {							\
        XP_ERROR(XPATH_INVALID_ARITY);					\
    }									\

void		xmlXPatherror	(xmlXPathParserContextPtr ctxt,
				 const char *file,
				 int line,
				 int no);

269
270
271
272
void		xmlXPathDebugDumpObject	(FILE *output,
					 xmlXPathObjectPtr cur,
					 int depth);

273
/**
274
 * Utilities to extend XPath (XPointer)
275
 */
276
277
278
279
280
xmlXPathParserContextPtr
		  xmlXPathNewParserContext	(const xmlChar *str,
			  			 xmlXPathContextPtr ctxt);
void		  xmlXPathFreeParserContext	(xmlXPathParserContextPtr ctxt);

281
282
xmlXPathObjectPtr valuePop			(xmlXPathParserContextPtr ctxt);
int		  valuePush			(xmlXPathParserContextPtr ctxt,
Daniel Veillard's avatar
Daniel Veillard committed
283
284
285
					 	xmlXPathObjectPtr value);

xmlXPathObjectPtr xmlXPathNewString		(const xmlChar *val);
286
287
288
xmlXPathObjectPtr xmlXPathNewCString		(const char *val);
xmlXPathObjectPtr xmlXPathNewFloat		(double val);
xmlXPathObjectPtr xmlXPathNewBoolean		(int val);
Daniel Veillard's avatar
Daniel Veillard committed
289
290
291
292
293
294
295
296
297
xmlXPathObjectPtr xmlXPathNewNodeSet		(xmlNodePtr val);
void		  xmlXPathNodeSetAdd		(xmlNodeSetPtr cur,
						 xmlNodePtr val);


void		  xmlXPathIdFunction		(xmlXPathParserContextPtr ctxt,
					 	int nargs);
void		  xmlXPathRoot			(xmlXPathParserContextPtr ctxt);
void		  xmlXPathEvalExpr		(xmlXPathParserContextPtr ctxt);
298
xmlChar *	  xmlXPathParseName		(xmlXPathParserContextPtr ctxt);
299

300
301
302
303
304
305
/************************************************************************
 *									*
 *			Public API					*
 *									*
 ************************************************************************/

306
/**
307
 * Extending a context
308
 */
309
int		   xmlXPathRegisterFunc		(xmlXPathContextPtr ctxt,
310
						 const xmlChar *name,
311
						 xmlXPathFunction f);
312
int		   xmlXPathRegisterVariable	(xmlXPathContextPtr ctxt,
313
						 const xmlChar *name,
314
						 xmlXPathObjectPtr value);
315
316
317
318

/**
 * Evaluation functions.
 */
319
void		   xmlXPathInit			(void);
320
xmlXPathContextPtr xmlXPathNewContext		(xmlDocPtr doc);
321
void		   xmlXPathFreeContext		(xmlXPathContextPtr ctxt);
322
xmlXPathObjectPtr  xmlXPathEval			(const xmlChar *str,
323
						 xmlXPathContextPtr ctxt);
324
325
xmlXPathObjectPtr  xmlXPathEvalXPtrExpr		(const xmlChar *str,
						 xmlXPathContextPtr ctxt);
326
void		   xmlXPathFreeObject		(xmlXPathObjectPtr obj);
327
xmlXPathObjectPtr  xmlXPathEvalExpression	(const xmlChar *str,
328
						 xmlXPathContextPtr ctxt);
329
330
331
xmlNodeSetPtr	   xmlXPathNodeSetCreate	(xmlNodePtr val);
void		   xmlXPathFreeNodeSetList	(xmlXPathObjectPtr obj);
void		   xmlXPathFreeNodeSet		(xmlNodeSetPtr obj);
332
xmlXPathObjectPtr  xmlXPathObjectCopy		(xmlXPathObjectPtr val);
333

334

335
336
337
#ifdef __cplusplus
}
#endif
338
#endif /* ! __XML_XPATH_H__ */