src/third_party/libxml/src/include/libxml/xpath.h

   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__ */