blob: 33deff354636f5120cc12d2b98c76f3f65337b6f [file] [log] [blame]
Radek Krejci8678fa42020-08-18 16:07:28 +02001/**
2 * @page transition Transition Manual (1.x -> 2.0)
Radek Krejcifba9c622020-10-30 08:28:54 +01003 *
Radek Krejci8678fa42020-08-18 16:07:28 +02004 * [TOC]
Radek Krejcifba9c622020-10-30 08:28:54 +01005 *
6 * Rewriting libyang codebase and creating libyang version 2.0 was motivated mainly by improving long term maintainability.
7 * Especially some of the features and design decisions become killers for further development and maintaining the libyang
8 * codebase. On the other hand, most of the principles introduced in libyang 1.x to handle YANG schemas and manipulate
9 * instantiated data have proved successful. Therefore, we have decided to keep the basic mechanisms from version 1.x and
10 * remove the problematic features and modify the improper design decisions. Despite the vision to keep with the mechanisms
11 * also the API, the new version became a great opportunity to clean up the API and improve its usability mainly by unifying
12 * how the libyang functions are used. So, in the end, this manual is not just a description of the removed features listing
13 * removed, modified or added functions. The API should be even better prepared for adding new features and functions.
14 * Shortly, almost everything has changed at least a little, so you cannot move from version 1.x to 2.0 just by replacing
15 * code snippets. However, we believe that the change is good and libyang 2.0 is simply better.
16 *
17 * In this Manual, we want to introduce the differences between libyang 1.x and 2.0. It is intended for the transition
18 * from 1.x to 2.0, so if you are new to libyang, simply go to the @ref howto section, this Manual is not for you.
19 *
20 * The complete generated list of changes (without any additional notes) can be found in
21 * <a href="../compat_report.html">the compatibility report</a>.
22 *
23 * @section transitionGeneral General Changes
24 *
25 *
26 * @subsection transitionGeneralErros Errors Handling
27 *
28 * The most visible change is probably the changed approach to handling errors. While libyang 1.x was using variable
29 * *ly_errno* to provide error information in case the called function failed, there is no such variable in libyang 2.0.
30 * On the other hand, most API functions now return ::LY_ERR values directly stating the result. In addition, in case
31 * the error is somehow connected with the [context](@ref howtoContext), more detailed error information can be obtained
32 * from the context handler itself. Mainly this change is responsible for the backward incompatibility of almost all
33 * functions between versions 1.x and 2.0.
34 *
35 * Here is the overview of the changed / removed / added functions connected with errors and logging.
36 *
37 * libyang 1.x | libyang 2.0 | Notes
38 * :-------------------------|:-------------------------------------|:-------------------------------------------------------
39 * - | ::ly_err_last() | New API for handling errors.
40 * - | ::ly_errcode() | ^
41 * ly_verb_dbg() | ::ly_log_dbg_groups() | Rename to align with the names of the accepted values.
42 * ly_verb() | ::ly_log_level() | ^
43 *
44 * More information about error handling in libyang 2.0 can be found at @ref howtoErrors page.
45 *
46 * @subsection transitionGeneralInOut Input / Output Processing
47 *
48 * libyang 2.0 introduces input (::ly_in) and output (::ly_out) handlers covering the specific input sources for parsers and
49 * output targets for printers. They are supposed mainly to simplify parser's and printer's API to avoid the need for
50 * separate functions for each source/target. The handlers can be used repeatedly to split the inputs or join the outputs.
51 *
52 * More information can be found at @ref howtoInput and @ref howtoOutput pages.
53 *
54 *
55 * @subsection transitionGeneralOutputFormatting Output Formatting
56 *
57 * In libyang 1.x, there was an inconsistency in printing schemas and data. While the schemas were always printed formatted,
58 * the data were printed by default without additional indentation. It is clearly visible in the YIN format of the schema,
59 * which is XML, and the XML encoding of the data. While there was a possibility to format data output with the LYP_FORMAT
60 * flag, it wasn't possible to change schema output formatting.
Michal Vaskoa24b9af2020-11-09 20:57:39 +010061 *
Radek Krejcifba9c622020-10-30 08:28:54 +010062 * libyang 2.0 unifies the behavior of all printers. By default, all the output formats are formatted now. Both, the data as
63 * well as the schema printers, accept the option to remove additional formatting (different for the specific format, usually
64 * indentations and blank lines): ::LYD_PRINT_SHRINK for the data printer and ::LYS_PRINT_SHRINK for the schema printer.
65 *
66 *
67 * @subsection transitionGeneralXPath Addressing
68 *
69 * If you compare the @ref howtoXPath page from libyang 1.x and 2.0 documentation, you will be probably confused since they
70 * seem very different. In fact, we have tried to simplify the API by removing the original Schema path format from the
71 * public API. Since this format is used in YANG format, libyang still supports it internally, but it is not possible to use
72 * it anywhere in the API. The new formats XPath and Path, mentioned at the @ref howtoXPath page, are both the Data paths
73 * used in libyang 1.x. The Path format is a subset of XPath format limited to refer to a single node.
74 *
75 * This change was reflected in functions serving to get a node based on the specified path. Unfortunately, when comparing
76 * old and new API, the transition can be confusing since the names are sometimes overloaded (be careful mainly of
77 * ::lys_find_path()). The following table depicts the changes, but probably a better approach is to handle the functions as
78 * a completely new API.
79 *
80 * libyang 1.x | libyang 2.0 | Notes
81 * :-------------------------|:-------------------------------------|:-------------------------------------------------------
82 * ly_ctx_find_path() | - | To simplify the different [types of paths](@ref howtoXPath), the Schema path format is not supported for now. If there will be use cases for it, it can be re-added later, but for now try using ::lys_find_xpath().
83 * %lys_find_path() | - | To simplify the different [types of paths](@ref howtoXPath), the Schema path format is not supported for now. If there will be use cases for it, it can be re-added later, but for now try using ::lys_find_xpath().
84 * ly_ctx_get_node() | ::lys_find_path() | Renamed to unify API functions, note that there was lys_find_path in libyang 1.x with different functionality in comparison to the function of the same name from libyang 2.0.
85 * - | ::lys_find_path_atoms() | Extension of ::lys_find_path().
86 * - | ::lys_find_lypath_atoms() | ^
87 * - | ::lys_find_xpath() | New function reflecting updated @ref howtoXPath\.
88 * lys_xpath_atomize() | ::lys_find_xpath_atoms() | Rename to unify with the new API, extends ::lys_find_xpath().
89 * - | ::lys_find_expr_atoms() | Extension of ::lys_find_xpath().
Radek Krejci635d2b82021-01-04 11:26:51 +010090 * %lyd_path() | ::lyd_path() | Same purpose, just extended functionality.
Radek Krejcifba9c622020-10-30 08:28:54 +010091 * lyd_find_path() | ::lyd_find_xpath() | Rename to unify with the new API.
Michal Vasko257bdcf2021-01-14 13:15:30 +010092 * - | ::lyd_find_path() | Simplified version of ::lyd_find_path().
Radek Krejcifba9c622020-10-30 08:28:54 +010093 * - | ::lyxp_get_expr() | Added functionality due to the changed representation of XPath expressions.
94 * ly_path_data2schema() | - | Removed since the schema path is not available in API.
95 * ly_path_xml2json() | - | Removed since done internally, note that even the generic XML parser is not available now.
96 * lys_node_xpath_atomize() | - | Removed as useless/redundant, use ::lys_find_xpath_atoms().
97 *
Radek Krejci8678fa42020-08-18 16:07:28 +020098 * @section transitionContext Context
Radek Krejci8678fa42020-08-18 16:07:28 +020099 *
Radek Krejcifba9c622020-10-30 08:28:54 +0100100 * Context, as a concept of a storage interconnecting YANG modules into a YANG schema and YANG schema with the instantiated
101 * data, was preserved. However, it is now more supposed to be prepared just once before connecting it with any instantiated
102 * data. The possibility of removing YANG modules from the context was completely dropped. Furthermore, we would like to
103 * introduce some kind of context lock to completely abandon any change of the YANG modules after starting work with the
104 * instantiated data.
Radek Krejci8678fa42020-08-18 16:07:28 +0200105 *
Radek Krejcifba9c622020-10-30 08:28:54 +0100106 * Other significant changes connected with the context are depicted in the following table.
Radek Krejci8678fa42020-08-18 16:07:28 +0200107 *
Radek Krejcifba9c622020-10-30 08:28:54 +0100108 * libyang 1.x | libyang 2.0 | Notes
109 * :-------------------------|:-------------------------------------|:-------------------------------------------------------
110 * ly_ctx_clean() | - | Removed functionality of manipulating with the context and the modules already placed in the context.
111 * ly_ctx_remove_module() | - | ^
112 * ly_ctx_set_module_data_clb() and the associated ly_module_data_clb type. | - | ^
113 * ly_ctx_get_disabled_module() and the associated ly_ctx_get_disabled_module_iter() | - | ^
114 * ly_ctx_info() | ::ly_ctx_get_yanglib_data() | Clarification of what to expect as the output of the function.
115 * - | ::ly_ctx_get_yanglib_id () | Supplement functionality for ::ly_ctx_get_yanglib_data().
116 * ly_ctx_new_ylmem() | TBD | Not yet implemented feature.
117 * ly_ctx_new_ylpath() | TBD | ^
118 * - | ::ly_ctx_unset_searchdir_last() | Extend the functionality of the ::ly_ctx_unset_searchdir() to make its use easier.
119 * ly_ctx_get_module_older() | - | Removed functionality.
120 * ly_ctx_get_submodule() | - | Removed functionality since the submodules are only in the parsed tree.
121 * ly_ctx_get_submodule2() | - | ^
122 * - | ::ly_ctx_get_module_implemented() | Supplement for ::ly_ctx_get_module()
123 * - | ::ly_ctx_get_module_latest() | ^
124 * - | ::ly_ctx_get_module_implemented_ns() | Supplement for ::ly_ctx_get_module_ns()
125 * - | ::ly_ctx_get_module_latest_ns() | ^
126 * ly_ctx_get_module_by_ns() | ::ly_ctx_get_module_ns () | Redesign the API - replace some of the parameters with standalone supplement functions.
127 * - | ::ly_ctx_reset_latests() | The new functionality of maintaining the latest module revision flag.
128 * ly_ctx_unset_searchdirs() | ::ly_ctx_unset_searchdir() | Simplify API and instead of index numbers, work with the values themselves.
129 * ly_ctx_set*() | ::ly_ctx_set_options() | API simplification.
130 * ly_ctx_unset*() | ::ly_ctx_unset_options() | ^
Radek Krejci8678fa42020-08-18 16:07:28 +0200131 *
132 *
Radek Krejcifba9c622020-10-30 08:28:54 +0100133 * @section transitionSchemas YANG Modules (Schema)
Radek Krejci8678fa42020-08-18 16:07:28 +0200134 *
Radek Krejcifba9c622020-10-30 08:28:54 +0100135 * The most significant change between libyang 1.x and 2.0 can be found in schema structures. The schema tree now has two
136 * different forms - parsed and compiled trees. While the parsed tree reflects the source of the YANG module, the compiled
137 * tree represents the final tree used to validate the instantiated data. Both formats can be found inside the covering
138 * ::lys_module structure. More about the new structures can be found at @ref howtoSchema page.
139 *
140 * This is an essential change allowing speed up and simplification of data validation, but requiring carefully determine
141 * which format is more suitable for the specific use case. As mentioned, the compiled trees are better for data validation
142 * and getting information about the intentioned structure of the schema with all the applied groupings, type modifications,
Michal Vasko08c8b272020-11-24 18:11:30 +0100143 * augments, deviations, and any defined if-features. On the other hand, the parsed trees are useful for the schema format conversions since they
Radek Krejcifba9c622020-10-30 08:28:54 +0100144 * provide the original structure of the modules. There is a number of new functions intended to work only with the
145 * parsed or the compiled tree. These functions are prefixed with `lysp_` and `lysp_` prefixes.
146 *
147 * Schema parser, as well as printer functions, are now extended to accept new
148 * [input / output handlers](@ref transitionGeneralInOut). The previous API working directly with inputs and outputs is
149 * preserved (or slightly changed), but the functions can be limited in the functionality of the new API. More information
150 * can be found at @ref howtoSchemaParsers and @ref howtoSchemaPrinters pages.
151 *
152 * libyang 1.x | libyang 2.0 | Notes
153 * :----------------------------|:--------------------------------|:---------------------------------------------------------
154 * - | ::lys_parse() | New generic schema parser API using [generic input handler](@ref howtoInput).
155 * - | ::lys_print_module() | New generic schema printer API using [generic output handler](@ref howtoOutput).
156 * - | ::lys_print_node() | ^
157 * - | ::lys_print_submodule() | ^
158 *
159 *
160 * The following table introduces other significant changes in the API functions connected with the schema.
161 *
162 * libyang 1.x | libyang 2.0 | Notes
163 * :----------------------------|:--------------------------------|:---------------------------------------------------------
164 * lys_set_private() | ::lysc_set_private() | Moving the private pointer only to the compiled tree.
165 * lys_is_disabled() | - | Make no sense since the nodes disabled by if-feature are not present in the compiled tree.
166 * lys_features_list() | - | Not needed, the list of features is available in the parsed tree of the module and submodule.
Michal Vasko08c8b272020-11-24 18:11:30 +0100167 * lys_features_enable(), lys_features_enable_force() | ::lys_set_implemented() | Set of enabled features can be changed but it causes the whole context (all the modules) to recompile.
Radek Krejcifba9c622020-10-30 08:28:54 +0100168 * lys_features_disable(), lys_features_disable_force() | - | ^
169 * lys_features_state() | - | Redesign of the features handling in the schema tree, the feature's status is newly directly visible as ::LYS_FENABLED flag (in parsed feature structure).
170 * - | ::lys_feature_value() | Simplified API to get feature's state only based on a feature name string.
171 * - | ::lysp_feature_next() | After redesigning features handling, this function helps to iterate over all features connected with the module.
172 * lys_iffeature_value() | ::lysc_iffeature_value() | Renamed, but note that after features handling redesign, the compiled if-feature structure to evaluate is only in ::lysp_feature.iffeatures_c.
173 * lys_iffeature_value() | - | Not needed since the if-feature statements are directly applied onto the compiled tree.
174 * lys_is_disabled() | - | ^
175 * lys_parent() | - | The compiled tree is more straightforward without the need to take care of nodes added via augments.
176 * lys_main_module() | - | The compiled tree does not include submodules, so there is always only the main module.
177 * lys_node_module() | - | ^
178 * lys_set_enabled() | - | It is not possible to change context this way (remove or disable modules).
179 * lys_set_disabled() | - | ^
180 * - | ::lys_find_child() | Helpers wrapper around ::lys_getnext().
181 * - | ::lys_nodetype2str() | New functionality.
182 * - | ::lys_value_validate() | Supplement functionality to ::lyd_value_validate().
183 * lys_is_key() | ::lysc_is_key() | Renamed to connect with the compiled schema tree.
184 * - | ::lysc_is_userordered() | Added functionality to simplify the examination of generic compiled schema nodes.
Michal Vasko5c123b02020-12-04 14:34:04 +0100185 * - | ::lysc_is_np_cont() | ^
Radek Krejcifba9c622020-10-30 08:28:54 +0100186 * - | ::lysc_node_children() | ^
187 * - | ::lysc_node_children_full() | ^
188 * - | ::lysc_node_actions() | ^
189 * - | ::lysc_node_notifs() | ^
190 * - | ::lysc_node_parent_full() | ^
191 * - | ::lysp_node_children() | Added functionality to simplify the examination of generic parsed schema nodes.
192 * - | ::lysp_node_actions() | ^
193 * - | ::lysp_node_notifs() | ^
194 * - | ::lysp_node_groupings() | ^
195 * - | ::lysp_node_typedefs() | ^
196 * - | ::lysc_tree_dfs_full() | Alternative DFS passing implementation to ::LYSC_TREE_DFS_BEGIN macro.
197 * - | ::lysc_module_dfs_full() | Supplement functionality to ::lysc_tree_dfs_full().
198 * lys_path(), lys_data_path() | ::lysc_path() | Redesigned functionality.
199 * lys_data_path_pattern() | - | Removed as useless
200 * lys_implemented_module() | ::ly_ctx_get_module_implemented() | Removed, the same result can be simply achieved using ::ly_ctx_get_module_implemented().
201 *
202 * There is a set of functions available to implement data type plugins for storing and manipulating data values in a more
203 * natural way to the specific data type. For example, IPv4 address type is defined as a string with a pattern, but it is
204 * more effective and usual to store and handle IPv4 as a 32-bit number.
205 *
206 * libyang 1.x | libyang 2.0 | Notes
207 * :----------------------------|:--------------------------------|:---------------------------------------------------------
208 * lys_getnext_union_type() | - | Removed after the type representation redesign.
209 * - | ::ly_type_identity_isderived() | Helper functions for base types.
210 * - | ::ly_type_parse_dec64() | ^
211 * - | ::ly_type_parse_int() | ^
212 * - | ::ly_type_parse_uint() | ^
213 * - | ::ly_type_validate_patterns() | ^
214 * - | ::ly_type_validate_range() | ^
215 * - | ::ly_type_print_get_prefix() | Helper functions for processing prefixes in data values.
216 * - | ::ly_type_store_resolve_prefix() | ^
217 * - | ::lysc_prefixes_compile() | ^
218 * - | ::lysc_prefixes_dup() | ^
219 * - | ::lysc_prefixes_free() | ^
220 *
221 *
222 * Extension implementation is not yet finished. The related functions (lys_ext_*()) from libyang 1.x are not currently
223 * available and all the API changes will be described later. The same situation is with plugins handling. The API is not
224 * yet ready. Despite the readiness of the data type plugins, support for loading them from external objects is not yet
225 * supported.
226 *
227 *
228 * libyang 1.x | libyang 2.0 | Notes
229 * :----------------------------|:--------------------------------|:---------------------------------------------------------
230 * lys_ext_complex_get_substmt() | TBD | Not yet implemented feature.
231 * lys_ext_instance_presence() | TBD | ^
232 * lys_ext_instance_substmt() | TBD | ^
233 * ly_clean_plugins() | TBD | ^
234 * ly_get_loaded_plugins() | TBD | ^
235 * ly_load_plugins() | TBD | ^
236 * ly_register_exts() | TBD | ^
237 * ly_register_types() | TBD | ^
238 *
239 *
240 * @section transitionData Data Instances
241 *
242 * Conceptually, the data tree did not change as much as the schema tree. There is still a generic ::lyd_node structure that
243 * maps according to the schema node's nodetype to some of the other lyd_node_* structures. All the data nodes were extended
244 * by hashes to improve performance when searching and processing data trees. The hashes are used for example in the
Michal Vasko787ce392021-01-11 11:34:02 +0100245 * lyd_find_* functions.
246 *
247 * All the data nodes are also implicitly ordered following the order of the schema nodes. This is the
Radek Krejcifba9c622020-10-30 08:28:54 +0100248 * reason to change the insertion function. Only the user-ordered lists and leaf-lists can be now placed relative to other
249 * instances of the same list/leaf-list. Otherwise, the data instance is always inserted/created at the correct place beside
250 * the right sibling nodes.
251 *
Michal Vasko787ce392021-01-11 11:34:02 +0100252 * For any functions that are available on inputs of different scale (node, subtree, all siblings, whole data tree),
253 * there are several variants of the specific function with suffix specifying what exactly the processed input will be
254 * (_single, _tree, _siblings, _all). This way the behavior is always clear in the code.
255 *
Radek Krejcifba9c622020-10-30 08:28:54 +0100256 * libyang 1.x | libyang 2.0 | Notes
257 * :----------------------------|:--------------------------------|:---------------------------------------------------------
258 * %lyd_insert_after() | ::lyd_insert_after() | Changed meaning by limiting applicability only to user-ordered list and leaf-list instances.
259 * %lyd_insert_before() | ::lyd_insert_before() | ^
260 * lyd_schema_sort() | - | Not necessary since the nodes are sorted implicitly.
261 *
262 *
263 * Parsing data instances in XML format is newly done directly, without any interstep. Therefore, complete XML API
264 * (lyxml_*() functions) from libyang 1.x was removed.
265 *
266 * Parser's API was simplified to avoid variadic parameters. The functions are newly split to parsed data, notifications,
267 * RPCs and replies to the RPCs. Similarly to the schema parsers, also the new data parser API works with
268 * [input handlers](@ref transitionGeneralInOut). The data printer's API was also extended to use new
269 * [output handlers](@ref transitionGeneralInOut). However, part of the previous API working directly with inputs
270 * and outputs was preserved. More information about the data parser and printer can be found at
271 * @ref howtoDataParsers and @ref howtoDataPrinters pages.
272 *
273 * libyang 1.x | libyang 2.0 | Notes
274 * :----------------------------|:--------------------------------|:---------------------------------------------------------
275 * - | ::lyd_parse_data() | Redesigned data tree parser.
276 * lyd_parse_xml() | - | XML tree format was removed.
277 * lyd_parse_fd() | ::lyd_parse_data_fd() | Renamed and limited to data trees only.
278 * lyd_parse_mem() | ::lyd_parse_data_mem() | ^
279 * lyd_parse_path() | ::lyd_parse_data_path() | ^
280 * - | ::lyd_parse_notif() | Separated function to parse Notifications.
281 * - | ::lyd_parse_rpc() | Separated function to parse RPCs.
282 * - | ::lyd_parse_reply() | Separated function to parse replies to RPCs
283 * - | ::lyd_print_all() | New API accepting ::ly_out.
284 * - | ::lyd_print_tree() | ^
285 *
286 *
287 * Data validation is still done as part of the parser's process. The standalone functionality is available to check the
288 * result of data manipulation with the values of the terminal nodes or with the structure of the data tree. In contrast to
289 * libyang 1.x, adding the default nodes was made available as a standalone function to simplify the data manipulation
290 * process before the final validation.
291 *
Michal Vaskoa24b9af2020-11-09 20:57:39 +0100292 * Many validation flags were removed because they became obsolete (LYD_OPT_DESTRUCT, LYD_OPT_WHENAUTODEL,
293 * LYD_OPT_NOEXTDEPS, LYD_OPT_DATA_NO_YANGLIB, LYD_OPT_VAL_DIFF) or we consider them redundant (LYD_OPT_OBSOLETE,
294 * LYD_OPT_NOSIBLINGS, LYD_OPT_DATA_ADD_YANGLIB). As for LYD_OPT_TRUSTED, this option was mostly replaced with
295 * ::LYD_PARSE_ONLY because both skip validation but with the significant difference that LYD_OPT_TRUSTED also sets
296 * the data node flags to be considered validated. The current option ::LYD_PARSE_ONLY does not do this because
297 * there is now much better support for working with non-validated data trees. Also, in case an invalid tree was marked
298 * as validated, it could lead to some undesired behavior, which is now avoided.
299 *
300 * Worth mentioning is a difference in the LYB format, which now also stores its validation flags. So, in case
301 * a validated data tree is stored, it is also loaded as validated.
302 *
Radek Krejcifba9c622020-10-30 08:28:54 +0100303 * libyang 1.x | libyang 2.0 | Notes
304 * :----------------------------|:--------------------------------|:---------------------------------------------------------
305 * lyd_validate() | ::lyd_validate_all(), ::lyd_validate_op() | Redesigned functionality.
306 * lyd_validate_modules() | ::lyd_validate_module() | ^
307 * lyd_validate_value(), lyd_value_type() | ::lyd_value_validate() | Redesigned functionality.
308 * - | ::lyd_new_implicit_all() | New in API to explicitly add default nodes, previously done only as part of the validation process.
309 * - | ::lyd_new_implicit_module() | Supplement functionality to ::lyd_new_implicit_all().
310 * - | ::lyd_new_implicit_tree() | ^
311 *
312 *
313 * The `diff` functionality was completely redesigned. Instead of the array of operations to transform one tree into another,
314 * the difference between two data trees has newly a form of the annotated data tree describing the differences. A number of
315 * functions to use the diff tree was added into API. To simply compare just nodes, there are the `compare` functions.
316 *
317 * libyang 1.x | libyang 2.0 | Notes
318 * :----------------------------|:--------------------------------|:---------------------------------------------------------
319 * lyd_diff() | ::lyd_diff_tree() | Redesigned functionality.
320 * - | ::lyd_diff_siblings() | Supplement functionality to ::lyd_diff_tree().
321 * - | ::lyd_diff_apply_all() | ^
322 * - | ::lyd_diff_apply_module() | ^
323 * - | ::lyd_diff_merge_all() | ^
324 * - | ::lyd_diff_merge_module() | ^
325 * - | ::lyd_diff_merge_tree() | ^
326 * - | ::lyd_diff_reverse_all() | ^
327 * lyd_free_diff() | - | Removed.
328 * lyd_free_val_diff() | - | Removed.
329 * - | ::lyd_compare_single() | Added functionality.
330 * - | ::lyd_compare_meta() | Supplement functionality to ::lyd_compare_single()
331 * - | ::lyd_compare_siblings() | ^
332 *
333 *
334 * For now, the functionality of moving data between two different contexts is not implemented. If you have a real use case
335 * for this functionality, let us know.
336 *
337 * libyang 1.x | libyang 2.0 | Notes
338 * :----------------------------|:--------------------------------|:---------------------------------------------------------
339 * lyd_dup() | ::lyd_dup_single() | Redesigned functionality.
340 * lyd_dup_withsiblings() | ::lyd_dup_siblings() | ^
341 * - | ::lyd_dup_meta_single() | Supplement functionality to ::lyd_dup_single().
342 * lyd_dup_to_ctx() | - | Transferring data from one context to another is not supported.
343 * lyd_merge() | ::lyd_merge_tree() | Renamed.
344 * - | ::lyd_merge_siblings() | Supplement functionality to ::lyd_merge_tree()
345 * lyd_merge_to_ctx() | - | Transferring data from one context to another is not supported.
346 *
347 *
348 * There is a significant change in the value structure in terminal nodes. Thanks to the changes in the schema tree,
349 * it is now much more straightforward to get the type of the value and work with the alternative representation of the value
350 * fitting better to its type. There is also a new API for the type plugins (see @ref howtoPluginsTypes). Even the base YANG
351 * data types are now implemented using this API and can be taken as examples for implementing derived data types.
352 *
353 * libyang 1.x | libyang 2.0 | Notes
354 * :----------------------------|:--------------------------------|:---------------------------------------------------------
355 * lyd_new(), lyd_new_output() | ::lyd_new_inner(), ::lyd_new_list(), ::lyd_new_list2() | Redesigned functionality to better fit new lyd_node structures, creating RPC's output data is now done via a flag parameter of the functions.
356 * lyd_new_leaf(), lyd_new_output_leaf() | ::lyd_new_term() | ^
357 * lyd_new_anydata(), lyd_new_output_anydata() | ::lyd_new_any() | ^
358 * lyd_insert_attr() | ::lyd_new_attr() | Unify naming used in other functions with the similar functionality.
359 * - | ::lyd_new_meta() | Added functionality to store the data (temporarily) not connected with schema definitions.
360 * - | ::lyd_new_opaq() | ^
361 * - | ::lyd_new_path2() | Supplement functionality to ::lyd_new_path().
362 * lyd_insert() | ::lyd_insert_child() | Renamed to better distinguish from ::lyd_insert_sibling().
363 * lyd_new_yangdata() | TBD | Not yet implemented feature.
364 * lyd_change_leaf() | ::lyd_change_term() | Align naming with changed names of data structures.
365 * - | ::lyd_change_meta() | Transferred functionality of ::lyd_change_term() to metadata.
366 * - | ::lyd_any_copy_value() | Added functionality.
367 * lyd_free() | ::lyd_free_tree() | Renamed.
368 * lyd_free_withsiblings() | ::lyd_free_all() | ^
369 * - | ::lyd_free_siblings() | Supplement functionality to ::lyd_free_siblings().
370 * lyd_free_attr() | ::lyd_free_attr_single() | Renamed.
371 * - | ::lyd_free_attr_siblings() | Supplement functionality to ::lyd_free_attr_single().
372 * - | ::lyd_free_meta_single() | Added functionality.
373 * - | ::lyd_free_meta_siblings() | ^
374 * lyd_unlink() | ::lyd_unlink_tree() | Renamed.
375 *
376 *
377 * Here is the table of other changes in data API.
378 *
379 * libyang 1.x | libyang 2.0 | Notes
380 * :----------------------------|:--------------------------------|:---------------------------------------------------------
381 * lyd_find_instance() | - | Removed.
382 * lyd_find_sibling() | - | Removed, functionality can be replaced by ::lyd_find_sibling_val().
383 * lyd_find_sibling_set() | - | ^
384 * - | ::lyd_find_sibling_first() | Alternative function to ::lyd_find_sibling_val().
385 * - | ::lyd_find_meta() | New functionality.
386 * lyd_wd_default() | ::lyd_is_default() | Renamed to unlink from with-default capability.
387 * - | ::lyd_parent() | New wrapper to get generic ::lyd_node pointer of the parent.
388 * - | ::lyd_child(), ::lyd_child_no_keys() | New wrapper to cover all children possibilities hidden behind a generic ::lyd_node structure.
389 * - | ::lyd_owner_module() | Added functionality.
390 * - | ::lyd_value_compare() | Added Functionality.
391 * - | ::lyd_target() | Added functionality for the instance-identifier representation.
392 * lyd_node_module() | - | Not necessary since the connection with the compiled modules is much more straightforward.
393 * lyd_leaf_type() | - | Not necessary since the real type information is much more clear from the new ::lyd_value.
394 * lyd_dec64_to_double() | - | Removed as useless.
395 * lyd_node_should_print() | - | ^
396
Radek Krejci8678fa42020-08-18 16:07:28 +0200397 */