glib/gmarkup.h

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