libxml2/include/libxml/xpath.h

   1 /*
   2  * xpath.c: interface for XML Path Language implementation
   3  *
   4  * Reference: W3C Working Draft 5 July 1999
   5  *            http://www.w3.org/Style/XSL/Group/1999/07/xpath-19990705.html
   6  *
   7  * See COPYRIGHT for the status of this software
   8  *
   9  * Author: daniel@veillard.com
  10  */
  11
  12 #ifndef __XML_XPATH_H__
  13 #define __XML_XPATH_H__
  14
  15 #include <libxml/tree.h>
  16 #include <libxml/hash.h>
  17
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21
  22 typedef struct _xmlXPathContext xmlXPathContext;
  23 typedef xmlXPathContext *xmlXPathContextPtr;
  24 typedef struct _xmlXPathParserContext xmlXPathParserContext;
  25 typedef xmlXPathParserContext *xmlXPathParserContextPtr;
  26
  27 /**
  28  * The set of XPath error codes.
  29  */
  30
  31 typedef enum {
  32     XPATH_EXPRESSION_OK = 0,
  33     XPATH_NUMBER_ERROR,
  34     XPATH_UNFINISHED_LITERAL_ERROR,
  35     XPATH_START_LITERAL_ERROR,
  36     XPATH_VARIABLE_REF_ERROR,
  37     XPATH_UNDEF_VARIABLE_ERROR,
  38     XPATH_INVALID_PREDICATE_ERROR,
  39     XPATH_EXPR_ERROR,
  40     XPATH_UNCLOSED_ERROR,
  41     XPATH_UNKNOWN_FUNC_ERROR,
  42     XPATH_INVALID_OPERAND,
  43     XPATH_INVALID_TYPE,
  44     XPATH_INVALID_ARITY,
  45     XPATH_INVALID_CTXT_SIZE,
  46     XPATH_INVALID_CTXT_POSITION,
  47     XPATH_MEMORY_ERROR,
  48     XPTR_SYNTAX_ERROR,
  49     XPTR_RESOURCE_ERROR,
  50     XPTR_SUB_RESOURCE_ERROR,
  51     XPATH_UNDEF_PREFIX_ERROR,
  52     XPATH_ENCODING_ERROR,
  53     XPATH_INVALID_CHAR_ERROR
  54 } xmlXPathError;
  55
  56 /*
  57  * A node-set (an unordered collection of nodes without duplicates).
  58  */
  59 typedef struct _xmlNodeSet xmlNodeSet;
  60 typedef xmlNodeSet *xmlNodeSetPtr;
  61 struct _xmlNodeSet {
  62     int nodeNr;                 /* number of nodes in the set */
  63     int nodeMax;                /* size of the array as allocated */
  64     xmlNodePtr *nodeTab;        /* array of nodes in no particular order */
  65     /* @@ with_ns to check wether namespace nodes should be looked at @@ */
  66 };
  67
  68 /*
  69  * An expression is evaluated to yield an object, which
  70  * has one of the following four basic types:
  71  *   - node-set
  72  *   - boolean
  73  *   - number
  74  *   - string
  75  *
  76  * @@ XPointer will add more types !
  77  */
  78
  79 typedef enum {
  80     XPATH_UNDEFINED = 0,
  81     XPATH_NODESET = 1,
  82     XPATH_BOOLEAN = 2,
  83     XPATH_NUMBER = 3,
  84     XPATH_STRING = 4,
  85     XPATH_POINT = 5,
  86     XPATH_RANGE = 6,
  87     XPATH_LOCATIONSET = 7,
  88     XPATH_USERS = 8,
  89     XPATH_XSLT_TREE = 9  /* An XSLT value tree, non modifiable */
  90 } xmlXPathObjectType;
  91
  92 typedef struct _xmlXPathObject xmlXPathObject;
  93 typedef xmlXPathObject *xmlXPathObjectPtr;
  94 struct _xmlXPathObject {
  95     xmlXPathObjectType type;
  96     xmlNodeSetPtr nodesetval;
  97     int boolval;
  98     double floatval;
  99     xmlChar *stringval;
 100     void *user;
 101     int index;
 102     void *user2;
 103     int index2;
 104 };
 105
 106 /**
 107  * xmlXPathConvertFunc:
 108  * @obj:  an XPath object
 109  * @type:  the number of the target type
 110  *
 111  * A conversion function is associated to a type and used to cast
 112  * the new type to primitive values.
 113  *
 114  * Returns -1 in case of error, 0 otherwise
 115  */
 116 typedef int (*xmlXPathConvertFunc) (xmlXPathObjectPtr obj, int type);
 117
 118 /*
 119  * Extra type: a name and a conversion function.
 120  */
 121
 122 typedef struct _xmlXPathType xmlXPathType;
 123 typedef xmlXPathType *xmlXPathTypePtr;
 124 struct _xmlXPathType {
 125     const xmlChar         *name;                /* the type name */
 126     xmlXPathConvertFunc func;           /* the conversion function */
 127 };
 128
 129 /*
 130  * Extra variable: a name and a value.
 131  */
 132
 133 typedef struct _xmlXPathVariable xmlXPathVariable;
 134 typedef xmlXPathVariable *xmlXPathVariablePtr;
 135 struct _xmlXPathVariable {
 136     const xmlChar       *name;          /* the variable name */
 137     xmlXPathObjectPtr value;            /* the value */
 138 };
 139
 140 /**
 141  * xmlXPathEvalFunc:
 142  * @ctxt: an XPath parser context
 143  * @nargs: the number of arguments passed to the function
 144  *
 145  * An XPath evaluation function, the parameters are on the XPath context stack.
 146  */
 147
 148 typedef void (*xmlXPathEvalFunc)(xmlXPathParserContextPtr ctxt,
 149                                  int nargs);
 150
 151 /*
 152  * Extra function: a name and a evaluation function.
 153  */
 154
 155 typedef struct _xmlXPathFunct xmlXPathFunct;
 156 typedef xmlXPathFunct *xmlXPathFuncPtr;
 157 struct _xmlXPathFunct {
 158     const xmlChar      *name;           /* the function name */
 159     xmlXPathEvalFunc func;              /* the evaluation function */
 160 };
 161
 162 /**
 163  * xmlXPathAxisFunc:
 164  * @ctxt:  the XPath interpreter context
 165  * @cur:  the previous node being explored on that axis
 166  *
 167  * An axis traversal function. To traverse an axis, the engine calls
 168  * the first time with cur == NULL and repeat until the function returns
 169  * NULL indicating the end of the axis traversal.
 170  *
 171  * Returns the next node in that axis or NULL if at the end of the axis.
 172  */
 173
 174 typedef xmlXPathObjectPtr (*xmlXPathAxisFunc) (xmlXPathParserContextPtr ctxt,
 175                                  xmlXPathObjectPtr cur);
 176
 177 /*
 178  * Extra axis: a name and an axis function.
 179  */
 180
 181 typedef struct _xmlXPathAxis xmlXPathAxis;
 182 typedef xmlXPathAxis *xmlXPathAxisPtr;
 183 struct _xmlXPathAxis {
 184     const xmlChar      *name;           /* the axis name */
 185     xmlXPathAxisFunc func;              /* the search function */
 186 };
 187
 188 /**
 189  * xmlXPathContext:
 190  *
 191  * Expression evaluation occurs with respect to a context.
 192  * he context consists of:
 193  *    - a node (the context node)
 194  *    - a node list (the context node list)
 195  *    - a set of variable bindings
 196  *    - a function library
 197  *    - the set of namespace declarations in scope for the expression
 198  * Following the switch to hash tables, this need to be trimmed up at
 199  * the next binary incompatible release.
 200  */
 201
 202 struct _xmlXPathContext {
 203     xmlDocPtr doc;                      /* The current document */
 204     xmlNodePtr node;                    /* The current node */
 205
 206     int nb_variables_unused;            /* unused (hash table) */
 207     int max_variables_unused;           /* unused (hash table) */
 208     xmlHashTablePtr varHash;            /* Hash table of defined variables */
 209
 210     int nb_types;                       /* number of defined types */
 211     int max_types;                      /* max number of types */
 212     xmlXPathTypePtr types;              /* Array of defined types */
 213
 214     int nb_funcs_unused;                /* unused (hash table) */
 215     int max_funcs_unused;               /* unused (hash table) */
 216     xmlHashTablePtr funcHash;           /* Hash table of defined funcs */
 217
 218     int nb_axis;                        /* number of defined axis */
 219     int max_axis;                       /* max number of axis */
 220     xmlXPathAxisPtr axis;               /* Array of defined axis */
 221
 222     /* the namespace nodes of the context node */
 223     xmlNsPtr *namespaces;               /* Array of namespaces */
 224     int nsNr;                           /* number of namespace in scope */
 225     void *user;                         /* function to free */
 226
 227     /* extra variables */
 228     int contextSize;                    /* the context size */
 229     int proximityPosition;              /* the proximity position */
 230
 231     /* extra stuff for XPointer */
 232     int xptr;                           /* it this an XPointer context */
 233     xmlNodePtr here;                    /* for here() */
 234     xmlNodePtr origin;                  /* for origin() */
 235
 236     /* the set of namespace declarations in scope for the expression */
 237     xmlHashTablePtr nsHash;             /* The namespaces hash table */
 238     void *varLookupFunc;                /* variable lookup func */
 239     void *varLookupData;                /* variable lookup data */
 240
 241     /* Possibility to link in an extra item */
 242     void *extra;                        /* needed for XSLT */
 243
 244     /* The function name and URI when calling a function */
 245     const xmlChar *function;
 246     const xmlChar *functionURI;
 247
 248     /* function lookup function and data */
 249     void *funcLookupFunc;               /* function lookup func */
 250     void *funcLookupData;               /* function lookup data */
 251
 252     /* temporary namespace lists kept for walking the namespace axis */
 253     xmlNsPtr *tmpNsList;                /* Array of namespaces */
 254     int tmpNsNr;                        /* number of namespace in scope */
 255 };
 256
 257 /*
 258  * The structure of a compiled expression form is not public.
 259  */
 260
 261 typedef struct _xmlXPathCompExpr xmlXPathCompExpr;
 262 typedef xmlXPathCompExpr *xmlXPathCompExprPtr;
 263
 264 /**
 265  * xmlXPathParserContext:
 266  *
 267  * An XPath parser context. It contains pure parsing informations,
 268  * an xmlXPathContext, and the stack of objects.
 269  */
 270 struct _xmlXPathParserContext {
 271     const xmlChar *cur;                 /* the current char being parsed */
 272     const xmlChar *base;                        /* the full expression */
 273
 274     int error;                          /* error code */
 275
 276     xmlXPathContextPtr  context;        /* the evaluation context */
 277     xmlXPathObjectPtr     value;        /* the current value */
 278     int                 valueNr;        /* number of values stacked */
 279     int                valueMax;        /* max number of values stacked */
 280     xmlXPathObjectPtr *valueTab;        /* stack of values */
 281
 282     xmlXPathCompExprPtr comp;           /* the precompiled expression */
 283     int xptr;                           /* it this an XPointer expression */
 284     xmlNodePtr         ancestor;        /* used for walking preceding axis */
 285 };
 286
 287 /**
 288  * xmlXPathFunction:
 289  * @ctxt:  the XPath interprestation context
 290  * @nargs:  the number of arguments
 291  *
 292  * An XPath function.
 293  * The arguments (if any) are popped out from the context stack
 294  * and the result is pushed on the stack.
 295  */
 296
 297 typedef void (*xmlXPathFunction) (xmlXPathParserContextPtr ctxt, int nargs);
 298
 299 /************************************************************************
 300  *                                                                      *
 301  *                      Public API                                      *
 302  *                                                                      *
 303  ************************************************************************/
 304
 305 /**
 306  * Objects and Nodesets handling
 307  */
 308
 309 LIBXML_DLL_IMPORT extern double xmlXPathNAN;
 310 LIBXML_DLL_IMPORT extern double xmlXPathPINF;
 311 LIBXML_DLL_IMPORT extern double xmlXPathNINF;
 312
 313 int             xmlXPathIsNaN   (double val);
 314 int             xmlXPathIsInf   (double val);
 315
 316 /* These macros may later turn into functions */
 317 /**
 318  * xmlXPathNodeSetGetLength:
 319  * @ns:  a node-set
 320  *
 321  * Implement a functionality similar to the DOM NodeList.length.
 322  *
 323  * Returns the number of nodes in the node-set.
 324  */
 325 #define xmlXPathNodeSetGetLength(ns) ((ns) ? (ns)->nodeNr : 0)
 326 /**
 327  * xmlXPathNodeSetItem:
 328  * @ns:  a node-set
 329  * @index:  index of a node in the set
 330  *
 331  * Implements a functionality similar to the DOM NodeList.item().
 332  *
 333  * Returns the xmlNodePtr at the given @index in @ns or NULL if
 334  *         @index is out of range (0 to length-1)
 335  */
 336 #define xmlXPathNodeSetItem(ns, index)                          \
 337                 ((((ns) != NULL) &&                             \
 338                   ((index) >= 0) && ((index) < (ns)->nodeNr)) ? \
 339                  (ns)->nodeTab[(index)]                         \
 340                  : NULL)
 341 /**
 342  * xmlXPathNodeSetIsEmpty:
 343  * @ns: a node-set
 344  *
 345  * Checks whether @ns is empty or not.
 346  *
 347  * Returns %TRUE if @ns is an empty node-set.
 348  */
 349 #define xmlXPathNodeSetIsEmpty(ns)                                      \
 350     (((ns) == NULL) || ((ns)->nodeNr == 0) || ((ns)->nodeTab == NULL))
 351
 352
 353 void               xmlXPathFreeObject           (xmlXPathObjectPtr obj);
 354 xmlNodeSetPtr      xmlXPathNodeSetCreate        (xmlNodePtr val);
 355 void               xmlXPathFreeNodeSetList      (xmlXPathObjectPtr obj);
 356 void               xmlXPathFreeNodeSet          (xmlNodeSetPtr obj);
 357 xmlXPathObjectPtr  xmlXPathObjectCopy           (xmlXPathObjectPtr val);
 358 int                xmlXPathCmpNodes             (xmlNodePtr node1,
 359                                                  xmlNodePtr node2);
 360 /**
 361  * Conversion functions to basic types.
 362  */
 363 int                xmlXPathCastNumberToBoolean  (double val);
 364 int                xmlXPathCastStringToBoolean  (const xmlChar * val);
 365 int                xmlXPathCastNodeSetToBoolean (xmlNodeSetPtr ns);
 366 int                xmlXPathCastToBoolean        (xmlXPathObjectPtr val);
 367
 368 double             xmlXPathCastBooleanToNumber  (int val);
 369 double             xmlXPathCastStringToNumber   (const xmlChar * val);
 370 double             xmlXPathCastNodeToNumber     (xmlNodePtr node);
 371 double             xmlXPathCastNodeSetToNumber  (xmlNodeSetPtr ns);
 372 double             xmlXPathCastToNumber         (xmlXPathObjectPtr val);
 373
 374 xmlChar *          xmlXPathCastBooleanToString  (int val);
 375 xmlChar *          xmlXPathCastNumberToString   (double val);
 376 xmlChar *          xmlXPathCastNodeToString     (xmlNodePtr node);
 377 xmlChar *          xmlXPathCastNodeSetToString  (xmlNodeSetPtr ns);
 378 xmlChar *          xmlXPathCastToString         (xmlXPathObjectPtr val);
 379
 380 xmlXPathObjectPtr  xmlXPathConvertBoolean       (xmlXPathObjectPtr val);
 381 xmlXPathObjectPtr  xmlXPathConvertNumber        (xmlXPathObjectPtr val);
 382 xmlXPathObjectPtr  xmlXPathConvertString        (xmlXPathObjectPtr val);
 383
 384 /**
 385  * Context handling.
 386  */
 387 void               xmlXPathInit                 (void);
 388 xmlXPathContextPtr xmlXPathNewContext           (xmlDocPtr doc);
 389 void               xmlXPathFreeContext          (xmlXPathContextPtr ctxt);
 390
 391 /**
 392  * Evaluation functions.
 393  */
 394 long               xmlXPathOrderDocElems        (xmlDocPtr doc);
 395 xmlXPathObjectPtr  xmlXPathEval                 (const xmlChar *str,
 396                                                  xmlXPathContextPtr ctx);
 397 xmlXPathObjectPtr  xmlXPathEvalExpression       (const xmlChar *str,
 398                                                  xmlXPathContextPtr ctxt);
 399 int                xmlXPathEvalPredicate        (xmlXPathContextPtr ctxt,
 400                                                  xmlXPathObjectPtr res);
 401 /**
 402  * Separate compilation/evaluation entry points.
 403  */
 404 xmlXPathCompExprPtr xmlXPathCompile             (const xmlChar *str);
 405 xmlXPathObjectPtr   xmlXPathCompiledEval        (xmlXPathCompExprPtr comp,
 406                                                  xmlXPathContextPtr ctx);
 407 void                xmlXPathFreeCompExpr        (xmlXPathCompExprPtr comp);
 408 #ifdef __cplusplus
 409 }
 410 #endif
 411 #endif /* ! __XML_XPATH_H__ */