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