/*

  * Summary: XML Path Language implementation

  * Description: API for the XML Path Language implementation

  *

  * XML Path Language implementation

  * XPath is a language for addressing parts of an XML document,

  * designed to be used by both XSLT and XPointer

  *     http://www.w3.org/TR/xpath

  *

  * Implements

  * W3C Recommendation 16 November 1999

  *     http://www.w3.org/TR/1999/REC-xpath-19991116

  *

  * Copy: See Copyright for the status of this software.

  *

  * Author: Daniel Veillard

  * Portion Copyright © 2009 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. 

  */

 /** @file

 @publishedAll

 @released

 */

 #ifndef XML_XPATH_H

 #define XML_XPATH_H

 #include <stdapis/libxml2/libxml2_hash.h>

 #include <stdapis/libxml2/libxml2_dict.h>

 #include <stdapis/libxml2/libxml2_xmlerror.h>

 #ifdef __cplusplus

 extern "C" {

 #endif

 typedef struct _xmlXPathContext xmlXPathContext;

 typedef xmlXPathContext *xmlXPathContextPtr;

 typedef struct _xmlXPathParserContext xmlXPathParserContext;

 typedef xmlXPathParserContext *xmlXPathParserContextPtr;

 /**

  * The set of XPath error codes.

  */

 typedef enum {

     XPATH_EXPRESSION_OK = 0,

     XPATH_NUMBER_ERROR,

     XPATH_UNFINISHED_LITERAL_ERROR,

     XPATH_START_LITERAL_ERROR,

     XPATH_VARIABLE_REF_ERROR,

     XPATH_UNDEF_VARIABLE_ERROR,

     XPATH_INVALID_PREDICATE_ERROR,

     XPATH_EXPR_ERROR,

     XPATH_UNCLOSED_ERROR,

     XPATH_UNKNOWN_FUNC_ERROR,

     XPATH_INVALID_OPERAND,

     XPATH_INVALID_TYPE,

     XPATH_INVALID_ARITY,

     XPATH_INVALID_CTXT_SIZE,

     XPATH_INVALID_CTXT_POSITION,

     XPATH_MEMORY_ERROR,

     XPTR_SYNTAX_ERROR,

     XPTR_RESOURCE_ERROR,

     XPTR_SUB_RESOURCE_ERROR,

     XPATH_UNDEF_PREFIX_ERROR,

     XPATH_ENCODING_ERROR,

     XPATH_INVALID_CHAR_ERROR,

     XPATH_XE_EXTENSION_FUNC_ERROR

 } xmlXPathError;

 /*

  * A node-set (an unordered collection of nodes without duplicates).

  */

 typedef struct _xmlNodeSet xmlNodeSet;

 typedef xmlNodeSet *xmlNodeSetPtr;

 struct _xmlNodeSet {

     int nodeNr;             /* number of nodes in the set */

     int nodeMax;            /* size of the array as allocated */

     xmlNodePtr* nodeTab;    /* array of nodes in no particular order */

     /* @@ with_ns to check wether namespace nodes should be looked at @@ */

 };

 /*

  * An expression is evaluated to yield an object, which

  * has one of the following four basic types:

  *   - node-set

  *   - boolean

  *   - number

  *   - string

  *

  * @@ XPointer will add more types !

  */

 typedef enum {

     XPATH_UNDEFINED = 0,

     XPATH_NODESET = 1,

     XPATH_BOOLEAN = 2,

     XPATH_NUMBER = 3,

     XPATH_STRING = 4,

     XPATH_POINT = 5,

     XPATH_RANGE = 6,

     XPATH_LOCATIONSET = 7,

     XPATH_USERS = 8,

     XPATH_XSLT_TREE = 9  /* An XSLT value tree, non modifiable */

 } xmlXPathObjectType;

 typedef struct _xmlXPathObject xmlXPathObject;

 typedef xmlXPathObject *xmlXPathObjectPtr;

 struct _xmlXPathObject {

     xmlXPathObjectType  type;

     xmlNodeSetPtr       nodesetval;

     int                 boolval;

     double              floatval;

     xmlChar*            stringval;

     void*               user;

     int                 index;

     void*               user2;

     int                 index2;

 };

 /**

  * xmlXPathConvertFunc:

  * @param obj an XPath object

  * @param type the number of the target type

  *

  * A conversion function is associated to a type and used to cast

  * the new type to primitive values.

  *

  * Returns -1 in case of error, 0 otherwise

  */

 typedef int (*xmlXPathConvertFunc) (xmlXPathObjectPtr obj, int type);

 /*

  * Extra type: a name and a conversion function.

  */

 typedef struct _xmlXPathType xmlXPathType;

 typedef xmlXPathType *xmlXPathTypePtr;

 struct _xmlXPathType {

     const xmlChar       *name;      /* the type name */

     xmlXPathConvertFunc func;       /* the conversion function */

 };

 /*

  * Extra variable: a name and a value.

  */

 typedef struct _xmlXPathVariable xmlXPathVariable;

 typedef xmlXPathVariable *xmlXPathVariablePtr;

 struct _xmlXPathVariable {

     const xmlChar     *name;        /* the variable name */

     xmlXPathObjectPtr value;        /* the value */

 };

 /**

  * xmlXPathEvalFunc:

  * @param ctxt an XPath parser context

  * @param nargs the number of arguments passed to the function

  *

  * An XPath evaluation function, the parameters are on the XPath context stack.

  */

 typedef void (*xmlXPathEvalFunc)(xmlXPathParserContextPtr ctxt, int nargs);

 /*

  * Extra function: a name and a evaluation function.

  */

 typedef struct _xmlXPathFunct xmlXPathFunct;

 typedef xmlXPathFunct *xmlXPathFuncPtr;

 struct _xmlXPathFunct {

     const xmlChar      *name;       /* the function name */

     xmlXPathEvalFunc func;      /* the evaluation function */

 };

 /**

  * xmlXPathAxisFunc:

  * @param ctxt the XPath interpreter context

  * @param cur the previous node being explored on that axis

  *

  * An axis traversal function. To traverse an axis, the engine calls

  * the first time with cur == NULL and repeat until the function returns

  * NULL indicating the end of the axis traversal.

  *

  * Returns the next node in that axis or NULL if at the end of the axis.

  */

 typedef xmlXPathObjectPtr (*xmlXPathAxisFunc) (xmlXPathParserContextPtr ctxt, xmlXPathObjectPtr cur);

 /*

  * Extra axis: a name and an axis function.

  */

 typedef struct _xmlXPathAxis xmlXPathAxis;

 typedef xmlXPathAxis* xmlXPathAxisPtr;

 struct _xmlXPathAxis {

     const xmlChar*   name;       /* the axis name */

     xmlXPathAxisFunc func;       /* the search function */

 };

 // XMLENGINE: NEW CODE -- XForms extensions support

 /**

 Callback for resolving prefix names into namespace URIs

 @return Namespace URI for aNs prefix.

 Resolving is made with aCtxt context.

 This function is used internally by for implementation of

 namespace-resovling feature in XPath API of XML Engine

 (MXmlEngNamespaceResolver interface is called by libxml2)

 */

 typedef const xmlChar* (*xeXPathNsResolverFunc)(void* aCtxt, const xmlChar* aNs);

 //---

 /**

  * xmlXPathContext:

  *

  * Expression evaluation occurs with respect to a context.

  * the context consists of:

  *    - a node (the context node)

  *    - a node list (the context node list)

  *    - a set of variable bindings

  *    - a function library

  *    - the set of namespace declarations in scope for the expression

  * Following the switch to hash tables, this need to be trimmed up at

  * the next binary incompatible release.

  */

 struct _xmlXPathContext {

     xmlDocPtr doc;          /* The current document */

     xmlNodePtr node;            /* The current node */

     //int nb_variables_unused;        /* unused (hash table) */

     //int max_variables_unused;       /* unused (hash table) */

     xmlHashTablePtr varHash;        /* Hash table of defined variables */

     int nb_types;           /* number of defined types */

     int max_types;          /* max number of types */

     xmlXPathTypePtr types;      /* Array of defined types */

     //int nb_funcs_unused;        /* unused (hash table) */

     //int max_funcs_unused;       /* unused (hash table) */

     xmlHashTablePtr funcHash;       /* Hash table of defined funcs */

     int nb_axis;            /* number of defined axis */

     int max_axis;           /* max number of axis */

     xmlXPathAxisPtr axis;       /* Array of defined axis */

     /* the namespace nodes of the context node */

     xmlNsPtr *namespaces;       /* Array of namespaces */

     int nsNr;               /* number of namespace in scope */

     void *user;             /* function to free */

     /* extra variables */

     int contextSize;            /* the context size */

     int proximityPosition;      /* the proximity position */

     /* extra stuff for XPointer */

     int xptr;               /* it this an XPointer context */

     xmlNodePtr here;            /* for here() */

     xmlNodePtr origin;          /* for origin() */

     /* the set of namespace declarations in scope for the expression */

     xmlHashTablePtr nsHash;         /* The namespaces hash table */

     void* varLookupFunc;            /* variable lookup func */

     void* varLookupData;            /* variable lookup data */

     /* Possibility to link in an extra item */

     void* extra;                    /* needed for XSLT */

     /* The function name and URI when calling a function */

     const xmlChar* function;

     const xmlChar* functionURI;

     /* function lookup function and data */

     void* funcLookupFunc;           /* function lookup func */

     void* funcLookupData;           /* function lookup data */

     /* temporary namespace lists kept for walking the namespace axis */

     xmlNsPtr* tmpNsList;            /* Array of namespaces */

     int       tmpNsNr;              /* number of namespace in scope */

     /* error reporting mechanism */

     void*   userData;               /* user specific data block */

     xmlStructuredErrorFunc error;   /* the callback in case of errors */

     xmlError lastError;             /* the last error */

     xmlNodePtr debugNode;           /* the source node XSLT */

     /* dictionnary */

     xmlDictPtr dict;                /* dictionnary if any */

 // XMLENGINE: NEW CODE -- XForms extensions support

     xmlHashTablePtr instanceDocs;  /* hash table that stores instance XForms instance docs,

                                       not owned by the structure, will be freed by the client*/

     xmlNodeSetPtr   dependencyList;/* nodes that the expression depends on */

     xeXPathNsResolverFunc xeResolveNs; /* find namespace URI bound to prefix in the current context */

     void*                 xeResolveNsCtxt; /* resolver-specific context for processing */

 // END NEW CODE

 };

 /*

  * The structure of a compiled expression form has become public in XML ENGINE

  */

 typedef enum {

     XPATH_OP_END=0,

     XPATH_OP_AND,

     XPATH_OP_OR,

     XPATH_OP_EQUAL,

     XPATH_OP_CMP,

     XPATH_OP_PLUS,

     XPATH_OP_MULT,

     XPATH_OP_UNION,

     XPATH_OP_ROOT,

     XPATH_OP_NODE,

     XPATH_OP_RESET,

     XPATH_OP_COLLECT,

     XPATH_OP_VALUE,

     XPATH_OP_VARIABLE,

     XPATH_OP_FUNCTION,

     XPATH_OP_ARG,

     XPATH_OP_PREDICATE,

     XPATH_OP_FILTER,

     XPATH_OP_SORT

 #ifdef LIBXML_XPTR_ENABLED

     ,XPATH_OP_RANGETO

 #endif

 } xmlXPathOp;

 typedef struct _xmlXPathStepOp xmlXPathStepOp;

 typedef xmlXPathStepOp *xmlXPathStepOpPtr;

 struct _xmlXPathStepOp {

     xmlXPathOp  op;      /* The identifier of the operation */

     int        ch1;      /* First child */

     int        ch2;      /* Second child */

     int      value;

     int     value2;

     int     value3;

     void*   value4;

     void*   value5;

     void*    cache;

     void* cacheURI;

 };

 /**

  The initial size of 'steps' table in the precompiled XPath exression

  Double-it policy for growth is used in the code

 */

 #define XPATH_STEPS_GRANULARITY 10

 typedef struct _xmlXPathCompExpr xmlXPathCompExpr;

 typedef xmlXPathCompExpr*   xmlXPathCompExprPtr;

 struct _xmlXPathCompExpr {

     int nbStep;             /* Number of steps in this expression */

     int maxStep;            /* Maximum number of steps allocated */

     xmlXPathStepOp* steps;  /* ops for computation of this expression */

     int last;               /* index of last step in expression */

     xmlChar*    expr;       /* the expression being computed */

     xmlDictPtr  dict;       /* the dictionnary to use if any */

 #ifdef DEBUG_EVAL_COUNTS

     int nb;

     xmlChar*  string;

 #endif

 //XMLENGINE: NEW CODE

     void* extendedContext;  /* some data set by API users and available for XPath extension functions */

     void* xeNsResolver;     /* default namespace resolver supplied when compiling expression */

 //XMLENGINE: END NEW CODE

 };

 /**

  * xmlXPathParserContext:

  *

  * An XPath parser context. It contains pure parsing informations,

  * an xmlXPathContext, and the stack of objects.

  */

 struct _xmlXPathParserContext {

     const xmlChar *cur;             /* the current char being parsed */

     const xmlChar *base;            /* the full expression */

     int error;                      /* error code */

     xmlXPathContextPtr  context;    /* the evaluation context */

     xmlXPathObjectPtr     value;    /* the current value */

     int                 valueNr;    /* number of values stacked */

     int                valueMax;    /* max number of values stacked */

     xmlXPathObjectPtr *valueTab;    /* stack of values */

     xmlXPathCompExprPtr comp;       /* the precompiled expression */

     int xptr;                       /* it this an XPointer expression */

     xmlNodePtr         ancestor;    /* used for walking preceding axis */

 };

 /**

  * xmlXPathFunction:

  * @param ctxt the XPath interprestation context

  * @param nargs the number of arguments

  *

  * An XPath function.

  * The arguments (if any) are popped out from the context stack

  * and the result is pushed on the stack.

  */

 typedef void (*xmlXPathFunction) (xmlXPathParserContextPtr ctxt, int nargs);

 /************************************************************************

  *                                                                      *

  *          Public API                                                  *

  *                                                                      *

  ************************************************************************/

 /*

 NOTE: Now defined as local inline functions in xpath.c

       It seems that no one uses them from outside..

      --> used by libxslt

 */

 #define xmlXPathIsNaN(val) trio_isnan(val)

 #define xmlXPathIsInf(val) trio_isinf(val)

 /* These macros may later turn into functions */

 /**

  * xmlXPathNodeSetGetLength:

  * @param ns a node-set

  *

  * Implements a functionality similar to the DOM NodeList.length.

  *

  * Returns the number of nodes in the node-set.

  */

 #define xmlXPathNodeSetGetLength(ns) ((ns) ? (ns)->nodeNr : 0)

 /**

  * xmlXPathNodeSetItem:

  * @param ns a node-set

  * @param index index of a node in the set

  *

  * Implements a functionality similar to the DOM NodeList.item().

  *

  * Returns the xmlNodePtr at the given index in ns or NULL if

  *         index is out of range (0 to length-1)

  */

 #define xmlXPathNodeSetItem(ns, index)                          \

         (( (ns) && ((index) >= 0) && ((index) < (ns)->nodeNr) ) \

         ? (ns)->nodeTab[(index)]                                \

         : NULL)

 /**

  * xmlXPathNodeSetIsEmpty:

  * @param ns a node-set

  *

  * Checks whether ns is empty or not.

  *

  * Returns %TRUE if ns is an empty node-set.

  */

 #define xmlXPathNodeSetIsEmpty(ns)                                      \

     (((ns) == NULL) || ((ns)->nodeNr == 0) || ((ns)->nodeTab == NULL))

 XMLPUBFUN void XMLCALL

             xmlXPathFreeObject      (xmlXPathObjectPtr obj);

 XMLPUBFUN xmlNodeSetPtr XMLCALL

             xmlXPathNodeSetCreate   (xmlNodePtr val);

 XMLPUBFUN void XMLCALL

             xmlXPathFreeNodeSetList (xmlXPathObjectPtr obj);

 XMLPUBFUN void XMLCALL

             xmlXPathFreeNodeSet     (xmlNodeSetPtr obj);

 XMLPUBFUN xmlXPathObjectPtr XMLCALL

             xmlXPathObjectCopy      (xmlXPathObjectPtr val);

 XMLPUBFUN int XMLCALL

             xmlXPathCmpNodes        (xmlNodePtr node1, xmlNodePtr node2);

 /**

  * Conversion functions to basic types.

  */

 XMLPUBFUN int XMLCALL

             xmlXPathCastNumberToBoolean (double val);

 XMLPUBFUN int XMLCALL

             xmlXPathCastStringToBoolean (const xmlChar * val);

 XMLPUBFUN int XMLCALL

             xmlXPathCastNodeSetToBoolean(xmlNodeSetPtr ns);

 XMLPUBFUN int XMLCALL

             xmlXPathCastToBoolean   (xmlXPathObjectPtr val);

 XMLPUBFUN double XMLCALL

             xmlXPathCastBooleanToNumber (int val);

 XMLPUBFUN double XMLCALL

             xmlXPathCastStringToNumber  (const xmlChar * val);

 XMLPUBFUN double XMLCALL

             xmlXPathCastNodeToNumber    (xmlNodePtr node);

 XMLPUBFUN double XMLCALL

             xmlXPathCastNodeSetToNumber (xmlNodeSetPtr ns);

 XMLPUBFUN double XMLCALL

             xmlXPathCastToNumber    (xmlXPathObjectPtr val);

 XMLPUBFUN xmlChar* XMLCALL

             xmlXPathCastBooleanToString (int val);

 XMLPUBFUN xmlChar* XMLCALL

             xmlXPathCastNumberToString  (double val);

 XMLPUBFUN xmlChar* XMLCALL

             xmlXPathCastNodeToString    (xmlNodePtr node);

 XMLPUBFUN xmlChar* XMLCALL

             xmlXPathCastNodeSetToString (xmlNodeSetPtr ns);

 XMLPUBFUN xmlChar* XMLCALL

             xmlXPathCastToString    (xmlXPathObjectPtr val);

 XMLPUBFUN xmlXPathObjectPtr XMLCALL

             xmlXPathConvertBoolean  (xmlXPathObjectPtr val);

 XMLPUBFUN xmlXPathObjectPtr XMLCALL

             xmlXPathConvertNumber   (xmlXPathObjectPtr val);

 XMLPUBFUN xmlXPathObjectPtr XMLCALL

             xmlXPathConvertString   (xmlXPathObjectPtr val);

 /**

  * Context handling.

  */

 XMLPUBFUN void XMLCALL

             xmlXPathInit            (void);

 XMLPUBFUN xmlXPathContextPtr XMLCALL

             xmlXPathNewContext      (xmlDocPtr doc);

 XMLPUBFUN void XMLCALL

             xmlXPathFreeContext     (xmlXPathContextPtr ctxt);

 /**

  * Evaluation functions.

  */

 XMLPUBFUN long XMLCALL

             xmlXPathOrderDocElems   (xmlDocPtr doc);

 XMLPUBFUN xmlXPathObjectPtr XMLCALL

             xmlXPathEval            (const xmlChar *str, xmlXPathContextPtr ctx);

 XMLPUBFUN xmlXPathObjectPtr XMLCALL

             xmlXPathEvalExpression  (const xmlChar *str, xmlXPathContextPtr ctxt);

 XMLPUBFUN int XMLCALL

             xmlXPathEvalPredicate   (xmlXPathContextPtr ctxt, xmlXPathObjectPtr res);

 /**

  * Separate compilation/evaluation entry points.

  */

 XMLPUBFUN xmlXPathCompExprPtr XMLCALL

             xmlXPathCompile         (const xmlChar *str);

 XMLPUBFUN xmlXPathCompExprPtr XMLCALL

             xmlXPathCtxtCompile     (xmlXPathContextPtr ctxt, const xmlChar *str);

 XMLPUBFUN xmlXPathObjectPtr XMLCALL

             xmlXPathCompiledEval    (xmlXPathCompExprPtr comp,xmlXPathContextPtr ctx);

 XMLPUBFUN void XMLCALL

             xmlXPathFreeCompExpr    (xmlXPathCompExprPtr comp);

 #ifdef __cplusplus

 }

 #endif

 #endif /* XML_XPATH_H */