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