blob: 2d0988717d5b343197ce5e6c83ca7464aee7659f [file] [log] [blame]
Radek Krejcib1646a92018-11-02 16:08:26 +01001/**
2 * @file xpath.h
3 * @author Michal Vasko <mvasko@cesnet.cz>
4 * @brief YANG XPath evaluation functions header
5 *
Michal Vasko519fd602020-05-26 12:17:39 +02006 * Copyright (c) 2015 - 2020 CESNET, z.s.p.o.
Radek Krejcib1646a92018-11-02 16:08:26 +01007 *
8 * This source code is licensed under BSD 3-Clause License (the "License").
9 * You may not use this file except in compliance with the License.
10 * You may obtain a copy of the License at
11 *
12 * https://opensource.org/licenses/BSD-3-Clause
13 */
14
Michal Vasko14676352020-05-29 11:35:55 +020015#ifndef LY_XPATH_H
16#define LY_XPATH_H
Radek Krejcib1646a92018-11-02 16:08:26 +010017
Radek Krejciad97c5f2020-06-30 09:19:28 +020018#include <stddef.h>
Michal Vasko69730152020-10-09 16:30:07 +020019#include <stdint.h>
Radek Krejcib1646a92018-11-02 16:08:26 +010020
Michal Vaskoc5a22832020-08-20 13:21:33 +020021#include "compat.h"
Radek Krejcie7b95092019-05-15 11:03:07 +020022#include "log.h"
Radek Krejci77114102021-03-10 15:21:57 +010023#include "tree.h"
Radek Krejci535ea9f2020-05-29 16:01:05 +020024#include "tree_schema.h"
Radek Krejcie7b95092019-05-15 11:03:07 +020025
26struct ly_ctx;
Radek Krejci77114102021-03-10 15:21:57 +010027struct lyd_node;
Radek Krejcie7b95092019-05-15 11:03:07 +020028
Radek Krejci84d7fd72021-07-14 18:32:21 +020029/**
30 * @internal
31 * @page internals
32 * @section internalsXpath XPath Implementation
33 *
Radek Krejcib1646a92018-11-02 16:08:26 +010034 * XPath evaluator fully compliant with http://www.w3.org/TR/1999/REC-xpath-19991116/
35 * except the following restrictions in the grammar.
36 *
Radek Krejci84d7fd72021-07-14 18:32:21 +020037 * @subsection internalsXpathGrammar Parsed Grammar
Radek Krejcib1646a92018-11-02 16:08:26 +010038 *
39 * Full axes are not supported, abbreviated forms must be used,
aPiecekfba75362021-10-07 12:39:48 +020040 * "id()" function is not supported, and processing instruction and comment nodes are not supported,
41 * which is also reflected in the grammar. Undefined rules and constants are tokens.
Radek Krejcib1646a92018-11-02 16:08:26 +010042 *
43 * Modified full grammar:
Radek Krejci84d7fd72021-07-14 18:32:21 +020044 * @code
Radek Krejcib1646a92018-11-02 16:08:26 +010045 * [1] Expr ::= OrExpr // just an alias
46 *
47 * [2] LocationPath ::= RelativeLocationPath | AbsoluteLocationPath
48 * [3] AbsoluteLocationPath ::= '/' RelativeLocationPath? | '//' RelativeLocationPath
49 * [4] RelativeLocationPath ::= Step | RelativeLocationPath '/' Step | RelativeLocationPath '//' Step
50 * [5] Step ::= '@'? NodeTest Predicate* | '.' | '..'
51 * [6] NodeTest ::= NameTest | NodeType '(' ')'
Michal Vaskod3678892020-05-21 10:06:58 +020052 * [7] NameTest ::= '*' | NCName ':' '*' | QName
53 * [8] NodeType ::= 'text' | 'node'
54 * [9] Predicate ::= '[' Expr ']'
aPiecekfba75362021-10-07 12:39:48 +020055 * [10] PrimaryExpr ::= VariableReference | '(' Expr ')' | Literal | Number | FunctionCall
Michal Vaskod3678892020-05-21 10:06:58 +020056 * [11] FunctionCall ::= FunctionName '(' ( Expr ( ',' Expr )* )? ')'
57 * [12] PathExpr ::= LocationPath | PrimaryExpr Predicate*
Radek Krejcib1646a92018-11-02 16:08:26 +010058 * | PrimaryExpr Predicate* '/' RelativeLocationPath
59 * | PrimaryExpr Predicate* '//' RelativeLocationPath
Michal Vaskod3678892020-05-21 10:06:58 +020060 * [13] OrExpr ::= AndExpr | OrExpr 'or' AndExpr
61 * [14] AndExpr ::= EqualityExpr | AndExpr 'and' EqualityExpr
62 * [15] EqualityExpr ::= RelationalExpr | EqualityExpr '=' RelationalExpr
Radek Krejcib1646a92018-11-02 16:08:26 +010063 * | EqualityExpr '!=' RelationalExpr
Michal Vaskod3678892020-05-21 10:06:58 +020064 * [16] RelationalExpr ::= AdditiveExpr
Radek Krejcib1646a92018-11-02 16:08:26 +010065 * | RelationalExpr '<' AdditiveExpr
66 * | RelationalExpr '>' AdditiveExpr
67 * | RelationalExpr '<=' AdditiveExpr
68 * | RelationalExpr '>=' AdditiveExpr
Michal Vaskod3678892020-05-21 10:06:58 +020069 * [17] AdditiveExpr ::= MultiplicativeExpr
Radek Krejcib1646a92018-11-02 16:08:26 +010070 * | AdditiveExpr '+' MultiplicativeExpr
71 * | AdditiveExpr '-' MultiplicativeExpr
Michal Vaskod3678892020-05-21 10:06:58 +020072 * [18] MultiplicativeExpr ::= UnaryExpr
Radek Krejcib1646a92018-11-02 16:08:26 +010073 * | MultiplicativeExpr '*' UnaryExpr
74 * | MultiplicativeExpr 'div' UnaryExpr
75 * | MultiplicativeExpr 'mod' UnaryExpr
Michal Vaskod3678892020-05-21 10:06:58 +020076 * [19] UnaryExpr ::= UnionExpr | '-' UnaryExpr
77 * [20] UnionExpr ::= PathExpr | UnionExpr '|' PathExpr
Radek Krejci84d7fd72021-07-14 18:32:21 +020078 * @endcode
Radek Krejcib1646a92018-11-02 16:08:26 +010079 */
80
81/* expression tokens allocation */
82#define LYXP_EXPR_SIZE_START 10
83#define LYXP_EXPR_SIZE_STEP 5
84
85/* XPath matches allocation */
Michal Vasko871df522022-04-06 12:14:41 +020086#define LYXP_SET_SIZE_START 4
87#define LYXP_SET_SIZE_MUL_STEP 2
Radek Krejcib1646a92018-11-02 16:08:26 +010088
89/* building string when casting */
90#define LYXP_STRING_CAST_SIZE_START 64
91#define LYXP_STRING_CAST_SIZE_STEP 16
92
aPiecekbf968d92021-05-27 14:35:05 +020093/* Maximum number of nested expressions. */
94#define LYXP_MAX_BLOCK_DEPTH 100
95
Radek Krejcib1646a92018-11-02 16:08:26 +010096/**
97 * @brief Tokens that can be in an XPath expression.
98 */
99enum lyxp_token {
100 LYXP_TOKEN_NONE = 0,
101 LYXP_TOKEN_PAR1, /* '(' */
102 LYXP_TOKEN_PAR2, /* ')' */
103 LYXP_TOKEN_BRACK1, /* '[' */
104 LYXP_TOKEN_BRACK2, /* ']' */
105 LYXP_TOKEN_DOT, /* '.' */
106 LYXP_TOKEN_DDOT, /* '..' */
107 LYXP_TOKEN_AT, /* '@' */
108 LYXP_TOKEN_COMMA, /* ',' */
109 /* LYXP_TOKEN_DCOLON, * '::' * axes not supported */
110 LYXP_TOKEN_NAMETEST, /* NameTest */
111 LYXP_TOKEN_NODETYPE, /* NodeType */
aPiecekfba75362021-10-07 12:39:48 +0200112 LYXP_TOKEN_VARREF, /* VariableReference */
Radek Krejcib1646a92018-11-02 16:08:26 +0100113 LYXP_TOKEN_FUNCNAME, /* FunctionName */
Michal Vasko3e48bf32020-06-01 08:39:07 +0200114 LYXP_TOKEN_OPER_LOG, /* Operator 'and', 'or' */
115 LYXP_TOKEN_OPER_EQUAL, /* Operator '=' */
116 LYXP_TOKEN_OPER_NEQUAL, /* Operator '!=' */
117 LYXP_TOKEN_OPER_COMP, /* Operator '<', '<=', '>', '>=' */
118 LYXP_TOKEN_OPER_MATH, /* Operator '+', '-', '*', 'div', 'mod', '-' (unary) */
119 LYXP_TOKEN_OPER_UNI, /* Operator '|' */
120 LYXP_TOKEN_OPER_PATH, /* Operator '/' */
121 LYXP_TOKEN_OPER_RPATH, /* Operator '//' (recursive path) */
Radek Krejcib1646a92018-11-02 16:08:26 +0100122 /* LYXP_TOKEN_AXISNAME, * AxisName * axes not supported */
123 LYXP_TOKEN_LITERAL, /* Literal - with either single or double quote */
124 LYXP_TOKEN_NUMBER /* Number */
125};
126
127/**
128 * @brief XPath (sub)expressions that can be repeated.
129 */
130enum lyxp_expr_type {
131 LYXP_EXPR_NONE = 0,
132 LYXP_EXPR_OR,
133 LYXP_EXPR_AND,
134 LYXP_EXPR_EQUALITY,
135 LYXP_EXPR_RELATIONAL,
136 LYXP_EXPR_ADDITIVE,
137 LYXP_EXPR_MULTIPLICATIVE,
138 LYXP_EXPR_UNARY,
Michal Vasko69730152020-10-09 16:30:07 +0200139 LYXP_EXPR_UNION
Radek Krejcib1646a92018-11-02 16:08:26 +0100140};
141
142/**
Michal Vasko03ff5a72019-09-11 13:49:33 +0200143 * @brief Types of context nodes, #LYXP_NODE_ROOT_CONFIG used only in when or must conditions.
144 */
145enum lyxp_node_type {
Michal Vasko2caefc12019-11-14 16:07:56 +0100146 LYXP_NODE_NONE, /* invalid node type */
147
Michal Vasko03ff5a72019-09-11 13:49:33 +0200148 /* XML document roots */
149 LYXP_NODE_ROOT, /* access to all the data (node value first top-level node) */
150 LYXP_NODE_ROOT_CONFIG, /* <running> data context, no state data (node value first top-level node) */
151
152 /* XML elements */
Michal Vasko9f96a052020-03-10 09:41:45 +0100153 LYXP_NODE_ELEM, /* YANG data element (most common) */
154 LYXP_NODE_TEXT, /* YANG data text element (extremely specific use, unlikely to be ever needed) */
155 LYXP_NODE_META /* YANG metadata (do not use for the context node) */
Michal Vasko03ff5a72019-09-11 13:49:33 +0200156};
157
158/**
Radek Krejcib1646a92018-11-02 16:08:26 +0100159 * @brief Structure holding a parsed XPath expression.
160 */
161struct lyxp_expr {
aPiecek6da713d2021-10-11 12:50:28 +0200162 enum lyxp_token *tokens; /**< Array of tokens. */
163 uint16_t *tok_pos; /**< Array of the token offsets in expr. */
164 uint16_t *tok_len; /**< Array of token lengths in expr. */
165 enum lyxp_expr_type **repeat; /**< Array of expression types that this token begins and is repeated ended with 0,
166 more in the comment after this declaration. */
167 uint16_t used; /**< Used array items. */
168 uint16_t size; /**< Allocated array items. */
Radek Krejcib1646a92018-11-02 16:08:26 +0100169
aPiecek6da713d2021-10-11 12:50:28 +0200170 const char *expr; /**< The original XPath expression. */
Radek Krejcib1646a92018-11-02 16:08:26 +0100171};
172
173/*
174 * lyxp_expr repeat
175 *
176 * This value is NULL for all the tokens that do not begin an
177 * expression which can be repeated. Otherwise it is an array
178 * of expression types that this token begins. These values
179 * are used during evaluation to know whether we need to
180 * duplicate the current context or not and to decide what
181 * the current expression is (for example, if we are only
182 * starting the parsing and the first token has no repeat,
183 * we do not parse it as an OrExpr but directly as PathExpr).
184 * Examples:
185 *
aPiecekff49d762021-10-11 10:25:27 +0200186 * Expr: "/ *[key1 and key2 or key1 < key2]"
187 * Tokens: '/' '*' '[' NameTest 'and' NameTest 'or' NameTest '<' NameTest ']'
188 * Repeat: NULL NULL NULL _ NULL NULL NULL _ NULL NULL NULL
189 * | v
190 * v RelationalExpr 0
191 * AndExpr OrExpr 0
Radek Krejcib1646a92018-11-02 16:08:26 +0100192 *
aPiecekff49d762021-10-11 10:25:27 +0200193 * Expr: "//node[key and node2]/key | /cont"
194 * Tokens: '//' NameTest '[' NameTest 'and' NameTest ']' '/' NameTest '|' '/' NameTest
195 * Repeat: _ NULL NULL _ NULL NULL NULL NULL NULL NULL NULL NULL
196 * | v
197 * v AndExpr 0
198 * UnionExpr 0
Radek Krejcib1646a92018-11-02 16:08:26 +0100199 *
200 * Operators between expressions which this concerns:
201 * 'or', 'and', '=', '!=', '<', '>', '<=', '>=', '+', '-', '*', 'div', 'mod', '|'
202 */
203
204/**
205 * @brief Supported types of (partial) XPath results.
206 */
207enum lyxp_set_type {
Michal Vaskod3678892020-05-21 10:06:58 +0200208 LYXP_SET_NODE_SET = 0,
Michal Vasko03ff5a72019-09-11 13:49:33 +0200209 LYXP_SET_SCNODE_SET,
Radek Krejcib1646a92018-11-02 16:08:26 +0100210 LYXP_SET_BOOLEAN,
211 LYXP_SET_NUMBER,
212 LYXP_SET_STRING
213};
Radek Krejcib1646a92018-11-02 16:08:26 +0100214
215/**
216 * @brief Item stored in an XPath set hash table.
217 */
218struct lyxp_set_hash_node {
219 struct lyd_node *node;
220 enum lyxp_node_type type;
221} _PACKED;
222
Radek Krejcib1646a92018-11-02 16:08:26 +0100223/**
aPiecekdf23eee2021-10-07 12:21:50 +0200224 * @brief XPath variable bindings.
225 */
226struct lyxp_var {
227 char *name; /**< Variable name. In the XPath expression, the name is preceded by a '$' character. */
228 char *value; /**< The value of a variable is an object, which can be of any of the type that are possible
229 for the value of an expression. */
230};
231
232/**
Radek Krejcib1646a92018-11-02 16:08:26 +0100233 * @brief XPath set - (partial) result.
234 */
235struct lyxp_set {
aPiecek6da713d2021-10-11 12:50:28 +0200236 enum lyxp_set_type type; /**< Type of the object (value). */
Radek Krejcib1646a92018-11-02 16:08:26 +0100237 union {
238 struct lyxp_set_node {
aPiecek6da713d2021-10-11 12:50:28 +0200239 struct lyd_node *node; /**< Data node. */
240 enum lyxp_node_type type; /**< Type of the node. */
241 uint32_t pos; /**< Unique node position in the data. */
242 } *nodes; /**< Set of data nodes. */
Michal Vasko03ff5a72019-09-11 13:49:33 +0200243 struct lyxp_set_scnode {
aPiecek6da713d2021-10-11 12:50:28 +0200244 struct lysc_node *scnode; /**< Compiled YANG node. */
245 enum lyxp_node_type type; /**< Type of the node. */
Radek Krejcif13b87b2020-12-01 22:02:17 +0100246
Michal Vaskod97959c2020-12-10 12:18:28 +0100247/* _START and _ATOM values should have grouped values */
Radek Krejcif13b87b2020-12-01 22:02:17 +0100248#define LYXP_SET_SCNODE_START -2 /**< scnode not traversed, currently (the only node) in context */
249#define LYXP_SET_SCNODE_START_USED -1 /**< scnode not traversed except for the eval start, not currently in the context */
Michal Vasko1a09b212021-05-06 13:00:10 +0200250#define LYXP_SET_SCNODE_ATOM_NODE 0 /**< scnode was traversed, but not currently in the context */
251#define LYXP_SET_SCNODE_ATOM_VAL 1 /**< scnode was traversed and its value used, but not currently in the context */
252#define LYXP_SET_SCNODE_ATOM_CTX 2 /**< scnode currently in context */
253#define LYXP_SET_SCNODE_ATOM_NEW_CTX 3 /**< scnode in context and just added, so skip it for the current operation */
254#define LYXP_SET_SCNODE_ATOM_PRED_CTX 4 /**< includes any higher value - scnode is not in context because we are in
Radek Krejcif13b87b2020-12-01 22:02:17 +0100255 a predicate and this scnode was used/will be used later */
aPiecek6da713d2021-10-11 12:50:28 +0200256 int32_t in_ctx; /**< Flag specifies the state of the node in context. Values are defined
257 as LYXP_SET_SCNODE_* */
258 } *scnodes; /**< Set of compiled YANG data nodes. */
Michal Vasko9f96a052020-03-10 09:41:45 +0100259 struct lyxp_set_meta {
aPiecek6da713d2021-10-11 12:50:28 +0200260 struct lyd_meta *meta; /**< Node that provides information about metadata of a data element. */
261 enum lyxp_node_type type; /**< Type of the node. */
262 uint32_t pos; /**< Unique node position in the data. if node_type is LYXP_SET_NODE_META,
263 it is the parent node position */
264 } *meta; /**< Set of YANG metadata objects. */
265 char *str; /**< String object. */
266 long double num; /**< Object of the floating-point number. */
267 ly_bool bln; /**< Boolean object. */
268 } val; /**< Evaluated object (value). */
Radek Krejcib1646a92018-11-02 16:08:26 +0100269
Michal Vasko03ff5a72019-09-11 13:49:33 +0200270 /* this is valid only for type LYXP_SET_NODE_SET and LYXP_SET_SCNODE_SET */
aPiecek6da713d2021-10-11 12:50:28 +0200271 uint32_t used; /**< Number of nodes in the set. */
272 uint32_t size; /**< Allocated size for the set. */
273 struct hash_table *ht; /**< Hash table for quick determination of whether a node is in the set. */
Michal Vasko03ff5a72019-09-11 13:49:33 +0200274
275 /* XPath context information, this is valid only for type LYXP_SET_NODE_SET */
aPiecek6da713d2021-10-11 12:50:28 +0200276 uint32_t ctx_pos; /**< Position of the current examined node in the set. */
277 uint32_t ctx_size; /**< Position of the last node at the time the node was examined. */
Michal Vasko03ff5a72019-09-11 13:49:33 +0200278
279 /* general context */
aPiecek6da713d2021-10-11 12:50:28 +0200280 struct ly_ctx *ctx; /**< General context for logging. */
Michal Vasko03ff5a72019-09-11 13:49:33 +0200281 union {
aPiecek6da713d2021-10-11 12:50:28 +0200282 const struct lyd_node *cur_node; /**< Current (original context) node. */
283 const struct lysc_node *cur_scnode; /**< Current (original context) compiled node. */
Michal Vasko03ff5a72019-09-11 13:49:33 +0200284 };
aPiecek6da713d2021-10-11 12:50:28 +0200285 enum lyxp_node_type root_type; /**< Type of root node. */
286 const struct lysc_node *context_op; /**< Schema of the current node. */
287 const struct lyd_node *tree; /**< Data tree on which to perform the evaluation. */
288 const struct lys_module *cur_mod; /**< Current module for the expression (where it was "instantiated"). */
289 LY_VALUE_FORMAT format; /**< Format of the XPath expression. */
290 void *prefix_data; /**< Format-specific prefix data (see ::ly_resolve_prefix). */
aPiecekfba75362021-10-07 12:39:48 +0200291 const struct lyxp_var *vars; /**< XPath variables. [Sized array](@ref sizedarrays).
292 Set of variable bindings. */
Radek Krejcib1646a92018-11-02 16:08:26 +0100293};
294
295/**
Michal Vasko24cddf82020-06-01 08:17:01 +0200296 * @brief Print an XPath token \p tok type.
297 *
298 * @param[in] tok Token to print.
299 * @return Token type string.
300 */
301const char *lyxp_print_token(enum lyxp_token tok);
302
303/**
Michal Vasko03ff5a72019-09-11 13:49:33 +0200304 * @brief Evaluate an XPath expression on data. Be careful when using this function, the result can often
305 * be confusing without thorough understanding of XPath evaluation rules defined in RFC 7950.
Radek Krejcib1646a92018-11-02 16:08:26 +0100306 *
Michal Vasko400e9672021-01-11 13:39:17 +0100307 * @param[in] ctx libyang context to use.
Michal Vaskoecd62de2019-11-13 12:35:11 +0100308 * @param[in] exp Parsed XPath expression to be evaluated.
Michal Vasko5d24f6c2020-10-13 13:49:06 +0200309 * @param[in] cur_mod Current module for the expression (where it was "instantiated").
aPiecekb0445f22021-06-24 11:34:07 +0200310 * @param[in] format Format of the XPath expression (more specifically, of any used prefixes).
Michal Vasko5d24f6c2020-10-13 13:49:06 +0200311 * @param[in] prefix_data Format-specific prefix data (see ::ly_resolve_prefix).
312 * @param[in] ctx_node Current (context) data node, NULL in case of the root node.
Michal Vaskof03ed032020-03-04 13:31:44 +0100313 * @param[in] tree Data tree on which to perform the evaluation, it must include all the available data (including
Michal Vaskod3bb12f2020-12-04 14:33:09 +0100314 * the tree of @p ctx_node). Can be any node of the tree, it is adjusted.
aPiecekfba75362021-10-07 12:39:48 +0200315 * @param[in] vars [Sized array](@ref sizedarrays) of XPath variables.
Michal Vasko004d3152020-06-11 19:59:22 +0200316 * @param[out] set Result set.
Radek Krejcib1646a92018-11-02 16:08:26 +0100317 * @param[in] options Whether to apply some evaluation restrictions.
Michal Vasko004d3152020-06-11 19:59:22 +0200318 * @return LY_EVALID for invalid argument types/count,
319 * @return LY_EINCOMPLETE for unresolved when,
320 * @return LY_EINVAL, LY_EMEM, LY_EINT for other errors.
Radek Krejcib1646a92018-11-02 16:08:26 +0100321 */
Michal Vasko400e9672021-01-11 13:39:17 +0100322LY_ERR lyxp_eval(const struct ly_ctx *ctx, const struct lyxp_expr *exp, const struct lys_module *cur_mod,
Radek Krejci8df109d2021-04-23 12:19:08 +0200323 LY_VALUE_FORMAT format, void *prefix_data, const struct lyd_node *ctx_node, const struct lyd_node *tree,
aPiecekfba75362021-10-07 12:39:48 +0200324 const struct lyxp_var *vars, struct lyxp_set *set, uint32_t options);
Michal Vasko03ff5a72019-09-11 13:49:33 +0200325
Radek Krejcib1646a92018-11-02 16:08:26 +0100326/**
Michal Vasko03ff5a72019-09-11 13:49:33 +0200327 * @brief Get all the partial XPath nodes (atoms) that are required for @p exp to be evaluated.
Radek Krejcib1646a92018-11-02 16:08:26 +0100328 *
Michal Vasko400e9672021-01-11 13:39:17 +0100329 * @param[in] ctx libyang context to use.
Michal Vasko03ff5a72019-09-11 13:49:33 +0200330 * @param[in] exp Parsed XPath expression to be evaluated.
Michal Vasko5d24f6c2020-10-13 13:49:06 +0200331 * @param[in] cur_mod Current module for the expression (where it was "instantiated").
aPiecekb0445f22021-06-24 11:34:07 +0200332 * @param[in] format Format of the XPath expression (more specifically, of any used prefixes).
Michal Vasko5d24f6c2020-10-13 13:49:06 +0200333 * @param[in] prefix_data Format-specific prefix data (see ::ly_resolve_prefix).
334 * @param[in] ctx_scnode Current (context) schema node, NULL in case of the root node.
Michal Vasko004d3152020-06-11 19:59:22 +0200335 * @param[out] set Result set.
Radek Krejcib1646a92018-11-02 16:08:26 +0100336 * @param[in] options Whether to apply some evaluation restrictions, one flag must always be used.
Radek Krejci8678fa42020-08-18 16:07:28 +0200337 * @return LY_ERR (same as ::lyxp_eval()).
Radek Krejcib1646a92018-11-02 16:08:26 +0100338 */
Michal Vasko400e9672021-01-11 13:39:17 +0100339LY_ERR lyxp_atomize(const struct ly_ctx *ctx, const struct lyxp_expr *exp, const struct lys_module *cur_mod,
Radek Krejci8df109d2021-04-23 12:19:08 +0200340 LY_VALUE_FORMAT format, void *prefix_data, const struct lysc_node *ctx_scnode, struct lyxp_set *set,
Michal Vasko400e9672021-01-11 13:39:17 +0100341 uint32_t options);
Radek Krejcib1646a92018-11-02 16:08:26 +0100342
Michal Vasko4ad69e72021-10-26 16:25:55 +0200343/** used only internally, maps with @ref findxpathoptions */
Michal Vaskoa27245c2022-05-02 09:01:35 +0200344#define LYXP_IGNORE_WHEN 0x01 /**< Ignore unevaluated when in data nodes and do not return ::LY_EINCOMPLETE. */
345#define LYXP_SCHEMA 0x02 /**< Apply data node access restrictions defined for 'when' and 'must' evaluation. */
346#define LYXP_SCNODE 0x04 /**< No special tree access modifiers. */
347#define LYXP_SCNODE_SCHEMA LYS_FIND_XP_SCHEMA /**< Apply node access restrictions defined for 'when' and 'must' evaluation. */
348#define LYXP_SCNODE_OUTPUT LYS_FIND_XP_OUTPUT /**< Search RPC/action output nodes instead of input ones. */
349#define LYXP_SCNODE_ALL 0x1C /**< mask for all the LYXP_* values */
350#define LYXP_SKIP_EXPR 0x20 /**< The rest of the expression will not be evaluated (lazy evaluation) */
351#define LYXP_SCNODE_ERROR LYS_FIND_NO_MATCH_ERROR /**< Return error if a path segment matches no nodes, otherwise only
352 warning is printed. */
353#define LYXP_ACCESS_TREE_ALL 0x80 /**< Explicit accessible tree of all the nodes. */
354#define LYXP_ACCESS_TREE_CONFIG 0x0100 /**< Explicit accessible tree of only configuration data. */
Radek Krejcib1646a92018-11-02 16:08:26 +0100355
356/**
Radek Krejcib1646a92018-11-02 16:08:26 +0100357 * @brief Cast XPath set to another type.
358 * Indirectly context position aware.
359 *
360 * @param[in] set Set to cast.
361 * @param[in] target Target type to cast \p set into.
Michal Vasko03ff5a72019-09-11 13:49:33 +0200362 * @return LY_ERR
Radek Krejcib1646a92018-11-02 16:08:26 +0100363 */
Michal Vasko5e0e6eb2019-11-06 15:47:50 +0100364LY_ERR lyxp_set_cast(struct lyxp_set *set, enum lyxp_set_type target);
Michal Vasko03ff5a72019-09-11 13:49:33 +0200365
Radek Krejcib1646a92018-11-02 16:08:26 +0100366/**
Michal Vaskod3678892020-05-21 10:06:58 +0200367 * @brief Free dynamic content of a set.
368 *
369 * @param[in] set Set to modify.
370 */
371void lyxp_set_free_content(struct lyxp_set *set);
372
373/**
Michal Vaskoecd62de2019-11-13 12:35:11 +0100374 * @brief Insert schema node into set.
375 *
376 * @param[in] set Set to insert into.
377 * @param[in] node Node to insert.
378 * @param[in] node_type Node type of @p node.
Radek Krejciaa6b53f2020-08-27 15:19:03 +0200379 * @param[out] index_p Optional pointer to store index if the inserted @p node.
380 * @return LY_SUCCESS on success.
381 * @return LY_EMEM on memory allocation failure.
Michal Vaskoecd62de2019-11-13 12:35:11 +0100382 */
Michal Vaskoee38a5d2020-11-09 21:02:18 +0100383LY_ERR lyxp_set_scnode_insert_node(struct lyxp_set *set, const struct lysc_node *node, enum lyxp_node_type node_type,
384 uint32_t *index_p);
Michal Vaskoecd62de2019-11-13 12:35:11 +0100385
386/**
387 * @brief Check for duplicates in a schema node set.
388 *
389 * @param[in] set Set to check.
390 * @param[in] node Node to look for in @p set.
391 * @param[in] node_type Type of @p node.
392 * @param[in] skip_idx Index from @p set to skip.
Radek Krejciaa6b53f2020-08-27 15:19:03 +0200393 * @param[out] index_p Optional pointer to store index if the node is found.
Radek Krejci857189e2020-09-01 13:26:36 +0200394 * @return Boolean value whether the @p node found or not.
Michal Vaskoecd62de2019-11-13 12:35:11 +0100395 */
Radek Krejci857189e2020-09-01 13:26:36 +0200396ly_bool lyxp_set_scnode_contains(struct lyxp_set *set, const struct lysc_node *node, enum lyxp_node_type node_type,
Radek Krejciaa6b53f2020-08-27 15:19:03 +0200397 int skip_idx, uint32_t *index_p);
Michal Vaskoecd62de2019-11-13 12:35:11 +0100398
399/**
400 * @brief Merge 2 schema node sets.
401 *
402 * @param[in] set1 Set to merge into.
403 * @param[in] set2 Set to merge. Its content is freed.
404 */
405void lyxp_set_scnode_merge(struct lyxp_set *set1, struct lyxp_set *set2);
406
407/**
Radek Krejcib1646a92018-11-02 16:08:26 +0100408 * @brief Parse an XPath expression into a structure of tokens.
409 * Logs directly.
410 *
Michal Vasko03ff5a72019-09-11 13:49:33 +0200411 * https://www.w3.org/TR/1999/REC-xpath-19991116/#exprlex
Radek Krejcib1646a92018-11-02 16:08:26 +0100412 *
413 * @param[in] ctx Context for errors.
Radek Krejcif03a9e22020-09-18 20:09:31 +0200414 * @param[in] expr_str XPath expression to parse. It is duplicated.
Michal Vasko004d3152020-06-11 19:59:22 +0200415 * @param[in] expr_len Length of @p expr, can be 0 if @p expr is 0-terminated.
416 * @param[in] reparse Whether to re-parse the expression to finalize full XPath parsing and fill
417 * information about expressions and their operators (fill repeat).
Radek Krejcif03a9e22020-09-18 20:09:31 +0200418 * @param[out] expr_p Pointer to return the filled expression structure.
419 * @return LY_SUCCESS in case of success.
420 * @return LY_EMEM in case of memory allocation failure.
421 * @return LY_EVALID in case of invalid XPath expression in @p expr_str.
Radek Krejcib1646a92018-11-02 16:08:26 +0100422 */
Michal Vaskoee38a5d2020-11-09 21:02:18 +0100423LY_ERR lyxp_expr_parse(const struct ly_ctx *ctx, const char *expr_str, size_t expr_len, ly_bool reparse,
424 struct lyxp_expr **expr_p);
Michal Vasko004d3152020-06-11 19:59:22 +0200425
426/**
427 * @brief Duplicate parsed XPath expression.
428 *
429 * @param[in] ctx Context with a dictionary.
430 * @param[in] exp Parsed expression.
Michal Vasko1734be92020-09-22 08:55:10 +0200431 * @param[out] dup Duplicated structure.
432 * @return LY_ERR value.
Michal Vasko004d3152020-06-11 19:59:22 +0200433 */
Michal Vasko1734be92020-09-22 08:55:10 +0200434LY_ERR lyxp_expr_dup(const struct ly_ctx *ctx, const struct lyxp_expr *exp, struct lyxp_expr **dup);
Michal Vasko14676352020-05-29 11:35:55 +0200435
436/**
437 * @brief Look at the next token and check its kind.
438 *
439 * @param[in] ctx Context for logging, not logged if NULL.
440 * @param[in] exp Expression to use.
Michal Vasko004d3152020-06-11 19:59:22 +0200441 * @param[in] tok_idx Token index in the expression \p exp.
Michal Vasko14676352020-05-29 11:35:55 +0200442 * @param[in] want_tok Expected token.
443 * @return LY_EINCOMPLETE on EOF,
444 * @return LY_ENOT on non-matching token,
445 * @return LY_SUCCESS on success.
446 */
Michal Vasko004d3152020-06-11 19:59:22 +0200447LY_ERR lyxp_check_token(const struct ly_ctx *ctx, const struct lyxp_expr *exp, uint16_t tok_idx, enum lyxp_token want_tok);
448
449/**
450 * @brief Look at the next token and skip it if it matches the expected one.
451 *
452 * @param[in] ctx Context for logging, not logged if NULL.
453 * @param[in] exp Expression to use.
454 * @param[in,out] tok_idx Token index in the expression \p exp, is updated.
455 * @param[in] want_tok Expected token.
456 * @return LY_EINCOMPLETE on EOF,
457 * @return LY_ENOT on non-matching token,
458 * @return LY_SUCCESS on success.
459 */
460LY_ERR lyxp_next_token(const struct ly_ctx *ctx, const struct lyxp_expr *exp, uint16_t *tok_idx, enum lyxp_token want_tok);
Radek Krejcib1646a92018-11-02 16:08:26 +0100461
462/**
Michal Vasko4911eeb2021-06-28 11:23:05 +0200463 * @brief Look at the next token and skip it if it matches either of the 2 expected ones.
464 *
465 * @param[in] ctx Context for logging, not logged if NULL.
466 * @param[in] exp Expression to use.
467 * @param[in,out] tok_idx Token index in the expression \p exp, is updated.
468 * @param[in] want_tok1 Expected token 1.
469 * @param[in] want_tok2 Expected token 2.
470 * @return LY_EINCOMPLETE on EOF,
471 * @return LY_ENOT on non-matching token,
472 * @return LY_SUCCESS on success.
473 */
474LY_ERR lyxp_next_token2(const struct ly_ctx *ctx, const struct lyxp_expr *exp, uint16_t *tok_idx,
475 enum lyxp_token want_tok1, enum lyxp_token want_tok2);
476
477/**
aPiecekdf23eee2021-10-07 12:21:50 +0200478 * @brief Find variable named @name in @p vars.
479 *
480 * @param[in] vars [Sized array](@ref sizedarrays) of XPath variables.
481 * @param[in] name Name of the variable being searched.
482 * @param[in] name_len Name length can be set to 0 if @p name is terminated by null byte.
483 * @param[out] var Variable that was found. The parameter is optional.
484 * @return LY_SUCCESS if the variable was found, otherwise LY_ENOTFOUND.
485 */
486LY_ERR lyxp_vars_find(struct lyxp_var *vars, const char *name, size_t name_len, struct lyxp_var **var);
487
488/**
Michal Vasko03ff5a72019-09-11 13:49:33 +0200489 * @brief Frees a parsed XPath expression. @p expr should not be used afterwards.
Radek Krejcib1646a92018-11-02 16:08:26 +0100490 *
491 * @param[in] ctx libyang context of the expression.
492 * @param[in] expr Expression to free.
493 */
Michal Vasko14676352020-05-29 11:35:55 +0200494void lyxp_expr_free(const struct ly_ctx *ctx, struct lyxp_expr *expr);
Radek Krejcib1646a92018-11-02 16:08:26 +0100495
Michal Vasko14676352020-05-29 11:35:55 +0200496#endif /* LY_XPATH_H */