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