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