You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

557 lines
16 KiB

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