| <!-- ##### 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 ##### --> |
| |
| |
| <!-- ##### 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; something was wrong with contents of the document, e.g. invalid attribute value |
| |
| <!-- ##### 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> |
| There are no flags right now. Pass "0" for the flags argument to all |
| functions. |
| </para> |
| |
| @G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG: flag you should not use. |
| |
| <!-- ##### 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 |
| @text: Callback to invoke when some text is seen (text is always |
| inside an element) |
| @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 |
| @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_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: |
| |
| |