1/* gmarkup.h - Simple XML-like string parser/writer
2 *
3 * Copyright 2000 Red Hat, Inc.
4 *
5 * SPDX-License-Identifier: LGPL-2.1-or-later
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public License
18 * along with this library; if not, see <http://www.gnu.org/licenses/>.
19 */
20
21#ifndef __G_MARKUP_H__
22#define __G_MARKUP_H__
23
24#if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
25#error "Only <glib.h> can be included directly."
26#endif
27
28#include <stdarg.h>
29
30#include <glib/gerror.h>
31#include <glib/gslist.h>
32
33G_BEGIN_DECLS
34
35/**
36 * GMarkupError:
37 * @G_MARKUP_ERROR_BAD_UTF8: text being parsed was not valid UTF-8
38 * @G_MARKUP_ERROR_EMPTY: document contained nothing, or only whitespace
39 * @G_MARKUP_ERROR_PARSE: document was ill-formed
40 * @G_MARKUP_ERROR_UNKNOWN_ELEMENT: error should be set by #GMarkupParser
41 * functions; element wasn't known
42 * @G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE: error should be set by #GMarkupParser
43 * functions; attribute wasn't known
44 * @G_MARKUP_ERROR_INVALID_CONTENT: error should be set by #GMarkupParser
45 * functions; content was invalid
46 * @G_MARKUP_ERROR_MISSING_ATTRIBUTE: error should be set by #GMarkupParser
47 * functions; a required attribute was missing
48 *
49 * Error codes returned by markup parsing.
50 */
51typedef enum
52{
53 G_MARKUP_ERROR_BAD_UTF8,
54 G_MARKUP_ERROR_EMPTY,
55 G_MARKUP_ERROR_PARSE,
56 /* The following are primarily intended for specific GMarkupParser
57 * implementations to set.
58 */
59 G_MARKUP_ERROR_UNKNOWN_ELEMENT,
60 G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE,
61 G_MARKUP_ERROR_INVALID_CONTENT,
62 G_MARKUP_ERROR_MISSING_ATTRIBUTE
63} GMarkupError;
64
65/**
66 * G_MARKUP_ERROR:
67 *
68 * Error domain for markup parsing.
69 * Errors in this domain will be from the #GMarkupError enumeration.
70 * See #GError for information on error domains.
71 */
72#define G_MARKUP_ERROR g_markup_error_quark ()
73
74GLIB_AVAILABLE_IN_ALL
75GQuark g_markup_error_quark (void);
76
77/**
78 * GMarkupParseFlags:
79 * @G_MARKUP_DEFAULT_FLAGS: No special behaviour. Since: 2.74
80 * @G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG: flag you should not use
81 * @G_MARKUP_TREAT_CDATA_AS_TEXT: When this flag is set, CDATA marked
82 * sections are not passed literally to the @passthrough function of
83 * the parser. Instead, the content of the section (without the
84 * `<![CDATA[` and `]]>`) is
85 * passed to the @text function. This flag was added in GLib 2.12
86 * @G_MARKUP_PREFIX_ERROR_POSITION: Normally errors caught by GMarkup
87 * itself have line/column information prefixed to them to let the
88 * caller know the location of the error. When this flag is set the
89 * location information is also prefixed to errors generated by the
90 * #GMarkupParser implementation functions
91 * @G_MARKUP_IGNORE_QUALIFIED: Ignore (don't report) qualified
92 * attributes and tags, along with their contents. A qualified
93 * attribute or tag is one that contains ':' in its name (ie: is in
94 * another namespace). Since: 2.40.
95 *
96 * Flags that affect the behaviour of the parser.
97 */
98typedef enum
99{
100 G_MARKUP_DEFAULT_FLAGS GLIB_AVAILABLE_ENUMERATOR_IN_2_74 = 0,
101 G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG = 1 << 0,
102 G_MARKUP_TREAT_CDATA_AS_TEXT = 1 << 1,
103 G_MARKUP_PREFIX_ERROR_POSITION = 1 << 2,
104 G_MARKUP_IGNORE_QUALIFIED = 1 << 3
105} GMarkupParseFlags;
106
107/**
108 * GMarkupParseContext:
109 *
110 * A parse context is used to parse a stream of bytes that
111 * you expect to contain marked-up text.
112 *
113 * See g_markup_parse_context_new(), #GMarkupParser, and so
114 * on for more details.
115 */
116typedef struct _GMarkupParseContext GMarkupParseContext;
117typedef struct _GMarkupParser GMarkupParser;
118
119/**
120 * GMarkupParser:
121 * @start_element: Callback to invoke when the opening tag of an element
122 * is seen. The callback's @attribute_names and @attribute_values parameters
123 * are %NULL-terminated.
124 * @end_element: Callback to invoke when the closing tag of an element
125 * is seen. Note that this is also called for empty tags like
126 * `<empty/>`.
127 * @text: Callback to invoke when some text is seen (text is always
128 * inside an element). Note that the text of an element may be spread
129 * over multiple calls of this function. If the
130 * %G_MARKUP_TREAT_CDATA_AS_TEXT flag is set, this function is also
131 * called for the content of CDATA marked sections.
132 * @passthrough: Callback to invoke for comments, processing instructions
133 * and doctype declarations; if you're re-writing the parsed document,
134 * write the passthrough text back out in the same position. If the
135 * %G_MARKUP_TREAT_CDATA_AS_TEXT flag is not set, this function is also
136 * called for CDATA marked sections.
137 * @error: Callback to invoke when an error occurs.
138 *
139 * Any of the fields in #GMarkupParser can be %NULL, in which case they
140 * will be ignored. Except for the @error function, any of these callbacks
141 * can set an error; in particular the %G_MARKUP_ERROR_UNKNOWN_ELEMENT,
142 * %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE, and %G_MARKUP_ERROR_INVALID_CONTENT
143 * errors are intended to be set from these callbacks. If you set an error
144 * from a callback, g_markup_parse_context_parse() will report that error
145 * back to its caller.
146 *
147 * Refer to the [GMarkup](../glib/markup.html) documentation to understand
148 * the scope and limitations of `GMarkupParser`. In particular, it is not a
149 * full XML parser and it must not be used to process untrusted data.
150 */
151struct _GMarkupParser
152{
153 /* Called for open tags <foo bar="baz"> */
154 void (*start_element) (GMarkupParseContext *context,
155 const gchar *element_name,
156 const gchar **attribute_names,
157 const gchar **attribute_values,
158 gpointer user_data,
159 GError **error);
160
161 /* Called for close tags </foo> */
162 void (*end_element) (GMarkupParseContext *context,
163 const gchar *element_name,
164 gpointer user_data,
165 GError **error);
166
167 /* Called for character data */
168 /* text is not nul-terminated */
169 void (*text) (GMarkupParseContext *context,
170 const gchar *text,
171 gsize text_len,
172 gpointer user_data,
173 GError **error);
174
175 /* Called for strings that should be re-saved verbatim in this same
176 * position, but are not otherwise interpretable. At the moment
177 * this includes comments and processing instructions.
178 */
179 /* text is not nul-terminated. */
180 void (*passthrough) (GMarkupParseContext *context,
181 const gchar *passthrough_text,
182 gsize text_len,
183 gpointer user_data,
184 GError **error);
185
186 /* Called on error, including one set by other
187 * methods in the vtable. The GError should not be freed.
188 */
189 void (*error) (GMarkupParseContext *context,
190 GError *error,
191 gpointer user_data);
192};
193
194GLIB_AVAILABLE_IN_ALL
195GMarkupParseContext *g_markup_parse_context_new (const GMarkupParser *parser,
196 GMarkupParseFlags flags,
197 gpointer user_data,
198 GDestroyNotify user_data_dnotify);
199GLIB_AVAILABLE_IN_2_36
200GMarkupParseContext *g_markup_parse_context_ref (GMarkupParseContext *context);
201GLIB_AVAILABLE_IN_2_36
202void g_markup_parse_context_unref (GMarkupParseContext *context);
203GLIB_AVAILABLE_IN_ALL
204void g_markup_parse_context_free (GMarkupParseContext *context);
205GLIB_AVAILABLE_IN_ALL
206gboolean g_markup_parse_context_parse (GMarkupParseContext *context,
207 const gchar *text,
208 gssize text_len,
209 GError **error);
210GLIB_AVAILABLE_IN_ALL
211void g_markup_parse_context_push (GMarkupParseContext *context,
212 const GMarkupParser *parser,
213 gpointer user_data);
214GLIB_AVAILABLE_IN_ALL
215gpointer g_markup_parse_context_pop (GMarkupParseContext *context);
216
217GLIB_AVAILABLE_IN_ALL
218gboolean g_markup_parse_context_end_parse (GMarkupParseContext *context,
219 GError **error);
220GLIB_AVAILABLE_IN_ALL
221const gchar * g_markup_parse_context_get_element (GMarkupParseContext *context);
222GLIB_AVAILABLE_IN_ALL
223const GSList * g_markup_parse_context_get_element_stack (GMarkupParseContext *context);
224
225/* For user-constructed error messages, has no precise semantics */
226GLIB_AVAILABLE_IN_ALL
227void g_markup_parse_context_get_position (GMarkupParseContext *context,
228 gint *line_number,
229 gint *char_number);
230GLIB_AVAILABLE_IN_ALL
231gpointer g_markup_parse_context_get_user_data (GMarkupParseContext *context);
232
233/* useful when saving */
234GLIB_AVAILABLE_IN_ALL
235gchar* g_markup_escape_text (const gchar *text,
236 gssize length);
237
238GLIB_AVAILABLE_IN_ALL
239gchar *g_markup_printf_escaped (const char *format,
240 ...) G_GNUC_PRINTF (1, 2);
241GLIB_AVAILABLE_IN_ALL
242gchar *g_markup_vprintf_escaped (const char *format,
243 va_list args) G_GNUC_PRINTF(1, 0);
244
245typedef enum
246{
247 G_MARKUP_COLLECT_INVALID,
248 G_MARKUP_COLLECT_STRING,
249 G_MARKUP_COLLECT_STRDUP,
250 G_MARKUP_COLLECT_BOOLEAN,
251 G_MARKUP_COLLECT_TRISTATE,
252
253 G_MARKUP_COLLECT_OPTIONAL = (1 << 16)
254} GMarkupCollectType;
255
256
257/* useful from start_element */
258GLIB_AVAILABLE_IN_ALL
259gboolean g_markup_collect_attributes (const gchar *element_name,
260 const gchar **attribute_names,
261 const gchar **attribute_values,
262 GError **error,
263 GMarkupCollectType first_type,
264 const gchar *first_attr,
265 ...);
266
267G_END_DECLS
268
269#endif /* __G_MARKUP_H__ */
270