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 int maxDepth; 363 int maxParserDepth; 364 }; 365 366 /* 367 * The structure of a compiled expression form is not public. 368 */ 369 370 typedef struct _xmlXPathCompExpr xmlXPathCompExpr; 371 typedef xmlXPathCompExpr *xmlXPathCompExprPtr; 372 373 /** 374 * xmlXPathParserContext: 375 * 376 * An XPath parser context. It contains pure parsing informations, 377 * an xmlXPathContext, and the stack of objects. 378 */ 379 struct _xmlXPathParserContext { 380 const xmlChar *cur; /* the current char being parsed */ 381 const xmlChar *base; /* the full expression */ 382 383 int error; /* error code */ 384 385 xmlXPathContextPtr context; /* the evaluation context */ 386 xmlXPathObjectPtr value; /* the current value */ 387 int valueNr; /* number of values stacked */ 388 int valueMax; /* max number of values stacked */ 389 xmlXPathObjectPtr *valueTab; /* stack of values */ 390 391 xmlXPathCompExprPtr comp; /* the precompiled expression */ 392 int xptr; /* it this an XPointer expression */ 393 xmlNodePtr ancestor; /* used for walking preceding axis */ 394 395 int valueFrame; /* used to limit Pop on the stack */ 396 }; 397 398 /************************************************************************ 399 * * 400 * Public API * 401 * * 402 ************************************************************************/ 403 404 /** 405 * Objects and Nodesets handling 406 */ 407 408 XMLPUBVAR double xmlXPathNAN; 409 XMLPUBVAR double xmlXPathPINF; 410 XMLPUBVAR double xmlXPathNINF; 411 412 /* These macros may later turn into functions */ 413 /** 414 * xmlXPathNodeSetGetLength: 415 * @ns: a node-set 416 * 417 * Implement a functionality similar to the DOM NodeList.length. 418 * 419 * Returns the number of nodes in the node-set. 420 */ 421 #define xmlXPathNodeSetGetLength(ns) ((ns) ? (ns)->nodeNr : 0) 422 /** 423 * xmlXPathNodeSetItem: 424 * @ns: a node-set 425 * @index: index of a node in the set 426 * 427 * Implements a functionality similar to the DOM NodeList.item(). 428 * 429 * Returns the xmlNodePtr at the given @index in @ns or NULL if 430 * @index is out of range (0 to length-1) 431 */ 432 #define xmlXPathNodeSetItem(ns, index) \ 433 ((((ns) != NULL) && \ 434 ((index) >= 0) && ((index) < (ns)->nodeNr)) ? \ 435 (ns)->nodeTab[(index)] \ 436 : NULL) 437 /** 438 * xmlXPathNodeSetIsEmpty: 439 * @ns: a node-set 440 * 441 * Checks whether @ns is empty or not. 442 * 443 * Returns %TRUE if @ns is an empty node-set. 444 */ 445 #define xmlXPathNodeSetIsEmpty(ns) \ 446 (((ns) == NULL) || ((ns)->nodeNr == 0) || ((ns)->nodeTab == NULL)) 447 448 449 XMLPUBFUN void XMLCALL 450 xmlXPathFreeObject (xmlXPathObjectPtr obj); 451 XMLPUBFUN xmlNodeSetPtr XMLCALL 452 xmlXPathNodeSetCreate (xmlNodePtr val); 453 XMLPUBFUN void XMLCALL 454 xmlXPathFreeNodeSetList (xmlXPathObjectPtr obj); 455 XMLPUBFUN void XMLCALL 456 xmlXPathFreeNodeSet (xmlNodeSetPtr obj); 457 XMLPUBFUN xmlXPathObjectPtr XMLCALL 458 xmlXPathObjectCopy (xmlXPathObjectPtr val); 459 XMLPUBFUN int XMLCALL 460 xmlXPathCmpNodes (xmlNodePtr node1, 461 xmlNodePtr node2); 462 /** 463 * Conversion functions to basic types. 464 */ 465 XMLPUBFUN int XMLCALL 466 xmlXPathCastNumberToBoolean (double val); 467 XMLPUBFUN int XMLCALL 468 xmlXPathCastStringToBoolean (const xmlChar * val); 469 XMLPUBFUN int XMLCALL 470 xmlXPathCastNodeSetToBoolean(xmlNodeSetPtr ns); 471 XMLPUBFUN int XMLCALL 472 xmlXPathCastToBoolean (xmlXPathObjectPtr val); 473 474 XMLPUBFUN double XMLCALL 475 xmlXPathCastBooleanToNumber (int val); 476 XMLPUBFUN double XMLCALL 477 xmlXPathCastStringToNumber (const xmlChar * val); 478 XMLPUBFUN double XMLCALL 479 xmlXPathCastNodeToNumber (xmlNodePtr node); 480 XMLPUBFUN double XMLCALL 481 xmlXPathCastNodeSetToNumber (xmlNodeSetPtr ns); 482 XMLPUBFUN double XMLCALL 483 xmlXPathCastToNumber (xmlXPathObjectPtr val); 484 485 XMLPUBFUN xmlChar * XMLCALL 486 xmlXPathCastBooleanToString (int val); 487 XMLPUBFUN xmlChar * XMLCALL 488 xmlXPathCastNumberToString (double val); 489 XMLPUBFUN xmlChar * XMLCALL 490 xmlXPathCastNodeToString (xmlNodePtr node); 491 XMLPUBFUN xmlChar * XMLCALL 492 xmlXPathCastNodeSetToString (xmlNodeSetPtr ns); 493 XMLPUBFUN xmlChar * XMLCALL 494 xmlXPathCastToString (xmlXPathObjectPtr val); 495 496 XMLPUBFUN xmlXPathObjectPtr XMLCALL 497 xmlXPathConvertBoolean (xmlXPathObjectPtr val); 498 XMLPUBFUN xmlXPathObjectPtr XMLCALL 499 xmlXPathConvertNumber (xmlXPathObjectPtr val); 500 XMLPUBFUN xmlXPathObjectPtr XMLCALL 501 xmlXPathConvertString (xmlXPathObjectPtr val); 502 503 /** 504 * Context handling. 505 */ 506 XMLPUBFUN xmlXPathContextPtr XMLCALL 507 xmlXPathNewContext (xmlDocPtr doc); 508 XMLPUBFUN void XMLCALL 509 xmlXPathFreeContext (xmlXPathContextPtr ctxt); 510 XMLPUBFUN int XMLCALL 511 xmlXPathContextSetCache(xmlXPathContextPtr ctxt, 512 int active, 513 int value, 514 int options); 515 /** 516 * Evaluation functions. 517 */ 518 XMLPUBFUN long XMLCALL 519 xmlXPathOrderDocElems (xmlDocPtr doc); 520 XMLPUBFUN int XMLCALL 521 xmlXPathSetContextNode (xmlNodePtr node, 522 xmlXPathContextPtr ctx); 523 XMLPUBFUN xmlXPathObjectPtr XMLCALL 524 xmlXPathNodeEval (xmlNodePtr node, 525 const xmlChar *str, 526 xmlXPathContextPtr ctx); 527 XMLPUBFUN xmlXPathObjectPtr XMLCALL 528 xmlXPathEval (const xmlChar *str, 529 xmlXPathContextPtr ctx); 530 XMLPUBFUN xmlXPathObjectPtr XMLCALL 531 xmlXPathEvalExpression (const xmlChar *str, 532 xmlXPathContextPtr ctxt); 533 XMLPUBFUN int XMLCALL 534 xmlXPathEvalPredicate (xmlXPathContextPtr ctxt, 535 xmlXPathObjectPtr res); 536 /** 537 * Separate compilation/evaluation entry points. 538 */ 539 XMLPUBFUN xmlXPathCompExprPtr XMLCALL 540 xmlXPathCompile (const xmlChar *str); 541 XMLPUBFUN xmlXPathCompExprPtr XMLCALL 542 xmlXPathCtxtCompile (xmlXPathContextPtr ctxt, 543 const xmlChar *str); 544 XMLPUBFUN xmlXPathObjectPtr XMLCALL 545 xmlXPathCompiledEval (xmlXPathCompExprPtr comp, 546 xmlXPathContextPtr ctx); 547 XMLPUBFUN int XMLCALL 548 xmlXPathCompiledEvalToBoolean(xmlXPathCompExprPtr comp, 549 xmlXPathContextPtr ctxt); 550 XMLPUBFUN void XMLCALL 551 xmlXPathFreeCompExpr (xmlXPathCompExprPtr comp); 552 #endif /* LIBXML_XPATH_ENABLED */ 553 #if defined(LIBXML_XPATH_ENABLED) || defined(LIBXML_SCHEMAS_ENABLED) 554 XMLPUBFUN void XMLCALL 555 xmlXPathInit (void); 556 XMLPUBFUN int XMLCALL 557 xmlXPathIsNaN (double val); 558 XMLPUBFUN int XMLCALL 559 xmlXPathIsInf (double val); 560 561 #ifdef __cplusplus 562 } 563 #endif 564 565 #endif /* LIBXML_XPATH_ENABLED or LIBXML_SCHEMAS_ENABLED*/ 566 #endif /* ! __XML_XPATH_H__ */ 567