libxml2/libxml/xpath.h

0001 /*
0002  * Summary: XML Path Language implementation
0003  * Description: API for the XML Path Language implementation
0004  *
0005  * XML Path Language implementation
0006  * XPath is a language for addressing parts of an XML document,
0007  * designed to be used by both XSLT and XPointer
0008  *     http://www.w3.org/TR/xpath
0009  *
0010  * Implements
0011  * W3C Recommendation 16 November 1999
0012  *     http://www.w3.org/TR/1999/REC-xpath-19991116
0013  *
0014  * Copy: See Copyright for the status of this software.
0015  *
0016  * Author: Daniel Veillard
0017  */
0018
0019 #ifndef __XML_XPATH_H__
0020 #define __XML_XPATH_H__
0021
0022 #include <libxml/xmlversion.h>
0023
0024 #ifdef LIBXML_XPATH_ENABLED
0025
0026 #include <libxml/xmlerror.h>
0027 #include <libxml/tree.h>
0028 #include <libxml/hash.h>
0029 #endif /* LIBXML_XPATH_ENABLED */
0030
0031 #if defined(LIBXML_XPATH_ENABLED) || defined(LIBXML_SCHEMAS_ENABLED)
0032 #ifdef __cplusplus
0033 extern "C" {
0034 #endif
0035 #endif /* LIBXML_XPATH_ENABLED or LIBXML_SCHEMAS_ENABLED */
0036
0037 #ifdef LIBXML_XPATH_ENABLED
0038
0039 typedef struct _xmlXPathContext xmlXPathContext;
0040 typedef xmlXPathContext *xmlXPathContextPtr;
0041 typedef struct _xmlXPathParserContext xmlXPathParserContext;
0042 typedef xmlXPathParserContext *xmlXPathParserContextPtr;
0043
0044 /**
0045  * The set of XPath error codes.
0046  */
0047
0048 typedef enum {
0049     XPATH_EXPRESSION_OK = 0,
0050     XPATH_NUMBER_ERROR,
0051     XPATH_UNFINISHED_LITERAL_ERROR,
0052     XPATH_START_LITERAL_ERROR,
0053     XPATH_VARIABLE_REF_ERROR,
0054     XPATH_UNDEF_VARIABLE_ERROR,
0055     XPATH_INVALID_PREDICATE_ERROR,
0056     XPATH_EXPR_ERROR,
0057     XPATH_UNCLOSED_ERROR,
0058     XPATH_UNKNOWN_FUNC_ERROR,
0059     XPATH_INVALID_OPERAND,
0060     XPATH_INVALID_TYPE,
0061     XPATH_INVALID_ARITY,
0062     XPATH_INVALID_CTXT_SIZE,
0063     XPATH_INVALID_CTXT_POSITION,
0064     XPATH_MEMORY_ERROR,
0065     XPTR_SYNTAX_ERROR,
0066     XPTR_RESOURCE_ERROR,
0067     XPTR_SUB_RESOURCE_ERROR,
0068     XPATH_UNDEF_PREFIX_ERROR,
0069     XPATH_ENCODING_ERROR,
0070     XPATH_INVALID_CHAR_ERROR,
0071     XPATH_INVALID_CTXT,
0072     XPATH_STACK_ERROR,
0073     XPATH_FORBID_VARIABLE_ERROR,
0074     XPATH_OP_LIMIT_EXCEEDED,
0075     XPATH_RECURSION_LIMIT_EXCEEDED
0076 } xmlXPathError;
0077
0078 /*
0079  * A node-set (an unordered collection of nodes without duplicates).
0080  */
0081 typedef struct _xmlNodeSet xmlNodeSet;
0082 typedef xmlNodeSet *xmlNodeSetPtr;
0083 struct _xmlNodeSet {
0084     int nodeNr;         /* number of nodes in the set */
0085     int nodeMax;        /* size of the array as allocated */
0086     xmlNodePtr *nodeTab;    /* array of nodes in no particular order */
0087     /* @@ with_ns to check whether namespace nodes should be looked at @@ */
0088 };
0089
0090 /*
0091  * An expression is evaluated to yield an object, which
0092  * has one of the following four basic types:
0093  *   - node-set
0094  *   - boolean
0095  *   - number
0096  *   - string
0097  *
0098  * @@ XPointer will add more types !
0099  */
0100
0101 typedef enum {
0102     XPATH_UNDEFINED = 0,
0103     XPATH_NODESET = 1,
0104     XPATH_BOOLEAN = 2,
0105     XPATH_NUMBER = 3,
0106     XPATH_STRING = 4,
0107 #ifdef LIBXML_XPTR_LOCS_ENABLED
0108     XPATH_POINT = 5,
0109     XPATH_RANGE = 6,
0110     XPATH_LOCATIONSET = 7,
0111 #endif
0112     XPATH_USERS = 8,
0113     XPATH_XSLT_TREE = 9  /* An XSLT value tree, non modifiable */
0114 } xmlXPathObjectType;
0115
0116 #ifndef LIBXML_XPTR_LOCS_ENABLED
0117 /** DOC_DISABLE */
0118 #define XPATH_POINT 5
0119 #define XPATH_RANGE 6
0120 #define XPATH_LOCATIONSET 7
0121 /** DOC_ENABLE */
0122 #endif
0123
0124 typedef struct _xmlXPathObject xmlXPathObject;
0125 typedef xmlXPathObject *xmlXPathObjectPtr;
0126 struct _xmlXPathObject {
0127     xmlXPathObjectType type;
0128     xmlNodeSetPtr nodesetval;
0129     int boolval;
0130     double floatval;
0131     xmlChar *stringval;
0132     void *user;
0133     int index;
0134     void *user2;
0135     int index2;
0136 };
0137
0138 /**
0139  * xmlXPathConvertFunc:
0140  * @obj:  an XPath object
0141  * @type:  the number of the target type
0142  *
0143  * A conversion function is associated to a type and used to cast
0144  * the new type to primitive values.
0145  *
0146  * Returns -1 in case of error, 0 otherwise
0147  */
0148 typedef int (*xmlXPathConvertFunc) (xmlXPathObjectPtr obj, int type);
0149
0150 /*
0151  * Extra type: a name and a conversion function.
0152  */
0153
0154 typedef struct _xmlXPathType xmlXPathType;
0155 typedef xmlXPathType *xmlXPathTypePtr;
0156 struct _xmlXPathType {
0157     const xmlChar         *name;        /* the type name */
0158     xmlXPathConvertFunc func;       /* the conversion function */
0159 };
0160
0161 /*
0162  * Extra variable: a name and a value.
0163  */
0164
0165 typedef struct _xmlXPathVariable xmlXPathVariable;
0166 typedef xmlXPathVariable *xmlXPathVariablePtr;
0167 struct _xmlXPathVariable {
0168     const xmlChar       *name;      /* the variable name */
0169     xmlXPathObjectPtr value;        /* the value */
0170 };
0171
0172 /**
0173  * xmlXPathEvalFunc:
0174  * @ctxt: an XPath parser context
0175  * @nargs: the number of arguments passed to the function
0176  *
0177  * An XPath evaluation function, the parameters are on the XPath context stack.
0178  */
0179
0180 typedef void (*xmlXPathEvalFunc)(xmlXPathParserContextPtr ctxt,
0181                              int nargs);
0182
0183 /*
0184  * Extra function: a name and a evaluation function.
0185  */
0186
0187 typedef struct _xmlXPathFunct xmlXPathFunct;
0188 typedef xmlXPathFunct *xmlXPathFuncPtr;
0189 struct _xmlXPathFunct {
0190     const xmlChar      *name;       /* the function name */
0191     xmlXPathEvalFunc func;      /* the evaluation function */
0192 };
0193
0194 /**
0195  * xmlXPathAxisFunc:
0196  * @ctxt:  the XPath interpreter context
0197  * @cur:  the previous node being explored on that axis
0198  *
0199  * An axis traversal function. To traverse an axis, the engine calls
0200  * the first time with cur == NULL and repeat until the function returns
0201  * NULL indicating the end of the axis traversal.
0202  *
0203  * Returns the next node in that axis or NULL if at the end of the axis.
0204  */
0205
0206 typedef xmlXPathObjectPtr (*xmlXPathAxisFunc) (xmlXPathParserContextPtr ctxt,
0207                  xmlXPathObjectPtr cur);
0208
0209 /*
0210  * Extra axis: a name and an axis function.
0211  */
0212
0213 typedef struct _xmlXPathAxis xmlXPathAxis;
0214 typedef xmlXPathAxis *xmlXPathAxisPtr;
0215 struct _xmlXPathAxis {
0216     const xmlChar      *name;       /* the axis name */
0217     xmlXPathAxisFunc func;      /* the search function */
0218 };
0219
0220 /**
0221  * xmlXPathFunction:
0222  * @ctxt:  the XPath interprestation context
0223  * @nargs:  the number of arguments
0224  *
0225  * An XPath function.
0226  * The arguments (if any) are popped out from the context stack
0227  * and the result is pushed on the stack.
0228  */
0229
0230 typedef void (*xmlXPathFunction) (xmlXPathParserContextPtr ctxt, int nargs);
0231
0232 /*
0233  * Function and Variable Lookup.
0234  */
0235
0236 /**
0237  * xmlXPathVariableLookupFunc:
0238  * @ctxt:  an XPath context
0239  * @name:  name of the variable
0240  * @ns_uri:  the namespace name hosting this variable
0241  *
0242  * Prototype for callbacks used to plug variable lookup in the XPath
0243  * engine.
0244  *
0245  * Returns the XPath object value or NULL if not found.
0246  */
0247 typedef xmlXPathObjectPtr (*xmlXPathVariableLookupFunc) (void *ctxt,
0248                                          const xmlChar *name,
0249                                          const xmlChar *ns_uri);
0250
0251 /**
0252  * xmlXPathFuncLookupFunc:
0253  * @ctxt:  an XPath context
0254  * @name:  name of the function
0255  * @ns_uri:  the namespace name hosting this function
0256  *
0257  * Prototype for callbacks used to plug function lookup in the XPath
0258  * engine.
0259  *
0260  * Returns the XPath function or NULL if not found.
0261  */
0262 typedef xmlXPathFunction (*xmlXPathFuncLookupFunc) (void *ctxt,
0263                      const xmlChar *name,
0264                      const xmlChar *ns_uri);
0265
0266 /**
0267  * xmlXPathFlags:
0268  * Flags for XPath engine compilation and runtime
0269  */
0270 /**
0271  * XML_XPATH_CHECKNS:
0272  *
0273  * check namespaces at compilation
0274  */
0275 #define XML_XPATH_CHECKNS (1<<0)
0276 /**
0277  * XML_XPATH_NOVAR:
0278  *
0279  * forbid variables in expression
0280  */
0281 #define XML_XPATH_NOVAR   (1<<1)
0282
0283 /**
0284  * xmlXPathContext:
0285  *
0286  * Expression evaluation occurs with respect to a context.
0287  * he context consists of:
0288  *    - a node (the context node)
0289  *    - a node list (the context node list)
0290  *    - a set of variable bindings
0291  *    - a function library
0292  *    - the set of namespace declarations in scope for the expression
0293  * Following the switch to hash tables, this need to be trimmed up at
0294  * the next binary incompatible release.
0295  * The node may be modified when the context is passed to libxml2
0296  * for an XPath evaluation so you may need to initialize it again
0297  * before the next call.
0298  */
0299
0300 struct _xmlXPathContext {
0301     xmlDocPtr doc;          /* The current document */
0302     xmlNodePtr node;            /* The current node */
0303
0304     int nb_variables_unused;        /* unused (hash table) */
0305     int max_variables_unused;       /* unused (hash table) */
0306     xmlHashTablePtr varHash;        /* Hash table of defined variables */
0307
0308     int nb_types;           /* number of defined types */
0309     int max_types;          /* max number of types */
0310     xmlXPathTypePtr types;      /* Array of defined types */
0311
0312     int nb_funcs_unused;        /* unused (hash table) */
0313     int max_funcs_unused;       /* unused (hash table) */
0314     xmlHashTablePtr funcHash;       /* Hash table of defined funcs */
0315
0316     int nb_axis;            /* number of defined axis */
0317     int max_axis;           /* max number of axis */
0318     xmlXPathAxisPtr axis;       /* Array of defined axis */
0319
0320     /* the namespace nodes of the context node */
0321     xmlNsPtr *namespaces;       /* Array of namespaces */
0322     int nsNr;               /* number of namespace in scope */
0323     void *user;             /* function to free */
0324
0325     /* extra variables */
0326     int contextSize;            /* the context size */
0327     int proximityPosition;      /* the proximity position */
0328
0329     /* extra stuff for XPointer */
0330     int xptr;               /* is this an XPointer context? */
0331     xmlNodePtr here;            /* for here() */
0332     xmlNodePtr origin;          /* for origin() */
0333
0334     /* the set of namespace declarations in scope for the expression */
0335     xmlHashTablePtr nsHash;     /* The namespaces hash table */
0336     xmlXPathVariableLookupFunc varLookupFunc;/* variable lookup func */
0337     void *varLookupData;        /* variable lookup data */
0338
0339     /* Possibility to link in an extra item */
0340     void *extra;                        /* needed for XSLT */
0341
0342     /* The function name and URI when calling a function */
0343     const xmlChar *function;
0344     const xmlChar *functionURI;
0345
0346     /* function lookup function and data */
0347     xmlXPathFuncLookupFunc funcLookupFunc;/* function lookup func */
0348     void *funcLookupData;       /* function lookup data */
0349
0350     /* temporary namespace lists kept for walking the namespace axis */
0351     xmlNsPtr *tmpNsList;        /* Array of namespaces */
0352     int tmpNsNr;            /* number of namespaces in scope */
0353
0354     /* error reporting mechanism */
0355     void *userData;                     /* user specific data block */
0356     xmlStructuredErrorFunc error;       /* the callback in case of errors */
0357     xmlError lastError;         /* the last error */
0358     xmlNodePtr debugNode;       /* the source node XSLT */
0359
0360     /* dictionary */
0361     xmlDictPtr dict;            /* dictionary if any */
0362
0363     int flags;              /* flags to control compilation */
0364
0365     /* Cache for reusal of XPath objects */
0366     void *cache;
0367
0368     /* Resource limits */
0369     unsigned long opLimit;
0370     unsigned long opCount;
0371     int depth;
0372 };
0373
0374 /*
0375  * The structure of a compiled expression form is not public.
0376  */
0377
0378 typedef struct _xmlXPathCompExpr xmlXPathCompExpr;
0379 typedef xmlXPathCompExpr *xmlXPathCompExprPtr;
0380
0381 /**
0382  * xmlXPathParserContext:
0383  *
0384  * An XPath parser context. It contains pure parsing information,
0385  * an xmlXPathContext, and the stack of objects.
0386  */
0387 struct _xmlXPathParserContext {
0388     const xmlChar *cur;         /* the current char being parsed */
0389     const xmlChar *base;            /* the full expression */
0390
0391     int error;              /* error code */
0392
0393     xmlXPathContextPtr  context;    /* the evaluation context */
0394     xmlXPathObjectPtr     value;    /* the current value */
0395     int                 valueNr;    /* number of values stacked */
0396     int                valueMax;    /* max number of values stacked */
0397     xmlXPathObjectPtr *valueTab;    /* stack of values */
0398
0399     xmlXPathCompExprPtr comp;       /* the precompiled expression */
0400     int xptr;               /* it this an XPointer expression */
0401     xmlNodePtr         ancestor;    /* used for walking preceding axis */
0402
0403     int              valueFrame;        /* always zero for compatibility */
0404 };
0405
0406 /************************************************************************
0407  *                                  *
0408  *          Public API                  *
0409  *                                  *
0410  ************************************************************************/
0411
0412 /**
0413  * Objects and Nodesets handling
0414  */
0415
0416 XMLPUBVAR double xmlXPathNAN;
0417 XMLPUBVAR double xmlXPathPINF;
0418 XMLPUBVAR double xmlXPathNINF;
0419
0420 /* These macros may later turn into functions */
0421 /**
0422  * xmlXPathNodeSetGetLength:
0423  * @ns:  a node-set
0424  *
0425  * Implement a functionality similar to the DOM NodeList.length.
0426  *
0427  * Returns the number of nodes in the node-set.
0428  */
0429 #define xmlXPathNodeSetGetLength(ns) ((ns) ? (ns)->nodeNr : 0)
0430 /**
0431  * xmlXPathNodeSetItem:
0432  * @ns:  a node-set
0433  * @index:  index of a node in the set
0434  *
0435  * Implements a functionality similar to the DOM NodeList.item().
0436  *
0437  * Returns the xmlNodePtr at the given @index in @ns or NULL if
0438  *         @index is out of range (0 to length-1)
0439  */
0440 #define xmlXPathNodeSetItem(ns, index)              \
0441         ((((ns) != NULL) &&             \
0442           ((index) >= 0) && ((index) < (ns)->nodeNr)) ? \
0443          (ns)->nodeTab[(index)]             \
0444          : NULL)
0445 /**
0446  * xmlXPathNodeSetIsEmpty:
0447  * @ns: a node-set
0448  *
0449  * Checks whether @ns is empty or not.
0450  *
0451  * Returns %TRUE if @ns is an empty node-set.
0452  */
0453 #define xmlXPathNodeSetIsEmpty(ns)                                      \
0454     (((ns) == NULL) || ((ns)->nodeNr == 0) || ((ns)->nodeTab == NULL))
0455
0456
0457 XMLPUBFUN void
0458             xmlXPathFreeObject      (xmlXPathObjectPtr obj);
0459 XMLPUBFUN xmlNodeSetPtr
0460             xmlXPathNodeSetCreate   (xmlNodePtr val);
0461 XMLPUBFUN void
0462             xmlXPathFreeNodeSetList (xmlXPathObjectPtr obj);
0463 XMLPUBFUN void
0464             xmlXPathFreeNodeSet     (xmlNodeSetPtr obj);
0465 XMLPUBFUN xmlXPathObjectPtr
0466             xmlXPathObjectCopy      (xmlXPathObjectPtr val);
0467 XMLPUBFUN int
0468             xmlXPathCmpNodes        (xmlNodePtr node1,
0469                          xmlNodePtr node2);
0470 /**
0471  * Conversion functions to basic types.
0472  */
0473 XMLPUBFUN int
0474             xmlXPathCastNumberToBoolean (double val);
0475 XMLPUBFUN int
0476             xmlXPathCastStringToBoolean (const xmlChar * val);
0477 XMLPUBFUN int
0478             xmlXPathCastNodeSetToBoolean(xmlNodeSetPtr ns);
0479 XMLPUBFUN int
0480             xmlXPathCastToBoolean   (xmlXPathObjectPtr val);
0481
0482 XMLPUBFUN double
0483             xmlXPathCastBooleanToNumber (int val);
0484 XMLPUBFUN double
0485             xmlXPathCastStringToNumber  (const xmlChar * val);
0486 XMLPUBFUN double
0487             xmlXPathCastNodeToNumber    (xmlNodePtr node);
0488 XMLPUBFUN double
0489             xmlXPathCastNodeSetToNumber (xmlNodeSetPtr ns);
0490 XMLPUBFUN double
0491             xmlXPathCastToNumber    (xmlXPathObjectPtr val);
0492
0493 XMLPUBFUN xmlChar *
0494             xmlXPathCastBooleanToString (int val);
0495 XMLPUBFUN xmlChar *
0496             xmlXPathCastNumberToString  (double val);
0497 XMLPUBFUN xmlChar *
0498             xmlXPathCastNodeToString    (xmlNodePtr node);
0499 XMLPUBFUN xmlChar *
0500             xmlXPathCastNodeSetToString (xmlNodeSetPtr ns);
0501 XMLPUBFUN xmlChar *
0502             xmlXPathCastToString    (xmlXPathObjectPtr val);
0503
0504 XMLPUBFUN xmlXPathObjectPtr
0505             xmlXPathConvertBoolean  (xmlXPathObjectPtr val);
0506 XMLPUBFUN xmlXPathObjectPtr
0507             xmlXPathConvertNumber   (xmlXPathObjectPtr val);
0508 XMLPUBFUN xmlXPathObjectPtr
0509             xmlXPathConvertString   (xmlXPathObjectPtr val);
0510
0511 /**
0512  * Context handling.
0513  */
0514 XMLPUBFUN xmlXPathContextPtr
0515             xmlXPathNewContext      (xmlDocPtr doc);
0516 XMLPUBFUN void
0517             xmlXPathFreeContext     (xmlXPathContextPtr ctxt);
0518 XMLPUBFUN void
0519             xmlXPathSetErrorHandler(xmlXPathContextPtr ctxt,
0520                         xmlStructuredErrorFunc handler,
0521                         void *context);
0522 XMLPUBFUN int
0523             xmlXPathContextSetCache(xmlXPathContextPtr ctxt,
0524                             int active,
0525                         int value,
0526                         int options);
0527 /**
0528  * Evaluation functions.
0529  */
0530 XMLPUBFUN long
0531             xmlXPathOrderDocElems   (xmlDocPtr doc);
0532 XMLPUBFUN int
0533             xmlXPathSetContextNode  (xmlNodePtr node,
0534                          xmlXPathContextPtr ctx);
0535 XMLPUBFUN xmlXPathObjectPtr
0536             xmlXPathNodeEval        (xmlNodePtr node,
0537                          const xmlChar *str,
0538                          xmlXPathContextPtr ctx);
0539 XMLPUBFUN xmlXPathObjectPtr
0540             xmlXPathEval        (const xmlChar *str,
0541                          xmlXPathContextPtr ctx);
0542 XMLPUBFUN xmlXPathObjectPtr
0543             xmlXPathEvalExpression  (const xmlChar *str,
0544                          xmlXPathContextPtr ctxt);
0545 XMLPUBFUN int
0546             xmlXPathEvalPredicate   (xmlXPathContextPtr ctxt,
0547                          xmlXPathObjectPtr res);
0548 /**
0549  * Separate compilation/evaluation entry points.
0550  */
0551 XMLPUBFUN xmlXPathCompExprPtr
0552             xmlXPathCompile     (const xmlChar *str);
0553 XMLPUBFUN xmlXPathCompExprPtr
0554             xmlXPathCtxtCompile     (xmlXPathContextPtr ctxt,
0555                          const xmlChar *str);
0556 XMLPUBFUN xmlXPathObjectPtr
0557             xmlXPathCompiledEval    (xmlXPathCompExprPtr comp,
0558                          xmlXPathContextPtr ctx);
0559 XMLPUBFUN int
0560             xmlXPathCompiledEvalToBoolean(xmlXPathCompExprPtr comp,
0561                          xmlXPathContextPtr ctxt);
0562 XMLPUBFUN void
0563             xmlXPathFreeCompExpr    (xmlXPathCompExprPtr comp);
0564 #endif /* LIBXML_XPATH_ENABLED */
0565 #if defined(LIBXML_XPATH_ENABLED) || defined(LIBXML_SCHEMAS_ENABLED)
0566 XML_DEPRECATED
0567 XMLPUBFUN void
0568             xmlXPathInit        (void);
0569 XMLPUBFUN int
0570         xmlXPathIsNaN   (double val);
0571 XMLPUBFUN int
0572         xmlXPathIsInf   (double val);
0573
0574 #ifdef __cplusplus
0575 }
0576 #endif
0577
0578 #endif /* LIBXML_XPATH_ENABLED or LIBXML_SCHEMAS_ENABLED*/
0579 #endif /* ! __XML_XPATH_H__ */