nexmon – Blame information for rev 1

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