blob: 125271f4d2eca01694128869f95843c8241f5577 [file] [log] [blame]
Radek Krejcid91dbaf2018-09-21 15:51:39 +02001/**
2 * @file xml.h
3 * @author Radek Krejci <rkrejci@cesnet.cz>
4 * @brief Generic XML parser routines.
5 *
6 * Copyright (c) 2015 - 2018 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_XML_H_
16#define LY_XML_H_
17
Radek Krejcie7b95092019-05-15 11:03:07 +020018#include <stddef.h>
Radek Krejcid91dbaf2018-09-21 15:51:39 +020019#include <stdint.h>
20
Radek Krejcie7b95092019-05-15 11:03:07 +020021#include "log.h"
Radek Krejcid91dbaf2018-09-21 15:51:39 +020022#include "set.h"
23
Radek Krejci535ea9f2020-05-29 16:01:05 +020024struct ly_ctx;
Radek Krejci47fab892020-11-05 17:02:41 +010025struct ly_in;
Radek Krejci241f6b52020-05-21 18:13:49 +020026struct ly_out;
Radek Krejcie7b95092019-05-15 11:03:07 +020027
Radek Krejcib1646a92018-11-02 16:08:26 +010028/* Macro to test if character is whitespace */
29#define is_xmlws(c) (c == 0x20 || c == 0x9 || c == 0xa || c == 0xd)
30
31/* Macro to test if character is allowed to be a first character of an qualified identifier */
32#define is_xmlqnamestartchar(c) ((c >= 'a' && c <= 'z') || c == '_' || \
33 (c >= 'A' && c <= 'Z') || /* c == ':' || */ \
34 (c >= 0x370 && c <= 0x1fff && c != 0x37e ) || \
35 (c >= 0xc0 && c <= 0x2ff && c != 0xd7 && c != 0xf7) || c == 0x200c || \
36 c == 0x200d || (c >= 0x2070 && c <= 0x218f) || \
37 (c >= 0x2c00 && c <= 0x2fef) || (c >= 0x3001 && c <= 0xd7ff) || \
38 (c >= 0xf900 && c <= 0xfdcf) || (c >= 0xfdf0 && c <= 0xfffd) || \
39 (c >= 0x10000 && c <= 0xeffff))
40
41/* Macro to test if character is allowed to be used in an qualified identifier */
42#define is_xmlqnamechar(c) ((c >= 'a' && c <= 'z') || c == '_' || c == '-' || \
43 (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || /* c == ':' || */ \
44 c == '.' || c == 0xb7 || (c >= 0x370 && c <= 0x1fff && c != 0x37e ) ||\
45 (c >= 0xc0 && c <= 0x2ff && c != 0xd7 && c != 0xf7) || c == 0x200c || \
46 c == 0x200d || (c >= 0x300 && c <= 0x36f) || \
Radek Krejcic8a63902021-02-04 14:48:19 +010047 (c >= 0x2070 && c <= 0x218f) || (c >= 0x203f && c <= 0x2040) || \
Radek Krejcib1646a92018-11-02 16:08:26 +010048 (c >= 0x2c00 && c <= 0x2fef) || (c >= 0x3001 && c <= 0xd7ff) || \
49 (c >= 0xf900 && c <= 0xfdcf) || (c >= 0xfdf0 && c <= 0xfffd) || \
50 (c >= 0x10000 && c <= 0xeffff))
51
Radek Krejcid91dbaf2018-09-21 15:51:39 +020052struct lyxml_ns {
Radek Krejci4b74d5e2018-09-26 14:30:55 +020053 char *prefix; /* prefix of the namespace, NULL for the default namespace */
54 char *uri; /* namespace URI */
Michal Vaskob36053d2020-03-26 15:49:30 +010055 uint32_t depth; /* depth level of the element to maintain the list of accessible namespace definitions */
Radek Krejcid91dbaf2018-09-21 15:51:39 +020056};
57
Radek Krejcib1890642018-10-03 14:05:40 +020058/* element tag identifier for matching opening and closing tags */
59struct lyxml_elem {
Michal Vaskoda8fbbf2021-06-16 11:44:44 +020060 const char *prefix; /**< only pointer, not in dictionary */
61 const char *name; /**< only pointer, not in dictionary */
Radek Krejcib1890642018-10-03 14:05:40 +020062 size_t prefix_len;
63 size_t name_len;
64};
65
Radek Krejci28e8cb52019-03-08 11:31:31 +010066/**
67 * @brief Status of the parser providing information what is expected next (which function is supposed to be called).
68 */
Radek Krejcid91dbaf2018-09-21 15:51:39 +020069enum LYXML_PARSER_STATUS {
Michal Vaskob36053d2020-03-26 15:49:30 +010070 LYXML_ELEMENT, /* opening XML element parsed */
71 LYXML_ELEM_CLOSE, /* closing XML element parsed */
72 LYXML_ELEM_CONTENT, /* XML element context parsed */
73 LYXML_ATTRIBUTE, /* XML attribute parsed */
74 LYXML_ATTR_CONTENT, /* XML attribute content parsed */
Radek Krejcib1890642018-10-03 14:05:40 +020075 LYXML_END /* end of input data */
Radek Krejcid91dbaf2018-09-21 15:51:39 +020076};
77
Michal Vaskob36053d2020-03-26 15:49:30 +010078struct lyxml_ctx {
Radek Krejci1798aae2020-07-14 13:26:06 +020079 const struct ly_ctx *ctx;
Radek Krejci1798aae2020-07-14 13:26:06 +020080 struct ly_in *in; /* input structure */
81
Michal Vaskob36053d2020-03-26 15:49:30 +010082 enum LYXML_PARSER_STATUS status; /* status providing information about the last parsed object, following attributes
83 are filled based on it */
84 union {
Michal Vasko8cef5232020-06-15 17:59:47 +020085 const char *prefix; /* LYXML_ELEMENT, LYXML_ATTRIBUTE - elem/attr prefix */
86 const char *value; /* LYXML_ELEM_CONTENT, LYXML_ATTR_CONTENT - elem/attr value */
Michal Vaskob36053d2020-03-26 15:49:30 +010087 };
88 union {
Michal Vasko8cef5232020-06-15 17:59:47 +020089 size_t prefix_len; /* LYXML_ELEMENT, LYXML_ATTRIBUTE - elem/attr prefix length */
90 size_t value_len; /* LYXML_ELEM_CONTENT, LYXML_ATTR_CONTENT - elem/attr value length */
Michal Vaskob36053d2020-03-26 15:49:30 +010091 };
92 union {
Michal Vasko8cef5232020-06-15 17:59:47 +020093 const char *name; /* LYXML_ELEMENT, LYXML_ATTRIBUTE - elem/attr name */
Radek Krejci857189e2020-09-01 13:26:36 +020094 ly_bool ws_only; /* LYXML_ELEM_CONTENT, LYXML_ATTR_CONTENT - whether elem/attr value is empty/white-space only */
Michal Vaskob36053d2020-03-26 15:49:30 +010095 };
96 union {
Michal Vasko8cef5232020-06-15 17:59:47 +020097 size_t name_len; /* LYXML_ELEMENT, LYXML_ATTRIBUTE - elem/attr name length */
Radek Krejci857189e2020-09-01 13:26:36 +020098 ly_bool dynamic; /* LYXML_ELEM_CONTENT, LYXML_ATTR_CONTENT - whether elem/attr value is dynamically allocated */
Michal Vaskob36053d2020-03-26 15:49:30 +010099 };
100
Radek Krejcib1890642018-10-03 14:05:40 +0200101 struct ly_set elements; /* list of not-yet-closed elements */
Michal Vaskob36053d2020-03-26 15:49:30 +0100102 struct ly_set ns; /* handled with LY_SET_OPT_USEASLIST */
Radek Krejcid91dbaf2018-09-21 15:51:39 +0200103};
104
Michal Vasko8cef5232020-06-15 17:59:47 +0200105/**
106 * @brief Create a new XML parser context and start parsing.
107 *
108 * @param[in] ctx libyang context.
Michal Vasko63f3d842020-07-08 10:10:14 +0200109 * @param[in] in Input structure.
Michal Vasko8cef5232020-06-15 17:59:47 +0200110 * @param[out] xmlctx New XML context with status ::LYXML_ELEMENT.
111 * @return LY_ERR value.
112 */
Michal Vasko63f3d842020-07-08 10:10:14 +0200113LY_ERR lyxml_ctx_new(const struct ly_ctx *ctx, struct ly_in *in, struct lyxml_ctx **xmlctx);
Radek Krejci4b74d5e2018-09-26 14:30:55 +0200114
Michal Vasko8cef5232020-06-15 17:59:47 +0200115/**
116 * @brief Move to the next XML artefact and update parser status.
117 *
118 * LYXML_ELEMENT (-> LYXML_ATTRIBUTE -> LYXML_ATTR_CONTENT)* -> LYXML_ELEM_CONTENT -> LYXML_ELEM_CLOSE ...
119 * -> LYXML_ELEMENT ...
120 *
121 * @param[in] xmlctx XML context to move.
122 * @return LY_ERR value.
123 */
Michal Vaskob36053d2020-03-26 15:49:30 +0100124LY_ERR lyxml_ctx_next(struct lyxml_ctx *xmlctx);
Michal Vasko52927e22020-03-16 17:26:14 +0100125
Michal Vasko8cef5232020-06-15 17:59:47 +0200126/**
127 * @brief Peek at the next XML parser status without changing it.
128 *
129 * @param[in] xmlctx XML context to use.
130 * @param[out] next Next XML parser status.
131 * @return LY_ERR value.
132 */
Michal Vaskob36053d2020-03-26 15:49:30 +0100133LY_ERR lyxml_ctx_peek(struct lyxml_ctx *xmlctx, enum LYXML_PARSER_STATUS *next);
Radek Krejci4b74d5e2018-09-26 14:30:55 +0200134
135/**
Michal Vaskoddd76592022-01-17 13:34:48 +0100136 * @brief Remove all the namespaces defined in the element recently closed (removed from the xmlctx->elements).
137 *
138 * @param[in] xmlctx XML context to work with.
139 */
140void lyxml_ns_rm(struct lyxml_ctx *xmlctx);
141
142/**
Radek Krejci4b74d5e2018-09-26 14:30:55 +0200143 * @brief Get a namespace record for the given prefix in the current context.
144 *
Michal Vaskoc8a230d2020-08-14 12:17:10 +0200145 * @param[in] ns_set Set with namespaces from the XML context.
Radek Krejci84d7fd72021-07-14 18:32:21 +0200146 * @param[in] prefix Pointer to the namespace prefix. Can be NULL for default namespace.
147 * @param[in] prefix_len Length of the prefix string (since it might not be NULL-terminated).
Radek Krejci4b74d5e2018-09-26 14:30:55 +0200148 * @return The namespace record or NULL if the record for the specified prefix not found.
149 */
Michal Vaskoc8a230d2020-08-14 12:17:10 +0200150const struct lyxml_ns *lyxml_ns_get(const struct ly_set *ns_set, const char *prefix, size_t prefix_len);
Radek Krejci4b74d5e2018-09-26 14:30:55 +0200151
152/**
Radek Krejcie7b95092019-05-15 11:03:07 +0200153 * @brief Print the given @p text as XML string which replaces some of the characters which cannot appear in XML data.
154 *
155 * @param[in] out Output structure for printing.
156 * @param[in] text String to print.
157 * @param[in] attribute Flag for attribute's value where a double quotes must be replaced.
158 * @return LY_ERR values.
159 */
Radek Krejci857189e2020-09-01 13:26:36 +0200160LY_ERR lyxml_dump_text(struct ly_out *out, const char *text, ly_bool attribute);
Radek Krejcie7b95092019-05-15 11:03:07 +0200161
162/**
Radek Krejcib1890642018-10-03 14:05:40 +0200163 * @brief Remove the allocated working memory of the context.
164 *
Michal Vaskob36053d2020-03-26 15:49:30 +0100165 * @param[in] xmlctx XML context to clear.
Radek Krejcib1890642018-10-03 14:05:40 +0200166 */
Michal Vaskob36053d2020-03-26 15:49:30 +0100167void lyxml_ctx_free(struct lyxml_ctx *xmlctx);
Radek Krejcib1890642018-10-03 14:05:40 +0200168
Michal Vasko52927e22020-03-16 17:26:14 +0100169/**
Michal Vaskoda8fbbf2021-06-16 11:44:44 +0200170 * @brief Create a backup of XML context.
171 *
172 * @param[in] xmlctx XML context to back up.
173 * @param[out] backup Backup XML context.
174 * @return LY_ERR value.
175 */
176LY_ERR lyxml_ctx_backup(struct lyxml_ctx *xmlctx, struct lyxml_ctx *backup);
177
178/**
179 * @brief Restore previous backup of XML context.
180 *
181 * @param[in,out] xmlctx XML context to restore.
aPiecekb0445f22021-06-24 11:34:07 +0200182 * @param[in] backup Backup XML context to restore, is unusable afterwards.
Michal Vaskoda8fbbf2021-06-16 11:44:44 +0200183 */
184void lyxml_ctx_restore(struct lyxml_ctx *xmlctx, struct lyxml_ctx *backup);
185
186/**
Michal Vasko52927e22020-03-16 17:26:14 +0100187 * @brief Compare values and their prefix mappings.
188 *
aPiecek2f63f952021-03-30 12:22:18 +0200189 * @param[in] ctx1 Libyang context for resolving prefixes in @p value1.
Michal Vasko52927e22020-03-16 17:26:14 +0100190 * @param[in] value1 First value.
Michal Vasko6b5cb2a2020-11-11 19:11:21 +0100191 * @param[in] val_prefix_data1 First value prefix data.
aPiecek2f63f952021-03-30 12:22:18 +0200192 * @param[in] ctx2 Libyang context for resolving prefixes in @p value2.
193 * Can be set to NULL if @p ctx1 is equal to @p ctx2.
Michal Vasko52927e22020-03-16 17:26:14 +0100194 * @param[in] value2 Second value.
Michal Vasko6b5cb2a2020-11-11 19:11:21 +0100195 * @param[in] val_prefix_data2 Second value prefix data.
Michal Vasko52927e22020-03-16 17:26:14 +0100196 * @return LY_SUCCESS if values are equal.
197 * @return LY_ENOT if values are not equal.
198 * @return LY_ERR on error.
199 */
aPiecek2f63f952021-03-30 12:22:18 +0200200LY_ERR lyxml_value_compare(const struct ly_ctx *ctx1, const char *value1, void *val_prefix_data1,
201 const struct ly_ctx *ctx2, const char *value2, void *val_prefix_data2);
Michal Vasko52927e22020-03-16 17:26:14 +0100202
Radek Krejcib416be62018-10-01 14:51:45 +0200203#endif /* LY_XML_H_ */