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 31 G_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 */ 49 typedef 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 72 GLIB_AVAILABLE_IN_ALL 73 GQuark 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 */ 95 typedef 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 */ 112 typedef struct _GMarkupParseContext GMarkupParseContext; 113 typedef 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 */ 143 struct _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 186 GLIB_AVAILABLE_IN_ALL 187 GMarkupParseContext *g_markup_parse_context_new (const GMarkupParser *parser, 188 GMarkupParseFlags flags, 189 gpointer user_data, 190 GDestroyNotify user_data_dnotify); 191 GLIB_AVAILABLE_IN_2_36 192 GMarkupParseContext *g_markup_parse_context_ref (GMarkupParseContext *context); 193 GLIB_AVAILABLE_IN_2_36 194 void g_markup_parse_context_unref (GMarkupParseContext *context); 195 GLIB_AVAILABLE_IN_ALL 196 void g_markup_parse_context_free (GMarkupParseContext *context); 197 GLIB_AVAILABLE_IN_ALL 198 gboolean g_markup_parse_context_parse (GMarkupParseContext *context, 199 const gchar *text, 200 gssize text_len, 201 GError **error); 202 GLIB_AVAILABLE_IN_ALL 203 void g_markup_parse_context_push (GMarkupParseContext *context, 204 const GMarkupParser *parser, 205 gpointer user_data); 206 GLIB_AVAILABLE_IN_ALL 207 gpointer g_markup_parse_context_pop (GMarkupParseContext *context); 208 209 GLIB_AVAILABLE_IN_ALL 210 gboolean g_markup_parse_context_end_parse (GMarkupParseContext *context, 211 GError **error); 212 GLIB_AVAILABLE_IN_ALL 213 const gchar * g_markup_parse_context_get_element (GMarkupParseContext *context); 214 GLIB_AVAILABLE_IN_ALL 215 const GSList * g_markup_parse_context_get_element_stack (GMarkupParseContext *context); 216 217 /* For user-constructed error messages, has no precise semantics */ 218 GLIB_AVAILABLE_IN_ALL 219 void g_markup_parse_context_get_position (GMarkupParseContext *context, 220 gint *line_number, 221 gint *char_number); 222 GLIB_AVAILABLE_IN_ALL 223 gpointer g_markup_parse_context_get_user_data (GMarkupParseContext *context); 224 225 /* useful when saving */ 226 GLIB_AVAILABLE_IN_ALL 227 gchar* g_markup_escape_text (const gchar *text, 228 gssize length); 229 230 GLIB_AVAILABLE_IN_ALL 231 gchar *g_markup_printf_escaped (const char *format, 232 ...) G_GNUC_PRINTF (1, 2); 233 GLIB_AVAILABLE_IN_ALL 234 gchar *g_markup_vprintf_escaped (const char *format, 235 va_list args) G_GNUC_PRINTF(1, 0); 236 237 typedef 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 */ 250 GLIB_AVAILABLE_IN_ALL 251 gboolean 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 259 G_END_DECLS 260 261 #endif /* __G_MARKUP_H__ */ 262