blob: 7306272ef4c5da39da68bd7b14f28d992e90b8d4 [file] [log] [blame]
Radek Krejcid3ca0632019-04-16 16:54:54 +02001/**
2 * @file printer_schema.h
3 * @author Radek Krejci <rkrejci@cesnet.cz>
4 * @brief Schema printers for libyang
5 *
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_SCHEMA_H_
16#define LY_PRINTER_SCHEMA_H_
17
Radek Krejci47fab892020-11-05 17:02:41 +010018#include <stdint.h>
Radek Krejcica376bd2020-06-11 16:04:06 +020019#include <stdio.h>
Radek Krejcid3ca0632019-04-16 16:54:54 +020020
Radek Krejcica376bd2020-06-11 16:04:06 +020021#include "log.h"
Michal Vaskoafac7822020-10-20 14:22:26 +020022#include "out.h"
Radek Krejcica376bd2020-06-11 16:04:06 +020023
24#ifdef __cplusplus
25extern "C" {
26#endif
Radek Krejcie7b95092019-05-15 11:03:07 +020027
Radek Krejci535ea9f2020-05-29 16:01:05 +020028struct ly_out;
Radek Krejcica376bd2020-06-11 16:04:06 +020029struct lys_module;
30struct lysc_node;
Michal Vasko7c8439f2020-08-05 13:25:19 +020031struct lysp_submodule;
Radek Krejci535ea9f2020-05-29 16:01:05 +020032
Radek Krejci8678fa42020-08-18 16:07:28 +020033/**
34 * @page howtoSchemaPrinters Module Printers
35 *
36 * Schema printers allows to serialize internal representations of a schema module in a specific format. libyang
37 * supports the following schema formats for printing:
38 *
39 * - YANG
40 *
41 * Basic YANG schemas format described in [RFC 6020](http://tools.ietf.org/html/rfc6020) and
42 * [RFC 7951](http://tools.ietf.org/html/rfc7951) (so both YANG 1.0 and YANG 1.1 versions are supported).
43 *
44 * - YANG compiled
45 *
46 * Syntactically, this format is based on standard YANG format. In contrast to standard YANG format, YANG compiled format
47 * represents the module how it is used by libyang - with all uses expanded, augments and deviations applied, etc.
48 * (more details about the compiled modules can be found on @ref howtoContext page).
49 *
50 * - YIN
51 *
52 * Alternative XML-based format to YANG - YANG Independent Notation. The details can be found in
53 * [RFC 6020](http://tools.ietf.org/html/rfc6020#section-11) and
54 * [RFC 7951](http://tools.ietf.org/html/rfc7951#section-13).
55 *
56 * - Tree Diagram
57 *
58 * Simple tree diagram providing overview of the module. The details can be found in
59 * [RFC 8340](https://tools.ietf.org/html/rfc8340).
60 *
61 * For simpler transition from libyang 1.x (and for some simple use cases), there are functions (::lys_print_clb(),
62 * ::lys_print_fd(), ::lys_print_file() and ::lys_print_mem()) to print the complete module into the specified output. But note,
63 * that these functions are limited to print only the complete module.
64 *
Michal Vaskoafac7822020-10-20 14:22:26 +020065 * The full functionality of the schema printers is available via functions using [output handler](@ref howtoOutput). Besides
Radek Krejci8678fa42020-08-18 16:07:28 +020066 * the ::lys_print_module() function to print the complete module, there are functions to print a submodule
67 * (::lys_print_submodule()) or a subtree (::lys_print_node()). Note that these functions might not support all the output
68 * formats mentioned above.
69 *
70 * Functions List
71 * --------------
72 * - ::lys_print_module()
73 * - ::lys_print_submodule()
74 * - ::lys_print_node()
75 *
76 * - ::lys_print_clb()
77 * - ::lys_print_fd()
78 * - ::lys_print_file()
79 * - ::lys_print_mem()
80 * - ::lys_print_path()
81 */
82
Radek Krejci2ff0d572020-05-21 15:27:28 +020083/**
84 * @addtogroup schematree
85 * @{
86 */
Radek Krejcid8c0f5e2019-11-17 12:18:34 +080087
88/**
89 * @defgroup schemaprinterflags Schema output options
Radek Krejci8678fa42020-08-18 16:07:28 +020090 *
91 * Options to change default behavior of the schema printers.
92 *
Radek Krejcid8c0f5e2019-11-17 12:18:34 +080093 * @{
94 */
Radek Krejci52f65552020-09-01 17:03:35 +020095#define LYS_PRINT_SHRINK LY_PRINT_SHRINK /**< Flag for output without indentation and formatting new lines. */
96#define LYS_PRINT_NO_SUBSTMT 0x10 /**< Print only top-level/referede node information,
97 do not print information from the substatements */
aPiecek61d062b2020-11-02 11:05:09 +010098// #define LYS_PRINT_TREE_RFC 0x01 /**< Conform to the RFC8340 tree output (only for tree format) */
Radek Krejci52f65552020-09-01 17:03:35 +020099// #define LYS_PRINT_TREE_GROUPING 0x02 /**< Print groupings separately (only for tree format) */
100// #define LYS_PRINT_TREE_USES 0x04 /**< Print only uses instead the resolved grouping nodes (only for tree format) */
101// #define LYS_PRINT_TREE_NO_LEAFREF 0x08 /**< Do not print the target of leafrefs (only for tree format) */
Radek Krejcid8c0f5e2019-11-17 12:18:34 +0800102
Radek Krejci2ff0d572020-05-21 15:27:28 +0200103/** @} schemaprinterflags */
Radek Krejcid8c0f5e2019-11-17 12:18:34 +0800104
Radek Krejcid3ca0632019-04-16 16:54:54 +0200105/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200106 * @brief Schema output formats accepted by libyang [printer functions](@ref howtoSchemaPrinters).
Radek Krejcif0e1ba52020-05-22 15:14:35 +0200107 */
108typedef enum {
109 LYS_OUT_UNKNOWN = 0, /**< unknown format, used as return value in case of error */
110 LYS_OUT_YANG = 1, /**< YANG schema output format */
111 LYS_OUT_YANG_COMPILED = 2, /**< YANG schema output format of the compiled schema tree */
112 LYS_OUT_YIN = 3, /**< YIN schema output format */
Radek Krejci8678fa42020-08-18 16:07:28 +0200113 LYS_OUT_TREE /**< Tree schema output format */
Radek Krejcif0e1ba52020-05-22 15:14:35 +0200114} LYS_OUTFORMAT;
115
116/**
Radek Krejcia5bba312020-01-09 15:41:20 +0100117 * @brief Schema module printer.
Radek Krejcid3ca0632019-04-16 16:54:54 +0200118 *
Radek Krejci241f6b52020-05-21 18:13:49 +0200119 * @param[in] out Printer handler for a specific output. Use ly_out_*() functions to create and free the handler.
Michal Vasko7c8439f2020-08-05 13:25:19 +0200120 * @param[in] module Main module with the parsed schema to print.
Radek Krejcia5bba312020-01-09 15:41:20 +0100121 * @param[in] format Output format.
Radek Krejcid3ca0632019-04-16 16:54:54 +0200122 * @param[in] line_length Maximum characters to be printed on a line, 0 for unlimited. Only for #LYS_OUT_TREE printer.
123 * @param[in] options Schema output options (see @ref schemaprinterflags).
Michal Vasko63f3d842020-07-08 10:10:14 +0200124 * @return LY_ERR value.
Radek Krejcid3ca0632019-04-16 16:54:54 +0200125 */
Michal Vasko7997d5a2021-02-22 10:55:56 +0100126LY_ERR lys_print_module(struct ly_out *out, const struct lys_module *module, LYS_OUTFORMAT format, size_t line_length,
127 uint32_t options);
Michal Vasko7c8439f2020-08-05 13:25:19 +0200128
129/**
130 * @brief Schema submodule printer.
131 *
132 * @param[in] out Printer handler for a specific output. Use ly_out_*() functions to create and free the handler.
Michal Vasko7c8439f2020-08-05 13:25:19 +0200133 * @param[in] submodule Parsed submodule to print.
Radek Krejci8678fa42020-08-18 16:07:28 +0200134 * @param[in] format Output format (LYS_OUT_YANG_COMPILED is not supported).
Michal Vasko7c8439f2020-08-05 13:25:19 +0200135 * @param[in] line_length Maximum characters to be printed on a line, 0 for unlimited. Only for #LYS_OUT_TREE printer.
136 * @param[in] options Schema output options (see @ref schemaprinterflags).
137 * @return LY_ERR value.
138 */
Michal Vasko7997d5a2021-02-22 10:55:56 +0100139LY_ERR lys_print_submodule(struct ly_out *out, const struct lysp_submodule *submodule, LYS_OUTFORMAT format,
140 size_t line_length, uint32_t options);
Radek Krejcid3ca0632019-04-16 16:54:54 +0200141
142/**
Radek Krejci26da5222020-06-09 17:43:17 +0200143 * @brief Print schema tree in the specified format into a memory block.
144 * It is up to caller to free the returned string by free().
145 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200146 * This is just a wrapper around ::lys_print_module() for simple use cases.
Radek Krejci26da5222020-06-09 17:43:17 +0200147 * In case of a complex use cases, use lys_print with ly_out output handler.
148 *
149 * @param[out] strp Pointer to store the resulting dump.
150 * @param[in] module Schema tree to print.
151 * @param[in] format Schema output format.
Radek Krejci26da5222020-06-09 17:43:17 +0200152 * @param[in] options Schema output options (see @ref schemaprinterflags).
153 * @return LY_ERR value.
154 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200155LY_ERR lys_print_mem(char **strp, const struct lys_module *module, LYS_OUTFORMAT format, uint32_t options);
Radek Krejci26da5222020-06-09 17:43:17 +0200156
157/**
158 * @brief Print schema tree in the specified format into a file descriptor.
159 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200160 * This is just a wrapper around ::lys_print_module() for simple use cases.
Radek Krejci26da5222020-06-09 17:43:17 +0200161 * In case of a complex use cases, use lys_print with ly_out output handler.
162 *
163 * @param[in] fd File descriptor where to print the data.
164 * @param[in] module Schema tree to print.
165 * @param[in] format Schema output format.
Radek Krejci26da5222020-06-09 17:43:17 +0200166 * @param[in] options Schema output options (see @ref schemaprinterflags).
167 * @return LY_ERR value.
168 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200169LY_ERR lys_print_fd(int fd, const struct lys_module *module, LYS_OUTFORMAT format, uint32_t options);
Radek Krejci26da5222020-06-09 17:43:17 +0200170
171/**
172 * @brief Print schema tree in the specified format into a file stream.
173 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200174 * This is just a wrapper around ::lys_print_module() for simple use cases.
Radek Krejci26da5222020-06-09 17:43:17 +0200175 * In case of a complex use cases, use lys_print with ly_out output handler.
176 *
177 * @param[in] module Schema tree to print.
178 * @param[in] f File stream where to print the schema.
179 * @param[in] format Schema output format.
Radek Krejci26da5222020-06-09 17:43:17 +0200180 * @param[in] options Schema output options (see @ref schemaprinterflags).
181 * @return LY_ERR value.
182 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200183LY_ERR lys_print_file(FILE *f, const struct lys_module *module, LYS_OUTFORMAT format, uint32_t options);
Radek Krejci26da5222020-06-09 17:43:17 +0200184
185/**
186 * @brief Print schema tree in the specified format into a file.
187 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200188 * This is just a wrapper around ::lys_print_module() for simple use cases.
Radek Krejci26da5222020-06-09 17:43:17 +0200189 * In case of a complex use cases, use lys_print with ly_out output handler.
190 *
191 * @param[in] path File where to print the schema.
192 * @param[in] module Schema tree to print.
193 * @param[in] format Schema output format.
Radek Krejci26da5222020-06-09 17:43:17 +0200194 * @param[in] options Schema output options (see @ref schemaprinterflags).
195 * @return LY_ERR value.
196 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200197LY_ERR lys_print_path(const char *path, const struct lys_module *module, LYS_OUTFORMAT format, uint32_t options);
Radek Krejci26da5222020-06-09 17:43:17 +0200198
199/**
200 * @brief Print schema tree in the specified format using a provided callback.
201 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200202 * This is just a wrapper around ::lys_print_module() for simple use cases.
Radek Krejci26da5222020-06-09 17:43:17 +0200203 * In case of a complex use cases, use lys_print with ly_out output handler.
204 *
205 * @param[in] module Schema tree to print.
206 * @param[in] writeclb Callback function to write the data (see write(1)).
Michal Vaskoce2b8742020-08-24 13:20:25 +0200207 * @param[in] user_data Optional caller-specific argument to be passed to the \p writeclb callback.
Radek Krejci26da5222020-06-09 17:43:17 +0200208 * @param[in] format Schema output format.
Radek Krejci26da5222020-06-09 17:43:17 +0200209 * @param[in] options Schema output options (see @ref schemaprinterflags).
210 * @return LY_ERR value.
211 */
Michal Vaskoce2b8742020-08-24 13:20:25 +0200212LY_ERR lys_print_clb(ly_write_clb writeclb, void *user_data,
Radek Krejci1deb5be2020-08-26 16:43:36 +0200213 const struct lys_module *module, LYS_OUTFORMAT format, uint32_t options);
Radek Krejci26da5222020-06-09 17:43:17 +0200214
215/**
Radek Krejcia5bba312020-01-09 15:41:20 +0100216 * @brief Schema node printer.
Radek Krejcid8c0f5e2019-11-17 12:18:34 +0800217 *
Radek Krejci241f6b52020-05-21 18:13:49 +0200218 * @param[in] out Printer handler for a specific output. Use ly_out_*() functions to create and free the handler.
Radek Krejci8678fa42020-08-18 16:07:28 +0200219 * @param[in] node Schema node to print.
Radek Krejcia5bba312020-01-09 15:41:20 +0100220 * @param[in] format Output format.
Radek Krejcid8c0f5e2019-11-17 12:18:34 +0800221 * @param[in] line_length Maximum characters to be printed on a line, 0 for unlimited. Only for #LYS_OUT_TREE printer.
222 * @param[in] options Schema output options (see @ref schemaprinterflags).
Michal Vasko63f3d842020-07-08 10:10:14 +0200223 * @return LY_ERR value.
Radek Krejcid8c0f5e2019-11-17 12:18:34 +0800224 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200225LY_ERR lys_print_node(struct ly_out *out, const struct lysc_node *node, LYS_OUTFORMAT format, size_t line_length, uint32_t options);
Radek Krejcid8c0f5e2019-11-17 12:18:34 +0800226
Radek Krejci2ff0d572020-05-21 15:27:28 +0200227/** @} schematree */
228
Radek Krejcica376bd2020-06-11 16:04:06 +0200229#ifdef __cplusplus
230}
231#endif
232
Radek Krejcid3ca0632019-04-16 16:54:54 +0200233#endif /* LY_PRINTER_SCHEMA_H_ */