gettext-tools/gnulib-lib/libxml/xpath.in.h

   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  */
 282
 283 struct _xmlXPathContext {
 284     xmlDocPtr doc;                      /* The current document */
 285     xmlNodePtr node;                    /* The current node */
 286
 287     int nb_variables_unused;            /* unused (hash table) */
 288     int max_variables_unused;           /* unused (hash table) */
 289     xmlHashTablePtr varHash;            /* Hash table of defined variables */
 290
 291     int nb_types;                       /* number of defined types */
 292     int max_types;                      /* max number of types */
 293     xmlXPathTypePtr types;              /* Array of defined types */
 294
 295     int nb_funcs_unused;                /* unused (hash table) */
 296     int max_funcs_unused;               /* unused (hash table) */
 297     xmlHashTablePtr funcHash;           /* Hash table of defined funcs */
 298
 299     int nb_axis;                        /* number of defined axis */
 300     int max_axis;                       /* max number of axis */
 301     xmlXPathAxisPtr axis;               /* Array of defined axis */
 302
 303     /* the namespace nodes of the context node */
 304     xmlNsPtr *namespaces;               /* Array of namespaces */
 305     int nsNr;                           /* number of namespace in scope */
 306     void *user;                         /* function to free */
 307
 308     /* extra variables */
 309     int contextSize;                    /* the context size */
 310     int proximityPosition;              /* the proximity position */
 311
 312     /* extra stuff for XPointer */
 313     int xptr;                           /* it this an XPointer context */
 314     xmlNodePtr here;                    /* for here() */
 315     xmlNodePtr origin;                  /* for origin() */
 316
 317     /* the set of namespace declarations in scope for the expression */
 318     xmlHashTablePtr nsHash;             /* The namespaces hash table */
 319     xmlXPathVariableLookupFunc varLookupFunc;/* variable lookup func */
 320     void *varLookupData;                /* variable lookup data */
 321
 322     /* Possibility to link in an extra item */
 323     void *extra;                        /* needed for XSLT */
 324
 325     /* The function name and URI when calling a function */
 326     const xmlChar *function;
 327     const xmlChar *functionURI;
 328
 329     /* function lookup function and data */
 330     xmlXPathFuncLookupFunc funcLookupFunc;/* function lookup func */
 331     void *funcLookupData;               /* function lookup data */
 332
 333     /* temporary namespace lists kept for walking the namespace axis */
 334     xmlNsPtr *tmpNsList;                /* Array of namespaces */
 335     int tmpNsNr;                        /* number of namespace in scope */
 336
 337     /* error reporting mechanism */
 338     void *userData;                     /* user specific data block */
 339     xmlStructuredErrorFunc error;       /* the callback in case of errors */
 340     xmlError lastError;                 /* the last error */
 341     xmlNodePtr debugNode;               /* the source node XSLT */
 342
 343     /* dictionnary */
 344     xmlDictPtr dict;                    /* dictionnary if any */
 345
 346     int flags;                          /* flags to control compilation */
 347
 348     /* Cache for reusal of XPath objects */
 349     void *cache;
 350 };
 351
 352 /*
 353  * The structure of a compiled expression form is not public.
 354  */
 355
 356 typedef struct _xmlXPathCompExpr xmlXPathCompExpr;
 357 typedef xmlXPathCompExpr *xmlXPathCompExprPtr;
 358
 359 /**
 360  * xmlXPathParserContext:
 361  *
 362  * An XPath parser context. It contains pure parsing informations,
 363  * an xmlXPathContext, and the stack of objects.
 364  */
 365 struct _xmlXPathParserContext {
 366     const xmlChar *cur;                 /* the current char being parsed */
 367     const xmlChar *base;                        /* the full expression */
 368
 369     int error;                          /* error code */
 370
 371     xmlXPathContextPtr  context;        /* the evaluation context */
 372     xmlXPathObjectPtr     value;        /* the current value */
 373     int                 valueNr;        /* number of values stacked */
 374     int                valueMax;        /* max number of values stacked */
 375     xmlXPathObjectPtr *valueTab;        /* stack of values */
 376
 377     xmlXPathCompExprPtr comp;           /* the precompiled expression */
 378     int xptr;                           /* it this an XPointer expression */
 379     xmlNodePtr         ancestor;        /* used for walking preceding axis */
 380 };
 381
 382 /************************************************************************
 383  *                                                                      *
 384  *                      Public API                                      *
 385  *                                                                      *
 386  ************************************************************************/
 387
 388 /**
 389  * Objects and Nodesets handling
 390  */
 391
 392 XMLPUBVAR double xmlXPathNAN;
 393 XMLPUBVAR double xmlXPathPINF;
 394 XMLPUBVAR double xmlXPathNINF;
 395
 396 /* These macros may later turn into functions */
 397 /**
 398  * xmlXPathNodeSetGetLength:
 399  * @ns:  a node-set
 400  *
 401  * Implement a functionality similar to the DOM NodeList.length.
 402  *
 403  * Returns the number of nodes in the node-set.
 404  */
 405 #define xmlXPathNodeSetGetLength(ns) ((ns) ? (ns)->nodeNr : 0)
 406 /**
 407  * xmlXPathNodeSetItem:
 408  * @ns:  a node-set
 409  * @index:  index of a node in the set
 410  *
 411  * Implements a functionality similar to the DOM NodeList.item().
 412  *
 413  * Returns the xmlNodePtr at the given @index in @ns or NULL if
 414  *         @index is out of range (0 to length-1)
 415  */
 416 #define xmlXPathNodeSetItem(ns, index)                          \
 417                 ((((ns) != NULL) &&                             \
 418                   ((index) >= 0) && ((index) < (ns)->nodeNr)) ? \
 419                  (ns)->nodeTab[(index)]                         \
 420                  : NULL)
 421 /**
 422  * xmlXPathNodeSetIsEmpty:
 423  * @ns: a node-set
 424  *
 425  * Checks whether @ns is empty or not.
 426  *
 427  * Returns %TRUE if @ns is an empty node-set.
 428  */
 429 #define xmlXPathNodeSetIsEmpty(ns)                                      \
 430     (((ns) == NULL) || ((ns)->nodeNr == 0) || ((ns)->nodeTab == NULL))
 431
 432
 433 XMLPUBFUN void XMLCALL
 434                     xmlXPathFreeObject          (xmlXPathObjectPtr obj);
 435 XMLPUBFUN xmlNodeSetPtr XMLCALL
 436                     xmlXPathNodeSetCreate       (xmlNodePtr val);
 437 XMLPUBFUN void XMLCALL
 438                     xmlXPathFreeNodeSetList     (xmlXPathObjectPtr obj);
 439 XMLPUBFUN void XMLCALL
 440                     xmlXPathFreeNodeSet         (xmlNodeSetPtr obj);
 441 XMLPUBFUN xmlXPathObjectPtr XMLCALL
 442                     xmlXPathObjectCopy          (xmlXPathObjectPtr val);
 443 XMLPUBFUN int XMLCALL
 444                     xmlXPathCmpNodes            (xmlNodePtr node1,
 445                                                  xmlNodePtr node2);
 446 /**
 447  * Conversion functions to basic types.
 448  */
 449 XMLPUBFUN int XMLCALL
 450                     xmlXPathCastNumberToBoolean (double val);
 451 XMLPUBFUN int XMLCALL
 452                     xmlXPathCastStringToBoolean (const xmlChar * val);
 453 XMLPUBFUN int XMLCALL
 454                     xmlXPathCastNodeSetToBoolean(xmlNodeSetPtr ns);
 455 XMLPUBFUN int XMLCALL
 456                     xmlXPathCastToBoolean       (xmlXPathObjectPtr val);
 457
 458 XMLPUBFUN double XMLCALL
 459                     xmlXPathCastBooleanToNumber (int val);
 460 XMLPUBFUN double XMLCALL
 461                     xmlXPathCastStringToNumber  (const xmlChar * val);
 462 XMLPUBFUN double XMLCALL
 463                     xmlXPathCastNodeToNumber    (xmlNodePtr node);
 464 XMLPUBFUN double XMLCALL
 465                     xmlXPathCastNodeSetToNumber (xmlNodeSetPtr ns);
 466 XMLPUBFUN double XMLCALL
 467                     xmlXPathCastToNumber        (xmlXPathObjectPtr val);
 468
 469 XMLPUBFUN xmlChar * XMLCALL
 470                     xmlXPathCastBooleanToString (int val);
 471 XMLPUBFUN xmlChar * XMLCALL
 472                     xmlXPathCastNumberToString  (double val);
 473 XMLPUBFUN xmlChar * XMLCALL
 474                     xmlXPathCastNodeToString    (xmlNodePtr node);
 475 XMLPUBFUN xmlChar * XMLCALL
 476                     xmlXPathCastNodeSetToString (xmlNodeSetPtr ns);
 477 XMLPUBFUN xmlChar * XMLCALL
 478                     xmlXPathCastToString        (xmlXPathObjectPtr val);
 479
 480 XMLPUBFUN xmlXPathObjectPtr XMLCALL
 481                     xmlXPathConvertBoolean      (xmlXPathObjectPtr val);
 482 XMLPUBFUN xmlXPathObjectPtr XMLCALL
 483                     xmlXPathConvertNumber       (xmlXPathObjectPtr val);
 484 XMLPUBFUN xmlXPathObjectPtr XMLCALL
 485                     xmlXPathConvertString       (xmlXPathObjectPtr val);
 486
 487 /**
 488  * Context handling.
 489  */
 490 XMLPUBFUN xmlXPathContextPtr XMLCALL
 491                     xmlXPathNewContext          (xmlDocPtr doc);
 492 XMLPUBFUN void XMLCALL
 493                     xmlXPathFreeContext         (xmlXPathContextPtr ctxt);
 494 XMLPUBFUN int XMLCALL
 495                     xmlXPathContextSetCache(xmlXPathContextPtr ctxt,
 496                                             int active,
 497                                             int value,
 498                                             int options);
 499 /**
 500  * Evaluation functions.
 501  */
 502 XMLPUBFUN long XMLCALL
 503                     xmlXPathOrderDocElems       (xmlDocPtr doc);
 504 XMLPUBFUN xmlXPathObjectPtr XMLCALL
 505                     xmlXPathEval                (const xmlChar *str,
 506                                                  xmlXPathContextPtr ctx);
 507 XMLPUBFUN xmlXPathObjectPtr XMLCALL
 508                     xmlXPathEvalExpression      (const xmlChar *str,
 509                                                  xmlXPathContextPtr ctxt);
 510 XMLPUBFUN int XMLCALL
 511                     xmlXPathEvalPredicate       (xmlXPathContextPtr ctxt,
 512                                                  xmlXPathObjectPtr res);
 513 /**
 514  * Separate compilation/evaluation entry points.
 515  */
 516 XMLPUBFUN xmlXPathCompExprPtr XMLCALL
 517                     xmlXPathCompile             (const xmlChar *str);
 518 XMLPUBFUN xmlXPathCompExprPtr XMLCALL
 519                     xmlXPathCtxtCompile         (xmlXPathContextPtr ctxt,
 520                                                  const xmlChar *str);
 521 XMLPUBFUN xmlXPathObjectPtr XMLCALL
 522                     xmlXPathCompiledEval        (xmlXPathCompExprPtr comp,
 523                                                  xmlXPathContextPtr ctx);
 524 XMLPUBFUN int XMLCALL
 525                     xmlXPathCompiledEvalToBoolean(xmlXPathCompExprPtr comp,
 526                                                  xmlXPathContextPtr ctxt);
 527 XMLPUBFUN void XMLCALL
 528                     xmlXPathFreeCompExpr        (xmlXPathCompExprPtr comp);
 529 #endif /* LIBXML_XPATH_ENABLED */
 530 #if defined(LIBXML_XPATH_ENABLED) || defined(LIBXML_SCHEMAS_ENABLED)
 531 XMLPUBFUN void XMLCALL
 532                     xmlXPathInit                (void);
 533 XMLPUBFUN int XMLCALL
 534                 xmlXPathIsNaN   (double val);
 535 XMLPUBFUN int XMLCALL
 536                 xmlXPathIsInf   (double val);
 537
 538 #ifdef __cplusplus
 539 }
 540 #endif
 541
 542 #endif /* LIBXML_XPATH_ENABLED or LIBXML_SCHEMAS_ENABLED*/
 543 #endif /* ! __XML_XPATH_H__ */