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
,
73 XPATH_FORBID_VARIABLE_ERROR
77 * A node-set (an unordered collection of nodes without duplicates).
79 typedef struct _xmlNodeSet xmlNodeSet
;
80 typedef xmlNodeSet
*xmlNodeSetPtr
;
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 @@ */
89 * An expression is evaluated to yield an object, which
90 * has one of the following four basic types:
96 * @@ XPointer will add more types !
107 XPATH_LOCATIONSET
= 7,
109 XPATH_XSLT_TREE
= 9 /* An XSLT value tree, non modifiable */
110 } xmlXPathObjectType
;
112 typedef struct _xmlXPathObject xmlXPathObject
;
113 typedef xmlXPathObject
*xmlXPathObjectPtr
;
114 struct _xmlXPathObject
{
115 xmlXPathObjectType type
;
116 xmlNodeSetPtr nodesetval
;
127 * xmlXPathConvertFunc:
128 * @obj: an XPath object
129 * @type: the number of the target type
131 * A conversion function is associated to a type and used to cast
132 * the new type to primitive values.
134 * Returns -1 in case of error, 0 otherwise
136 typedef int (*xmlXPathConvertFunc
) (xmlXPathObjectPtr obj
, int type
);
139 * Extra type: a name and a conversion function.
142 typedef struct _xmlXPathType xmlXPathType
;
143 typedef xmlXPathType
*xmlXPathTypePtr
;
144 struct _xmlXPathType
{
145 const xmlChar
*name
; /* the type name */
146 xmlXPathConvertFunc func
; /* the conversion function */
150 * Extra variable: a name and a value.
153 typedef struct _xmlXPathVariable xmlXPathVariable
;
154 typedef xmlXPathVariable
*xmlXPathVariablePtr
;
155 struct _xmlXPathVariable
{
156 const xmlChar
*name
; /* the variable name */
157 xmlXPathObjectPtr value
; /* the value */
162 * @ctxt: an XPath parser context
163 * @nargs: the number of arguments passed to the function
165 * An XPath evaluation function, the parameters are on the XPath context stack.
168 typedef void (*xmlXPathEvalFunc
)(xmlXPathParserContextPtr ctxt
,
172 * Extra function: a name and a evaluation function.
175 typedef struct _xmlXPathFunct xmlXPathFunct
;
176 typedef xmlXPathFunct
*xmlXPathFuncPtr
;
177 struct _xmlXPathFunct
{
178 const xmlChar
*name
; /* the function name */
179 xmlXPathEvalFunc func
; /* the evaluation function */
184 * @ctxt: the XPath interpreter context
185 * @cur: the previous node being explored on that axis
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.
191 * Returns the next node in that axis or NULL if at the end of the axis.
194 typedef xmlXPathObjectPtr (*xmlXPathAxisFunc
) (xmlXPathParserContextPtr ctxt
,
195 xmlXPathObjectPtr cur
);
198 * Extra axis: a name and an axis function.
201 typedef struct _xmlXPathAxis xmlXPathAxis
;
202 typedef xmlXPathAxis
*xmlXPathAxisPtr
;
203 struct _xmlXPathAxis
{
204 const xmlChar
*name
; /* the axis name */
205 xmlXPathAxisFunc func
; /* the search function */
210 * @ctxt: the XPath interprestation context
211 * @nargs: the number of arguments
214 * The arguments (if any) are popped out from the context stack
215 * and the result is pushed on the stack.
218 typedef void (*xmlXPathFunction
) (xmlXPathParserContextPtr ctxt
, int nargs
);
221 * Function and Variable Lookup.
225 * xmlXPathVariableLookupFunc:
226 * @ctxt: an XPath context
227 * @name: name of the variable
228 * @ns_uri: the namespace name hosting this variable
230 * Prototype for callbacks used to plug variable lookup in the XPath
233 * Returns the XPath object value or NULL if not found.
235 typedef xmlXPathObjectPtr (*xmlXPathVariableLookupFunc
) (void *ctxt
,
237 const xmlChar
*ns_uri
);
240 * xmlXPathFuncLookupFunc:
241 * @ctxt: an XPath context
242 * @name: name of the function
243 * @ns_uri: the namespace name hosting this function
245 * Prototype for callbacks used to plug function lookup in the XPath
248 * Returns the XPath function or NULL if not found.
250 typedef xmlXPathFunction (*xmlXPathFuncLookupFunc
) (void *ctxt
,
252 const xmlChar
*ns_uri
);
256 * Flags for XPath engine compilation and runtime
261 * check namespaces at compilation
263 #define XML_XPATH_CHECKNS (1<<0)
267 * forbid variables in expression
269 #define XML_XPATH_NOVAR (1<<1)
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.
288 struct _xmlXPathContext
{
289 xmlDocPtr doc
; /* The current document */
290 xmlNodePtr node
; /* The current node */
292 int nb_variables_unused
; /* unused (hash table) */
293 int max_variables_unused
; /* unused (hash table) */
294 xmlHashTablePtr varHash
; /* Hash table of defined variables */
296 int nb_types
; /* number of defined types */
297 int max_types
; /* max number of types */
298 xmlXPathTypePtr types
; /* Array of defined types */
300 int nb_funcs_unused
; /* unused (hash table) */
301 int max_funcs_unused
; /* unused (hash table) */
302 xmlHashTablePtr funcHash
; /* Hash table of defined funcs */
304 int nb_axis
; /* number of defined axis */
305 int max_axis
; /* max number of axis */
306 xmlXPathAxisPtr axis
; /* Array of defined axis */
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 */
313 /* extra variables */
314 int contextSize
; /* the context size */
315 int proximityPosition
; /* the proximity position */
317 /* extra stuff for XPointer */
318 int xptr
; /* is this an XPointer context? */
319 xmlNodePtr here
; /* for here() */
320 xmlNodePtr origin
; /* for origin() */
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 */
327 /* Possibility to link in an extra item */
328 void *extra
; /* needed for XSLT */
330 /* The function name and URI when calling a function */
331 const xmlChar
*function
;
332 const xmlChar
*functionURI
;
334 /* function lookup function and data */
335 xmlXPathFuncLookupFunc funcLookupFunc
;/* function lookup func */
336 void *funcLookupData
; /* function lookup data */
338 /* temporary namespace lists kept for walking the namespace axis */
339 xmlNsPtr
*tmpNsList
; /* Array of namespaces */
340 int tmpNsNr
; /* number of namespaces in scope */
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 */
349 xmlDictPtr dict
; /* dictionary if any */
351 int flags
; /* flags to control compilation */
353 /* Cache for reusal of XPath objects */
358 * The structure of a compiled expression form is not public.
361 typedef struct _xmlXPathCompExpr xmlXPathCompExpr
;
362 typedef xmlXPathCompExpr
*xmlXPathCompExprPtr
;
365 * xmlXPathParserContext:
367 * An XPath parser context. It contains pure parsing informations,
368 * an xmlXPathContext, and the stack of objects.
370 struct _xmlXPathParserContext
{
371 const xmlChar
*cur
; /* the current char being parsed */
372 const xmlChar
*base
; /* the full expression */
374 int error
; /* error code */
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 */
382 xmlXPathCompExprPtr comp
; /* the precompiled expression */
383 int xptr
; /* it this an XPointer expression */
384 xmlNodePtr ancestor
; /* used for walking preceding axis */
386 int valueFrame
; /* used to limit Pop on the stack */
389 /************************************************************************
393 ************************************************************************/
396 * Objects and Nodesets handling
399 XMLPUBVAR
double xmlXPathNAN
;
400 XMLPUBVAR
double xmlXPathPINF
;
401 XMLPUBVAR
double xmlXPathNINF
;
403 /* These macros may later turn into functions */
405 * xmlXPathNodeSetGetLength:
408 * Implement a functionality similar to the DOM NodeList.length.
410 * Returns the number of nodes in the node-set.
412 #define xmlXPathNodeSetGetLength(ns) ((ns) ? (ns)->nodeNr : 0)
414 * xmlXPathNodeSetItem:
416 * @index: index of a node in the set
418 * Implements a functionality similar to the DOM NodeList.item().
420 * Returns the xmlNodePtr at the given @index in @ns or NULL if
421 * @index is out of range (0 to length-1)
423 #define xmlXPathNodeSetItem(ns, index) \
424 ((((ns) != NULL) && \
425 ((index) >= 0) && ((index) < (ns)->nodeNr)) ? \
426 (ns)->nodeTab[(index)] \
429 * xmlXPathNodeSetIsEmpty:
432 * Checks whether @ns is empty or not.
434 * Returns %TRUE if @ns is an empty node-set.
436 #define xmlXPathNodeSetIsEmpty(ns) \
437 (((ns) == NULL) || ((ns)->nodeNr == 0) || ((ns)->nodeTab == NULL))
440 XMLPUBFUN
void XMLCALL
441 xmlXPathFreeObject (xmlXPathObjectPtr obj
);
442 XMLPUBFUN xmlNodeSetPtr XMLCALL
443 xmlXPathNodeSetCreate (xmlNodePtr val
);
444 XMLPUBFUN
void XMLCALL
445 xmlXPathFreeNodeSetList (xmlXPathObjectPtr obj
);
446 XMLPUBFUN
void XMLCALL
447 xmlXPathFreeNodeSet (xmlNodeSetPtr obj
);
448 XMLPUBFUN xmlXPathObjectPtr XMLCALL
449 xmlXPathObjectCopy (xmlXPathObjectPtr val
);
450 XMLPUBFUN
int XMLCALL
451 xmlXPathCmpNodes (xmlNodePtr node1
,
454 * Conversion functions to basic types.
456 XMLPUBFUN
int XMLCALL
457 xmlXPathCastNumberToBoolean (double val
);
458 XMLPUBFUN
int XMLCALL
459 xmlXPathCastStringToBoolean (const xmlChar
* val
);
460 XMLPUBFUN
int XMLCALL
461 xmlXPathCastNodeSetToBoolean(xmlNodeSetPtr ns
);
462 XMLPUBFUN
int XMLCALL
463 xmlXPathCastToBoolean (xmlXPathObjectPtr val
);
465 XMLPUBFUN
double XMLCALL
466 xmlXPathCastBooleanToNumber (int val
);
467 XMLPUBFUN
double XMLCALL
468 xmlXPathCastStringToNumber (const xmlChar
* val
);
469 XMLPUBFUN
double XMLCALL
470 xmlXPathCastNodeToNumber (xmlNodePtr node
);
471 XMLPUBFUN
double XMLCALL
472 xmlXPathCastNodeSetToNumber (xmlNodeSetPtr ns
);
473 XMLPUBFUN
double XMLCALL
474 xmlXPathCastToNumber (xmlXPathObjectPtr val
);
476 XMLPUBFUN xmlChar
* XMLCALL
477 xmlXPathCastBooleanToString (int val
);
478 XMLPUBFUN xmlChar
* XMLCALL
479 xmlXPathCastNumberToString (double val
);
480 XMLPUBFUN xmlChar
* XMLCALL
481 xmlXPathCastNodeToString (xmlNodePtr node
);
482 XMLPUBFUN xmlChar
* XMLCALL
483 xmlXPathCastNodeSetToString (xmlNodeSetPtr ns
);
484 XMLPUBFUN xmlChar
* XMLCALL
485 xmlXPathCastToString (xmlXPathObjectPtr val
);
487 XMLPUBFUN xmlXPathObjectPtr XMLCALL
488 xmlXPathConvertBoolean (xmlXPathObjectPtr val
);
489 XMLPUBFUN xmlXPathObjectPtr XMLCALL
490 xmlXPathConvertNumber (xmlXPathObjectPtr val
);
491 XMLPUBFUN xmlXPathObjectPtr XMLCALL
492 xmlXPathConvertString (xmlXPathObjectPtr val
);
497 XMLPUBFUN xmlXPathContextPtr XMLCALL
498 xmlXPathNewContext (xmlDocPtr doc
);
499 XMLPUBFUN
void XMLCALL
500 xmlXPathFreeContext (xmlXPathContextPtr ctxt
);
501 XMLPUBFUN
int XMLCALL
502 xmlXPathContextSetCache(xmlXPathContextPtr ctxt
,
507 * Evaluation functions.
509 XMLPUBFUN
long XMLCALL
510 xmlXPathOrderDocElems (xmlDocPtr doc
);
511 XMLPUBFUN xmlXPathObjectPtr XMLCALL
512 xmlXPathEval (const xmlChar
*str
,
513 xmlXPathContextPtr ctx
);
514 XMLPUBFUN xmlXPathObjectPtr XMLCALL
515 xmlXPathEvalExpression (const xmlChar
*str
,
516 xmlXPathContextPtr ctxt
);
517 XMLPUBFUN
int XMLCALL
518 xmlXPathEvalPredicate (xmlXPathContextPtr ctxt
,
519 xmlXPathObjectPtr res
);
521 * Separate compilation/evaluation entry points.
523 XMLPUBFUN xmlXPathCompExprPtr XMLCALL
524 xmlXPathCompile (const xmlChar
*str
);
525 XMLPUBFUN xmlXPathCompExprPtr XMLCALL
526 xmlXPathCtxtCompile (xmlXPathContextPtr ctxt
,
528 XMLPUBFUN xmlXPathObjectPtr XMLCALL
529 xmlXPathCompiledEval (xmlXPathCompExprPtr comp
,
530 xmlXPathContextPtr ctx
);
531 XMLPUBFUN
int XMLCALL
532 xmlXPathCompiledEvalToBoolean(xmlXPathCompExprPtr comp
,
533 xmlXPathContextPtr ctxt
);
534 XMLPUBFUN
void XMLCALL
535 xmlXPathFreeCompExpr (xmlXPathCompExprPtr comp
);
536 #endif /* LIBXML_XPATH_ENABLED */
537 #if defined(LIBXML_XPATH_ENABLED) || defined(LIBXML_SCHEMAS_ENABLED)
538 XMLPUBFUN
void XMLCALL
540 XMLPUBFUN
int XMLCALL
541 xmlXPathIsNaN (double val
);
542 XMLPUBFUN
int XMLCALL
543 xmlXPathIsInf (double val
);
549 #endif /* LIBXML_XPATH_ENABLED or LIBXML_SCHEMAS_ENABLED*/
550 #endif /* ! __XML_XPATH_H__ */