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