1 /* libxml2 - Library for parsing XML documents 2 * Copyright (C) 2006-2019 Free Software Foundation, Inc. 3 * 4 * This file is not part of the GNU gettext program, but is used with 5 * GNU gettext. 6 * 7 * The original copyright notice is as follows: 8 */ 9 10 /* 11 * Copyright (C) 1998-2012 Daniel Veillard. All Rights Reserved. 12 * 13 * Permission is hereby granted, free of charge, to any person obtaining a copy 14 * of this software and associated documentation files (the "Software"), to deal 15 * in the Software without restriction, including without limitation the rights 16 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 17 * copies of the Software, and to permit persons to whom the Software is fur- 18 * nished to do so, subject to the following conditions: 19 * 20 * The above copyright notice and this permission notice shall be included in 21 * all copies or substantial portions of the Software. 22 * 23 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 24 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FIT- 25 * NESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 26 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 27 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 28 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 29 * THE SOFTWARE. 30 * 31 * Author: Daniel Veillard 32 */ 33 34 /* 35 * Summary: XML Path Language implementation 36 * Description: API for the XML Path Language implementation 37 * 38 * XML Path Language implementation 39 * XPath is a language for addressing parts of an XML document, 40 * designed to be used by both XSLT and XPointer 41 * http://www.w3.org/TR/xpath 42 * 43 * Implements 44 * W3C Recommendation 16 November 1999 45 * http://www.w3.org/TR/1999/REC-xpath-19991116 46 */ 47 48 #ifndef __XML_XPATH_H__ 49 #define __XML_XPATH_H__ 50 51 #include <libxml/xmlversion.h> 52 53 #ifdef LIBXML_XPATH_ENABLED 54 55 #include <libxml/xmlerror.h> 56 #include <libxml/tree.h> 57 #include <libxml/hash.h> 58 #endif /* LIBXML_XPATH_ENABLED */ 59 60 #if defined(LIBXML_XPATH_ENABLED) || defined(LIBXML_SCHEMAS_ENABLED) 61 #ifdef __cplusplus 62 extern "C" { 63 #endif 64 #endif /* LIBXML_XPATH_ENABLED or LIBXML_SCHEMAS_ENABLED */ 65 66 #ifdef LIBXML_XPATH_ENABLED 67 68 typedef struct _xmlXPathContext xmlXPathContext; 69 typedef xmlXPathContext *xmlXPathContextPtr; 70 typedef struct _xmlXPathParserContext xmlXPathParserContext; 71 typedef xmlXPathParserContext *xmlXPathParserContextPtr; 72 73 /** 74 * The set of XPath error codes. 75 */ 76 77 typedef enum { 78 XPATH_EXPRESSION_OK = 0, 79 XPATH_NUMBER_ERROR, 80 XPATH_UNFINISHED_LITERAL_ERROR, 81 XPATH_START_LITERAL_ERROR, 82 XPATH_VARIABLE_REF_ERROR, 83 XPATH_UNDEF_VARIABLE_ERROR, 84 XPATH_INVALID_PREDICATE_ERROR, 85 XPATH_EXPR_ERROR, 86 XPATH_UNCLOSED_ERROR, 87 XPATH_UNKNOWN_FUNC_ERROR, 88 XPATH_INVALID_OPERAND, 89 XPATH_INVALID_TYPE, 90 XPATH_INVALID_ARITY, 91 XPATH_INVALID_CTXT_SIZE, 92 XPATH_INVALID_CTXT_POSITION, 93 XPATH_MEMORY_ERROR, 94 XPTR_SYNTAX_ERROR, 95 XPTR_RESOURCE_ERROR, 96 XPTR_SUB_RESOURCE_ERROR, 97 XPATH_UNDEF_PREFIX_ERROR, 98 XPATH_ENCODING_ERROR, 99 XPATH_INVALID_CHAR_ERROR, 100 XPATH_INVALID_CTXT, 101 XPATH_STACK_ERROR, 102 XPATH_FORBID_VARIABLE_ERROR 103 } xmlXPathError; 104 105 /* 106 * A node-set (an unordered collection of nodes without duplicates). 107 */ 108 typedef struct _xmlNodeSet xmlNodeSet; 109 typedef xmlNodeSet *xmlNodeSetPtr; 110 struct _xmlNodeSet { 111 int nodeNr; /* number of nodes in the set */ 112 int nodeMax; /* size of the array as allocated */ 113 xmlNodePtr *nodeTab; /* array of nodes in no particular order */ 114 /* @@ with_ns to check wether namespace nodes should be looked at @@ */ 115 }; 116 117 /* 118 * An expression is evaluated to yield an object, which 119 * has one of the following four basic types: 120 * - node-set 121 * - boolean 122 * - number 123 * - string 124 * 125 * @@ XPointer will add more types ! 126 */ 127 128 typedef enum { 129 XPATH_UNDEFINED = 0, 130 XPATH_NODESET = 1, 131 XPATH_BOOLEAN = 2, 132 XPATH_NUMBER = 3, 133 XPATH_STRING = 4, 134 XPATH_POINT = 5, 135 XPATH_RANGE = 6, 136 XPATH_LOCATIONSET = 7, 137 XPATH_USERS = 8, 138 XPATH_XSLT_TREE = 9 /* An XSLT value tree, non modifiable */ 139 } xmlXPathObjectType; 140 141 typedef struct _xmlXPathObject xmlXPathObject; 142 typedef xmlXPathObject *xmlXPathObjectPtr; 143 struct _xmlXPathObject { 144 xmlXPathObjectType type; 145 xmlNodeSetPtr nodesetval; 146 int boolval; 147 double floatval; 148 xmlChar *stringval; 149 void *user; 150 int index; 151 void *user2; 152 int index2; 153 }; 154 155 /** 156 * xmlXPathConvertFunc: 157 * @obj: an XPath object 158 * @type: the number of the target type 159 * 160 * A conversion function is associated to a type and used to cast 161 * the new type to primitive values. 162 * 163 * Returns -1 in case of error, 0 otherwise 164 */ 165 typedef int (*xmlXPathConvertFunc) (xmlXPathObjectPtr obj, int type); 166 167 /* 168 * Extra type: a name and a conversion function. 169 */ 170 171 typedef struct _xmlXPathType xmlXPathType; 172 typedef xmlXPathType *xmlXPathTypePtr; 173 struct _xmlXPathType { 174 const xmlChar *name; /* the type name */ 175 xmlXPathConvertFunc func; /* the conversion function */ 176 }; 177 178 /* 179 * Extra variable: a name and a value. 180 */ 181 182 typedef struct _xmlXPathVariable xmlXPathVariable; 183 typedef xmlXPathVariable *xmlXPathVariablePtr; 184 struct _xmlXPathVariable { 185 const xmlChar *name; /* the variable name */ 186 xmlXPathObjectPtr value; /* the value */ 187 }; 188 189 /** 190 * xmlXPathEvalFunc: 191 * @ctxt: an XPath parser context 192 * @nargs: the number of arguments passed to the function 193 * 194 * An XPath evaluation function, the parameters are on the XPath context stack. 195 */ 196 197 typedef void (*xmlXPathEvalFunc)(xmlXPathParserContextPtr ctxt, 198 int nargs); 199 200 /* 201 * Extra function: a name and a evaluation function. 202 */ 203 204 typedef struct _xmlXPathFunct xmlXPathFunct; 205 typedef xmlXPathFunct *xmlXPathFuncPtr; 206 struct _xmlXPathFunct { 207 const xmlChar *name; /* the function name */ 208 xmlXPathEvalFunc func; /* the evaluation function */ 209 }; 210 211 /** 212 * xmlXPathAxisFunc: 213 * @ctxt: the XPath interpreter context 214 * @cur: the previous node being explored on that axis 215 * 216 * An axis traversal function. To traverse an axis, the engine calls 217 * the first time with cur == NULL and repeat until the function returns 218 * NULL indicating the end of the axis traversal. 219 * 220 * Returns the next node in that axis or NULL if at the end of the axis. 221 */ 222 223 typedef xmlXPathObjectPtr (*xmlXPathAxisFunc) (xmlXPathParserContextPtr ctxt, 224 xmlXPathObjectPtr cur); 225 226 /* 227 * Extra axis: a name and an axis function. 228 */ 229 230 typedef struct _xmlXPathAxis xmlXPathAxis; 231 typedef xmlXPathAxis *xmlXPathAxisPtr; 232 struct _xmlXPathAxis { 233 const xmlChar *name; /* the axis name */ 234 xmlXPathAxisFunc func; /* the search function */ 235 }; 236 237 /** 238 * xmlXPathFunction: 239 * @ctxt: the XPath interprestation context 240 * @nargs: the number of arguments 241 * 242 * An XPath function. 243 * The arguments (if any) are popped out from the context stack 244 * and the result is pushed on the stack. 245 */ 246 247 typedef void (*xmlXPathFunction) (xmlXPathParserContextPtr ctxt, int nargs); 248 249 /* 250 * Function and Variable Lookup. 251 */ 252 253 /** 254 * xmlXPathVariableLookupFunc: 255 * @ctxt: an XPath context 256 * @name: name of the variable 257 * @ns_uri: the namespace name hosting this variable 258 * 259 * Prototype for callbacks used to plug variable lookup in the XPath 260 * engine. 261 * 262 * Returns the XPath object value or NULL if not found. 263 */ 264 typedef xmlXPathObjectPtr (*xmlXPathVariableLookupFunc) (void *ctxt, 265 const xmlChar *name, 266 const xmlChar *ns_uri); 267 268 /** 269 * xmlXPathFuncLookupFunc: 270 * @ctxt: an XPath context 271 * @name: name of the function 272 * @ns_uri: the namespace name hosting this function 273 * 274 * Prototype for callbacks used to plug function lookup in the XPath 275 * engine. 276 * 277 * Returns the XPath function or NULL if not found. 278 */ 279 typedef xmlXPathFunction (*xmlXPathFuncLookupFunc) (void *ctxt, 280 const xmlChar *name, 281 const xmlChar *ns_uri); 282 283 /** 284 * xmlXPathFlags: 285 * Flags for XPath engine compilation and runtime 286 */ 287 /** 288 * XML_XPATH_CHECKNS: 289 * 290 * check namespaces at compilation 291 */ 292 #define XML_XPATH_CHECKNS (1<<0) 293 /** 294 * XML_XPATH_NOVAR: 295 * 296 * forbid variables in expression 297 */ 298 #define XML_XPATH_NOVAR (1<<1) 299 300 /** 301 * xmlXPathContext: 302 * 303 * Expression evaluation occurs with respect to a context. 304 * he context consists of: 305 * - a node (the context node) 306 * - a node list (the context node list) 307 * - a set of variable bindings 308 * - a function library 309 * - the set of namespace declarations in scope for the expression 310 * Following the switch to hash tables, this need to be trimmed up at 311 * the next binary incompatible release. 312 * The node may be modified when the context is passed to libxml2 313 * for an XPath evaluation so you may need to initialize it again 314 * before the next call. 315 */ 316 317 struct _xmlXPathContext { 318 xmlDocPtr doc; /* The current document */ 319 xmlNodePtr node; /* The current node */ 320 321 int nb_variables_unused; /* unused (hash table) */ 322 int max_variables_unused; /* unused (hash table) */ 323 xmlHashTablePtr varHash; /* Hash table of defined variables */ 324 325 int nb_types; /* number of defined types */ 326 int max_types; /* max number of types */ 327 xmlXPathTypePtr types; /* Array of defined types */ 328 329 int nb_funcs_unused; /* unused (hash table) */ 330 int max_funcs_unused; /* unused (hash table) */ 331 xmlHashTablePtr funcHash; /* Hash table of defined funcs */ 332 333 int nb_axis; /* number of defined axis */ 334 int max_axis; /* max number of axis */ 335 xmlXPathAxisPtr axis; /* Array of defined axis */ 336 337 /* the namespace nodes of the context node */ 338 xmlNsPtr *namespaces; /* Array of namespaces */ 339 int nsNr; /* number of namespace in scope */ 340 void *user; /* function to free */ 341 342 /* extra variables */ 343 int contextSize; /* the context size */ 344 int proximityPosition; /* the proximity position */ 345 346 /* extra stuff for XPointer */ 347 int xptr; /* is this an XPointer context? */ 348 xmlNodePtr here; /* for here() */ 349 xmlNodePtr origin; /* for origin() */ 350 351 /* the set of namespace declarations in scope for the expression */ 352 xmlHashTablePtr nsHash; /* The namespaces hash table */ 353 xmlXPathVariableLookupFunc varLookupFunc;/* variable lookup func */ 354 void *varLookupData; /* variable lookup data */ 355 356 /* Possibility to link in an extra item */ 357 void *extra; /* needed for XSLT */ 358 359 /* The function name and URI when calling a function */ 360 const xmlChar *function; 361 const xmlChar *functionURI; 362 363 /* function lookup function and data */ 364 xmlXPathFuncLookupFunc funcLookupFunc;/* function lookup func */ 365 void *funcLookupData; /* function lookup data */ 366 367 /* temporary namespace lists kept for walking the namespace axis */ 368 xmlNsPtr *tmpNsList; /* Array of namespaces */ 369 int tmpNsNr; /* number of namespaces in scope */ 370 371 /* error reporting mechanism */ 372 void *userData; /* user specific data block */ 373 xmlStructuredErrorFunc error; /* the callback in case of errors */ 374 xmlError lastError; /* the last error */ 375 xmlNodePtr debugNode; /* the source node XSLT */ 376 377 /* dictionary */ 378 xmlDictPtr dict; /* dictionary if any */ 379 380 int flags; /* flags to control compilation */ 381 382 /* Cache for reusal of XPath objects */ 383 void *cache; 384 }; 385 386 /* 387 * The structure of a compiled expression form is not public. 388 */ 389 390 typedef struct _xmlXPathCompExpr xmlXPathCompExpr; 391 typedef xmlXPathCompExpr *xmlXPathCompExprPtr; 392 393 /** 394 * xmlXPathParserContext: 395 * 396 * An XPath parser context. It contains pure parsing informations, 397 * an xmlXPathContext, and the stack of objects. 398 */ 399 struct _xmlXPathParserContext { 400 const xmlChar *cur; /* the current char being parsed */ 401 const xmlChar *base; /* the full expression */ 402 403 int error; /* error code */ 404 405 xmlXPathContextPtr context; /* the evaluation context */ 406 xmlXPathObjectPtr value; /* the current value */ 407 int valueNr; /* number of values stacked */ 408 int valueMax; /* max number of values stacked */ 409 xmlXPathObjectPtr *valueTab; /* stack of values */ 410 411 xmlXPathCompExprPtr comp; /* the precompiled expression */ 412 int xptr; /* it this an XPointer expression */ 413 xmlNodePtr ancestor; /* used for walking preceding axis */ 414 415 int valueFrame; /* used to limit Pop on the stack */ 416 }; 417 418 /************************************************************************ 419 * * 420 * Public API * 421 * * 422 ************************************************************************/ 423 424 /** 425 * Objects and Nodesets handling 426 */ 427 428 XMLPUBVAR double xmlXPathNAN; 429 XMLPUBVAR double xmlXPathPINF; 430 XMLPUBVAR double xmlXPathNINF; 431 432 /* These macros may later turn into functions */ 433 /** 434 * xmlXPathNodeSetGetLength: 435 * @ns: a node-set 436 * 437 * Implement a functionality similar to the DOM NodeList.length. 438 * 439 * Returns the number of nodes in the node-set. 440 */ 441 #define xmlXPathNodeSetGetLength(ns) ((ns) ? (ns)->nodeNr : 0) 442 /** 443 * xmlXPathNodeSetItem: 444 * @ns: a node-set 445 * @index: index of a node in the set 446 * 447 * Implements a functionality similar to the DOM NodeList.item(). 448 * 449 * Returns the xmlNodePtr at the given @index in @ns or NULL if 450 * @index is out of range (0 to length-1) 451 */ 452 #define xmlXPathNodeSetItem(ns, index) \ 453 ((((ns) != NULL) && \ 454 ((index) >= 0) && ((index) < (ns)->nodeNr)) ? \ 455 (ns)->nodeTab[(index)] \ 456 : NULL) 457 /** 458 * xmlXPathNodeSetIsEmpty: 459 * @ns: a node-set 460 * 461 * Checks whether @ns is empty or not. 462 * 463 * Returns %TRUE if @ns is an empty node-set. 464 */ 465 #define xmlXPathNodeSetIsEmpty(ns) \ 466 (((ns) == NULL) || ((ns)->nodeNr == 0) || ((ns)->nodeTab == NULL)) 467 468 469 XMLPUBFUN void XMLCALL 470 xmlXPathFreeObject (xmlXPathObjectPtr obj); 471 XMLPUBFUN xmlNodeSetPtr XMLCALL 472 xmlXPathNodeSetCreate (xmlNodePtr val); 473 XMLPUBFUN void XMLCALL 474 xmlXPathFreeNodeSetList (xmlXPathObjectPtr obj); 475 XMLPUBFUN void XMLCALL 476 xmlXPathFreeNodeSet (xmlNodeSetPtr obj); 477 XMLPUBFUN xmlXPathObjectPtr XMLCALL 478 xmlXPathObjectCopy (xmlXPathObjectPtr val); 479 XMLPUBFUN int XMLCALL 480 xmlXPathCmpNodes (xmlNodePtr node1, 481 xmlNodePtr node2); 482 /** 483 * Conversion functions to basic types. 484 */ 485 XMLPUBFUN int XMLCALL 486 xmlXPathCastNumberToBoolean (double val); 487 XMLPUBFUN int XMLCALL 488 xmlXPathCastStringToBoolean (const xmlChar * val); 489 XMLPUBFUN int XMLCALL 490 xmlXPathCastNodeSetToBoolean(xmlNodeSetPtr ns); 491 XMLPUBFUN int XMLCALL 492 xmlXPathCastToBoolean (xmlXPathObjectPtr val); 493 494 XMLPUBFUN double XMLCALL 495 xmlXPathCastBooleanToNumber (int val); 496 XMLPUBFUN double XMLCALL 497 xmlXPathCastStringToNumber (const xmlChar * val); 498 XMLPUBFUN double XMLCALL 499 xmlXPathCastNodeToNumber (xmlNodePtr node); 500 XMLPUBFUN double XMLCALL 501 xmlXPathCastNodeSetToNumber (xmlNodeSetPtr ns); 502 XMLPUBFUN double XMLCALL 503 xmlXPathCastToNumber (xmlXPathObjectPtr val); 504 505 XMLPUBFUN xmlChar * XMLCALL 506 xmlXPathCastBooleanToString (int val); 507 XMLPUBFUN xmlChar * XMLCALL 508 xmlXPathCastNumberToString (double val); 509 XMLPUBFUN xmlChar * XMLCALL 510 xmlXPathCastNodeToString (xmlNodePtr node); 511 XMLPUBFUN xmlChar * XMLCALL 512 xmlXPathCastNodeSetToString (xmlNodeSetPtr ns); 513 XMLPUBFUN xmlChar * XMLCALL 514 xmlXPathCastToString (xmlXPathObjectPtr val); 515 516 XMLPUBFUN xmlXPathObjectPtr XMLCALL 517 xmlXPathConvertBoolean (xmlXPathObjectPtr val); 518 XMLPUBFUN xmlXPathObjectPtr XMLCALL 519 xmlXPathConvertNumber (xmlXPathObjectPtr val); 520 XMLPUBFUN xmlXPathObjectPtr XMLCALL 521 xmlXPathConvertString (xmlXPathObjectPtr val); 522 523 /** 524 * Context handling. 525 */ 526 XMLPUBFUN xmlXPathContextPtr XMLCALL 527 xmlXPathNewContext (xmlDocPtr doc); 528 XMLPUBFUN void XMLCALL 529 xmlXPathFreeContext (xmlXPathContextPtr ctxt); 530 XMLPUBFUN int XMLCALL 531 xmlXPathContextSetCache(xmlXPathContextPtr ctxt, 532 int active, 533 int value, 534 int options); 535 /** 536 * Evaluation functions. 537 */ 538 XMLPUBFUN long XMLCALL 539 xmlXPathOrderDocElems (xmlDocPtr doc); 540 XMLPUBFUN int XMLCALL 541 xmlXPathSetContextNode (xmlNodePtr node, 542 xmlXPathContextPtr ctx); 543 XMLPUBFUN xmlXPathObjectPtr XMLCALL 544 xmlXPathNodeEval (xmlNodePtr node, 545 const xmlChar *str, 546 xmlXPathContextPtr ctx); 547 XMLPUBFUN xmlXPathObjectPtr XMLCALL 548 xmlXPathEval (const xmlChar *str, 549 xmlXPathContextPtr ctx); 550 XMLPUBFUN xmlXPathObjectPtr XMLCALL 551 xmlXPathEvalExpression (const xmlChar *str, 552 xmlXPathContextPtr ctxt); 553 XMLPUBFUN int XMLCALL 554 xmlXPathEvalPredicate (xmlXPathContextPtr ctxt, 555 xmlXPathObjectPtr res); 556 /** 557 * Separate compilation/evaluation entry points. 558 */ 559 XMLPUBFUN xmlXPathCompExprPtr XMLCALL 560 xmlXPathCompile (const xmlChar *str); 561 XMLPUBFUN xmlXPathCompExprPtr XMLCALL 562 xmlXPathCtxtCompile (xmlXPathContextPtr ctxt, 563 const xmlChar *str); 564 XMLPUBFUN xmlXPathObjectPtr XMLCALL 565 xmlXPathCompiledEval (xmlXPathCompExprPtr comp, 566 xmlXPathContextPtr ctx); 567 XMLPUBFUN int XMLCALL 568 xmlXPathCompiledEvalToBoolean(xmlXPathCompExprPtr comp, 569 xmlXPathContextPtr ctxt); 570 XMLPUBFUN void XMLCALL 571 xmlXPathFreeCompExpr (xmlXPathCompExprPtr comp); 572 #endif /* LIBXML_XPATH_ENABLED */ 573 #if defined(LIBXML_XPATH_ENABLED) || defined(LIBXML_SCHEMAS_ENABLED) 574 XMLPUBFUN void XMLCALL 575 xmlXPathInit (void); 576 XMLPUBFUN int XMLCALL 577 xmlXPathIsNaN (double val); 578 XMLPUBFUN int XMLCALL 579 xmlXPathIsInf (double val); 580 581 #ifdef __cplusplus 582 } 583 #endif 584 585 #endif /* LIBXML_XPATH_ENABLED or LIBXML_SCHEMAS_ENABLED*/ 586 #endif /* ! __XML_XPATH_H__ */ 587