blob: ff938de2e5e2c869a8312ca046094b1baa969f21 [file] [log] [blame]
Radek Krejcie7b95092019-05-15 11:03:07 +02001/**
Michal Vasko52927e22020-03-16 17:26:14 +01002 * @file printer_data.h
Radek Krejcie7b95092019-05-15 11:03:07 +02003 * @author Radek Krejci <rkrejci@cesnet.cz>
Michal Vasko52927e22020-03-16 17:26:14 +01004 * @brief Data printers for libyang
Radek Krejcie7b95092019-05-15 11:03:07 +02005 *
6 * Copyright (c) 2015-2019 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_PRINTER_DATA_H_
16#define LY_PRINTER_DATA_H_
17
Radek Krejci47fab892020-11-05 17:02:41 +010018#include <stdint.h>
Radek Krejci26da5222020-06-09 17:43:17 +020019#include <stdio.h>
Radek Krejcie7b95092019-05-15 11:03:07 +020020
Radek Krejci26da5222020-06-09 17:43:17 +020021#include "log.h"
Michal Vaskoafac7822020-10-20 14:22:26 +020022#include "out.h"
Radek Krejcie7b95092019-05-15 11:03:07 +020023#include "tree_data.h"
Radek Krejci535ea9f2020-05-29 16:01:05 +020024
Radek Krejcica376bd2020-06-11 16:04:06 +020025#ifdef __cplusplus
26extern "C" {
27#endif
28
Radek Krejci535ea9f2020-05-29 16:01:05 +020029struct ly_out;
Radek Krejcie7b95092019-05-15 11:03:07 +020030
31/**
Radek Krejci8678fa42020-08-18 16:07:28 +020032 * @page howtoDataPrinters Printing Data
Radek Krejcie7b95092019-05-15 11:03:07 +020033 *
Radek Krejci8678fa42020-08-18 16:07:28 +020034 * Data printers allows to serialize internal representation of a data tree in a specific format. libyang
35 * supports the following data formats for printing:
36 *
37 * - XML
38 *
39 * Basic format as specified in rules of mapping YANG modeled data to XML in
40 * [RFC 6020](http://tools.ietf.org/html/rfc6020).
41 *
42 * - JSON
43 *
44 * The alternative data format available in RESTCONF protocol. Specification of JSON encoding of data modeled by YANG
45 * can be found in [RFC 7951](https://tools.ietf.org/html/rfc7951).
46 *
47 * By default, both formats are printed with indentation (formatting), which can be avoided by ::LYD_PRINT_SHRINK
48 * [printer option](@ref dataprinterflags)). Other options adjust e.g. [with-defaults mode](@ref howtoDataWD).
49 *
50 * Besides the legacy functions from libyang 1.x (::lyd_print_clb(), ::lyd_print_fd(), ::lyd_print_file(), ::lyd_print_mem()
51 * and ::lyd_print_path()) printing data into the specified output, there are also new functions using
Michal Vaskoafac7822020-10-20 14:22:26 +020052 * [output handler](@ref howtoOutput) introduced in libyang 2.0. In contrast to
Radek Krejci8678fa42020-08-18 16:07:28 +020053 * [schema printers](@ref howtoSchemaPrinters), there is no limit of the functionality and the functions can be used
54 * interchangeable. The only think to note is that the new functions ::lyd_print_all() and ::lyd_print_tree() does not
55 * accept ::LYD_PRINT_WITHSIBLINGS [printer option](@ref dataprinterflags)) since this flag differentiate the functions
56 * themselves.
57 *
58 * Functions List
59 * --------------
60 * - ::lyd_print_all()
61 * - ::lyd_print_tree()
62 * - ::lyd_print_mem()
63 * - ::lyd_print_fd()
64 * - ::lyd_print_file()
65 * - ::lyd_print_path()
66 * - ::lyd_print_clb()
67 */
68
69/**
70 * @ingroup datatree
71 * @defgroup dataprinterflags Data printer flags
72 *
73 * Options to change default behavior of the data printers.
Radek Krejcie7b95092019-05-15 11:03:07 +020074 *
75 * @{
76 */
Radek Krejci8678fa42020-08-18 16:07:28 +020077#define LYD_PRINT_WITHSIBLINGS 0x01 /**< Flag for printing also the (following) sibling nodes of the data node.
78 The flag is not allowed for ::lyd_print_all() and ::lyd_print_tree(). */
Radek Krejci52f65552020-09-01 17:03:35 +020079#define LYD_PRINT_SHRINK LY_PRINT_SHRINK /**< Flag for output without indentation and formatting new lines. */
80#define LYD_PRINT_KEEPEMPTYCONT 0x04 /**< Preserve empty non-presence containers */
81#define LYD_PRINT_WD_MASK 0xF0 /**< Mask for with-defaults modes */
Radek Krejci8678fa42020-08-18 16:07:28 +020082#define LYD_PRINT_WD_EXPLICIT 0x00 /**< Explicit with-defaults mode. Only the data explicitly being present in
83 the data tree are printed, so the implicitly added default nodes are
84 not printed. Note that this is the default value when no WD option is
85 specified. */
86#define LYD_PRINT_WD_TRIM 0x10 /**< Trim mode avoids printing the nodes with the value equal to their
87 default value */
Michal Vasko7c2648e2021-05-11 13:07:54 +020088#define LYD_PRINT_WD_ALL 0x20 /**< With this option, all the nodes are printed as none of them are
89 considered default */
Radek Krejci8678fa42020-08-18 16:07:28 +020090#define LYD_PRINT_WD_ALL_TAG 0x40 /**< Same as ::LYD_PRINT_WD_ALL but also adds attribute 'default' with value 'true' to
Radek Krejci52f65552020-09-01 17:03:35 +020091 all nodes that has its default value. The 'default' attribute has namespace:
92 urn:ietf:params:xml:ns:netconf:default:1.0 and thus the attributes are
93 printed only when the ietf-netconf-with-defaults module is present in libyang
94 context (but in that case this namespace is always printed). */
Radek Krejci8678fa42020-08-18 16:07:28 +020095#define LYD_PRINT_WD_IMPL_TAG 0x80 /**< Same as ::LYD_PRINT_WD_ALL_TAG but the attributes are added only to the nodes that
Radek Krejci52f65552020-09-01 17:03:35 +020096 are not explicitly present in the original data tree despite their
97 value is equal to their default value. There is the same limitation regarding
98 the presence of ietf-netconf-with-defaults module in libyang context. */
Radek Krejcie7b95092019-05-15 11:03:07 +020099/**
100 * @}
101 */
102
103/**
Michal Vasko3a41dff2020-07-15 14:30:28 +0200104 * @brief Print the whole data tree of the root, including all the siblings.
Radek Krejcie7b95092019-05-15 11:03:07 +0200105 *
Radek Krejci241f6b52020-05-21 18:13:49 +0200106 * @param[in] out Printer handler for a specific output. Use ly_out_*() functions to create and free the handler.
Michal Vasko3a41dff2020-07-15 14:30:28 +0200107 * @param[in] root The root element of the tree to print, can be any sibling.
Radek Krejcia5bba312020-01-09 15:41:20 +0100108 * @param[in] format Output format.
Michal Vasko3a41dff2020-07-15 14:30:28 +0200109 * @param[in] options [Data printer flags](@ref dataprinterflags) except ::LYD_PRINT_WITHSIBLINGS.
Michal Vasko63f3d842020-07-08 10:10:14 +0200110 * @return LY_ERR value.
Radek Krejcie7b95092019-05-15 11:03:07 +0200111 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100112LIBYANG_API_DECL LY_ERR lyd_print_all(struct ly_out *out, const struct lyd_node *root, LYD_FORMAT format, uint32_t options);
Michal Vasko3a41dff2020-07-15 14:30:28 +0200113
114/**
115 * @brief Print the selected data subtree.
116 *
117 * @param[in] out Printer handler for a specific output. Use ly_out_*() functions to create and free the handler.
118 * @param[in] root The root element of the subtree to print.
119 * @param[in] format Output format.
120 * @param[in] options [Data printer flags](@ref dataprinterflags) except ::LYD_PRINT_WITHSIBLINGS.
121 * @return LY_ERR value.
122 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100123LIBYANG_API_DECL LY_ERR lyd_print_tree(struct ly_out *out, const struct lyd_node *root, LYD_FORMAT format, uint32_t options);
Radek Krejcie7b95092019-05-15 11:03:07 +0200124
Radek Krejci26da5222020-06-09 17:43:17 +0200125/**
Michal Vaskodcd356f2020-07-14 12:26:51 +0200126 * @brief Print data tree in the specified format.
127 *
128 * @param[out] strp Pointer to store the resulting dump.
Radek Krejci26da5222020-06-09 17:43:17 +0200129 * @param[in] root The root element of the (sub)tree to print.
130 * @param[in] format Output format.
Michal Vaskodcd356f2020-07-14 12:26:51 +0200131 * @param[in] options [Data printer flags](@ref dataprinterflags).
132 * @return LY_ERR value.
133 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100134LIBYANG_API_DECL LY_ERR lyd_print_mem(char **strp, const struct lyd_node *root, LYD_FORMAT format, uint32_t options);
Radek Krejci26da5222020-06-09 17:43:17 +0200135
136/**
137 * @brief Print data tree in the specified format.
138 *
139 * @param[in] fd File descriptor where to print the data.
140 * @param[in] root The root element of the (sub)tree to print.
141 * @param[in] format Output format.
Michal Vaskodcd356f2020-07-14 12:26:51 +0200142 * @param[in] options [Data printer flags](@ref dataprinterflags).
Radek Krejci26da5222020-06-09 17:43:17 +0200143 * @return LY_ERR value.
144 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100145LIBYANG_API_DECL LY_ERR lyd_print_fd(int fd, const struct lyd_node *root, LYD_FORMAT format, uint32_t options);
Radek Krejci26da5222020-06-09 17:43:17 +0200146
147/**
148 * @brief Print data tree in the specified format.
149 *
150 * @param[in] f File stream where to print the data.
151 * @param[in] root The root element of the (sub)tree to print.
152 * @param[in] format Output format.
Michal Vaskodcd356f2020-07-14 12:26:51 +0200153 * @param[in] options [Data printer flags](@ref dataprinterflags).
Radek Krejci26da5222020-06-09 17:43:17 +0200154 * @return LY_ERR value.
155 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100156LIBYANG_API_DECL LY_ERR lyd_print_file(FILE *f, const struct lyd_node *root, LYD_FORMAT format, uint32_t options);
Radek Krejci26da5222020-06-09 17:43:17 +0200157
158/**
159 * @brief Print data tree in the specified format.
160 *
161 * @param[in] path File path where to print the data.
162 * @param[in] root The root element of the (sub)tree to print.
163 * @param[in] format Output format.
Michal Vaskodcd356f2020-07-14 12:26:51 +0200164 * @param[in] options [Data printer flags](@ref dataprinterflags).
Radek Krejci26da5222020-06-09 17:43:17 +0200165 * @return LY_ERR value.
166 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100167LIBYANG_API_DECL LY_ERR lyd_print_path(const char *path, const struct lyd_node *root, LYD_FORMAT format, uint32_t options);
Radek Krejci26da5222020-06-09 17:43:17 +0200168
169/**
170 * @brief Print data tree in the specified format.
171 *
172 * @param[in] writeclb Callback function to write the data (see write(1)).
Michal Vaskoce2b8742020-08-24 13:20:25 +0200173 * @param[in] user_data Optional caller-specific argument to be passed to the \p writeclb callback.
Radek Krejci26da5222020-06-09 17:43:17 +0200174 * @param[in] root The root element of the (sub)tree to print.
175 * @param[in] format Output format.
Michal Vaskodcd356f2020-07-14 12:26:51 +0200176 * @param[in] options [Data printer flags](@ref dataprinterflags).
Radek Krejci26da5222020-06-09 17:43:17 +0200177 * @return LY_ERR value.
178 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100179LIBYANG_API_DECL LY_ERR lyd_print_clb(ly_write_clb writeclb, void *user_data, const struct lyd_node *root, LYD_FORMAT format, uint32_t options);
Radek Krejci26da5222020-06-09 17:43:17 +0200180
181#ifdef __cplusplus
182}
183#endif
184
Radek Krejcie7b95092019-05-15 11:03:07 +0200185#endif /* LY_PRINTER_DATA_H_ */