data tree FEATURE initial implementation of YANG data support
diff --git a/src/printer_internal.h b/src/printer_internal.h
index 2fb582e..7d0e312 100644
--- a/src/printer_internal.h
+++ b/src/printer_internal.h
@@ -16,7 +16,11 @@
#define LY_PRINTER_INTERNAL_H_
#include "printer_schema.h"
+#include "printer_data.h"
+/**
+ * @brief Types of the printer's output
+ */
typedef enum LYOUT_TYPE {
LYOUT_FD, /**< file descriptor */
LYOUT_STREAM, /**< FILE stream */
@@ -25,44 +29,43 @@
LYOUT_CALLBACK /**< print via provided callback */
} LYOUT_TYPE;
+/**
+ * @brief Printer output structure specifying where the data are printed.
+ */
struct lyout {
- LYOUT_TYPE type;
+ LYOUT_TYPE type; /**< type of the output to select the output method */
union {
- int fd;
- FILE *f;
+ int fd; /**< file descriptor for LYOUT_FD type */
+ FILE *f; /**< file structure for LYOUT_STREAM and LYOUT_FDSTREAM types */
struct {
- char *buf;
- size_t len;
- size_t size;
- } mem;
+ char *buf; /**< pointer to the memory buffer to store the output */
+ size_t len; /**< number of used bytes in the buffer */
+ size_t size; /**< allocated size of the buffer */
+ } mem; /**< memory buffer information for LYOUT_MEMORY type */
struct {
- ssize_t (*f)(void *arg, const void *buf, size_t count);
- void *arg;
- } clb;
- } method;
+ ssize_t (*f)(void *arg, const void *buf, size_t count); /**< callback function */
+ void *arg; /**< optional argument for the callback function */
+ } clb; /**< printer callback for LYOUT_CALLBACK type */
+ } method; /**< type-specific information about the output */
- /* buffer for holes */
- char *buffered;
- size_t buf_len;
- size_t buf_size;
+ char *buffered; /**< additional buffer for holes, used only for LYB data format */
+ size_t buf_len; /**< number of used bytes in the additional buffer for holes, used only for LYB data format */
+ size_t buf_size; /**< allocated size of the buffer for holes, used only for LYB data format */
+ size_t hole_count; /**< hole counter, used only for LYB data format */
- /* hole counter */
- size_t hole_count;
+ size_t printed; /**< Number of printed bytes */
- /* counter for printed bytes */
- size_t printed;
-
- /* libyang context for error logging */
- struct ly_ctx *ctx;
- LY_ERR status;
+ struct ly_ctx *ctx; /**< libyang context for error logging */
+ LY_ERR status; /**< current status of the printer */
};
-#define LYOUT_CHECK(LYOUT, ...) if (LYOUT->status) {return __VA_ARGS__;}
-
+/**
+ * @brief Informational structure for YANG statements
+ */
struct ext_substmt_info_s {
- const char *name;
- const char *arg;
- int flags;
+ const char *name; /**< name of the statement */
+ const char *arg; /**< name of YIN's attribute to present the statement */
+ int flags; /**< various flags to clarify printing of the statement */
#define SUBST_FLAG_YIN 0x1 /**< has YIN element */
#define SUBST_FLAG_ID 0x2 /**< the value is identifier -> no quotes */
};
@@ -70,21 +73,97 @@
/* filled in printer.c */
extern struct ext_substmt_info_s ext_substmt_info[];
+/**
+ * @brief macro to check current status of the printer.
+ */
+#define LYOUT_CHECK(LYOUT, ...) if (LYOUT->status) {return __VA_ARGS__;}
/**
- * @brief
+ * @brief YANG printer of the parsed schemas. Full YANG printer.
+ *
+ * @param[in] out Output specification.
+ * @param[in] module Schema to be printed (the parsed member is used).
+ * @return LY_ERR value, number of the printed bytes is updated in lyout::printed.
*/
LY_ERR yang_print_parsed(struct lyout *out, const struct lys_module *module);
/**
- * @brief
+ * @brief YANG printer of the compiled schemas.
+ *
+ * This printer provides information about modules how they are understood by libyang.
+ * Despite the format is inspired by YANG, it is not fully compatible and should not be
+ * used as a standard YANG format.
+ *
+ * @param[in] out Output specification.
+ * @param[in] module Schema to be printed (the compiled member is used).
+ * @return LY_ERR value, number of the printed bytes is updated in lyout::printed.
*/
LY_ERR yang_print_compiled(struct lyout *out, const struct lys_module *module);
+/**
+ * @brief XML printer of the YANG data.
+ *
+ * @param[in] out Output specification.
+ * @param[in] root The root element of the (sub)tree to print.
+ * @param[in] options [Data printer flags](@ref dataprinterflags).
+ * @return LY_ERR value, number of the printed bytes is updated in lyout::printed.
+ */
+LY_ERR xml_print_data(struct lyout *out, const struct lyd_node *root, int options);
+
+/**
+ * @brief Generic printer of the given format string into the specified output.
+ *
+ * Alternatively, ly_write() can be used.
+ *
+ * @param[in] out Output specification.
+ * @param[in] format format string to be printed.
+ * @return LY_ERR value, number of the printed bytes is updated in lyout::printed.
+ */
LY_ERR ly_print(struct lyout *out, const char *format, ...);
+/**
+ * @brief Flush the output from any internal buffers and clean any auxiliary data.
+ * @param[in] out Output specification.
+ */
void ly_print_flush(struct lyout *out);
-LY_ERR ly_write(struct lyout *out, const char *buf, size_t count);
+/**
+ * @brief Generic printer of the given string buffer into the specified output.
+ *
+ * Alternatively, ly_print() can be used.
+ *
+ * As an extension for printing holes (skipping some data until they are known),
+ * ly_write_skip() and ly_write_skipped() can be used.
+ *
+ * @param[in] out Output specification.
+ * @param[in] buf Memory buffer with the data to print.
+ * @param[in] len Length of the data to print in the @p buf.
+ * @return LY_ERR value, number of the printed bytes is updated in lyout::printed.
+ */
+LY_ERR ly_write(struct lyout *out, const char *buf, size_t len);
+
+/**
+ * @brief Create a hole in the output data that will be filled later.
+ *
+ * @param[in] out Output specification.
+ * @param[in] len Length of the created hole.
+ * @param[out] position Position of the hole, value must be later provided to the ly_write_skipped() call.
+ * @return LY_ERR value. The number of the printed bytes is updated in lyout::printed
+ * only in case the data are really written into the output.
+ */
+LY_ERR ly_write_skip(struct lyout *out, size_t len, size_t *position);
+
+/**
+ * @brief Write data into the hole at given position.
+ *
+ * @param[in] out Output specification.
+ * @param[in] position Position of the hole to fill, the value was provided by ly_write_skip().
+ * @param[in] buf Memory buffer with the data to print.
+ * @param[in] len Length of the data to print in the @p buf. Not that the length must correspond
+ * to the len value specified in the corresponding ly_write_skip() call.
+ * @return LY_ERR value. The number of the printed bytes is updated in lyout::printed
+ * only in case the data are really written into the output.
+ */
+LY_ERR ly_write_skipped(struct lyout *out, size_t position, const char *buf, size_t len);
#endif /* LY_PRINTER_INTERNAL_H_ */