blob: 7965e7e05b53721eb81287381d5d3344f1649918 [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 Krejcie7b95092019-05-15 11:03:07 +020024struct lyout;
25
Radek Krejcib1646a92018-11-02 16:08:26 +010026/* Macro to test if character is whitespace */
27#define is_xmlws(c) (c == 0x20 || c == 0x9 || c == 0xa || c == 0xd)
28
29/* Macro to test if character is allowed to be a first character of an qualified identifier */
30#define is_xmlqnamestartchar(c) ((c >= 'a' && c <= 'z') || c == '_' || \
31 (c >= 'A' && c <= 'Z') || /* c == ':' || */ \
32 (c >= 0x370 && c <= 0x1fff && c != 0x37e ) || \
33 (c >= 0xc0 && c <= 0x2ff && c != 0xd7 && c != 0xf7) || c == 0x200c || \
34 c == 0x200d || (c >= 0x2070 && c <= 0x218f) || \
35 (c >= 0x2c00 && c <= 0x2fef) || (c >= 0x3001 && c <= 0xd7ff) || \
36 (c >= 0xf900 && c <= 0xfdcf) || (c >= 0xfdf0 && c <= 0xfffd) || \
37 (c >= 0x10000 && c <= 0xeffff))
38
39/* Macro to test if character is allowed to be used in an qualified identifier */
40#define is_xmlqnamechar(c) ((c >= 'a' && c <= 'z') || c == '_' || c == '-' || \
41 (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || /* c == ':' || */ \
42 c == '.' || c == 0xb7 || (c >= 0x370 && c <= 0x1fff && c != 0x37e ) ||\
43 (c >= 0xc0 && c <= 0x2ff && c != 0xd7 && c != 0xf7) || c == 0x200c || \
44 c == 0x200d || (c >= 0x300 && c <= 0x36f) || \
45 (c >= 0x2070 && c <= 0x218f) || (c >= 0x2030f && c <= 0x2040) || \
46 (c >= 0x2c00 && c <= 0x2fef) || (c >= 0x3001 && c <= 0xd7ff) || \
47 (c >= 0xf900 && c <= 0xfdcf) || (c >= 0xfdf0 && c <= 0xfffd) || \
48 (c >= 0x10000 && c <= 0xeffff))
49
Radek Krejcid91dbaf2018-09-21 15:51:39 +020050struct lyxml_ns {
Radek Krejci4b74d5e2018-09-26 14:30:55 +020051 char *prefix; /* prefix of the namespace, NULL for the default namespace */
52 char *uri; /* namespace URI */
Radek Krejci17a78d82019-05-15 15:49:55 +020053 unsigned int depth; /* depth level of the element to maintain the list of accessible namespace definitions */
Radek Krejcid91dbaf2018-09-21 15:51:39 +020054};
55
Radek Krejcib1890642018-10-03 14:05:40 +020056/* element tag identifier for matching opening and closing tags */
57struct lyxml_elem {
58 const char *prefix;
59 const char *name;
60 size_t prefix_len;
61 size_t name_len;
62};
63
Radek Krejci28e8cb52019-03-08 11:31:31 +010064/**
65 * @brief Status of the parser providing information what is expected next (which function is supposed to be called).
66 */
Radek Krejcid91dbaf2018-09-21 15:51:39 +020067enum LYXML_PARSER_STATUS {
Michal Vasko9b368d32020-02-14 13:53:31 +010068 LYXML_ELEMENT = 0, /* expecting XML element, call lyxml_get_element() */
Radek Krejcib1890642018-10-03 14:05:40 +020069 LYXML_ELEM_CONTENT, /* expecting content of an element, call lyxml_get_string */
70 LYXML_ATTRIBUTE, /* expecting XML attribute, call lyxml_get_attribute() */
71 LYXML_ATTR_CONTENT, /* expecting value of an attribute, call lyxml_get_string */
72 LYXML_END /* end of input data */
Radek Krejcid91dbaf2018-09-21 15:51:39 +020073};
74
75struct lyxml_context {
76 struct ly_ctx *ctx;
77 uint64_t line;
Radek Krejcib1890642018-10-03 14:05:40 +020078 enum LYXML_PARSER_STATUS status; /* status providing information about the next expected object in input data */
79 struct ly_set elements; /* list of not-yet-closed elements */
Radek Krejci4b74d5e2018-09-26 14:30:55 +020080 struct ly_set ns; /* handled with LY_SET_OPT_USEASLIST */
Radek Krejcid91dbaf2018-09-21 15:51:39 +020081};
82
Radek Krejci4b74d5e2018-09-26 14:30:55 +020083/**
84 * @brief Parse input expecting an XML element.
85 *
Radek Krejcie7b95092019-05-15 11:03:07 +020086 * Able to silently skip comments, PIs and CData. DOCTYPE is not parseable, so it is reported as LY_EVALID error.
Radek Krejci4b74d5e2018-09-26 14:30:55 +020087 * If '<' is not found in input, LY_EINVAL is returned (but no error is logged), so it is possible to continue
88 * with parsing input as text content.
89 *
90 * Input string is not being modified, so the returned values are not NULL-terminated, instead their length
91 * is returned.
92 *
93 * @param[in] context XML context to track lines or store errors into libyang context.
94 * @param[in,out] input Input string to process, updated according to the processed/read data.
95 * @param[in] options Currently unused options to modify input processing.
96 * @param[out] prefix Pointer to prefix if present in the element name, NULL otherwise.
97 * @param[out] prefix_len Length of the prefix if any.
Radek Krejcib1890642018-10-03 14:05:40 +020098 * @param[out] name Element name. When LY_SUCCESS is returned but name is NULL, check context's status field:
99 * - LYXML_END - end of input was reached
Radek Krejci28e8cb52019-03-08 11:31:31 +0100100 * - LYXML_ELEMENT - closing element found, expecting now a sibling element so call lyxml_get_element() again
Radek Krejci4b74d5e2018-09-26 14:30:55 +0200101 * @param[out] name_len Length of the element name.
102 * @return LY_ERR values.
103 */
104LY_ERR lyxml_get_element(struct lyxml_context *context, const char **input,
105 const char **prefix, size_t *prefix_len, const char **name, size_t *name_len);
106
107/**
108 * @brief Parse input expecting an XML attribute (including XML namespace).
109 *
110 * Input string is not being modified, so the returned values are not NULL-terminated, instead their length
111 * is returned.
112 *
Radek Krejci17a78d82019-05-15 15:49:55 +0200113 * Namespace definitions are processed automatically and stored internally. To get namespace for a specific
114 * prefix, use lyxml_get_ns(). This also means, that in case there are only the namespace definitions,
115 * lyxml_get_attribute() can succeed, but nothing (name, prefix) is returned.
116 *
117 * The status member of the context is updated to provide information what the caller is supposed to call
118 * after this function.
Radek Krejci4b74d5e2018-09-26 14:30:55 +0200119 *
120 * @param[in] context XML context to track lines or store errors into libyang context.
121 * @param[in,out] input Input string to process, updated according to the processed/read data so,
122 * when succeeded, it points to the opening quote of the attribute's value.
123 * @param[out] prefix Pointer to prefix if present in the attribute name, NULL otherwise.
124 * @param[out] prefix_len Length of the prefix if any.
Radek Krejci17a78d82019-05-15 15:49:55 +0200125 * @param[out] name Attribute name. Can be NULL only in case there is actually no attribute, but namespaces.
Radek Krejci4b74d5e2018-09-26 14:30:55 +0200126 * @param[out] name_len Length of the element name.
127 * @return LY_ERR values.
128 */
129LY_ERR lyxml_get_attribute(struct lyxml_context *context, const char **input,
130 const char **prefix, size_t *prefix_len, const char **name, size_t *name_len);
131
132/**
133 * @brief Parse input as XML text (attribute's values and element's content).
134 *
135 * Mixed content of XML elements is not allowed. Formating whitespaces before child element are ignored,
Radek Krejcid70d1072018-10-09 14:20:47 +0200136 * LY_EINVAL is returned in such a case (output is not set, no error is printed) and input is moved
Radek Krejci4b74d5e2018-09-26 14:30:55 +0200137 * to the beginning of a child definition.
138 *
139 * In the case of attribute's values, the input string is expected to start on a quotation mark to
140 * select which delimiter (single or double quote) is used. Otherwise, the element content is being
141 * parsed expected to be terminated by '<' character.
142 *
Radek Krejcid70d1072018-10-09 14:20:47 +0200143 * If function succeeds, the string in a dynamically allocated output buffer is always NULL-terminated.
144 *
145 * The dynamically allocated buffer is used only when necessary because of a character or the supported entity
146 * reference which modify the input data. These constructs are replaced by their real value, so in case the output
147 * string will be again printed as an XML data, it may be necessary to correctly encode such characters.
Radek Krejci4b74d5e2018-09-26 14:30:55 +0200148 *
Radek Krejciee4cab22019-07-17 17:07:47 +0200149 * Optionally, the buffer, buffer_size, output, length and dynamic arguments (altogether) can be NULL.
150 * In such a case, the XML text in @p input is just checked, the @p input pointer is moved after the XML text, but nothing is stored.
151 *
Radek Krejci4b74d5e2018-09-26 14:30:55 +0200152 * @param[in] context XML context to track lines or store errors into libyang context.
153 * @param[in,out] input Input string to process, updated according to the processed/read data.
Radek Krejcid70d1072018-10-09 14:20:47 +0200154 * @param[in, out] buffer Storage for the output string. If the parameter points to NULL, the buffer is allocated if needed.
155 * Otherwise, when needed, the buffer is used and enlarged when necessary. Whenever the buffer is used, the string is NULL-terminated.
156 * @param[in, out] buffer_size Allocated size of the returned buffer. If a buffer is provided by a caller, it
Radek Krejci4b74d5e2018-09-26 14:30:55 +0200157 * is not being reduced even if the string is shorter. On the other hand, it can be enlarged if needed.
Radek Krejcid70d1072018-10-09 14:20:47 +0200158 * @param[out] output Returns pointer to the resulting string - to the provided/allocated buffer if it was necessary to modify
159 * the input string or directly into the input string (see the \p dynamic parameter).
160 * @param[out] length Length of the \p output string.
161 * @param[out] dynamic Flag if a dynamically allocated memory (\p buffer) was used and caller is supposed to free it at the end.
162 * In case the value is zero, the \p output points directly into the \p input string.
Radek Krejci4b74d5e2018-09-26 14:30:55 +0200163 * @return LY_ERR value.
164 */
Radek Krejcid70d1072018-10-09 14:20:47 +0200165LY_ERR lyxml_get_string(struct lyxml_context *context, const char **input, char **buffer, size_t *buffer_size, char **output, size_t *length, int *dynamic);
Radek Krejci4b74d5e2018-09-26 14:30:55 +0200166
167/**
Radek Krejci4b74d5e2018-09-26 14:30:55 +0200168 * @brief Get a namespace record for the given prefix in the current context.
169 *
170 * @param[in] context XML context to work with.
171 * @param[in] prefix Pointer to the namespace prefix as taken from lyxml_get_attribute() or lyxml_get_element().
172 * Can be NULL for default namespace.
173 * @param[in] prefix_len Length of the prefix string (since it is not NULL-terminated when returned from lyxml_get_attribute() or
174 * lyxml_get_element()).
175 * @return The namespace record or NULL if the record for the specified prefix not found.
176 */
177const struct lyxml_ns *lyxml_ns_get(struct lyxml_context *context, const char *prefix, size_t prefix_len);
178
179/**
Radek Krejcie7b95092019-05-15 11:03:07 +0200180 * @brief Print the given @p text as XML string which replaces some of the characters which cannot appear in XML data.
181 *
182 * @param[in] out Output structure for printing.
183 * @param[in] text String to print.
184 * @param[in] attribute Flag for attribute's value where a double quotes must be replaced.
185 * @return LY_ERR values.
186 */
187LY_ERR lyxml_dump_text(struct lyout *out, const char *text, int attribute);
188
189/**
Radek Krejcib1890642018-10-03 14:05:40 +0200190 * @brief Remove the allocated working memory of the context.
191 *
192 * @param[in] context XML context to clear.
193 */
194void lyxml_context_clear(struct lyxml_context *context);
195
Radek Krejcib416be62018-10-01 14:51:45 +0200196#endif /* LY_XML_H_ */