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 #if defined(G_DISABLE_SINGLE_INCLUDES) && !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
  22 #error "Only <glib.h> can be included directly."
  23 #endif
  24
  25 #ifndef __G_MARKUP_H__
  26 #define __G_MARKUP_H__
  27
  28 #include <stdarg.h>
  29
  30 #include <glib/gerror.h>
  31 #include <glib/gslist.h>
  32
  33 G_BEGIN_DECLS
  34
  35 typedef enum
  36 {
  37   G_MARKUP_ERROR_BAD_UTF8,
  38   G_MARKUP_ERROR_EMPTY,
  39   G_MARKUP_ERROR_PARSE,
  40   /* The following are primarily intended for specific GMarkupParser
  41    * implementations to set.
  42    */
  43   G_MARKUP_ERROR_UNKNOWN_ELEMENT,
  44   G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE,
  45   G_MARKUP_ERROR_INVALID_CONTENT,
  46   G_MARKUP_ERROR_MISSING_ATTRIBUTE
  47 } GMarkupError;
  48
  49 #define G_MARKUP_ERROR g_markup_error_quark ()
  50
  51 GQuark g_markup_error_quark (void);
  52
  53 typedef enum
  54 {
  55   G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG = 1 << 0,
  56   G_MARKUP_TREAT_CDATA_AS_TEXT              = 1 << 1,
  57   G_MARKUP_PREFIX_ERROR_POSITION            = 1 << 2
  58 } GMarkupParseFlags;
  59
  60 typedef struct _GMarkupParseContext GMarkupParseContext;
  61 typedef struct _GMarkupParser GMarkupParser;
  62
  63 struct _GMarkupParser
  64 {
  65   /* Called for open tags <foo bar="baz"> */
  66   void (*start_element)  (GMarkupParseContext *context,
  67                           const gchar         *element_name,
  68                           const gchar        **attribute_names,
  69                           const gchar        **attribute_values,
  70                           gpointer             user_data,
  71                           GError             **error);
  72
  73   /* Called for close tags </foo> */
  74   void (*end_element)    (GMarkupParseContext *context,
  75                           const gchar         *element_name,
  76                           gpointer             user_data,
  77                           GError             **error);
  78
  79   /* Called for character data */
  80   /* text is not nul-terminated */
  81   void (*text)           (GMarkupParseContext *context,
  82                           const gchar         *text,
  83                           gsize                text_len,
  84                           gpointer             user_data,
  85                           GError             **error);
  86
  87   /* Called for strings that should be re-saved verbatim in this same
  88    * position, but are not otherwise interpretable.  At the moment
  89    * this includes comments and processing instructions.
  90    */
  91   /* text is not nul-terminated. */
  92   void (*passthrough)    (GMarkupParseContext *context,
  93                           const gchar         *passthrough_text,
  94                           gsize                text_len,
  95                           gpointer             user_data,
  96                           GError             **error);
  97
  98   /* Called on error, including one set by other
  99    * methods in the vtable. The GError should not be freed.
 100    */
 101   void (*error)          (GMarkupParseContext *context,
 102                           GError              *error,
 103                           gpointer             user_data);
 104 };
 105
 106 GMarkupParseContext *g_markup_parse_context_new   (const GMarkupParser *parser,
 107                                                    GMarkupParseFlags    flags,
 108                                                    gpointer             user_data,
 109                                                    GDestroyNotify       user_data_dnotify);
 110 void                 g_markup_parse_context_free  (GMarkupParseContext *context);
 111 gboolean             g_markup_parse_context_parse (GMarkupParseContext *context,
 112                                                    const gchar         *text,
 113                                                    gssize               text_len,
 114                                                    GError             **error);
 115 void                 g_markup_parse_context_push  (GMarkupParseContext *context,
 116                                                    GMarkupParser       *parser,
 117                                                    gpointer             user_data);
 118 gpointer             g_markup_parse_context_pop   (GMarkupParseContext *context);
 119
 120 gboolean             g_markup_parse_context_end_parse (GMarkupParseContext *context,
 121                                                        GError             **error);
 122 G_CONST_RETURN gchar *g_markup_parse_context_get_element (GMarkupParseContext *context);
 123 G_CONST_RETURN GSList *g_markup_parse_context_get_element_stack (GMarkupParseContext *context);
 124
 125 /* For user-constructed error messages, has no precise semantics */
 126 void                 g_markup_parse_context_get_position (GMarkupParseContext *context,
 127                                                           gint                *line_number,
 128                                                           gint                *char_number);
 129 gpointer             g_markup_parse_context_get_user_data (GMarkupParseContext *context);
 130
 131 /* useful when saving */
 132 gchar* g_markup_escape_text (const gchar *text,
 133                              gssize       length);
 134
 135 gchar *g_markup_printf_escaped (const char *format,
 136                                 ...) G_GNUC_PRINTF (1, 2);
 137 gchar *g_markup_vprintf_escaped (const char *format,
 138                                  va_list     args);
 139
 140 typedef enum
 141 {
 142   G_MARKUP_COLLECT_INVALID,
 143   G_MARKUP_COLLECT_STRING,
 144   G_MARKUP_COLLECT_STRDUP,
 145   G_MARKUP_COLLECT_BOOLEAN,
 146   G_MARKUP_COLLECT_TRISTATE,
 147
 148   G_MARKUP_COLLECT_OPTIONAL = (1 << 16)
 149 } GMarkupCollectType;
 150
 151
 152 /* useful from start_element */
 153 gboolean   g_markup_collect_attributes (const gchar         *element_name,
 154                                         const gchar        **attribute_names,
 155                                         const gchar        **attribute_values,
 156                                         GError             **error,
 157                                         GMarkupCollectType   first_type,
 158                                         const gchar         *first_attr,
 159                                         ...);
 160
 161 G_END_DECLS
 162
 163 #endif /* __G_MARKUP_H__ */