docs/reference/glib/tmpl/markup.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Simple XML Subset Parser
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5
   6 Parses a subset of XML
   7
   8 <!-- ##### SECTION Long_Description ##### -->
   9 <para>
  10 The "GMarkup" parser is intended to parse a simple markup format
  11 that's a subset of XML format. This is a small, efficient, easy-to-use
  12 parser. It should not be used if you expect to interoperate with other
  13 applications generating full-scale XML. However, it's very useful for
  14 application data files, config files, etc. where you know your
  15 application will be the only one writing the file. Full-scale XML
  16 parsers should be able to parse the subset used by GMarkup, so you can
  17 easily migrate to full-scale XML at a later time if the need arises.
  18 </para>
  19
  20 <para>
  21 GMarkup is not guaranteed to signal an error on all invalid XML; the
  22 parser may accept documents that an XML parser would not, e.g. the
  23 sequence <literal>&lt;[[</literal> has special meaning in XML and not
  24 in GMarkup. However, invalid XML documents are not considered valid
  25 GMarkup documents.
  26 </para>
  27
  28 <para>
  29 Simplifications to XML include:
  30 <itemizedlist>
  31 <listitem>
  32 <para>
  33 Only UTF-8 encoding is allowed.
  34 </para>
  35 </listitem>
  36 <listitem>
  37 <para>
  38 No CDATA, no user-defined entities.
  39 </para>
  40 </listitem>
  41 <listitem>
  42 <para>
  43 Processing instructions and comments are "passed through" but are not
  44 interpreted in any way.
  45 </para>
  46 </listitem>
  47 <listitem>
  48 <para>
  49 No DTD or validation.
  50 </para>
  51 </listitem>
  52 <listitem>
  53 <para>
  54 </para>
  55 </listitem>
  56 </itemizedlist>
  57 </para>
  58
  59 <para>
  60 The markup format does support:
  61 <itemizedlist>
  62 <listitem>
  63 <para>
  64 Elements
  65 </para>
  66 </listitem>
  67 <listitem>
  68 <para>
  69 Attributes
  70 </para>
  71 </listitem>
  72 <listitem>
  73 <para>
  74 5 standard entities: <literal>&amp;amp; &amp;lt; &amp;gt; &amp;quot; &amp;apos;</literal>
  75 </para>
  76 </listitem>
  77 <listitem>
  78 <para>
  79 Character references
  80 </para>
  81 </listitem>
  82 </itemizedlist>
  83 </para>
  84
  85 <!-- ##### SECTION See_Also ##### -->
  86 <para>
  87
  88 </para>
  89
  90 <!-- ##### ENUM GMarkupError ##### -->
  91 <para>
  92
  93 </para>
  94
  95 @G_MARKUP_ERROR_BAD_UTF8: text being parsed was not valid UTF-8
  96 @G_MARKUP_ERROR_EMPTY: document contained nothing, or only whitespace
  97 @G_MARKUP_ERROR_PARSE: document was ill-formed
  98 @G_MARKUP_ERROR_UNKNOWN_ELEMENT: error should be set by #GMarkupParser functions; element wasn't known
  99 @G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE: error should be set by #GMarkupParser functions; attribute wasn't known
 100 @G_MARKUP_ERROR_INVALID_CONTENT: error should be set by #GMarkupParser functions; something was wrong with contents of the document, e.g. invalid attribute value
 101
 102 <!-- ##### MACRO G_MARKUP_ERROR ##### -->
 103 <para>
 104
 105 </para>
 106
 107
 108
 109 <!-- ##### ENUM GMarkupParseFlags ##### -->
 110 <para>
 111 There are no flags right now
 112 </para>
 113
 114 @G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG:
 115
 116 <!-- ##### STRUCT GMarkupParseContext ##### -->
 117 <para>
 118
 119 </para>
 120
 121
 122 <!-- ##### STRUCT GMarkupParser ##### -->
 123 <para>
 124 Any of the fields in #GMarkupParser can be %NULL, in which case they
 125 will be ignored. Except for the @error function, any of these
 126 callbacks can set an error; in particular the
 127 %G_MARKUP_ERROR_UNKNOWN_ELEMENT, %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE,
 128 and %G_MARKUP_ERROR_INVALID_CONTENT errors are intended to be set
 129 from these callbacks. If you set an error from a callback,
 130 g_markup_parse_context_parse() will report that error back to its caller.
 131 </para>
 132
 133 @start_element: Callback to invoke when the opening tag of an element
 134 is seen.
 135 @end_element: Callback to invoke when the closing tag of an element is seen
 136 @text: Callback to invoke when some text is seen (text is always
 137 inside an element)
 138 @passthrough: Callback to invoke for comments and processing
 139 instructions; if you're re-writing the parsed document, write the
 140 passthrough text back out in the same position
 141 @error: Callback to invoke when an error occurs
 142
 143 <!-- ##### FUNCTION g_markup_escape_text ##### -->
 144 <para>
 145
 146 </para>
 147
 148 @text:
 149 @length:
 150 @Returns:
 151
 152
 153 <!-- ##### FUNCTION g_markup_parse_context_end_parse ##### -->
 154 <para>
 155
 156 </para>
 157
 158 @context:
 159 @error:
 160 @Returns:
 161
 162
 163 <!-- ##### FUNCTION g_markup_parse_context_free ##### -->
 164 <para>
 165
 166 </para>
 167
 168 @context:
 169
 170
 171 <!-- ##### FUNCTION g_markup_parse_context_get_position ##### -->
 172 <para>
 173
 174 </para>
 175
 176 @context:
 177 @line_number:
 178 @char_number:
 179
 180
 181 <!-- ##### FUNCTION g_markup_parse_context_new ##### -->
 182 <para>
 183
 184 </para>
 185
 186 @parser:
 187 @flags:
 188 @user_data:
 189 @user_data_dnotify:
 190 @Returns:
 191
 192
 193 <!-- ##### FUNCTION g_markup_parse_context_parse ##### -->
 194 <para>
 195
 196 </para>
 197
 198 @context:
 199 @text:
 200 @text_len:
 201 @error:
 202 @Returns:
 203
 204