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