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