xpath.h
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 XPATH_STACK_ERROR, 73 XPATH_FORBID_VARIABLE_ERROR 74 } xmlXPathError; 75 76 /* 77 * A node-set (an unordered collection of nodes without duplicates). 78 */ 79 typedef struct _xmlNodeSet xmlNodeSet; 80 typedef xmlNodeSet *xmlNodeSetPtr; 81 struct _xmlNodeSet { 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 @@ */ 86 }; 87 88 /* 89 * An expression is evaluated to yield an object, which 90 * has one of the following four basic types: 91 * - node-set 92 * - boolean 93 * - number 94 * - string 95 * 96 * @@ XPointer will add more types ! 97 */ 98 99 typedef enum { 100 XPATH_UNDEFINED = 0, 101 XPATH_NODESET = 1, 102 XPATH_BOOLEAN = 2, 103 XPATH_NUMBER = 3, 104 XPATH_STRING = 4, 105 XPATH_POINT = 5, 106 XPATH_RANGE = 6, 107 XPATH_LOCATIONSET = 7, 108 XPATH_USERS = 8, 109 XPATH_XSLT_TREE = 9 /* An XSLT value tree, non modifiable */ 110 } xmlXPathObjectType; 111 112 typedef struct _xmlXPathObject xmlXPathObject; 113 typedef xmlXPathObject *xmlXPathObjectPtr; 114 struct _xmlXPathObject { 115 xmlXPathObjectType type; 116 xmlNodeSetPtr nodesetval; 117 int boolval; 118 double floatval; 119 xmlChar *stringval; 120 void *user; 121 int index; 122 void *user2; 123 int index2; 124 }; 125 126 /** 127 * xmlXPathConvertFunc: 128 * @obj: an XPath object 129 * @type: the number of the target type 130 * 131 * A conversion function is associated to a type and used to cast 132 * the new type to primitive values. 133 * 134 * Returns -1 in case of error, 0 otherwise 135 */ 136 typedef int (*xmlXPathConvertFunc) (xmlXPathObjectPtr obj, int type); 137 138 /* 139 * Extra type: a name and a conversion function. 140 */ 141 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 */ 147 }; 148 149 /* 150 * Extra variable: a name and a value. 151 */ 152 153 typedef struct _xmlXPathVariable xmlXPathVariable; 154 typedef xmlXPathVariable *xmlXPathVariablePtr; 155 struct _xmlXPathVariable { 156 const xmlChar *name; /* the variable name */ 157 xmlXPathObjectPtr value; /* the value */ 158 }; 159 160 /** 161 * xmlXPathEvalFunc: 162 * @ctxt: an XPath parser context 163 * @nargs: the number of arguments passed to the function 164 * 165 * An XPath evaluation function, the parameters are on the XPath context stack. 166 */ 167 168 typedef void (*xmlXPathEvalFunc)(xmlXPathParserContextPtr ctxt, 169 int nargs); 170 171 /* 172 * Extra function: a name and a evaluation function. 173 */ 174 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 */ 180 }; 181 182 /** 183 * xmlXPathAxisFunc: 184 * @ctxt: the XPath interpreter context 185 * @cur: the previous node being explored on that axis 186 * 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. 190 * 191 * Returns the next node in that axis or NULL if at the end of the axis. 192 */ 193 194 typedef xmlXPathObjectPtr (*xmlXPathAxisFunc) (xmlXPathParserContextPtr ctxt, 195 xmlXPathObjectPtr cur); 196 197 /* 198 * Extra axis: a name and an axis function. 199 */ 200 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 */ 206 }; 207 208 /** 209 * xmlXPathFunction: 210 * @ctxt: the XPath interprestation context 211 * @nargs: the number of arguments 212 * 213 * An XPath function. 214 * The arguments (if any) are popped out from the context stack 215 * and the result is pushed on the stack. 216 */ 217 218 typedef void (*xmlXPathFunction) (xmlXPathParserContextPtr ctxt, int nargs); 219 220 /* 221 * Function and Variable Lookup. 222 */ 223 224 /** 225 * xmlXPathVariableLookupFunc: 226 * @ctxt: an XPath context 227 * @name: name of the variable 228 * @ns_uri: the namespace name hosting this variable 229 * 230 * Prototype for callbacks used to plug variable lookup in the XPath 231 * engine. 232 * 233 * Returns the XPath object value or NULL if not found. 234 */ 235 typedef xmlXPathObjectPtr (*xmlXPathVariableLookupFunc) (void *ctxt, 236 const xmlChar *name, 237 const xmlChar *ns_uri); 238 239 /** 240 * xmlXPathFuncLookupFunc: 241 * @ctxt: an XPath context 242 * @name: name of the function 243 * @ns_uri: the namespace name hosting this function 244 * 245 * Prototype for callbacks used to plug function lookup in the XPath 246 * engine. 247 * 248 * Returns the XPath function or NULL if not found. 249 */ 250 typedef xmlXPathFunction (*xmlXPathFuncLookupFunc) (void *ctxt, 251 const xmlChar *name, 252 const xmlChar *ns_uri); 253 254 /** 255 * xmlXPathFlags: 256 * Flags for XPath engine compilation and runtime 257 */ 258 /** 259 * XML_XPATH_CHECKNS: 260 * 261 * check namespaces at compilation 262 */ 263 #define XML_XPATH_CHECKNS (1<<0) 264 /** 265 * XML_XPATH_NOVAR: 266 * 267 * forbid variables in expression 268 */ 269 #define XML_XPATH_NOVAR (1<<1) 270 271 /** 272 * xmlXPathContext: 273 * 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. 286 */ 287 288 struct _xmlXPathContext { 289 xmlDocPtr doc; /* The current document */ 290 xmlNodePtr node; /* The current node */ 291 292 int nb_variables_unused; /* unused (hash table) */ 293 int max_variables_unused; /* unused (hash table) */ 294 xmlHashTablePtr varHash; /* Hash table of defined variables */ 295 296 int nb_types; /* number of defined types */ 297 int max_types; /* max number of types */ 298 xmlXPathTypePtr types; /* Array of defined types */ 299 300 int nb_funcs_unused; /* unused (hash table) */ 301 int max_funcs_unused; /* unused (hash table) */ 302 xmlHashTablePtr funcHash; /* Hash table of defined funcs */ 303 304 int nb_axis; /* number of defined axis */ 305 int max_axis; /* max number of axis */ 306 xmlXPathAxisPtr axis; /* Array of defined axis */ 307 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 */ 312 313 /* extra variables */ 314 int contextSize; /* the context size */ 315 int proximityPosition; /* the proximity position */ 316 317 /* extra stuff for XPointer */ 318 int xptr; /* is this an XPointer context? */ 319 xmlNodePtr here; /* for here() */ 320 xmlNodePtr origin; /* for origin() */ 321 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 */ 326 327 /* Possibility to link in an extra item */ 328 void *extra; /* needed for XSLT */ 329 330 /* The function name and URI when calling a function */ 331 const xmlChar *function; 332 const xmlChar *functionURI; 333 334 /* function lookup function and data */ 335 xmlXPathFuncLookupFunc funcLookupFunc;/* function lookup func */ 336 void *funcLookupData; /* function lookup data */ 337 338 /* temporary namespace lists kept for walking the namespace axis */ 339 xmlNsPtr *tmpNsList; /* Array of namespaces */ 340 int tmpNsNr; /* number of namespaces in scope */ 341 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 */ 347 348 /* dictionary */ 349 xmlDictPtr dict; /* dictionary if any */ 350 351 int flags; /* flags to control compilation */ 352 353 /* Cache for reusal of XPath objects */ 354 void *cache; 355 }; 356 357 /* 358 * The structure of a compiled expression form is not public. 359 */ 360 361 typedef struct _xmlXPathCompExpr xmlXPathCompExpr; 362 typedef xmlXPathCompExpr *xmlXPathCompExprPtr; 363 364 /** 365 * xmlXPathParserContext: 366 * 367 * An XPath parser context. It contains pure parsing informations, 368 * an xmlXPathContext, and the stack of objects. 369 */ 370 struct _xmlXPathParserContext { 371 const xmlChar *cur; /* the current char being parsed */ 372 const xmlChar *base; /* the full expression */ 373 374 int error; /* error code */ 375 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 */ 381 382 xmlXPathCompExprPtr comp; /* the precompiled expression */ 383 int xptr; /* it this an XPointer expression */ 384 xmlNodePtr ancestor; /* used for walking preceding axis */ 385 386 int valueFrame; /* used to limit Pop on the stack */ 387 }; 388 389 /************************************************************************ 390 * * 391 * Public API * 392 * * 393 ************************************************************************/ 394 395 /** 396 * Objects and Nodesets handling 397 */ 398 399 XMLPUBVAR double xmlXPathNAN; 400 XMLPUBVAR double xmlXPathPINF; 401 XMLPUBVAR double xmlXPathNINF; 402 403 /* These macros may later turn into functions */ 404 /** 405 * xmlXPathNodeSetGetLength: 406 * @ns: a node-set 407 * 408 * Implement a functionality similar to the DOM NodeList.length. 409 * 410 * Returns the number of nodes in the node-set. 411 */ 412 #define xmlXPathNodeSetGetLength(ns) ((ns) ? (ns)->nodeNr : 0) 413 /** 414 * xmlXPathNodeSetItem: 415 * @ns: a node-set 416 * @index: index of a node in the set 417 * 418 * Implements a functionality similar to the DOM NodeList.item(). 419 * 420 * Returns the xmlNodePtr at the given @index in @ns or NULL if 421 * @index is out of range (0 to length-1) 422 */ 423 #define xmlXPathNodeSetItem(ns, index) \ 424 ((((ns) != NULL) && \ 425 ((index) >= 0) && ((index) < (ns)->nodeNr)) ? \ 426 (ns)->nodeTab[(index)] \ 427 : NULL) 428 /** 429 * xmlXPathNodeSetIsEmpty: 430 * @ns: a node-set 431 * 432 * Checks whether @ns is empty or not. 433 * 434 * Returns %TRUE if @ns is an empty node-set. 435 */ 436 #define xmlXPathNodeSetIsEmpty(ns) \ 437 (((ns) == NULL) || ((ns)->nodeNr == 0) || ((ns)->nodeTab == NULL)) 438 439 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, 452 xmlNodePtr node2); 453 /** 454 * Conversion functions to basic types. 455 */ 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); 464 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); 475 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); 486 487 XMLPUBFUN xmlXPathObjectPtr XMLCALL 488 xmlXPathConvertBoolean (xmlXPathObjectPtr val); 489 XMLPUBFUN xmlXPathObjectPtr XMLCALL 490 xmlXPathConvertNumber (xmlXPathObjectPtr val); 491 XMLPUBFUN xmlXPathObjectPtr XMLCALL 492 xmlXPathConvertString (xmlXPathObjectPtr val); 493 494 /** 495 * Context handling. 496 */ 497 XMLPUBFUN xmlXPathContextPtr XMLCALL 498 xmlXPathNewContext (xmlDocPtr doc); 499 XMLPUBFUN void XMLCALL 500 xmlXPathFreeContext (xmlXPathContextPtr ctxt); 501 XMLPUBFUN int XMLCALL 502 xmlXPathContextSetCache(xmlXPathContextPtr ctxt, 503 int active, 504 int value, 505 int options); 506 /** 507 * Evaluation functions. 508 */ 509 XMLPUBFUN long XMLCALL 510 xmlXPathOrderDocElems (xmlDocPtr doc); 511 XMLPUBFUN int XMLCALL 512 xmlXPathSetContextNode (xmlNodePtr node, 513 xmlXPathContextPtr ctx); 514 XMLPUBFUN xmlXPathObjectPtr XMLCALL 515 xmlXPathNodeEval (xmlNodePtr node, 516 const xmlChar *str, 517 xmlXPathContextPtr ctx); 518 XMLPUBFUN xmlXPathObjectPtr XMLCALL 519 xmlXPathEval (const xmlChar *str, 520 xmlXPathContextPtr ctx); 521 XMLPUBFUN xmlXPathObjectPtr XMLCALL 522 xmlXPathEvalExpression (const xmlChar *str, 523 xmlXPathContextPtr ctxt); 524 XMLPUBFUN int XMLCALL 525 xmlXPathEvalPredicate (xmlXPathContextPtr ctxt, 526 xmlXPathObjectPtr res); 527 /** 528 * Separate compilation/evaluation entry points. 529 */ 530 XMLPUBFUN xmlXPathCompExprPtr XMLCALL 531 xmlXPathCompile (const xmlChar *str); 532 XMLPUBFUN xmlXPathCompExprPtr XMLCALL 533 xmlXPathCtxtCompile (xmlXPathContextPtr ctxt, 534 const xmlChar *str); 535 XMLPUBFUN xmlXPathObjectPtr XMLCALL 536 xmlXPathCompiledEval (xmlXPathCompExprPtr comp, 537 xmlXPathContextPtr ctx); 538 XMLPUBFUN int XMLCALL 539 xmlXPathCompiledEvalToBoolean(xmlXPathCompExprPtr comp, 540 xmlXPathContextPtr ctxt); 541 XMLPUBFUN void XMLCALL 542 xmlXPathFreeCompExpr (xmlXPathCompExprPtr comp); 543 #endif /* LIBXML_XPATH_ENABLED */ 544 #if defined(LIBXML_XPATH_ENABLED) || defined(LIBXML_SCHEMAS_ENABLED) 545 XMLPUBFUN void XMLCALL 546 xmlXPathInit (void); 547 XMLPUBFUN int XMLCALL 548 xmlXPathIsNaN (double val); 549 XMLPUBFUN int XMLCALL 550 xmlXPathIsInf (double val); 551 552 #ifdef __cplusplus 553 } 554 #endif 555 556 #endif /* LIBXML_XPATH_ENABLED or LIBXML_SCHEMAS_ENABLED*/ 557 #endif /* ! __XML_XPATH_H__ */