2 * Summary: XML Path Language implementation
3 * Description: API for the XML Path Language implementation
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
11 * W3C Recommendation 16 November 1999
12 * http://www.w3.org/TR/1999/REC-xpath-19991116
14 * Copy: See Copyright for the status of this software.
16 * Author: Daniel Veillard
19 #ifndef __XML_XPATH_H__
20 #define __XML_XPATH_H__
22 #include <libxml/xmlversion.h>
24 #ifdef LIBXML_XPATH_ENABLED
26 #include <libxml/xmlerror.h>
27 #include <libxml/tree.h>
28 #include <libxml/hash.h>
29 #endif /* LIBXML_XPATH_ENABLED */
31 #if defined(LIBXML_XPATH_ENABLED) || defined(LIBXML_SCHEMAS_ENABLED)
35 #endif /* LIBXML_XPATH_ENABLED or LIBXML_SCHEMAS_ENABLED */
37 #ifdef LIBXML_XPATH_ENABLED
39 typedef struct _xmlXPathContext xmlXPathContext;
40 typedef xmlXPathContext *xmlXPathContextPtr;
41 typedef struct _xmlXPathParserContext xmlXPathParserContext;
42 typedef xmlXPathParserContext *xmlXPathParserContextPtr;
45 * The set of XPath error codes.
49 XPATH_EXPRESSION_OK = 0,
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,
58 XPATH_UNKNOWN_FUNC_ERROR,
59 XPATH_INVALID_OPERAND,
62 XPATH_INVALID_CTXT_SIZE,
63 XPATH_INVALID_CTXT_POSITION,
67 XPTR_SUB_RESOURCE_ERROR,
68 XPATH_UNDEF_PREFIX_ERROR,
70 XPATH_INVALID_CHAR_ERROR,
75 * A node-set (an unordered collection of nodes without duplicates).
77 typedef struct _xmlNodeSet xmlNodeSet;
78 typedef xmlNodeSet *xmlNodeSetPtr;
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 @@ */
87 * An expression is evaluated to yield an object, which
88 * has one of the following four basic types:
94 * @@ XPointer will add more types !
105 XPATH_LOCATIONSET = 7,
107 XPATH_XSLT_TREE = 9 /* An XSLT value tree, non modifiable */
108 } xmlXPathObjectType;
110 typedef struct _xmlXPathObject xmlXPathObject;
111 typedef xmlXPathObject *xmlXPathObjectPtr;
112 struct _xmlXPathObject {
113 xmlXPathObjectType type;
114 xmlNodeSetPtr nodesetval;
125 * xmlXPathConvertFunc:
126 * @obj: an XPath object
127 * @type: the number of the target type
129 * A conversion function is associated to a type and used to cast
130 * the new type to primitive values.
132 * Returns -1 in case of error, 0 otherwise
134 typedef int (*xmlXPathConvertFunc) (xmlXPathObjectPtr obj, int type);
137 * Extra type: a name and a conversion function.
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 */
148 * Extra variable: a name and a value.
151 typedef struct _xmlXPathVariable xmlXPathVariable;
152 typedef xmlXPathVariable *xmlXPathVariablePtr;
153 struct _xmlXPathVariable {
154 const xmlChar *name; /* the variable name */
155 xmlXPathObjectPtr value; /* the value */
160 * @ctxt: an XPath parser context
161 * @nargs: the number of arguments passed to the function
163 * An XPath evaluation function, the parameters are on the XPath context stack.
166 typedef void (*xmlXPathEvalFunc)(xmlXPathParserContextPtr ctxt,
170 * Extra function: a name and a evaluation function.
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 */
182 * @ctxt: the XPath interpreter context
183 * @cur: the previous node being explored on that axis
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.
189 * Returns the next node in that axis or NULL if at the end of the axis.
192 typedef xmlXPathObjectPtr (*xmlXPathAxisFunc) (xmlXPathParserContextPtr ctxt,
193 xmlXPathObjectPtr cur);
196 * Extra axis: a name and an axis function.
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 */
208 * @ctxt: the XPath interprestation context
209 * @nargs: the number of arguments
212 * The arguments (if any) are popped out from the context stack
213 * and the result is pushed on the stack.
216 typedef void (*xmlXPathFunction) (xmlXPathParserContextPtr ctxt, int nargs);
219 * Function and Variable Lookup.
223 * xmlXPathVariableLookupFunc:
224 * @ctxt: an XPath context
225 * @name: name of the variable
226 * @ns_uri: the namespace name hosting this variable
228 * Prototype for callbacks used to plug variable lookup in the XPath
231 * Returns the XPath object value or NULL if not found.
233 typedef xmlXPathObjectPtr (*xmlXPathVariableLookupFunc) (void *ctxt,
235 const xmlChar *ns_uri);
238 * xmlXPathFuncLookupFunc:
239 * @ctxt: an XPath context
240 * @name: name of the function
241 * @ns_uri: the namespace name hosting this function
243 * Prototype for callbacks used to plug function lookup in the XPath
246 * Returns the XPath function or NULL if not found.
248 typedef xmlXPathFunction (*xmlXPathFuncLookupFunc) (void *ctxt,
250 const xmlChar *ns_uri);
254 * Flags for XPath engine compilation and runtime
259 * check namespaces at compilation
261 #define XML_XPATH_CHECKNS (1<<0)
265 * forbid variables in expression
267 #define XML_XPATH_NOVAR (1<<1)
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.
283 struct _xmlXPathContext {
284 xmlDocPtr doc; /* The current document */
285 xmlNodePtr node; /* The current node */
287 int nb_variables_unused; /* unused (hash table) */
288 int max_variables_unused; /* unused (hash table) */
289 xmlHashTablePtr varHash; /* Hash table of defined variables */
291 int nb_types; /* number of defined types */
292 int max_types; /* max number of types */
293 xmlXPathTypePtr types; /* Array of defined types */
295 int nb_funcs_unused; /* unused (hash table) */
296 int max_funcs_unused; /* unused (hash table) */
297 xmlHashTablePtr funcHash; /* Hash table of defined funcs */
299 int nb_axis; /* number of defined axis */
300 int max_axis; /* max number of axis */
301 xmlXPathAxisPtr axis; /* Array of defined axis */
303 /* the namespace nodes of the context node */
304 xmlNsPtr *namespaces; /* Array of namespaces */
305 int nsNr; /* number of namespace in scope */
306 void *user; /* function to free */
308 /* extra variables */
309 int contextSize; /* the context size */
310 int proximityPosition; /* the proximity position */
312 /* extra stuff for XPointer */
313 int xptr; /* it this an XPointer context */
314 xmlNodePtr here; /* for here() */
315 xmlNodePtr origin; /* for origin() */
317 /* the set of namespace declarations in scope for the expression */
318 xmlHashTablePtr nsHash; /* The namespaces hash table */
319 xmlXPathVariableLookupFunc varLookupFunc;/* variable lookup func */
320 void *varLookupData; /* variable lookup data */
322 /* Possibility to link in an extra item */
323 void *extra; /* needed for XSLT */
325 /* The function name and URI when calling a function */
326 const xmlChar *function;
327 const xmlChar *functionURI;
329 /* function lookup function and data */
330 xmlXPathFuncLookupFunc funcLookupFunc;/* function lookup func */
331 void *funcLookupData; /* function lookup data */
333 /* temporary namespace lists kept for walking the namespace axis */
334 xmlNsPtr *tmpNsList; /* Array of namespaces */
335 int tmpNsNr; /* number of namespace in scope */
337 /* error reporting mechanism */
338 void *userData; /* user specific data block */
339 xmlStructuredErrorFunc error; /* the callback in case of errors */
340 xmlError lastError; /* the last error */
341 xmlNodePtr debugNode; /* the source node XSLT */
344 xmlDictPtr dict; /* dictionnary if any */
346 int flags; /* flags to control compilation */
348 /* Cache for reusal of XPath objects */
353 * The structure of a compiled expression form is not public.
356 typedef struct _xmlXPathCompExpr xmlXPathCompExpr;
357 typedef xmlXPathCompExpr *xmlXPathCompExprPtr;
360 * xmlXPathParserContext:
362 * An XPath parser context. It contains pure parsing informations,
363 * an xmlXPathContext, and the stack of objects.
365 struct _xmlXPathParserContext {
366 const xmlChar *cur; /* the current char being parsed */
367 const xmlChar *base; /* the full expression */
369 int error; /* error code */
371 xmlXPathContextPtr context; /* the evaluation context */
372 xmlXPathObjectPtr value; /* the current value */
373 int valueNr; /* number of values stacked */
374 int valueMax; /* max number of values stacked */
375 xmlXPathObjectPtr *valueTab; /* stack of values */
377 xmlXPathCompExprPtr comp; /* the precompiled expression */
378 int xptr; /* it this an XPointer expression */
379 xmlNodePtr ancestor; /* used for walking preceding axis */
382 /************************************************************************
386 ************************************************************************/
389 * Objects and Nodesets handling
392 XMLPUBVAR double xmlXPathNAN;
393 XMLPUBVAR double xmlXPathPINF;
394 XMLPUBVAR double xmlXPathNINF;
396 /* These macros may later turn into functions */
398 * xmlXPathNodeSetGetLength:
401 * Implement a functionality similar to the DOM NodeList.length.
403 * Returns the number of nodes in the node-set.
405 #define xmlXPathNodeSetGetLength(ns) ((ns) ? (ns)->nodeNr : 0)
407 * xmlXPathNodeSetItem:
409 * @index: index of a node in the set
411 * Implements a functionality similar to the DOM NodeList.item().
413 * Returns the xmlNodePtr at the given @index in @ns or NULL if
414 * @index is out of range (0 to length-1)
416 #define xmlXPathNodeSetItem(ns, index) \
417 ((((ns) != NULL) && \
418 ((index) >= 0) && ((index) < (ns)->nodeNr)) ? \
419 (ns)->nodeTab[(index)] \
422 * xmlXPathNodeSetIsEmpty:
425 * Checks whether @ns is empty or not.
427 * Returns %TRUE if @ns is an empty node-set.
429 #define xmlXPathNodeSetIsEmpty(ns) \
430 (((ns) == NULL) || ((ns)->nodeNr == 0) || ((ns)->nodeTab == NULL))
433 XMLPUBFUN void XMLCALL
434 xmlXPathFreeObject (xmlXPathObjectPtr obj);
435 XMLPUBFUN xmlNodeSetPtr XMLCALL
436 xmlXPathNodeSetCreate (xmlNodePtr val);
437 XMLPUBFUN void XMLCALL
438 xmlXPathFreeNodeSetList (xmlXPathObjectPtr obj);
439 XMLPUBFUN void XMLCALL
440 xmlXPathFreeNodeSet (xmlNodeSetPtr obj);
441 XMLPUBFUN xmlXPathObjectPtr XMLCALL
442 xmlXPathObjectCopy (xmlXPathObjectPtr val);
443 XMLPUBFUN int XMLCALL
444 xmlXPathCmpNodes (xmlNodePtr node1,
447 * Conversion functions to basic types.
449 XMLPUBFUN int XMLCALL
450 xmlXPathCastNumberToBoolean (double val);
451 XMLPUBFUN int XMLCALL
452 xmlXPathCastStringToBoolean (const xmlChar * val);
453 XMLPUBFUN int XMLCALL
454 xmlXPathCastNodeSetToBoolean(xmlNodeSetPtr ns);
455 XMLPUBFUN int XMLCALL
456 xmlXPathCastToBoolean (xmlXPathObjectPtr val);
458 XMLPUBFUN double XMLCALL
459 xmlXPathCastBooleanToNumber (int val);
460 XMLPUBFUN double XMLCALL
461 xmlXPathCastStringToNumber (const xmlChar * val);
462 XMLPUBFUN double XMLCALL
463 xmlXPathCastNodeToNumber (xmlNodePtr node);
464 XMLPUBFUN double XMLCALL
465 xmlXPathCastNodeSetToNumber (xmlNodeSetPtr ns);
466 XMLPUBFUN double XMLCALL
467 xmlXPathCastToNumber (xmlXPathObjectPtr val);
469 XMLPUBFUN xmlChar * XMLCALL
470 xmlXPathCastBooleanToString (int val);
471 XMLPUBFUN xmlChar * XMLCALL
472 xmlXPathCastNumberToString (double val);
473 XMLPUBFUN xmlChar * XMLCALL
474 xmlXPathCastNodeToString (xmlNodePtr node);
475 XMLPUBFUN xmlChar * XMLCALL
476 xmlXPathCastNodeSetToString (xmlNodeSetPtr ns);
477 XMLPUBFUN xmlChar * XMLCALL
478 xmlXPathCastToString (xmlXPathObjectPtr val);
480 XMLPUBFUN xmlXPathObjectPtr XMLCALL
481 xmlXPathConvertBoolean (xmlXPathObjectPtr val);
482 XMLPUBFUN xmlXPathObjectPtr XMLCALL
483 xmlXPathConvertNumber (xmlXPathObjectPtr val);
484 XMLPUBFUN xmlXPathObjectPtr XMLCALL
485 xmlXPathConvertString (xmlXPathObjectPtr val);
490 XMLPUBFUN xmlXPathContextPtr XMLCALL
491 xmlXPathNewContext (xmlDocPtr doc);
492 XMLPUBFUN void XMLCALL
493 xmlXPathFreeContext (xmlXPathContextPtr ctxt);
494 XMLPUBFUN int XMLCALL
495 xmlXPathContextSetCache(xmlXPathContextPtr ctxt,
500 * Evaluation functions.
502 XMLPUBFUN long XMLCALL
503 xmlXPathOrderDocElems (xmlDocPtr doc);
504 XMLPUBFUN xmlXPathObjectPtr XMLCALL
505 xmlXPathEval (const xmlChar *str,
506 xmlXPathContextPtr ctx);
507 XMLPUBFUN xmlXPathObjectPtr XMLCALL
508 xmlXPathEvalExpression (const xmlChar *str,
509 xmlXPathContextPtr ctxt);
510 XMLPUBFUN int XMLCALL
511 xmlXPathEvalPredicate (xmlXPathContextPtr ctxt,
512 xmlXPathObjectPtr res);
514 * Separate compilation/evaluation entry points.
516 XMLPUBFUN xmlXPathCompExprPtr XMLCALL
517 xmlXPathCompile (const xmlChar *str);
518 XMLPUBFUN xmlXPathCompExprPtr XMLCALL
519 xmlXPathCtxtCompile (xmlXPathContextPtr ctxt,
521 XMLPUBFUN xmlXPathObjectPtr XMLCALL
522 xmlXPathCompiledEval (xmlXPathCompExprPtr comp,
523 xmlXPathContextPtr ctx);
524 XMLPUBFUN int XMLCALL
525 xmlXPathCompiledEvalToBoolean(xmlXPathCompExprPtr comp,
526 xmlXPathContextPtr ctxt);
527 XMLPUBFUN void XMLCALL
528 xmlXPathFreeCompExpr (xmlXPathCompExprPtr comp);
529 #endif /* LIBXML_XPATH_ENABLED */
530 #if defined(LIBXML_XPATH_ENABLED) || defined(LIBXML_SCHEMAS_ENABLED)
531 XMLPUBFUN void XMLCALL
533 XMLPUBFUN int XMLCALL
534 xmlXPathIsNaN (double val);
535 XMLPUBFUN int XMLCALL
536 xmlXPathIsInf (double val);
542 #endif /* LIBXML_XPATH_ENABLED or LIBXML_SCHEMAS_ENABLED*/
543 #endif /* ! __XML_XPATH_H__ */