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