| <!-- ##### SECTION Title ##### --> |
| Simple XML Subset Parser |
| |
| <!-- ##### SECTION Short_Description ##### --> |
| parses a subset of XML |
| |
| <!-- ##### SECTION Long_Description ##### --> |
| <para> |
| The "GMarkup" parser is intended to parse a simple markup format |
| that's a subset of XML. This is a small, efficient, easy-to-use |
| parser. It should not be used if you expect to interoperate with other |
| applications generating full-scale XML. However, it's very useful for |
| application data files, config files, etc. where you know your |
| application will be the only one writing the file. Full-scale XML |
| parsers should be able to parse the subset used by GMarkup, so you can |
| easily migrate to full-scale XML at a later time if the need arises. |
| </para> |
| |
| <para> |
| GMarkup is not guaranteed to signal an error on all invalid XML; the |
| parser may accept documents that an XML parser would not. However, XML |
| documents which are not well-formed<footnote id="wellformed">Being wellformed |
| is a weaker condition than being valid. See the |
| <ulink url="http://www.w3.org/TR/REC-xml/">XML specification</ulink> for |
| definitions of these terms.</footnote> are not considered valid GMarkup |
| documents. |
| </para> |
| |
| <para> |
| Simplifications to XML include: |
| <itemizedlist> |
| <listitem> |
| <para> |
| Only UTF-8 encoding is allowed. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| No user-defined entities. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Processing instructions, comments and the doctype declaration are "passed |
| through" but are not interpreted in any way. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| No DTD or validation. |
| </para> |
| </listitem> |
| </itemizedlist> |
| </para> |
| |
| <para> |
| The markup format does support: |
| <itemizedlist> |
| <listitem> |
| <para> |
| Elements |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Attributes |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| 5 standard entities: <literal>&amp; &lt; &gt; &quot; &apos;</literal> |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Character references |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Sections marked as CDATA |
| </para> |
| </listitem> |
| </itemizedlist> |
| </para> |
| |
| <!-- ##### SECTION See_Also ##### --> |
| <para> |
| |
| </para> |
| |
| <!-- ##### SECTION Stability_Level ##### --> |
| |
| |
| <!-- ##### SECTION Image ##### --> |
| |
| |
| <!-- ##### ENUM GMarkupError ##### --> |
| <para> |
| Error codes returned by markup parsing. |
| </para> |
| |
| @G_MARKUP_ERROR_BAD_UTF8: text being parsed was not valid UTF-8 |
| @G_MARKUP_ERROR_EMPTY: document contained nothing, or only whitespace |
| @G_MARKUP_ERROR_PARSE: document was ill-formed |
| @G_MARKUP_ERROR_UNKNOWN_ELEMENT: error should be set by #GMarkupParser functions; element wasn't known |
| @G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE: error should be set by #GMarkupParser functions; attribute wasn't known |
| @G_MARKUP_ERROR_INVALID_CONTENT: error should be set by #GMarkupParser functions; content was invalid |
| @G_MARKUP_ERROR_MISSING_ATTRIBUTE: error should be set by #GMarkupParser functions; a required attribute was missing |
| |
| <!-- ##### MACRO G_MARKUP_ERROR ##### --> |
| <para> |
| Error domain for markup parsing. Errors in this domain will |
| be from the #GMarkupError enumeration. See #GError for information on |
| error domains. |
| </para> |
| |
| |
| |
| <!-- ##### ENUM GMarkupParseFlags ##### --> |
| <para> |
| Flags that affect the behaviour of the parser. |
| </para> |
| |
| @G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG: flag you should not use. |
| @G_MARKUP_TREAT_CDATA_AS_TEXT: When this flag is set, CDATA marked |
| sections are not passed literally to the @passthrough function of |
| the parser. Instead, the content of the section (without the |
| <literal><![CDATA[</literal> and <literal>]]></literal>) is |
| passed to the @text function. This flag was added in GLib 2.12. |
| @G_MARKUP_PREFIX_ERROR_POSITION: Normally errors caught by GMarkup |
| itself have line/column information prefixed to them to let the |
| caller know the location of the error. When this flag is set the |
| location information is also prefixed to errors generated by the |
| #GMarkupParser implementation functions. |
| |
| <!-- ##### STRUCT GMarkupParseContext ##### --> |
| <para> |
| A parse context is used to parse a stream of bytes that you expect to |
| contain marked-up text. See g_markup_parse_context_new(), |
| #GMarkupParser, and so on for more details. |
| </para> |
| |
| |
| <!-- ##### STRUCT GMarkupParser ##### --> |
| <para> |
| Any of the fields in #GMarkupParser can be %NULL, in which case they |
| will be ignored. Except for the @error function, any of these |
| callbacks can set an error; in particular the |
| %G_MARKUP_ERROR_UNKNOWN_ELEMENT, %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE, |
| and %G_MARKUP_ERROR_INVALID_CONTENT errors are intended to be set |
| from these callbacks. If you set an error from a callback, |
| g_markup_parse_context_parse() will report that error back to its caller. |
| </para> |
| |
| @start_element: Callback to invoke when the opening tag of an element |
| is seen. |
| @end_element: Callback to invoke when the closing tag of an element is seen. |
| Note that this is also called for empty tags like |
| <literal><empty/></literal>. |
| @text: Callback to invoke when some text is seen (text is always |
| inside an element). Note that the text of an element may be spread |
| over multiple calls of this function. If the %G_MARKUP_TREAT_CDATA_AS_TEXT |
| flag is set, this function is also called for the content of CDATA marked |
| sections. |
| @passthrough: Callback to invoke for comments, processing instructions |
| and doctype declarations; if you're re-writing the parsed document, |
| write the passthrough text back out in the same position. If the |
| %G_MARKUP_TREAT_CDATA_AS_TEXT flag is not set, this function is also |
| called for CDATA marked sections. |
| @error: Callback to invoke when an error occurs. |
| |
| <!-- ##### FUNCTION g_markup_escape_text ##### --> |
| <para> |
| |
| </para> |
| |
| @text: |
| @length: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_markup_printf_escaped ##### --> |
| <para> |
| |
| </para> |
| |
| @format: |
| @Varargs: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_markup_vprintf_escaped ##### --> |
| <para> |
| |
| </para> |
| |
| @format: |
| @args: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_markup_parse_context_end_parse ##### --> |
| <para> |
| |
| </para> |
| |
| @context: |
| @error: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_markup_parse_context_free ##### --> |
| <para> |
| |
| </para> |
| |
| @context: |
| |
| |
| <!-- ##### FUNCTION g_markup_parse_context_get_position ##### --> |
| <para> |
| |
| </para> |
| |
| @context: |
| @line_number: |
| @char_number: |
| |
| |
| <!-- ##### FUNCTION g_markup_parse_context_get_element ##### --> |
| <para> |
| |
| </para> |
| |
| @context: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_markup_parse_context_get_element_stack ##### --> |
| <para> |
| |
| </para> |
| |
| @context: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_markup_parse_context_get_user_data ##### --> |
| <para> |
| |
| </para> |
| |
| @context: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_markup_parse_context_new ##### --> |
| <para> |
| |
| </para> |
| |
| @parser: |
| @flags: |
| @user_data: |
| @user_data_dnotify: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_markup_parse_context_parse ##### --> |
| <para> |
| |
| </para> |
| |
| @context: |
| @text: |
| @text_len: |
| @error: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_markup_parse_context_push ##### --> |
| <para> |
| |
| </para> |
| |
| @context: |
| @parser: |
| @user_data: |
| |
| |
| <!-- ##### FUNCTION g_markup_parse_context_pop ##### --> |
| <para> |
| |
| </para> |
| |
| @context: |
| @Returns: |
| |
| |
| <!-- ##### ENUM GMarkupCollectType ##### --> |
| <para> |
| |
| </para> |
| |
| @G_MARKUP_COLLECT_INVALID: |
| @G_MARKUP_COLLECT_STRING: |
| @G_MARKUP_COLLECT_STRDUP: |
| @G_MARKUP_COLLECT_BOOLEAN: |
| @G_MARKUP_COLLECT_TRISTATE: |
| @G_MARKUP_COLLECT_OPTIONAL: |
| |
| <!-- ##### FUNCTION g_markup_collect_attributes ##### --> |
| <para> |
| |
| </para> |
| |
| @element_name: |
| @attribute_names: |
| @attribute_values: |
| @error: |
| @first_type: |
| @first_attr: |
| @Varargs: |
| @Returns: |
| |
| |