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