xml MAINTENANCE docs added
diff --git a/src/xml.c b/src/xml.c
index ce296c4..d6f6cd7 100644
--- a/src/xml.c
+++ b/src/xml.c
@@ -191,31 +191,6 @@
}
}
-void *
-lyxml_elem_dup(void *item)
-{
- struct lyxml_elem *dup;
-
- dup = malloc(sizeof *dup);
- memcpy(dup, item, sizeof *dup);
-
- return dup;
-}
-
-void *
-lyxml_ns_dup(void *item)
-{
- struct lyxml_ns *dup, *orig;
-
- orig = (struct lyxml_ns *)item;
- dup = malloc(sizeof *dup);
- dup->prefix = orig->prefix ? strdup(orig->prefix) : NULL;
- dup->uri = strdup(orig->uri);
- dup->depth = orig->depth;
-
- return dup;
-}
-
const struct lyxml_ns *
lyxml_ns_get(struct lyxml_ctx *xmlctx, const char *prefix, size_t prefix_len)
{
@@ -237,6 +212,13 @@
return NULL;
}
+/**
+ * @brief Skip in the input until EOF or just after the opening tag.
+ * Handles special XML constructs (comment, cdata, doctype).
+ *
+ * @param[in] xmlctx XML context to use.
+ * @return LY_ERR value.
+ */
static LY_ERR
lyxml_skip_until_end_or_after_otag(struct lyxml_ctx *xmlctx)
{
@@ -302,6 +284,16 @@
return LY_SUCCESS;
}
+/**
+ * @brief Parse QName.
+ *
+ * @param[in] xmlctx XML context to use.
+ * @param[out] prefix Parsed prefix, may be NULL.
+ * @param[out] prefix_len Length of @p prefix.
+ * @param[out] name Parsed name.
+ * @param[out] name_len Length of @p name.
+ * @return LY_ERR value.
+ */
static LY_ERR
lyxml_parse_qname(struct lyxml_ctx *xmlctx, const char **prefix, size_t *prefix_len, const char **name, size_t *name_len)
{
@@ -388,6 +380,17 @@
return LY_SUCCESS;
}
+/**
+ * @brief Parse XML text content (value).
+ *
+ * @param[in] xmlctx XML context to use.
+ * @param[in] endchar Expected character to mark value end.
+ * @param[out] value Parsed value.
+ * @param[out] length Length of @p value.
+ * @param[out] ws_only Whether the value is empty/white-spaces only.
+ * @param[out] dynamic Whether the value was dynamically allocated.
+ * @return LY_ERR value.
+ */
static LY_ERR
lyxml_parse_value(struct lyxml_ctx *xmlctx, char endchar, char **value, size_t *length, int *ws_only, int *dynamic)
{
@@ -559,6 +562,17 @@
#undef BUFSIZE_STEP
}
+/**
+ * @brief Parse XML closing element and match it to a stored starting element.
+ *
+ * @param[in] xmlctx XML context to use.
+ * @param[in] prefix Expected closing element prefix.
+ * @param[in] prefix_len Length of @p prefix.
+ * @param[in] name Expected closing element name.
+ * @param[in] name_len Length of @p name.
+ * @param[in] empty Whether we are parsing a special "empty" element (with joined starting and closing tag) with no value.
+ * @return LY_ERR value.
+ */
static LY_ERR
lyxml_close_element(struct lyxml_ctx *xmlctx, const char *prefix, size_t prefix_len, const char *name, size_t name_len,
int empty)
@@ -609,6 +623,16 @@
return LY_SUCCESS;
}
+/**
+ * @brief Store parsed opening element and parse any included namespaces.
+ *
+ * @param[in] xmlctx XML context to use.
+ * @param[in] prefix Parsed starting element prefix.
+ * @param[in] prefix_len Length of @p prefix.
+ * @param[in] name Parsed starting element name.
+ * @param[in] name_len Length of @p name.
+ * @return LY_ERR value.
+ */
static LY_ERR
lyxml_open_element(struct lyxml_ctx *xmlctx, const char *prefix, size_t prefix_len, const char *name, size_t name_len)
{
@@ -673,6 +697,16 @@
return ret;
}
+/**
+ * @brief Move parser to the attribute content and parse it.
+ *
+ * @param[in] xmlctx XML context to use.
+ * @param[out] value Parsed attribute value.
+ * @param[out] value_len Length of @p value.
+ * @param[out] ws_only Whether the value is empty/white-spaces only.
+ * @param[out] dynamic Whether the value was dynamically allocated.
+ * @return LY_ERR value.
+ */
static LY_ERR
lyxml_next_attr_content(struct lyxml_ctx *xmlctx, const char **value, size_t *value_len, int *ws_only, int *dynamic)
{
@@ -718,6 +752,16 @@
return LY_SUCCESS;
}
+/**
+ * @brief Move parser to the next attribute and parse it.
+ *
+ * @param[in] xmlctx XML context to use.
+ * @param[out] prefix Parsed attribute prefix.
+ * @param[out] prefix_len Length of @p prefix.
+ * @param[out] name Parsed attribute name.
+ * @param[out] name_len Length of @p name.
+ * @return LY_ERR value.
+ */
static LY_ERR
lyxml_next_attribute(struct lyxml_ctx *xmlctx, const char **prefix, size_t *prefix_len, const char **name, size_t *name_len)
{
@@ -763,6 +807,16 @@
return LY_SUCCESS;
}
+/**
+ * @brief Move parser to the next element and parse it.
+ *
+ * @param[in] xmlctx XML context to use.
+ * @param[out] prefix Parsed element prefix.
+ * @param[out] prefix_len Length of @p prefix.
+ * @param[out] name Parse element name.
+ * @param[out] name_len Length of @p name.
+ * @return LY_ERR value.
+ */
static LY_ERR
lyxml_next_element(struct lyxml_ctx *xmlctx, const char **prefix, size_t *prefix_len, const char **name, size_t *name_len,
int *closing)
diff --git a/src/xml.h b/src/xml.h
index 38409fe..2ce7aa8 100644
--- a/src/xml.h
+++ b/src/xml.h
@@ -79,33 +79,57 @@
enum LYXML_PARSER_STATUS status; /* status providing information about the last parsed object, following attributes
are filled based on it */
union {
- const char *prefix; /* LYXML_ELEMENT, LYXML_ATTRIBUTE */
- const char *value; /* LYXML_ELEM_CONTENT, LYXML_ATTR_CONTENT */
+ const char *prefix; /* LYXML_ELEMENT, LYXML_ATTRIBUTE - elem/attr prefix */
+ const char *value; /* LYXML_ELEM_CONTENT, LYXML_ATTR_CONTENT - elem/attr value */
};
union {
- size_t prefix_len; /* LYXML_ELEMENT, LYXML_ATTRIBUTE */
- size_t value_len; /* LYXML_ELEM_CONTENT, LYXML_ATTR_CONTENT */
+ size_t prefix_len; /* LYXML_ELEMENT, LYXML_ATTRIBUTE - elem/attr prefix length */
+ size_t value_len; /* LYXML_ELEM_CONTENT, LYXML_ATTR_CONTENT - elem/attr value length */
};
union {
- const char *name; /* LYXML_ELEMENT, LYXML_ATTRIBUTE */
- int ws_only; /* LYXML_ELEM_CONTENT, LYXML_ATTR_CONTENT */
+ const char *name; /* LYXML_ELEMENT, LYXML_ATTRIBUTE - elem/attr name */
+ int ws_only; /* LYXML_ELEM_CONTENT, LYXML_ATTR_CONTENT - whether elem/attr value is empty/white-space only */
};
union {
- size_t name_len; /* LYXML_ELEMENT, LYXML_ATTRIBUTE */
- int dynamic; /* LYXML_ELEM_CONTENT, LYXML_ATTR_CONTENT */
+ size_t name_len; /* LYXML_ELEMENT, LYXML_ATTRIBUTE - elem/attr name length */
+ int dynamic; /* LYXML_ELEM_CONTENT, LYXML_ATTR_CONTENT - whether elem/attr value is dynamically allocated */
};
const struct ly_ctx *ctx;
- uint64_t line;
- const char *input;
+ uint64_t line; /* current line */
+ const char *input; /* current input pointer */
struct ly_set elements; /* list of not-yet-closed elements */
struct ly_set ns; /* handled with LY_SET_OPT_USEASLIST */
};
+/**
+ * @brief Create a new XML parser context and start parsing.
+ *
+ * @param[in] ctx libyang context.
+ * @param[in] input XML string data to parse.
+ * @param[out] xmlctx New XML context with status ::LYXML_ELEMENT.
+ * @return LY_ERR value.
+ */
LY_ERR lyxml_ctx_new(const struct ly_ctx *ctx, const char *input, struct lyxml_ctx **xmlctx);
+/**
+ * @brief Move to the next XML artefact and update parser status.
+ *
+ * LYXML_ELEMENT (-> LYXML_ATTRIBUTE -> LYXML_ATTR_CONTENT)* -> LYXML_ELEM_CONTENT -> LYXML_ELEM_CLOSE ...
+ * -> LYXML_ELEMENT ...
+ *
+ * @param[in] xmlctx XML context to move.
+ * @return LY_ERR value.
+ */
LY_ERR lyxml_ctx_next(struct lyxml_ctx *xmlctx);
+/**
+ * @brief Peek at the next XML parser status without changing it.
+ *
+ * @param[in] xmlctx XML context to use.
+ * @param[out] next Next XML parser status.
+ * @return LY_ERR value.
+ */
LY_ERR lyxml_ctx_peek(struct lyxml_ctx *xmlctx, enum LYXML_PARSER_STATUS *next);
/**
@@ -162,8 +186,4 @@
LY_ERR lyxml_value_compare(const char *value1, const struct ly_prefix *prefs1, const char *value2,
const struct ly_prefix *prefs2);
-void *lyxml_elem_dup(void *item);
-
-void *lyxml_ns_dup(void *item);
-
#endif /* LY_XML_H_ */