1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
/**
* @file printer_schema.h
* @author Radek Krejci <rkrejci@cesnet.cz>
* @author Michal Vasko <mvasko@cesnet.cz>
* @brief Schema printers for libyang
*
* Copyright (c) 2015-2022 CESNET, z.s.p.o.
*
* This source code is licensed under BSD 3-Clause License (the "License").
* You may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://opensource.org/licenses/BSD-3-Clause
*/
#ifndef LY_PRINTER_SCHEMA_H_
#define LY_PRINTER_SCHEMA_H_
#include <stdint.h>
#include <stdio.h>
#include "log.h"
#include "out.h"
#ifdef __cplusplus
extern "C" {
#endif
struct ly_out;
struct lys_module;
struct lysc_node;
struct lysp_submodule;
/**
* @page howtoSchemaPrinters Module Printers
*
* Schema printers allows to serialize internal representations of a schema module in a specific format. libyang
* supports the following schema formats for printing:
*
* - YANG
*
* Basic YANG schemas format described in [RFC 6020](http://tools.ietf.org/html/rfc6020) and
* [RFC 7951](http://tools.ietf.org/html/rfc7951) (so both YANG 1.0 and YANG 1.1 versions are supported).
*
* - YANG compiled
*
* Syntactically, this format is based on standard YANG format. In contrast to standard YANG format, YANG compiled format
* represents the module how it is used by libyang - with all uses expanded, augments and deviations applied, etc.
* (more details about the compiled modules can be found on @ref howtoContext page).
*
* - YIN
*
* Alternative XML-based format to YANG - YANG Independent Notation. The details can be found in
* [RFC 6020](http://tools.ietf.org/html/rfc6020#section-11) and
* [RFC 7951](http://tools.ietf.org/html/rfc7951#section-13).
*
* - Tree Diagram
*
* Simple tree diagram providing overview of the module. The details can be found in
* [RFC 8340](https://tools.ietf.org/html/rfc8340).
*
* For simpler transition from libyang 1.x (and for some simple use cases), there are functions (::lys_print_clb(),
* ::lys_print_fd(), ::lys_print_file() and ::lys_print_mem()) to print the complete module into the specified output. But note,
* that these functions are limited to print only the complete module.
*
* The full functionality of the schema printers is available via functions using [output handler](@ref howtoOutput). Besides
* the ::lys_print_module() function to print the complete module, there are functions to print a submodule
* (::lys_print_submodule()) or a subtree (::lys_print_node()). Note that these functions might not support all the output
* formats mentioned above.
*
* Functions List
* --------------
* - ::lys_print_module()
* - ::lys_print_submodule()
* - ::lys_print_node()
*
* - ::lys_print_clb()
* - ::lys_print_fd()
* - ::lys_print_file()
* - ::lys_print_mem()
* - ::lys_print_path()
*/
/**
* @addtogroup schematree
* @{
*/
/**
* @defgroup schemaprinterflags Schema output options
*
* Options to change default behavior of the schema printers.
*
* @{
*/
#define LYS_PRINT_SHRINK LY_PRINT_SHRINK /**< Flag for output without indentation and formatting new lines. */
#define LYS_PRINT_NO_SUBSTMT 0x10 /**< Print only top-level/referede node information,
do not print information from the substatements */
/** @} schemaprinterflags */
/**
* @brief Schema output formats accepted by libyang [printer functions](@ref howtoSchemaPrinters).
*/
typedef enum {
LYS_OUT_UNKNOWN = 0, /**< unknown format, used as return value in case of error */
LYS_OUT_YANG = 1, /**< YANG schema output format */
LYS_OUT_YANG_COMPILED = 2, /**< YANG schema output format of the compiled schema tree */
LYS_OUT_YIN = 3, /**< YIN schema output format */
LYS_OUT_TREE /**< Tree schema output format */
} LYS_OUTFORMAT;
/**
* @brief Schema module printer.
*
* @param[in] out Printer handler for a specific output. Use ly_out_*() functions to create and free the handler.
* @param[in] module Main module with the parsed schema to print.
* @param[in] format Output format.
* @param[in] line_length Maximum characters to be printed on a line, 0 for unlimited. Only for #LYS_OUT_TREE printer.
* @param[in] options Schema output options (see @ref schemaprinterflags).
* @return LY_ERR value.
*/
LIBYANG_API_DECL LY_ERR lys_print_module(struct ly_out *out, const struct lys_module *module, LYS_OUTFORMAT format,
size_t line_length, uint32_t options);
/**
* @brief Schema submodule printer.
*
* @param[in] out Printer handler for a specific output. Use ly_out_*() functions to create and free the handler.
* @param[in] submodule Parsed submodule to print.
* @param[in] format Output format (LYS_OUT_YANG_COMPILED is not supported).
* @param[in] line_length Maximum characters to be printed on a line, 0 for unlimited. Only for #LYS_OUT_TREE printer.
* @param[in] options Schema output options (see @ref schemaprinterflags).
* @return LY_ERR value.
*/
LIBYANG_API_DECL LY_ERR lys_print_submodule(struct ly_out *out, const struct lysp_submodule *submodule, LYS_OUTFORMAT format,
size_t line_length, uint32_t options);
/**
* @brief Print schema tree in the specified format into a memory block.
* It is up to caller to free the returned string by free().
*
* This is just a wrapper around ::lys_print_module() for simple use cases.
* In case of a complex use cases, use lys_print with ly_out output handler.
*
* @param[out] strp Pointer to store the resulting dump.
* @param[in] module Schema tree to print.
* @param[in] format Schema output format.
* @param[in] options Schema output options (see @ref schemaprinterflags).
* @return LY_ERR value.
*/
LIBYANG_API_DECL LY_ERR lys_print_mem(char **strp, const struct lys_module *module, LYS_OUTFORMAT format, uint32_t options);
/**
* @brief Print schema tree in the specified format into a file descriptor.
*
* This is just a wrapper around ::lys_print_module() for simple use cases.
* In case of a complex use cases, use lys_print with ly_out output handler.
*
* @param[in] fd File descriptor where to print the data.
* @param[in] module Schema tree to print.
* @param[in] format Schema output format.
* @param[in] options Schema output options (see @ref schemaprinterflags).
* @return LY_ERR value.
*/
LIBYANG_API_DECL LY_ERR lys_print_fd(int fd, const struct lys_module *module, LYS_OUTFORMAT format, uint32_t options);
/**
* @brief Print schema tree in the specified format into a file stream.
*
* This is just a wrapper around ::lys_print_module() for simple use cases.
* In case of a complex use cases, use lys_print with ly_out output handler.
*
* @param[in] module Schema tree to print.
* @param[in] f File stream where to print the schema.
* @param[in] format Schema output format.
* @param[in] options Schema output options (see @ref schemaprinterflags).
* @return LY_ERR value.
*/
LIBYANG_API_DECL LY_ERR lys_print_file(FILE *f, const struct lys_module *module, LYS_OUTFORMAT format, uint32_t options);
/**
* @brief Print schema tree in the specified format into a file.
*
* This is just a wrapper around ::lys_print_module() for simple use cases.
* In case of a complex use cases, use lys_print with ly_out output handler.
*
* @param[in] path File where to print the schema.
* @param[in] module Schema tree to print.
* @param[in] format Schema output format.
* @param[in] options Schema output options (see @ref schemaprinterflags).
* @return LY_ERR value.
*/
LIBYANG_API_DECL LY_ERR lys_print_path(const char *path, const struct lys_module *module, LYS_OUTFORMAT format,
uint32_t options);
/**
* @brief Print schema tree in the specified format using a provided callback.
*
* This is just a wrapper around ::lys_print_module() for simple use cases.
* In case of a complex use cases, use lys_print with ly_out output handler.
*
* @param[in] module Schema tree to print.
* @param[in] writeclb Callback function to write the data (see write(1)).
* @param[in] user_data Optional caller-specific argument to be passed to the \p writeclb callback.
* @param[in] format Schema output format.
* @param[in] options Schema output options (see @ref schemaprinterflags).
* @return LY_ERR value.
*/
LIBYANG_API_DECL LY_ERR lys_print_clb(ly_write_clb writeclb, void *user_data, const struct lys_module *module,
LYS_OUTFORMAT format, uint32_t options);
/**
* @brief Schema node printer.
*
* @param[in] out Printer handler for a specific output. Use ly_out_*() functions to create and free the handler.
* @param[in] node Schema node to print.
* @param[in] format Output format.
* @param[in] line_length Maximum characters to be printed on a line, 0 for unlimited. Only for #LYS_OUT_TREE printer.
* @param[in] options Schema output options (see @ref schemaprinterflags).
* @return LY_ERR value.
*/
LIBYANG_API_DECL LY_ERR lys_print_node(struct ly_out *out, const struct lysc_node *node, LYS_OUTFORMAT format,
size_t line_length, uint32_t options);
/** @} schematree */
#ifdef __cplusplus
}
#endif
#endif /* LY_PRINTER_SCHEMA_H_ */