blob: f3e88b0e22223a8a0517d9025aed942839a2a144 [file] [log] [blame]
Michal Vasko004d3152020-06-11 19:59:22 +02001/**
2 * @file path.h
3 * @author Michal Vasko <mvasko@cesnet.cz>
4 * @brief Path structure and manipulation routines.
5 *
6 * Copyright (c) 2020 CESNET, z.s.p.o.
7 *
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
15#ifndef LY_PATH_H_
16#define LY_PATH_H_
17
Radek Krejciad97c5f2020-06-30 09:19:28 +020018#include <stddef.h>
Michal Vasko004d3152020-06-11 19:59:22 +020019#include <stdint.h>
20
21#include "log.h"
Michal Vasko00cbf532020-06-15 13:58:47 +020022#include "tree.h"
Michal Vasko004d3152020-06-11 19:59:22 +020023#include "tree_data.h"
24
Radek Krejciad97c5f2020-06-30 09:19:28 +020025struct ly_ctx;
Michal Vasko405cc9e2020-12-01 12:01:27 +010026struct lys_glob_unres;
Radek Krejci0aa1f702021-04-01 16:16:19 +020027struct lys_module;
28struct lysc_ext_instance;
29struct lysc_node;
Michal Vasko004d3152020-06-11 19:59:22 +020030struct lyxp_expr;
31
32enum ly_path_pred_type {
33 LY_PATH_PREDTYPE_NONE = 0, /**< no predicate */
34 LY_PATH_PREDTYPE_POSITION, /**< position predicate - [2] */
35 LY_PATH_PREDTYPE_LIST, /**< keys predicate - [key1='val1'][key2='val2']... */
36 LY_PATH_PREDTYPE_LEAFLIST /**< leaflist value predicate - [.='value'] */
37};
38
39/**
Christian Hopps61213e02021-04-12 20:41:32 -040040 * @brief Structure for simple path predicate.
41 */
42struct ly_path_predicate {
43 union {
44 uint64_t position; /**< position value for the position-predicate */
45 struct {
46 const struct lysc_node *key; /**< key node of the predicate, NULL in
47 case of a leaf-list predicate */
48 struct lyd_value value; /**< value representation according to the
49 key's type, its realtype is allocated */
50 };
51 };
52};
53
54/**
55 * @brief Structure for holding one segment of resolved path on schema including
56 * simple predicates. Is used as a [sized array](@ref sizedarrays).
Michal Vasko004d3152020-06-11 19:59:22 +020057 */
58struct ly_path {
59 const struct lysc_node *node; /**< Schema node representing the path segment, first node has special meaning:
60 - is a top-level node - path is absolute,
61 - is inner node - path is relative */
Christian Hopps61213e02021-04-12 20:41:32 -040062 struct ly_path_predicate *predicates; /**< [Sized array](@ref sizedarrays) of the path segment's predicates */
Michal Vasko004d3152020-06-11 19:59:22 +020063 enum ly_path_pred_type pred_type; /**< Predicate type (see YANG ABNF) */
64};
65
66/**
67 * @defgroup path_begin_options Path begin options.
68 * @{
69 */
70#define LY_PATH_BEGIN_ABSOLUTE 0x01 /**< path must be absolute */
71#define LY_PATH_BEGIN_EITHER 0x02 /**< path be be iether absolute or relative */
72/** @} */
73
74/**
75 * @defgroup path_lref_options Path leafref options.
76 * @{
77 */
78#define LY_PATH_LREF_FALSE 0x04 /**< path does not represent leafref */
79#define LY_PATH_LREF_TRUE 0x08 /* '..' in path allowed, special leafref predicates expected (but are not compiled),
80 implement traversed modules */
81/** @} */
82
83/**
84 * @defgroup path_prefix_options Path prefix options.
85 * @{
86 */
87#define LY_PATH_PREFIX_OPTIONAL 0x10 /**< prefixes in the path are optional */
Michal Vasko8b06a5e2020-08-06 12:13:08 +020088#define LY_PATH_PREFIX_MANDATORY 0x20 /**< prefixes in the path are mandatory (XML instance-identifier) */
89#define LY_PATH_PREFIX_STRICT_INHERIT 0x30 /**< prefixes in the path are mandatory in case they differ from the
90 previous prefixes, otherwise they are prohibited (JSON instance-identifier) */
Michal Vasko004d3152020-06-11 19:59:22 +020091/** @} */
92
93/**
94 * @defgroup path_pred_options Path predicate options.
95 * @{
96 */
97#define LY_PATH_PRED_KEYS 0x40 /* expected predicate only - [node='value']* */
98#define LY_PATH_PRED_SIMPLE 0x80 /* expected predicates - [node='value']*; [.='value']; [1] */
99#define LY_PATH_PRED_LEAFREF 0xC0 /* expected predicates only leafref - [node=current()/../../../node/node];
100 at least 1 ".." and 1 "node" after */
101/** @} */
102
103/**
104 * @brief Parse path into XPath token structure and perform all additional checks.
105 *
106 * @param[in] ctx libyang context.
Michal Vaskoaef00cb2020-10-16 11:58:57 +0200107 * @param[in] ctx_node Optional context node, used for logging.
Michal Vasko004d3152020-06-11 19:59:22 +0200108 * @param[in] str_path Path to parse.
109 * @param[in] path_len Length of @p str_path.
110 * @param[in] begin Begin option (@ref path_begin_options).
111 * @param[in] lref Lref option (@ref path_lref_options).
112 * @param[in] prefix Prefix option (@ref path_prefix_options).
113 * @param[in] pred Predicate option (@ref path_pred_options).
114 * @param[out] expr Parsed path.
115 * @return LY_ERR value.
116 */
Michal Vasko6b26e742020-07-17 15:02:10 +0200117LY_ERR ly_path_parse(const struct ly_ctx *ctx, const struct lysc_node *ctx_node, const char *str_path, size_t path_len,
Radek Krejci0f969882020-08-21 16:56:47 +0200118 uint8_t begin, uint8_t lref, uint8_t prefix, uint8_t pred, struct lyxp_expr **expr);
Michal Vasko004d3152020-06-11 19:59:22 +0200119
120/**
121 * @brief Parse predicate into XPath token structure and perform all additional checks.
122 *
123 * @param[in] ctx libyang context.
Michal Vaskoaef00cb2020-10-16 11:58:57 +0200124 * @param[in] cur_node Optional current (original context) node, used for logging.
Michal Vasko004d3152020-06-11 19:59:22 +0200125 * @param[in] str_path Path to parse.
126 * @param[in] path_len Length of @p str_path.
127 * @param[in] prefix Prefix option (@ref path_prefix_options).
128 * @param[in] pred Predicate option (@ref path_pred_options).
129 * @param[out] expr Parsed path.
130 * @return LY_ERR value.
131 */
Michal Vasko6b26e742020-07-17 15:02:10 +0200132LY_ERR ly_path_parse_predicate(const struct ly_ctx *ctx, const struct lysc_node *cur_node, const char *str_path,
Radek Krejci0f969882020-08-21 16:56:47 +0200133 size_t path_len, uint8_t prefix, uint8_t pred, struct lyxp_expr **expr);
Michal Vasko004d3152020-06-11 19:59:22 +0200134
135/**
Michal Vasko00cbf532020-06-15 13:58:47 +0200136 * @defgroup path_oper_options Path operation options.
137 * @{
138 */
139#define LY_PATH_OPER_INPUT 0x01 /**< if any RPC/action is traversed, its input nodes are used */
140#define LY_PATH_OPER_OUTPUT 0x02 /**< if any RPC/action is traversed, its output nodes are used */
141/** @} */
142
143/* lref */
144
145/**
146 * @defgroup path_target_options Path target options.
147 * @{
148 */
149#define LY_PATH_TARGET_SINGLE 0x10 /**< last (target) node must identify an exact instance */
150#define LY_PATH_TARGET_MANY 0x20 /**< last (target) node may identify all instances (of leaf-list/list) */
151/** @} */
152
153/**
Michal Vasko004d3152020-06-11 19:59:22 +0200154 * @brief Compile path into ly_path structure. Any predicates of a leafref are only checked, not compiled.
155 *
Michal Vasko00cbf532020-06-15 13:58:47 +0200156 * @param[in] ctx libyang context.
Michal Vasko5d24f6c2020-10-13 13:49:06 +0200157 * @param[in] cur_mod Current module of the path (where it was "instantiated"). Used for nodes without a prefix
158 * for ::LY_PREF_SCHEMA* format.
Michal Vasko6b26e742020-07-17 15:02:10 +0200159 * @param[in] ctx_node Optional context node.
Radek Krejcid5d37432021-03-12 13:46:40 +0100160 * @param[in] ext Extension instance containing the definition of the data being created. It is used to find the top-level
161 * node inside the extension instance instead of a module. Note that this is the case not only if the @p ctx_node is NULL,
162 * but also if the relative path starting in @p ctx_node reaches the document root via double dots.
Michal Vasko004d3152020-06-11 19:59:22 +0200163 * @param[in] expr Parsed path.
164 * @param[in] lref Lref option (@ref path_lref_options).
Michal Vasko00cbf532020-06-15 13:58:47 +0200165 * @param[in] oper Oper option (@ref path_oper_options).
166 * @param[in] target Target option (@ref path_target_options).
Michal Vasko004d3152020-06-11 19:59:22 +0200167 * @param[in] format Format of the path.
Michal Vaskoc8a230d2020-08-14 12:17:10 +0200168 * @param[in] prefix_data Format-specific data for resolving any prefixes (see ::ly_resolve_prefix).
Michal Vasko405cc9e2020-12-01 12:01:27 +0100169 * @param[in,out] unres Global unres structure for newly implemented modules, needed only if @p lref is ::LY_PATH_LREF_TRUE.
Michal Vasko004d3152020-06-11 19:59:22 +0200170 * @param[out] path Compiled path.
171 * @return LY_ERR value.
172 */
Michal Vasko00cbf532020-06-15 13:58:47 +0200173LY_ERR ly_path_compile(const struct ly_ctx *ctx, const struct lys_module *cur_mod, const struct lysc_node *ctx_node,
Radek Krejcid5d37432021-03-12 13:46:40 +0100174 const struct lysc_ext_instance *ext, const struct lyxp_expr *expr, uint8_t lref, uint8_t oper, uint8_t target,
175 LY_PREFIX_FORMAT format, void *prefix_data, struct lys_glob_unres *unres, struct ly_path **path);
Michal Vasko004d3152020-06-11 19:59:22 +0200176
177/**
178 * @brief Compile predicate into ly_path_predicate structure. Only simple predicates (not leafref) are supported.
179 *
Michal Vasko00cbf532020-06-15 13:58:47 +0200180 * @param[in] ctx libyang context.
Michal Vasko6b26e742020-07-17 15:02:10 +0200181 * @param[in] cur_node Optional current (original context) node.
Michal Vasko5d24f6c2020-10-13 13:49:06 +0200182 * @param[in] cur_mod Current module of the path (where it was "instantiated"). Used for nodes without a prefix
183 * for ::LY_PREF_SCHEMA* format.
Michal Vasko004d3152020-06-11 19:59:22 +0200184 * @param[in] ctx_node Context node, node for which the predicate is defined.
185 * @param[in] expr Parsed path.
186 * @param[in,out] tok_idx Index in @p expr, is adjusted for parsed tokens.
Michal Vasko004d3152020-06-11 19:59:22 +0200187 * @param[in] format Format of the path.
Michal Vaskoc8a230d2020-08-14 12:17:10 +0200188 * @param[in] prefix_data Format-specific data for resolving any prefixes (see ::ly_resolve_prefix).
Michal Vasko004d3152020-06-11 19:59:22 +0200189 * @param[out] predicates Compiled predicates.
190 * @param[out] pred_type Type of the compiled predicate(s).
191 * @return LY_ERR value.
192 */
Michal Vasko6b26e742020-07-17 15:02:10 +0200193LY_ERR ly_path_compile_predicate(const struct ly_ctx *ctx, const struct lysc_node *cur_node, const struct lys_module *cur_mod,
Michal Vasko5d24f6c2020-10-13 13:49:06 +0200194 const struct lysc_node *ctx_node, const struct lyxp_expr *expr, uint16_t *tok_idx, LY_PREFIX_FORMAT format,
195 void *prefix_data, struct ly_path_predicate **predicates, enum ly_path_pred_type *pred_type);
Michal Vasko00cbf532020-06-15 13:58:47 +0200196
197/**
198 * @brief Resolve at least partially the target defined by ly_path structure. Not supported for leafref!
199 *
200 * @param[in] path Path structure specifying the target.
201 * @param[in] start Starting node for relative paths, can be any for absolute paths.
202 * @param[out] path_idx Last found path segment index, can be NULL, set to 0 if not found.
203 * @param[out] match Last found matching node, can be NULL, set to NULL if not found.
204 * @return LY_ENOTFOUND if no nodes were found,
205 * @return LY_EINCOMPLETE if some node was found but not the last one,
206 * @return LY_SUCCESS when the last node in the path was found,
207 * @return LY_ERR on another error.
208 */
Michal Vaskofd69e1d2020-07-03 11:57:17 +0200209LY_ERR ly_path_eval_partial(const struct ly_path *path, const struct lyd_node *start, LY_ARRAY_COUNT_TYPE *path_idx,
Radek Krejci0f969882020-08-21 16:56:47 +0200210 struct lyd_node **match);
Michal Vasko004d3152020-06-11 19:59:22 +0200211
212/**
213 * @brief Resolve the target defined by ly_path structure. Not supported for leafref!
214 *
215 * @param[in] path Path structure specifying the target.
216 * @param[in] start Starting node for relative paths, can be any for absolute paths.
217 * @param[out] match Found matching node, can be NULL, set to NULL if not found.
218 * @return LY_ENOTFOUND if no nodes were found,
219 * @return LY_SUCCESS when the last node in the path was found,
220 * @return LY_ERR on another error.
221 */
222LY_ERR ly_path_eval(const struct ly_path *path, const struct lyd_node *start, struct lyd_node **match);
223
224/**
225 * @brief Duplicate ly_path structure.
226 *
227 * @param[in] ctx libyang context.
228 * @param[in] path Path to duplicate.
229 * @param[out] dup Duplicated path.
230 * @return LY_ERR value.
231 */
232LY_ERR ly_path_dup(const struct ly_ctx *ctx, const struct ly_path *path, struct ly_path **dup);
233
234/**
235 * @brief Free ly_path_predicate structure.
236 *
237 * @param[in] ctx libyang context.
238 * @param[in] pred_type Predicate type.
Michal Vasko004d3152020-06-11 19:59:22 +0200239 * @param[in] predicates Predicates ([sized array](@ref sizedarrays)) to free.
240 */
Michal Vaskof7e16e22020-10-21 09:24:39 +0200241void ly_path_predicates_free(const struct ly_ctx *ctx, enum ly_path_pred_type pred_type,
Radek Krejci0f969882020-08-21 16:56:47 +0200242 struct ly_path_predicate *predicates);
Michal Vasko004d3152020-06-11 19:59:22 +0200243
244/**
245 * @brief Free ly_path structure.
246 *
247 * @param[in] ctx libyang context.
248 * @param[in] path The structure ([sized array](@ref sizedarrays)) to free.
249 */
250void ly_path_free(const struct ly_ctx *ctx, struct ly_path *path);
251
252#endif /* LY_PATH_H_ */