docs/reference/glib/tmpl/markup.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Simple XML Subset Parser
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 parses a subset of XML
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The "GMarkup" parser is intended to parse a simple markup format
  10 that's a subset of XML. This is a small, efficient, easy-to-use
  11 parser. It should not be used if you expect to interoperate with other
  12 applications generating full-scale XML. However, it's very useful for
  13 application data files, config files, etc. where you know your
  14 application will be the only one writing the file. Full-scale XML
  15 parsers should be able to parse the subset used by GMarkup, so you can
  16 easily migrate to full-scale XML at a later time if the need arises.
  17 </para>
  18
  19 <para>
  20 GMarkup is not guaranteed to signal an error on all invalid XML; the
  21 parser may accept documents that an XML parser would not. However, XML
  22 documents which are not well-formed<footnote id="wellformed">Being wellformed
  23 is a weaker condition than being valid. See the
  24 <ulink url="http://www.w3.org/TR/REC-xml/">XML specification</ulink> for
  25 definitions of these terms.</footnote> are not considered valid GMarkup
  26 documents.
  27 </para>
  28
  29 <para>
  30 Simplifications to XML include:
  31 <itemizedlist>
  32 <listitem>
  33 <para>
  34 Only UTF-8 encoding is allowed.
  35 </para>
  36 </listitem>
  37 <listitem>
  38 <para>
  39 No user-defined entities.
  40 </para>
  41 </listitem>
  42 <listitem>
  43 <para>
  44 Processing instructions, comments and the doctype declaration are "passed
  45 through" but are not interpreted in any way.
  46 </para>
  47 </listitem>
  48 <listitem>
  49 <para>
  50 No DTD or validation.
  51 </para>
  52 </listitem>
  53 </itemizedlist>
  54 </para>
  55
  56 <para>
  57 The markup format does support:
  58 <itemizedlist>
  59 <listitem>
  60 <para>
  61 Elements
  62 </para>
  63 </listitem>
  64 <listitem>
  65 <para>
  66 Attributes
  67 </para>
  68 </listitem>
  69 <listitem>
  70 <para>
  71 5 standard entities: <literal>&amp;amp; &amp;lt; &amp;gt; &amp;quot; &amp;apos;</literal>
  72 </para>
  73 </listitem>
  74 <listitem>
  75 <para>
  76 Character references
  77 </para>
  78 </listitem>
  79 <listitem>
  80 <para>
  81 Sections 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>
  97 Error 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>
 110 Error domain for markup parsing. Errors in this domain will
 111 be from the #GMarkupError enumeration. See #GError for information on
 112 error domains.
 113 </para>
 114
 115
 116
 117 <!-- ##### ENUM GMarkupParseFlags ##### -->
 118 <para>
 119 Flags 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>&lt;![CDATA[</literal> and <literal>]]&gt;</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>
 136 A parse context is used to parse a stream of bytes that you expect to
 137 contain 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>
 144 Any of the fields in #GMarkupParser can be %NULL, in which case they
 145 will be ignored. Except for the @error function, any of these
 146 callbacks can set an error; in particular the
 147 %G_MARKUP_ERROR_UNKNOWN_ELEMENT, %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE,
 148 and %G_MARKUP_ERROR_INVALID_CONTENT errors are intended to be set
 149 from these callbacks. If you set an error from a callback,
 150 g_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>&lt;empty/&gt;</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