Adding upstream version 3.1.0.upstream/3.1.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 205 insertions, 0 deletions

diff --git a/src/printer_data.h b/src/printer_data.h
new file mode 100644
index 0000000..ef21aff
--- /dev/null
+++ b/src/printer_data.h
@@ -0,0 +1,205 @@
+/**
+ * @file printer_data.h
+ * @author Radek Krejci <rkrejci@cesnet.cz>
+ * @brief Data printers for libyang
+ *
+ * Copyright (c) 2015-2019 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_DATA_H_
+#define LY_PRINTER_DATA_H_
+
+#include <stdint.h>
+#include <stdio.h>
+
+#include "log.h"
+#include "out.h"
+#include "tree_data.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+struct ly_out;
+
+/**
+ * @page howtoDataPrinters Printing Data
+ *
+ * Data printers allows to serialize internal representation of a data tree in a specific format. libyang
+ * supports the following data formats for printing:
+ *
+ * - XML
+ *
+ *   Basic format as specified in rules of mapping YANG modeled data to XML in
+ *   [RFC 6020](http://tools.ietf.org/html/rfc6020).
+ *
+ * - JSON
+ *
+ *   The alternative data format available in RESTCONF protocol. Specification of JSON encoding of data modeled by YANG
+ *   can be found in [RFC 7951](https://tools.ietf.org/html/rfc7951).
+ *
+ * By default, both formats are printed with indentation (formatting), which can be avoided by ::LYD_PRINT_SHRINK
+ * [printer option](@ref dataprinterflags)). Other options adjust e.g. [with-defaults mode](@ref howtoDataWD).
+ *
+ * Besides the legacy functions from libyang 1.x (::lyd_print_clb(), ::lyd_print_fd(), ::lyd_print_file(), ::lyd_print_mem()
+ * and ::lyd_print_path()) printing data into the specified output, there are also new functions using
+ * [output handler](@ref howtoOutput) introduced in libyang 2.0. In contrast to
+ * [schema printers](@ref howtoSchemaPrinters), there is no limit of the functionality and the functions can be used
+ * interchangeable. The only think to note is that the new functions ::lyd_print_all() and ::lyd_print_tree() does not
+ * accept ::LYD_PRINT_WITHSIBLINGS [printer option](@ref dataprinterflags)) since this flag differentiate the functions
+ * themselves.
+ *
+ * Functions List
+ * --------------
+ * - ::lyd_print_all()
+ * - ::lyd_print_tree()
+ * - ::lyd_print_mem()
+ * - ::lyd_print_fd()
+ * - ::lyd_print_file()
+ * - ::lyd_print_path()
+ * - ::lyd_print_clb()
+ */
+
+/**
+ * @ingroup datatree
+ * @defgroup dataprinterflags Data printer flags
+ *
+ * Options to change default behavior of the data printers.
+ *
+ * @{
+ */
+#define LYD_PRINT_WITHSIBLINGS  0x01             /**< Flag for printing also the (following) sibling nodes of the data node.
+                                                      The flag is not allowed for ::lyd_print_all() and ::lyd_print_tree(). */
+#define LYD_PRINT_SHRINK        LY_PRINT_SHRINK  /**< Flag for output without indentation and formatting new lines. */
+#define LYD_PRINT_KEEPEMPTYCONT 0x04             /**< Preserve empty non-presence containers */
+#define LYD_PRINT_WD_MASK       0xF0             /**< Mask for with-defaults modes */
+#define LYD_PRINT_WD_EXPLICIT   0x00             /**< Explicit with-defaults mode. Only the data explicitly being present in
+                                                      the data tree are printed, so the implicitly added default nodes are
+                                                      not printed. Note that this is the default value when no WD option is
+                                                      specified. */
+#define LYD_PRINT_WD_TRIM       0x10             /**< Trim mode avoids printing the nodes with the value equal to their
+                                                      default value */
+#define LYD_PRINT_WD_ALL        0x20             /**< With this option, all the nodes are printed as none of them are
+                                                      considered default */
+#define LYD_PRINT_WD_ALL_TAG    0x40             /**< Same as ::LYD_PRINT_WD_ALL but also adds attribute 'default' with value 'true' to
+                                                      all nodes that has its default value. The 'default' attribute has namespace:
+                                                      urn:ietf:params:xml:ns:netconf:default:1.0 and thus the attributes are
+                                                      printed only when the ietf-netconf-with-defaults module is present in libyang
+                                                      context (but in that case this namespace is always printed). */
+#define LYD_PRINT_WD_IMPL_TAG   0x80             /**< Same as ::LYD_PRINT_WD_ALL_TAG but the attributes are added only to the nodes that
+                                                      are not explicitly present in the original data tree despite their
+                                                      value is equal to their default value.  There is the same limitation regarding
+                                                      the presence of ietf-netconf-with-defaults module in libyang context. */
+/**
+ * @}
+ */
+
+/**
+ * @brief Print the whole data tree of the root, including all the siblings.
+ *
+ * @param[in] out Printer handler for a specific output. Use ly_out_*() functions to create and free the handler.
+ * @param[in] root The root element of the tree to print, can be any sibling.
+ * @param[in] format Output format.
+ * @param[in] options [Data printer flags](@ref dataprinterflags) except ::LYD_PRINT_WITHSIBLINGS.
+ * @return LY_ERR value.
+ */
+LIBYANG_API_DECL LY_ERR lyd_print_all(struct ly_out *out, const struct lyd_node *root, LYD_FORMAT format, uint32_t options);
+
+/**
+ * @brief Print the selected data subtree.
+ *
+ * @param[in] out Printer handler for a specific output. Use ly_out_*() functions to create and free the handler.
+ * @param[in] root The root element of the subtree to print.
+ * @param[in] format Output format.
+ * @param[in] options [Data printer flags](@ref dataprinterflags) except ::LYD_PRINT_WITHSIBLINGS.
+ * @return LY_ERR value.
+ */
+LIBYANG_API_DECL LY_ERR lyd_print_tree(struct ly_out *out, const struct lyd_node *root, LYD_FORMAT format, uint32_t options);
+
+/**
+ * @brief Print data tree in the specified format.
+ *
+ * @param[out] strp Pointer to store the resulting dump.
+ * @param[in] root The root element of the (sub)tree to print.
+ * @param[in] format Output format.
+ * @param[in] options [Data printer flags](@ref dataprinterflags).
+ * @return LY_ERR value.
+ */
+LIBYANG_API_DECL LY_ERR lyd_print_mem(char **strp, const struct lyd_node *root, LYD_FORMAT format, uint32_t options);
+
+/**
+ * @brief Print data tree in the specified format.
+ *
+ * @param[in] fd File descriptor where to print the data.
+ * @param[in] root The root element of the (sub)tree to print.
+ * @param[in] format Output format.
+ * @param[in] options [Data printer flags](@ref dataprinterflags).
+ * @return LY_ERR value.
+ */
+LIBYANG_API_DECL LY_ERR lyd_print_fd(int fd, const struct lyd_node *root, LYD_FORMAT format, uint32_t options);
+
+/**
+ * @brief Print data tree in the specified format.
+ *
+ * @param[in] f File stream where to print the data.
+ * @param[in] root The root element of the (sub)tree to print.
+ * @param[in] format Output format.
+ * @param[in] options [Data printer flags](@ref dataprinterflags).
+ * @return LY_ERR value.
+ */
+LIBYANG_API_DECL LY_ERR lyd_print_file(FILE *f, const struct lyd_node *root, LYD_FORMAT format, uint32_t options);
+
+/**
+ * @brief Print data tree in the specified format.
+ *
+ * @param[in] path File path where to print the data.
+ * @param[in] root The root element of the (sub)tree to print.
+ * @param[in] format Output format.
+ * @param[in] options [Data printer flags](@ref dataprinterflags).
+ * @return LY_ERR value.
+ */
+LIBYANG_API_DECL LY_ERR lyd_print_path(const char *path, const struct lyd_node *root, LYD_FORMAT format, uint32_t options);
+
+/**
+ * @brief Print data tree in the specified format.
+ *
+ * @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] root The root element of the (sub)tree to print.
+ * @param[in] format Output format.
+ * @param[in] options [Data printer flags](@ref dataprinterflags).
+ * @return LY_ERR value.
+ */
+LIBYANG_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);
+
+/**
+ * @brief Check whether the node should be printed based on the printing options.
+ *
+ * @param[in] node Node to check.
+ * @param[in] options [Data printer flags](@ref dataprinterflags).
+ * @return 0 if not,
+ * @return non-0 if should be printed.
+ */
+LIBYANG_API_DECL ly_bool lyd_node_should_print(const struct lyd_node *node, uint32_t options);
+
+/**
+ * @brief Check whether the metadata should be printed.
+ *
+ * @param[in] meta Metadata to check.
+ * @return 0 if not,
+ * @return non-0 if should be printed.
+ */
+LIBYANG_API_DECL ly_bool lyd_metadata_should_print(const struct lyd_meta *meta);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* LY_PRINTER_DATA_H_ */