markup.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<refentry id="glib-Simple-XML-Subset-Parser">
<refmeta>
<refentrytitle>Simple XML Subset Parser</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Simple XML Subset Parser</refname><refpurpose>parses a subset of XML.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;


enum        <link linkend="GMarkupError">GMarkupError</link>;
#define     <link linkend="G-MARKUP-ERROR-CAPS">G_MARKUP_ERROR</link>
enum        <link linkend="GMarkupParseFlags">GMarkupParseFlags</link>;
struct      <link linkend="GMarkupParseContext">GMarkupParseContext</link>;
struct      <link linkend="GMarkupParser">GMarkupParser</link>;
<link linkend="gchar">gchar</link>*      <link linkend="g-markup-escape-text">g_markup_escape_text</link>            (const <link linkend="gchar">gchar</link> *text,
                                             <link linkend="gssize">gssize</link> length);
<link linkend="gboolean">gboolean</link>    <link linkend="g-markup-parse-context-end-parse">g_markup_parse_context_end_parse</link>
                                            (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context,
                                             <link linkend="GError">GError</link> **error);
void        <link linkend="g-markup-parse-context-free">g_markup_parse_context_free</link>     (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context);
void        <link linkend="g-markup-parse-context-get-position">g_markup_parse_context_get_position</link>
                                            (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context,
                                             <link linkend="gint">gint</link> *line_number,
                                             <link linkend="gint">gint</link> *char_number);
<link linkend="GMarkupParseContext">GMarkupParseContext</link>* <link linkend="g-markup-parse-context-new">g_markup_parse_context_new</link>
                                            (const <link linkend="GMarkupParser">GMarkupParser</link> *parser,
                                             <link linkend="GMarkupParseFlags">GMarkupParseFlags</link> flags,
                                             <link linkend="gpointer">gpointer</link> user_data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> user_data_dnotify);
<link linkend="gboolean">gboolean</link>    <link linkend="g-markup-parse-context-parse">g_markup_parse_context_parse</link>    (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context,
                                             const <link linkend="gchar">gchar</link> *text,
                                             <link linkend="gssize">gssize</link> text_len,
                                             <link linkend="GError">GError</link> **error);

</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<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, e.g. the
sequence <literal>&lt;[[</literal> has special meaning in XML and not
in GMarkup. However, invalid XML documents 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 CDATA, no user-defined entities.
</para>
</listitem>
<listitem>
<para>
Processing instructions and comments 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;amp; &amp;lt; &amp;gt; &amp;quot; &amp;apos;</literal>
</para>
</listitem>
<listitem>
<para>
Character references
</para>
</listitem>
</itemizedlist>
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GMarkupError">enum GMarkupError</title>
<programlisting>typedef enum
{
  G_MARKUP_ERROR_BAD_UTF8,
  G_MARKUP_ERROR_EMPTY,
  G_MARKUP_ERROR_PARSE,
  /* These three are primarily intended for specific GMarkupParser
   * implementations to set.
   */
  G_MARKUP_ERROR_UNKNOWN_ELEMENT,
  G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE,
  G_MARKUP_ERROR_INVALID_CONTENT
} GMarkupError;
</programlisting>
<para>
Error codes returned by markup parsing.
</para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>G_MARKUP_ERROR_BAD_UTF8</literal></entry>
<entry>text being parsed was not valid UTF-8
</entry>
</row>
<row>
<entry><literal>G_MARKUP_ERROR_EMPTY</literal></entry>
<entry>document contained nothing, or only whitespace
</entry>
</row>
<row>
<entry><literal>G_MARKUP_ERROR_PARSE</literal></entry>
<entry>document was ill-formed
</entry>
</row>
<row>
<entry><literal>G_MARKUP_ERROR_UNKNOWN_ELEMENT</literal></entry>
<entry>error should be set by <link linkend="GMarkupParser">GMarkupParser</link> functions; element wasn't known
</entry>
</row>
<row>
<entry><literal>G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE</literal></entry>
<entry>error should be set by <link linkend="GMarkupParser">GMarkupParser</link> functions; attribute wasn't known
</entry>
</row>
<row>
<entry><literal>G_MARKUP_ERROR_INVALID_CONTENT</literal></entry>
<entry>error should be set by <link linkend="GMarkupParser">GMarkupParser</link> functions; something was wrong with contents of the document, e.g. invalid attribute value

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-MARKUP-ERROR-CAPS">G_MARKUP_ERROR</title>
<programlisting>#define G_MARKUP_ERROR g_markup_error_quark ()
</programlisting>
<para>
Error domain for markup parsing. Errors in this domain will
be from the <link linkend="GMarkupError">GMarkupError</link> enumeration. See <link linkend="GError">GError</link> for information on 
error domains.
</para></refsect2>
<refsect2>
<title><anchor id="GMarkupParseFlags">enum GMarkupParseFlags</title>
<programlisting>typedef enum
{
  /* Hmm, can't think of any at the moment */
  G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG = 1 &lt;&lt; 0
  
} GMarkupParseFlags;
</programlisting>
<para>
There are no flags right now. Pass "0" for the flags argument to all 
functions.
</para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG</literal></entry>
<entry>flag you should not use.

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GMarkupParseContext">struct GMarkupParseContext</title>
<programlisting>struct GMarkupParseContext;</programlisting>
<para>
A parse context is used to parse a stream of bytes that you expect to
contain marked-up text. See <link linkend="g-markup-parse-context-new">g_markup_parse_context_new</link>(),
<link linkend="GMarkupParser">GMarkupParser</link>, and so on for more details.
</para></refsect2>
<refsect2>
<title><anchor id="GMarkupParser">struct GMarkupParser</title>
<programlisting>struct GMarkupParser
{
  /* Called for open tags &lt;foo bar="baz"&gt; */
  void (*start_element)  (GMarkupParseContext *context,
                          const gchar         *element_name,
                          const gchar        **attribute_names,
                          const gchar        **attribute_values,
                          gpointer             user_data,
                          GError             **error);

  /* Called for close tags &lt;/foo&gt; */
  void (*end_element)    (GMarkupParseContext *context,
                          const gchar         *element_name,
                          gpointer             user_data,
                          GError             **error);

  /* Called for character data */
  /* text is not nul-terminated */
  void (*text)           (GMarkupParseContext *context,
                          const gchar         *text,
                          gsize                text_len,  
                          gpointer             user_data,
                          GError             **error);

  /* Called for strings that should be re-saved verbatim in this same
   * position, but are not otherwise interpretable.  At the moment
   * this includes comments and processing instructions.
   */
  /* text is not nul-terminated. */