1<!-- ##### SECTION Title ##### --> 2Simple XML Subset Parser 3 4<!-- ##### SECTION Short_Description ##### --> 5parses a subset of XML 6 7<!-- ##### SECTION Long_Description ##### --> 8<para> 9The "GMarkup" parser is intended to parse a simple markup format 10that's a subset of XML. This is a small, efficient, easy-to-use 11parser. It should not be used if you expect to interoperate with other 12applications generating full-scale XML. However, it's very useful for 13application data files, config files, etc. where you know your 14application will be the only one writing the file. Full-scale XML 15parsers should be able to parse the subset used by GMarkup, so you can 16easily migrate to full-scale XML at a later time if the need arises. 17</para> 18 19<para> 20GMarkup is not guaranteed to signal an error on all invalid XML; the 21parser may accept documents that an XML parser would not. However, XML 22documents which are not well-formed<footnote id="wellformed">Being wellformed 23is a weaker condition than being valid. See the 24<ulink url="http://www.w3.org/TR/REC-xml/">XML specification</ulink> for 25definitions of these terms.</footnote> are not considered valid GMarkup 26documents. 27</para> 28 29<para> 30Simplifications to XML include: 31<itemizedlist> 32<listitem> 33<para> 34Only UTF-8 encoding is allowed. 35</para> 36</listitem> 37<listitem> 38<para> 39No user-defined entities. 40</para> 41</listitem> 42<listitem> 43<para> 44Processing instructions, comments and the doctype declaration are "passed 45through" but are not interpreted in any way. 46</para> 47</listitem> 48<listitem> 49<para> 50No DTD or validation. 51</para> 52</listitem> 53</itemizedlist> 54</para> 55 56<para> 57The markup format does support: 58<itemizedlist> 59<listitem> 60<para> 61Elements 62</para> 63</listitem> 64<listitem> 65<para> 66Attributes 67</para> 68</listitem> 69<listitem> 70<para> 715 standard entities: <literal>&amp; &lt; &gt; &quot; &apos;</literal> 72</para> 73</listitem> 74<listitem> 75<para> 76Character references 77</para> 78</listitem> 79<listitem> 80<para> 81Sections marked as CDATA 82</para> 83</listitem> 84</itemizedlist> 85</para> 86 87<!-- ##### SECTION See_Also ##### --> 88<para> 89 90</para> 91 92<!-- ##### SECTION Stability_Level ##### --> 93 94 95<!-- ##### ENUM GMarkupError ##### --> 96<para> 97Error codes returned by markup parsing. 98</para> 99 100@G_MARKUP_ERROR_BAD_UTF8: text being parsed was not valid UTF-8 101@G_MARKUP_ERROR_EMPTY: document contained nothing, or only whitespace 102@G_MARKUP_ERROR_PARSE: document was ill-formed 103@G_MARKUP_ERROR_UNKNOWN_ELEMENT: error should be set by #GMarkupParser functions; element wasn't known 104@G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE: error should be set by #GMarkupParser functions; attribute wasn't known 105@G_MARKUP_ERROR_INVALID_CONTENT: error should be set by #GMarkupParser functions; content was invalid 106@G_MARKUP_ERROR_MISSING_ATTRIBUTE: error should be set by #GMarkupParser functions; a required attribute was missing 107 108<!-- ##### MACRO G_MARKUP_ERROR ##### --> 109<para> 110Error domain for markup parsing. Errors in this domain will 111be from the #GMarkupError enumeration. See #GError for information on 112error domains. 113</para> 114 115 116 117<!-- ##### ENUM GMarkupParseFlags ##### --> 118<para> 119Flags that affect the behaviour of the parser. 120</para> 121 122@G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG: flag you should not use. 123@G_MARKUP_TREAT_CDATA_AS_TEXT: When this flag is set, CDATA marked 124 sections are not passed literally to the @passthrough function of 125 the parser. Instead, the content of the section (without the 126 <literal><![CDATA[</literal> and <literal>]]></literal>) is 127 passed to the @text function. This flag was added in GLib 2.12. 128@G_MARKUP_PREFIX_ERROR_POSITION: Normally errors caught by GMarkup 129 itself have line/column information prefixed to them to let the 130 caller know the location of the error. When this flag is set the 131 location information is also prefixed to errors generated by the 132 #GMarkupParser implementation functions. 133 134<!-- ##### STRUCT GMarkupParseContext ##### --> 135<para> 136A parse context is used to parse a stream of bytes that you expect to 137contain marked-up text. See g_markup_parse_context_new(), 138#GMarkupParser, and so on for more details. 139</para> 140 141 142<!-- ##### STRUCT GMarkupParser ##### --> 143<para> 144Any of the fields in #GMarkupParser can be %NULL, in which case they 145will be ignored. Except for the @error function, any of these 146callbacks can set an error; in particular the 147%G_MARKUP_ERROR_UNKNOWN_ELEMENT, %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE, 148and %G_MARKUP_ERROR_INVALID_CONTENT errors are intended to be set 149from these callbacks. If you set an error from a callback, 150g_markup_parse_context_parse() will report that error back to its caller. 151</para> 152 153@start_element: Callback to invoke when the opening tag of an element 154 is seen. 155@end_element: Callback to invoke when the closing tag of an element is seen. 156 Note that this is also called for empty tags like 157 <literal><empty/></literal>. 158@text: Callback to invoke when some text is seen (text is always 159 inside an element). Note that the text of an element may be spread 160 over multiple calls of this function. If the %G_MARKUP_TREAT_CDATA_AS_TEXT 161 flag is set, this function is also called for the content of CDATA marked 162 sections. 163@passthrough: Callback to invoke for comments, processing instructions 164 and doctype declarations; if you're re-writing the parsed document, 165 write the passthrough text back out in the same position. If the 166 %G_MARKUP_TREAT_CDATA_AS_TEXT flag is not set, this function is also 167 called for CDATA marked sections. 168@error: Callback to invoke when an error occurs. 169 170<!-- ##### FUNCTION g_markup_escape_text ##### --> 171<para> 172 173</para> 174 175@text: 176@length: 177@Returns: 178 179 180<!-- ##### FUNCTION g_markup_printf_escaped ##### --> 181<para> 182 183</para> 184 185@format: 186@Varargs: 187@Returns: 188 189 190<!-- ##### FUNCTION g_markup_vprintf_escaped ##### --> 191<para> 192 193</para> 194 195@format: 196@args: 197@Returns: 198 199 200<!-- ##### FUNCTION g_markup_parse_context_end_parse ##### --> 201<para> 202 203</para> 204 205@context: 206@error: 207@Returns: 208 209 210<!-- ##### FUNCTION g_markup_parse_context_free ##### --> 211<para> 212 213</para> 214 215@context: 216 217 218<!-- ##### FUNCTION g_markup_parse_context_get_position ##### --> 219<para> 220 221</para> 222 223@context: 224@line_number: 225@char_number: 226 227 228<!-- ##### FUNCTION g_markup_parse_context_get_element ##### --> 229<para> 230 231</para> 232 233@context: 234@Returns: 235 236 237<!-- ##### FUNCTION g_markup_parse_context_get_element_stack ##### --> 238<para> 239 240</para> 241 242@context: 243@Returns: 244 245 246<!-- ##### FUNCTION g_markup_parse_context_get_user_data ##### --> 247<para> 248 249</para> 250 251@context: 252@Returns: 253 254 255<!-- ##### FUNCTION g_markup_parse_context_new ##### --> 256<para> 257 258</para> 259 260@parser: 261@flags: 262@user_data: 263@user_data_dnotify: 264@Returns: 265 266 267<!-- ##### FUNCTION g_markup_parse_context_parse ##### --> 268<para> 269 270</para> 271 272@context: 273@text: 274@text_len: 275@error: 276@Returns: 277 278 279<!-- ##### FUNCTION g_markup_parse_context_push ##### --> 280<para> 281 282</para> 283 284@context: 285@parser: 286@user_data: 287 288 289<!-- ##### FUNCTION g_markup_parse_context_pop ##### --> 290<para> 291 292</para> 293 294@context: 295@Returns: 296 297 298<!-- ##### ENUM GMarkupCollectType ##### --> 299<para> 300 301</para> 302 303@G_MARKUP_COLLECT_INVALID: 304@G_MARKUP_COLLECT_STRING: 305@G_MARKUP_COLLECT_STRDUP: 306@G_MARKUP_COLLECT_BOOLEAN: 307@G_MARKUP_COLLECT_TRISTATE: 308@G_MARKUP_COLLECT_OPTIONAL: 309 310<!-- ##### FUNCTION g_markup_collect_attributes ##### --> 311<para> 312 313</para> 314 315@element_name: 316@attribute_names: 317@attribute_values: 318@error: 319@first_type: 320@first_attr: 321@Varargs: 322@Returns: 323 324 325