/*

 * 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);