glib/gmarkup.h

   1 /* gmarkup.h - Simple XML-like string parser/writer
   2  *
   3  *  Copyright 2000 Red Hat, Inc.
   4  *
   5  * GLib is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU Lesser General Public License as
   7  * published by the Free Software Foundation; either version 2 of the
   8  * License, or (at your option) any later version.
   9  *
  10  * GLib is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with GLib; see the file COPYING.LIB.  If not,
  17  * write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18  *   Boston, MA 02111-1307, USA.
  19  */
  20
  21 #ifndef __G_MARKUP_H__
  22 #define __G_MARKUP_H__
  23
  24 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
  25 #error "Only <glib.h> can be included directly."
  26 #endif
  27
  28 #include <stdarg.h>
  29
  30 #include <glib/gerror.h>
  31 #include <glib/gslist.h>
  32
  33 G_BEGIN_DECLS
  34
  35 /**
  36  * GMarkupError:
  37  * @G_MARKUP_ERROR_BAD_UTF8: text being parsed was not valid UTF-8
  38  * @G_MARKUP_ERROR_EMPTY: document contained nothing, or only whitespace
  39  * @G_MARKUP_ERROR_PARSE: document was ill-formed
  40  * @G_MARKUP_ERROR_UNKNOWN_ELEMENT: error should be set by #GMarkupParser
  41  *     functions; element wasn't known
  42  * @G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE: error should be set by #GMarkupParser
  43  *     functions; attribute wasn't known
  44  * @G_MARKUP_ERROR_INVALID_CONTENT: error should be set by #GMarkupParser
  45  *     functions; content was invalid
  46  * @G_MARKUP_ERROR_MISSING_ATTRIBUTE: error should be set by #GMarkupParser
  47  *     functions; a required attribute was missing
  48  *
  49  * Error codes returned by markup parsing.
  50  */
  51 typedef enum
  52 {
  53   G_MARKUP_ERROR_BAD_UTF8,
  54   G_MARKUP_ERROR_EMPTY,
  55   G_MARKUP_ERROR_PARSE,
  56   /* The following are primarily intended for specific GMarkupParser
  57    * implementations to set.
  58    */
  59   G_MARKUP_ERROR_UNKNOWN_ELEMENT,
  60   G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE,
  61   G_MARKUP_ERROR_INVALID_CONTENT,
  62   G_MARKUP_ERROR_MISSING_ATTRIBUTE
  63 } GMarkupError;
  64
  65 /**
  66  * G_MARKUP_ERROR:
  67  *
  68  * Error domain for markup parsing.
  69  * Errors in this domain will be from the #GMarkupError enumeration.
  70  * See #GError for information on error domains.
  71  */
  72 #define G_MARKUP_ERROR g_markup_error_quark ()
  73
  74 GQuark g_markup_error_quark (void);
  75
  76 /**
  77  * GMarkupParseFlags:
  78  * @G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG: flag you should not use
  79  * @G_MARKUP_TREAT_CDATA_AS_TEXT: When this flag is set, CDATA marked
  80  *     sections are not passed literally to the @passthrough function of
  81  *     the parser. Instead, the content of the section (without the
  82  *     <literal>&lt;![CDATA[</literal> and <literal>]]&gt;</literal>) is
  83  *     passed to the @text function. This flag was added in GLib 2.12
  84  * @G_MARKUP_PREFIX_ERROR_POSITION: Normally errors caught by GMarkup
  85  *     itself have line/column information prefixed to them to let the
  86  *     caller know the location of the error. When this flag is set the
  87  *     location information is also prefixed to errors generated by the
  88  *     #GMarkupParser implementation functions
  89  *
  90  * Flags that affect the behaviour of the parser.
  91  */
  92 typedef enum
  93 {
  94   G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG = 1 << 0,
  95   G_MARKUP_TREAT_CDATA_AS_TEXT              = 1 << 1,
  96   G_MARKUP_PREFIX_ERROR_POSITION            = 1 << 2
  97 } GMarkupParseFlags;
  98
  99 /**
 100  * GMarkupParseContext:
 101  *
 102  * A parse context is used to parse a stream of bytes that
 103  * you expect to contain marked-up text.
 104  *
 105  * See g_markup_parse_context_new(), #GMarkupParser, and so
 106  * on for more details.
 107  */
 108 typedef struct _GMarkupParseContext GMarkupParseContext;
 109 typedef struct _GMarkupParser GMarkupParser;
 110
 111 /**
 112  * GMarkupParser:
 113  * @start_element: Callback to invoke when the opening tag of an element
 114  *     is seen.
 115  * @end_element: Callback to invoke when the closing tag of an element
 116  *     is seen. Note that this is also called for empty tags like
 117  *     <literal>&lt;empty/&gt;</literal>.
 118  * @text: Callback to invoke when some text is seen (text is always
 119  *     inside an element). Note that the text of an element may be spread
 120  *     over multiple calls of this function. If the
 121  *     %G_MARKUP_TREAT_CDATA_AS_TEXT flag is set, this function is also
 122  *     called for the content of CDATA marked sections.
 123  * @passthrough: Callback to invoke for comments, processing instructions
 124  *     and doctype declarations; if you're re-writing the parsed document,
 125  *     write the passthrough text back out in the same position. If the
 126  *     %G_MARKUP_TREAT_CDATA_AS_TEXT flag is not set, this function is also
 127  *     called for CDATA marked sections.
 128  * @error: Callback to invoke when an error occurs.
 129  *
 130  * Any of the fields in #GMarkupParser can be %NULL, in which case they
 131  * will be ignored. Except for the @error function, any of these callbacks
 132  * can set an error; in particular the %G_MARKUP_ERROR_UNKNOWN_ELEMENT,
 133  * %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE, and %G_MARKUP_ERROR_INVALID_CONTENT
 134  * errors are intended to be set from these callbacks. If you set an error
 135  * from a callback, g_markup_parse_context_parse() will report that error
 136  * back to its caller.
 137  */
 138 struct _GMarkupParser
 139 {
 140   /* Called for open tags <foo bar="baz"> */
 141   void (*start_element)  (GMarkupParseContext *context,
 142                           const gchar         *element_name,
 143                           const gchar        **attribute_names,
 144                           const gchar        **attribute_values,
 145                           gpointer             user_data,
 146                           GError             **error);
 147
 148   /* Called for close tags </foo> */
 149   void (*end_element)    (GMarkupParseContext *context,
 150                           const gchar         *element_name,
 151                           gpointer             user_data,
 152                           GError             **error);
 153
 154   /* Called for character data */
 155   /* text is not nul-terminated */
 156   void (*text)           (GMarkupParseContext *context,
 157                           const gchar         *text,
 158                           gsize                text_len,
 159                           gpointer             user_data,
 160                           GError             **error);
 161
 162   /* Called for strings that should be re-saved verbatim in this same
 163    * position, but are not otherwise interpretable.  At the moment
 164    * this includes comments and processing instructions.
 165    */
 166   /* text is not nul-terminated. */
 167   void (*passthrough)    (GMarkupParseContext *context,
 168                           const gchar         *passthrough_text,
 169                           gsize                text_len,
 170                           gpointer             user_data,
 171                           GError             **error);
 172
 173   /* Called on error, including one set by other
 174    * methods in the vtable. The GError should not be freed.
 175    */
 176   void (*error)          (GMarkupParseContext *context,
 177                           GError              *error,
 178                           gpointer             user_data);
 179 };
 180
 181 GMarkupParseContext *g_markup_parse_context_new   (const GMarkupParser *parser,
 182                                                    GMarkupParseFlags    flags,
 183                                                    gpointer             user_data,
 184                                                    GDestroyNotify       user_data_dnotify);
 185 GLIB_AVAILABLE_IN_2_36
 186 GMarkupParseContext *g_markup_parse_context_ref   (GMarkupParseContext *context);
 187 GLIB_AVAILABLE_IN_2_36
 188 void                 g_markup_parse_context_unref (GMarkupParseContext *context);
 189 void                 g_markup_parse_context_free  (GMarkupParseContext *context);
 190 gboolean             g_markup_parse_context_parse (GMarkupParseContext *context,
 191                                                    const gchar         *text,
 192                                                    gssize               text_len,
 193                                                    GError             **error);
 194 void                 g_markup_parse_context_push  (GMarkupParseContext *context,
 195                                                    const GMarkupParser *parser,
 196                                                    gpointer             user_data);
 197 gpointer             g_markup_parse_context_pop   (GMarkupParseContext *context);
 198
 199 gboolean             g_markup_parse_context_end_parse (GMarkupParseContext *context,
 200                                                        GError             **error);
 201 const gchar *        g_markup_parse_context_get_element (GMarkupParseContext *context);
 202 const GSList *       g_markup_parse_context_get_element_stack (GMarkupParseContext *context);
 203
 204 /* For user-constructed error messages, has no precise semantics */
 205 void                 g_markup_parse_context_get_position (GMarkupParseContext *context,
 206                                                           gint                *line_number,
 207                                                           gint                *char_number);
 208 gpointer             g_markup_parse_context_get_user_data (GMarkupParseContext *context);
 209
 210 /* useful when saving */
 211 gchar* g_markup_escape_text (const gchar *text,
 212                              gssize       length);
 213
 214 gchar *g_markup_printf_escaped (const char *format,
 215                                 ...) G_GNUC_PRINTF (1, 2);
 216 gchar *g_markup_vprintf_escaped (const char *format,
 217                                  va_list     args) G_GNUC_PRINTF(1, 0);
 218
 219 typedef enum
 220 {
 221   G_MARKUP_COLLECT_INVALID,
 222   G_MARKUP_COLLECT_STRING,
 223   G_MARKUP_COLLECT_STRDUP,
 224   G_MARKUP_COLLECT_BOOLEAN,
 225   G_MARKUP_COLLECT_TRISTATE,
 226
 227   G_MARKUP_COLLECT_OPTIONAL = (1 << 16)
 228 } GMarkupCollectType;
 229
 230
 231 /* useful from start_element */
 232 gboolean   g_markup_collect_attributes (const gchar         *element_name,
 233                                         const gchar        **attribute_names,
 234                                         const gchar        **attribute_values,
 235                                         GError             **error,
 236                                         GMarkupCollectType   first_type,
 237                                         const gchar         *first_attr,
 238                                         ...);
 239
 240 G_END_DECLS
 241
 242 #endif /* __G_MARKUP_H__ */