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 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 typedef struct _xmlXPathContext xmlXPathContext; 35 typedef xmlXPathContext *xmlXPathContextPtr; 36 typedef struct _xmlXPathParserContext xmlXPathParserContext; 37 typedef xmlXPathParserContext *xmlXPathParserContextPtr; 38 39 /** 40 * The set of XPath error codes. 41 */ 42 43 typedef enum { 44 XPATH_EXPRESSION_OK = 0, 45 XPATH_NUMBER_ERROR, 46 XPATH_UNFINISHED_LITERAL_ERROR, 47 XPATH_START_LITERAL_ERROR, 48 XPATH_VARIABLE_REF_ERROR, 49 XPATH_UNDEF_VARIABLE_ERROR, 50 XPATH_INVALID_PREDICATE_ERROR, 51 XPATH_EXPR_ERROR, 52 XPATH_UNCLOSED_ERROR, 53 XPATH_UNKNOWN_FUNC_ERROR, 54 XPATH_INVALID_OPERAND, 55 XPATH_INVALID_TYPE, 56 XPATH_INVALID_ARITY, 57 XPATH_INVALID_CTXT_SIZE, 58 XPATH_INVALID_CTXT_POSITION, 59 XPATH_MEMORY_ERROR, 60 XPTR_SYNTAX_ERROR, 61 XPTR_RESOURCE_ERROR, 62 XPTR_SUB_RESOURCE_ERROR, 63 XPATH_UNDEF_PREFIX_ERROR, 64 XPATH_ENCODING_ERROR, 65 XPATH_INVALID_CHAR_ERROR, 66 XPATH_INVALID_CTXT, 67 XPATH_STACK_ERROR, 68 XPATH_FORBID_VARIABLE_ERROR, 69 XPATH_OP_LIMIT_EXCEEDED, 70 XPATH_RECURSION_LIMIT_EXCEEDED 71 } xmlXPathError; 72 73 /* 74 * A node-set (an unordered collection of nodes without duplicates). 75 */ 76 typedef struct _xmlNodeSet xmlNodeSet; 77 typedef xmlNodeSet *xmlNodeSetPtr; 78 struct _xmlNodeSet { 79 int nodeNr; /* number of nodes in the set */ 80 int nodeMax; /* size of the array as allocated */ 81 xmlNodePtr *nodeTab; /* array of nodes in no particular order */ 82 /* @@ with_ns to check whether namespace nodes should be looked at @@ */ 83 }; 84 85 /* 86 * An expression is evaluated to yield an object, which 87 * has one of the following four basic types: 88 * - node-set 89 * - boolean 90 * - number 91 * - string 92 * 93 * @@ XPointer will add more types ! 94 */ 95 96 typedef enum { 97 XPATH_UNDEFINED = 0, 98 XPATH_NODESET = 1, 99 XPATH_BOOLEAN = 2, 100 XPATH_NUMBER = 3, 101 XPATH_STRING = 4, 102 XPATH_USERS = 8, 103 XPATH_XSLT_TREE = 9 /* An XSLT value tree, non modifiable */ 104 } xmlXPathObjectType; 105 106 /** DOC_DISABLE */ 107 #define XPATH_POINT 5 108 #define XPATH_RANGE 6 109 #define XPATH_LOCATIONSET 7 110 /** DOC_ENABLE */ 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 /* Resource limits */ 357 unsigned long opLimit; 358 unsigned long opCount; 359 int depth; 360 }; 361 362 /* 363 * The structure of a compiled expression form is not public. 364 */ 365 366 typedef struct _xmlXPathCompExpr xmlXPathCompExpr; 367 typedef xmlXPathCompExpr *xmlXPathCompExprPtr; 368 369 /** 370 * xmlXPathParserContext: 371 * 372 * An XPath parser context. It contains pure parsing information, 373 * an xmlXPathContext, and the stack of objects. 374 */ 375 struct _xmlXPathParserContext { 376 const xmlChar *cur; /* the current char being parsed */ 377 const xmlChar *base; /* the full expression */ 378 379 int error; /* error code */ 380 381 xmlXPathContextPtr context; /* the evaluation context */ 382 xmlXPathObjectPtr value; /* the current value */ 383 int valueNr; /* number of values stacked */ 384 int valueMax; /* max number of values stacked */ 385 xmlXPathObjectPtr *valueTab; /* stack of values */ 386 387 xmlXPathCompExprPtr comp; /* the precompiled expression */ 388 int xptr; /* it this an XPointer expression */ 389 xmlNodePtr ancestor; /* used for walking preceding axis */ 390 391 int valueFrame; /* always zero for compatibility */ 392 }; 393 394 /************************************************************************ 395 * * 396 * Public API * 397 * * 398 ************************************************************************/ 399 400 /** 401 * Objects and Nodesets handling 402 */ 403 404 XML_DEPRECATED 405 XMLPUBVAR double xmlXPathNAN; 406 XML_DEPRECATED 407 XMLPUBVAR double xmlXPathPINF; 408 XML_DEPRECATED 409 XMLPUBVAR double xmlXPathNINF; 410 411 /* These macros may later turn into functions */ 412 /** 413 * xmlXPathNodeSetGetLength: 414 * @ns: a node-set 415 * 416 * Implement a functionality similar to the DOM NodeList.length. 417 * 418 * Returns the number of nodes in the node-set. 419 */ 420 #define xmlXPathNodeSetGetLength(ns) ((ns) ? (ns)->nodeNr : 0) 421 /** 422 * xmlXPathNodeSetItem: 423 * @ns: a node-set 424 * @index: index of a node in the set 425 * 426 * Implements a functionality similar to the DOM NodeList.item(). 427 * 428 * Returns the xmlNodePtr at the given @index in @ns or NULL if 429 * @index is out of range (0 to length-1) 430 */ 431 #define xmlXPathNodeSetItem(ns, index) \ 432 ((((ns) != NULL) && \ 433 ((index) >= 0) && ((index) < (ns)->nodeNr)) ? \ 434 (ns)->nodeTab[(index)] \ 435 : NULL) 436 /** 437 * xmlXPathNodeSetIsEmpty: 438 * @ns: a node-set 439 * 440 * Checks whether @ns is empty or not. 441 * 442 * Returns %TRUE if @ns is an empty node-set. 443 */ 444 #define xmlXPathNodeSetIsEmpty(ns) \ 445 (((ns) == NULL) || ((ns)->nodeNr == 0) || ((ns)->nodeTab == NULL)) 446 447 448 XMLPUBFUN void 449 xmlXPathFreeObject (xmlXPathObjectPtr obj); 450 XMLPUBFUN xmlNodeSetPtr 451 xmlXPathNodeSetCreate (xmlNodePtr val); 452 XMLPUBFUN void 453 xmlXPathFreeNodeSetList (xmlXPathObjectPtr obj); 454 XMLPUBFUN void 455 xmlXPathFreeNodeSet (xmlNodeSetPtr obj); 456 XMLPUBFUN xmlXPathObjectPtr 457 xmlXPathObjectCopy (xmlXPathObjectPtr val); 458 XMLPUBFUN int 459 xmlXPathCmpNodes (xmlNodePtr node1, 460 xmlNodePtr node2); 461 /** 462 * Conversion functions to basic types. 463 */ 464 XMLPUBFUN int 465 xmlXPathCastNumberToBoolean (double val); 466 XMLPUBFUN int 467 xmlXPathCastStringToBoolean (const xmlChar * val); 468 XMLPUBFUN int 469 xmlXPathCastNodeSetToBoolean(xmlNodeSetPtr ns); 470 XMLPUBFUN int 471 xmlXPathCastToBoolean (xmlXPathObjectPtr val); 472 473 XMLPUBFUN double 474 xmlXPathCastBooleanToNumber (int val); 475 XMLPUBFUN double 476 xmlXPathCastStringToNumber (const xmlChar * val); 477 XMLPUBFUN double 478 xmlXPathCastNodeToNumber (xmlNodePtr node); 479 XMLPUBFUN double 480 xmlXPathCastNodeSetToNumber (xmlNodeSetPtr ns); 481 XMLPUBFUN double 482 xmlXPathCastToNumber (xmlXPathObjectPtr val); 483 484 XMLPUBFUN xmlChar * 485 xmlXPathCastBooleanToString (int val); 486 XMLPUBFUN xmlChar * 487 xmlXPathCastNumberToString (double val); 488 XMLPUBFUN xmlChar * 489 xmlXPathCastNodeToString (xmlNodePtr node); 490 XMLPUBFUN xmlChar * 491 xmlXPathCastNodeSetToString (xmlNodeSetPtr ns); 492 XMLPUBFUN xmlChar * 493 xmlXPathCastToString (xmlXPathObjectPtr val); 494 495 XMLPUBFUN xmlXPathObjectPtr 496 xmlXPathConvertBoolean (xmlXPathObjectPtr val); 497 XMLPUBFUN xmlXPathObjectPtr 498 xmlXPathConvertNumber (xmlXPathObjectPtr val); 499 XMLPUBFUN xmlXPathObjectPtr 500 xmlXPathConvertString (xmlXPathObjectPtr val); 501 502 /** 503 * Context handling. 504 */ 505 XMLPUBFUN xmlXPathContextPtr 506 xmlXPathNewContext (xmlDocPtr doc); 507 XMLPUBFUN void 508 xmlXPathFreeContext (xmlXPathContextPtr ctxt); 509 XMLPUBFUN void 510 xmlXPathSetErrorHandler(xmlXPathContextPtr ctxt, 511 xmlStructuredErrorFunc handler, 512 void *context); 513 XMLPUBFUN int 514 xmlXPathContextSetCache(xmlXPathContextPtr ctxt, 515 int active, 516 int value, 517 int options); 518 /** 519 * Evaluation functions. 520 */ 521 XMLPUBFUN long 522 xmlXPathOrderDocElems (xmlDocPtr doc); 523 XMLPUBFUN int 524 xmlXPathSetContextNode (xmlNodePtr node, 525 xmlXPathContextPtr ctx); 526 XMLPUBFUN xmlXPathObjectPtr 527 xmlXPathNodeEval (xmlNodePtr node, 528 const xmlChar *str, 529 xmlXPathContextPtr ctx); 530 XMLPUBFUN xmlXPathObjectPtr 531 xmlXPathEval (const xmlChar *str, 532 xmlXPathContextPtr ctx); 533 XMLPUBFUN xmlXPathObjectPtr 534 xmlXPathEvalExpression (const xmlChar *str, 535 xmlXPathContextPtr ctxt); 536 XMLPUBFUN int 537 xmlXPathEvalPredicate (xmlXPathContextPtr ctxt, 538 xmlXPathObjectPtr res); 539 /** 540 * Separate compilation/evaluation entry points. 541 */ 542 XMLPUBFUN xmlXPathCompExprPtr 543 xmlXPathCompile (const xmlChar *str); 544 XMLPUBFUN xmlXPathCompExprPtr 545 xmlXPathCtxtCompile (xmlXPathContextPtr ctxt, 546 const xmlChar *str); 547 XMLPUBFUN xmlXPathObjectPtr 548 xmlXPathCompiledEval (xmlXPathCompExprPtr comp, 549 xmlXPathContextPtr ctx); 550 XMLPUBFUN int 551 xmlXPathCompiledEvalToBoolean(xmlXPathCompExprPtr comp, 552 xmlXPathContextPtr ctxt); 553 XMLPUBFUN void 554 xmlXPathFreeCompExpr (xmlXPathCompExprPtr comp); 555 556 XML_DEPRECATED 557 XMLPUBFUN void 558 xmlXPathInit (void); 559 XMLPUBFUN int 560 xmlXPathIsNaN (double val); 561 XMLPUBFUN int 562 xmlXPathIsInf (double val); 563 564 #ifdef __cplusplus 565 } 566 #endif 567 568 #endif /* LIBXML_XPATH_ENABLED */ 569 #endif /* ! __XML_XPATH_H__ */ 570