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 XPATH_OP_LIMIT_EXCEEDED, 75 XPATH_RECURSION_LIMIT_EXCEEDED 76 } xmlXPathError; 77 78 /* 79 * A node-set (an unordered collection of nodes without duplicates). 80 */ 81 typedef struct _xmlNodeSet xmlNodeSet; 82 typedef xmlNodeSet *xmlNodeSetPtr; 83 struct _xmlNodeSet { 84 int nodeNr; /* number of nodes in the set */ 85 int nodeMax; /* size of the array as allocated */ 86 xmlNodePtr *nodeTab; /* array of nodes in no particular order */ 87 /* @@ with_ns to check whether namespace nodes should be looked at @@ */ 88 }; 89 90 /* 91 * An expression is evaluated to yield an object, which 92 * has one of the following four basic types: 93 * - node-set 94 * - boolean 95 * - number 96 * - string 97 * 98 * @@ XPointer will add more types ! 99 */ 100 101 typedef enum { 102 XPATH_UNDEFINED = 0, 103 XPATH_NODESET = 1, 104 XPATH_BOOLEAN = 2, 105 XPATH_NUMBER = 3, 106 XPATH_STRING = 4, 107 #ifdef LIBXML_XPTR_LOCS_ENABLED 108 XPATH_POINT = 5, 109 XPATH_RANGE = 6, 110 XPATH_LOCATIONSET = 7, 111 #endif 112 XPATH_USERS = 8, 113 XPATH_XSLT_TREE = 9 /* An XSLT value tree, non modifiable */ 114 } xmlXPathObjectType; 115 116 #ifndef LIBXML_XPTR_LOCS_ENABLED 117 /** DOC_DISABLE */ 118 #define XPATH_POINT 5 119 #define XPATH_RANGE 6 120 #define XPATH_LOCATIONSET 7 121 /** DOC_ENABLE */ 122 #endif 123 124 typedef struct _xmlXPathObject xmlXPathObject; 125 typedef xmlXPathObject *xmlXPathObjectPtr; 126 struct _xmlXPathObject { 127 xmlXPathObjectType type; 128 xmlNodeSetPtr nodesetval; 129 int boolval; 130 double floatval; 131 xmlChar *stringval; 132 void *user; 133 int index; 134 void *user2; 135 int index2; 136 }; 137 138 /** 139 * xmlXPathConvertFunc: 140 * @obj: an XPath object 141 * @type: the number of the target type 142 * 143 * A conversion function is associated to a type and used to cast 144 * the new type to primitive values. 145 * 146 * Returns -1 in case of error, 0 otherwise 147 */ 148 typedef int (*xmlXPathConvertFunc) (xmlXPathObjectPtr obj, int type); 149 150 /* 151 * Extra type: a name and a conversion function. 152 */ 153 154 typedef struct _xmlXPathType xmlXPathType; 155 typedef xmlXPathType *xmlXPathTypePtr; 156 struct _xmlXPathType { 157 const xmlChar *name; /* the type name */ 158 xmlXPathConvertFunc func; /* the conversion function */ 159 }; 160 161 /* 162 * Extra variable: a name and a value. 163 */ 164 165 typedef struct _xmlXPathVariable xmlXPathVariable; 166 typedef xmlXPathVariable *xmlXPathVariablePtr; 167 struct _xmlXPathVariable { 168 const xmlChar *name; /* the variable name */ 169 xmlXPathObjectPtr value; /* the value */ 170 }; 171 172 /** 173 * xmlXPathEvalFunc: 174 * @ctxt: an XPath parser context 175 * @nargs: the number of arguments passed to the function 176 * 177 * An XPath evaluation function, the parameters are on the XPath context stack. 178 */ 179 180 typedef void (*xmlXPathEvalFunc)(xmlXPathParserContextPtr ctxt, 181 int nargs); 182 183 /* 184 * Extra function: a name and a evaluation function. 185 */ 186 187 typedef struct _xmlXPathFunct xmlXPathFunct; 188 typedef xmlXPathFunct *xmlXPathFuncPtr; 189 struct _xmlXPathFunct { 190 const xmlChar *name; /* the function name */ 191 xmlXPathEvalFunc func; /* the evaluation function */ 192 }; 193 194 /** 195 * xmlXPathAxisFunc: 196 * @ctxt: the XPath interpreter context 197 * @cur: the previous node being explored on that axis 198 * 199 * An axis traversal function. To traverse an axis, the engine calls 200 * the first time with cur == NULL and repeat until the function returns 201 * NULL indicating the end of the axis traversal. 202 * 203 * Returns the next node in that axis or NULL if at the end of the axis. 204 */ 205 206 typedef xmlXPathObjectPtr (*xmlXPathAxisFunc) (xmlXPathParserContextPtr ctxt, 207 xmlXPathObjectPtr cur); 208 209 /* 210 * Extra axis: a name and an axis function. 211 */ 212 213 typedef struct _xmlXPathAxis xmlXPathAxis; 214 typedef xmlXPathAxis *xmlXPathAxisPtr; 215 struct _xmlXPathAxis { 216 const xmlChar *name; /* the axis name */ 217 xmlXPathAxisFunc func; /* the search function */ 218 }; 219 220 /** 221 * xmlXPathFunction: 222 * @ctxt: the XPath interprestation context 223 * @nargs: the number of arguments 224 * 225 * An XPath function. 226 * The arguments (if any) are popped out from the context stack 227 * and the result is pushed on the stack. 228 */ 229 230 typedef void (*xmlXPathFunction) (xmlXPathParserContextPtr ctxt, int nargs); 231 232 /* 233 * Function and Variable Lookup. 234 */ 235 236 /** 237 * xmlXPathVariableLookupFunc: 238 * @ctxt: an XPath context 239 * @name: name of the variable 240 * @ns_uri: the namespace name hosting this variable 241 * 242 * Prototype for callbacks used to plug variable lookup in the XPath 243 * engine. 244 * 245 * Returns the XPath object value or NULL if not found. 246 */ 247 typedef xmlXPathObjectPtr (*xmlXPathVariableLookupFunc) (void *ctxt, 248 const xmlChar *name, 249 const xmlChar *ns_uri); 250 251 /** 252 * xmlXPathFuncLookupFunc: 253 * @ctxt: an XPath context 254 * @name: name of the function 255 * @ns_uri: the namespace name hosting this function 256 * 257 * Prototype for callbacks used to plug function lookup in the XPath 258 * engine. 259 * 260 * Returns the XPath function or NULL if not found. 261 */ 262 typedef xmlXPathFunction (*xmlXPathFuncLookupFunc) (void *ctxt, 263 const xmlChar *name, 264 const xmlChar *ns_uri); 265 266 /** 267 * xmlXPathFlags: 268 * Flags for XPath engine compilation and runtime 269 */ 270 /** 271 * XML_XPATH_CHECKNS: 272 * 273 * check namespaces at compilation 274 */ 275 #define XML_XPATH_CHECKNS (1<<0) 276 /** 277 * XML_XPATH_NOVAR: 278 * 279 * forbid variables in expression 280 */ 281 #define XML_XPATH_NOVAR (1<<1) 282 283 /** 284 * xmlXPathContext: 285 * 286 * Expression evaluation occurs with respect to a context. 287 * he context consists of: 288 * - a node (the context node) 289 * - a node list (the context node list) 290 * - a set of variable bindings 291 * - a function library 292 * - the set of namespace declarations in scope for the expression 293 * Following the switch to hash tables, this need to be trimmed up at 294 * the next binary incompatible release. 295 * The node may be modified when the context is passed to libxml2 296 * for an XPath evaluation so you may need to initialize it again 297 * before the next call. 298 */ 299 300 struct _xmlXPathContext { 301 xmlDocPtr doc; /* The current document */ 302 xmlNodePtr node; /* The current node */ 303 304 int nb_variables_unused; /* unused (hash table) */ 305 int max_variables_unused; /* unused (hash table) */ 306 xmlHashTablePtr varHash; /* Hash table of defined variables */ 307 308 int nb_types; /* number of defined types */ 309 int max_types; /* max number of types */ 310 xmlXPathTypePtr types; /* Array of defined types */ 311 312 int nb_funcs_unused; /* unused (hash table) */ 313 int max_funcs_unused; /* unused (hash table) */ 314 xmlHashTablePtr funcHash; /* Hash table of defined funcs */ 315 316 int nb_axis; /* number of defined axis */ 317 int max_axis; /* max number of axis */ 318 xmlXPathAxisPtr axis; /* Array of defined axis */ 319 320 /* the namespace nodes of the context node */ 321 xmlNsPtr *namespaces; /* Array of namespaces */ 322 int nsNr; /* number of namespace in scope */ 323 void *user; /* function to free */ 324 325 /* extra variables */ 326 int contextSize; /* the context size */ 327 int proximityPosition; /* the proximity position */ 328 329 /* extra stuff for XPointer */ 330 int xptr; /* is this an XPointer context? */ 331 xmlNodePtr here; /* for here() */ 332 xmlNodePtr origin; /* for origin() */ 333 334 /* the set of namespace declarations in scope for the expression */ 335 xmlHashTablePtr nsHash; /* The namespaces hash table */ 336 xmlXPathVariableLookupFunc varLookupFunc;/* variable lookup func */ 337 void *varLookupData; /* variable lookup data */ 338 339 /* Possibility to link in an extra item */ 340 void *extra; /* needed for XSLT */ 341 342 /* The function name and URI when calling a function */ 343 const xmlChar *function; 344 const xmlChar *functionURI; 345 346 /* function lookup function and data */ 347 xmlXPathFuncLookupFunc funcLookupFunc;/* function lookup func */ 348 void *funcLookupData; /* function lookup data */ 349 350 /* temporary namespace lists kept for walking the namespace axis */ 351 xmlNsPtr *tmpNsList; /* Array of namespaces */ 352 int tmpNsNr; /* number of namespaces in scope */ 353 354 /* error reporting mechanism */ 355 void *userData; /* user specific data block */ 356 xmlStructuredErrorFunc error; /* the callback in case of errors */ 357 xmlError lastError; /* the last error */ 358 xmlNodePtr debugNode; /* the source node XSLT */ 359 360 /* dictionary */ 361 xmlDictPtr dict; /* dictionary if any */ 362 363 int flags; /* flags to control compilation */ 364 365 /* Cache for reusal of XPath objects */ 366 void *cache; 367 368 /* Resource limits */ 369 unsigned long opLimit; 370 unsigned long opCount; 371 int depth; 372 }; 373 374 /* 375 * The structure of a compiled expression form is not public. 376 */ 377 378 typedef struct _xmlXPathCompExpr xmlXPathCompExpr; 379 typedef xmlXPathCompExpr *xmlXPathCompExprPtr; 380 381 /** 382 * xmlXPathParserContext: 383 * 384 * An XPath parser context. It contains pure parsing information, 385 * an xmlXPathContext, and the stack of objects. 386 */ 387 struct _xmlXPathParserContext { 388 const xmlChar *cur; /* the current char being parsed */ 389 const xmlChar *base; /* the full expression */ 390 391 int error; /* error code */ 392 393 xmlXPathContextPtr context; /* the evaluation context */ 394 xmlXPathObjectPtr value; /* the current value */ 395 int valueNr; /* number of values stacked */ 396 int valueMax; /* max number of values stacked */ 397 xmlXPathObjectPtr *valueTab; /* stack of values */ 398 399 xmlXPathCompExprPtr comp; /* the precompiled expression */ 400 int xptr; /* it this an XPointer expression */ 401 xmlNodePtr ancestor; /* used for walking preceding axis */ 402 403 int valueFrame; /* used to limit Pop on the stack */ 404 }; 405 406 /************************************************************************ 407 * * 408 * Public API * 409 * * 410 ************************************************************************/ 411 412 /** 413 * Objects and Nodesets handling 414 */ 415 416 XMLPUBVAR double xmlXPathNAN; 417 XMLPUBVAR double xmlXPathPINF; 418 XMLPUBVAR double xmlXPathNINF; 419 420 /* These macros may later turn into functions */ 421 /** 422 * xmlXPathNodeSetGetLength: 423 * @ns: a node-set 424 * 425 * Implement a functionality similar to the DOM NodeList.length. 426 * 427 * Returns the number of nodes in the node-set. 428 */ 429 #define xmlXPathNodeSetGetLength(ns) ((ns) ? (ns)->nodeNr : 0) 430 /** 431 * xmlXPathNodeSetItem: 432 * @ns: a node-set 433 * @index: index of a node in the set 434 * 435 * Implements a functionality similar to the DOM NodeList.item(). 436 * 437 * Returns the xmlNodePtr at the given @index in @ns or NULL if 438 * @index is out of range (0 to length-1) 439 */ 440 #define xmlXPathNodeSetItem(ns, index) \ 441 ((((ns) != NULL) && \ 442 ((index) >= 0) && ((index) < (ns)->nodeNr)) ? \ 443 (ns)->nodeTab[(index)] \ 444 : NULL) 445 /** 446 * xmlXPathNodeSetIsEmpty: 447 * @ns: a node-set 448 * 449 * Checks whether @ns is empty or not. 450 * 451 * Returns %TRUE if @ns is an empty node-set. 452 */ 453 #define xmlXPathNodeSetIsEmpty(ns) \ 454 (((ns) == NULL) || ((ns)->nodeNr == 0) || ((ns)->nodeTab == NULL)) 455 456 457 XMLPUBFUN void XMLCALL 458 xmlXPathFreeObject (xmlXPathObjectPtr obj); 459 XMLPUBFUN xmlNodeSetPtr XMLCALL 460 xmlXPathNodeSetCreate (xmlNodePtr val); 461 XMLPUBFUN void XMLCALL 462 xmlXPathFreeNodeSetList (xmlXPathObjectPtr obj); 463 XMLPUBFUN void XMLCALL 464 xmlXPathFreeNodeSet (xmlNodeSetPtr obj); 465 XMLPUBFUN xmlXPathObjectPtr XMLCALL 466 xmlXPathObjectCopy (xmlXPathObjectPtr val); 467 XMLPUBFUN int XMLCALL 468 xmlXPathCmpNodes (xmlNodePtr node1, 469 xmlNodePtr node2); 470 /** 471 * Conversion functions to basic types. 472 */ 473 XMLPUBFUN int XMLCALL 474 xmlXPathCastNumberToBoolean (double val); 475 XMLPUBFUN int XMLCALL 476 xmlXPathCastStringToBoolean (const xmlChar * val); 477 XMLPUBFUN int XMLCALL 478 xmlXPathCastNodeSetToBoolean(xmlNodeSetPtr ns); 479 XMLPUBFUN int XMLCALL 480 xmlXPathCastToBoolean (xmlXPathObjectPtr val); 481 482 XMLPUBFUN double XMLCALL 483 xmlXPathCastBooleanToNumber (int val); 484 XMLPUBFUN double XMLCALL 485 xmlXPathCastStringToNumber (const xmlChar * val); 486 XMLPUBFUN double XMLCALL 487 xmlXPathCastNodeToNumber (xmlNodePtr node); 488 XMLPUBFUN double XMLCALL 489 xmlXPathCastNodeSetToNumber (xmlNodeSetPtr ns); 490 XMLPUBFUN double XMLCALL 491 xmlXPathCastToNumber (xmlXPathObjectPtr val); 492 493 XMLPUBFUN xmlChar * XMLCALL 494 xmlXPathCastBooleanToString (int val); 495 XMLPUBFUN xmlChar * XMLCALL 496 xmlXPathCastNumberToString (double val); 497 XMLPUBFUN xmlChar * XMLCALL 498 xmlXPathCastNodeToString (xmlNodePtr node); 499 XMLPUBFUN xmlChar * XMLCALL 500 xmlXPathCastNodeSetToString (xmlNodeSetPtr ns); 501 XMLPUBFUN xmlChar * XMLCALL 502 xmlXPathCastToString (xmlXPathObjectPtr val); 503 504 XMLPUBFUN xmlXPathObjectPtr XMLCALL 505 xmlXPathConvertBoolean (xmlXPathObjectPtr val); 506 XMLPUBFUN xmlXPathObjectPtr XMLCALL 507 xmlXPathConvertNumber (xmlXPathObjectPtr val); 508 XMLPUBFUN xmlXPathObjectPtr XMLCALL 509 xmlXPathConvertString (xmlXPathObjectPtr val); 510 511 /** 512 * Context handling. 513 */ 514 XMLPUBFUN xmlXPathContextPtr XMLCALL 515 xmlXPathNewContext (xmlDocPtr doc); 516 XMLPUBFUN void XMLCALL 517 xmlXPathFreeContext (xmlXPathContextPtr ctxt); 518 XMLPUBFUN int XMLCALL 519 xmlXPathContextSetCache(xmlXPathContextPtr ctxt, 520 int active, 521 int value, 522 int options); 523 /** 524 * Evaluation functions. 525 */ 526 XMLPUBFUN long XMLCALL 527 xmlXPathOrderDocElems (xmlDocPtr doc); 528 XMLPUBFUN int XMLCALL 529 xmlXPathSetContextNode (xmlNodePtr node, 530 xmlXPathContextPtr ctx); 531 XMLPUBFUN xmlXPathObjectPtr XMLCALL 532 xmlXPathNodeEval (xmlNodePtr node, 533 const xmlChar *str, 534 xmlXPathContextPtr ctx); 535 XMLPUBFUN xmlXPathObjectPtr XMLCALL 536 xmlXPathEval (const xmlChar *str, 537 xmlXPathContextPtr ctx); 538 XMLPUBFUN xmlXPathObjectPtr XMLCALL 539 xmlXPathEvalExpression (const xmlChar *str, 540 xmlXPathContextPtr ctxt); 541 XMLPUBFUN int XMLCALL 542 xmlXPathEvalPredicate (xmlXPathContextPtr ctxt, 543 xmlXPathObjectPtr res); 544 /** 545 * Separate compilation/evaluation entry points. 546 */ 547 XMLPUBFUN xmlXPathCompExprPtr XMLCALL 548 xmlXPathCompile (const xmlChar *str); 549 XMLPUBFUN xmlXPathCompExprPtr XMLCALL 550 xmlXPathCtxtCompile (xmlXPathContextPtr ctxt, 551 const xmlChar *str); 552 XMLPUBFUN xmlXPathObjectPtr XMLCALL 553 xmlXPathCompiledEval (xmlXPathCompExprPtr comp, 554 xmlXPathContextPtr ctx); 555 XMLPUBFUN int XMLCALL 556 xmlXPathCompiledEvalToBoolean(xmlXPathCompExprPtr comp, 557 xmlXPathContextPtr ctxt); 558 XMLPUBFUN void XMLCALL 559 xmlXPathFreeCompExpr (xmlXPathCompExprPtr comp); 560 #endif /* LIBXML_XPATH_ENABLED */ 561 #if defined(LIBXML_XPATH_ENABLED) || defined(LIBXML_SCHEMAS_ENABLED) 562 XML_DEPRECATED 563 XMLPUBFUN void XMLCALL 564 xmlXPathInit (void); 565 XMLPUBFUN int XMLCALL 566 xmlXPathIsNaN (double val); 567 XMLPUBFUN int XMLCALL 568 xmlXPathIsInf (double val); 569 570 #ifdef __cplusplus 571 } 572 #endif 573 574 #endif /* LIBXML_XPATH_ENABLED or LIBXML_SCHEMAS_ENABLED*/ 575 #endif /* ! __XML_XPATH_H__ */ 576