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