gmarkup.h

00001 /* gmarkup.h - Simple XML-like string parser/writer
00002  *
00003  *  Copyright 2000 Red Hat, Inc.
00004  * Portions copyright (c) 2006 Nokia Corporation.  All rights reserved.
00005  *
00006  * GLib is free software; you can redistribute it and/or modify it
00007  * under the terms of the GNU Lesser General Public License as
00008  * published by the Free Software Foundation; either version 2 of the
00009  * License, or (at your option) any later version.
00010  *
00011  * GLib is distributed in the hope that it will be useful,
00012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00014  * Lesser General Public License for more details.
00015  *
00016  * You should have received a copy of the GNU Lesser General Public
00017  * License along with GLib; see the file COPYING.LIB.  If not,
00018  * write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
00019  *   Boston, MA 02111-1307, USA.
00020  */
00021 
00022 #ifndef __G_MARKUP_H__
00023 #define __G_MARKUP_H__
00024 
00025 #include <_ansi.h>
00026 #include <stdarg.h>
00027 
00028 #include <glib/gerror.h>
00029 
00030 G_BEGIN_DECLS
00031 
00032 typedef enum
00033 {
00034   G_MARKUP_ERROR_BAD_UTF8,
00035   G_MARKUP_ERROR_EMPTY,
00036   G_MARKUP_ERROR_PARSE,
00037   /* These three are primarily intended for specific GMarkupParser
00038    * implementations to set.
00039    */
00040   G_MARKUP_ERROR_UNKNOWN_ELEMENT,
00041   G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE,
00042   G_MARKUP_ERROR_INVALID_CONTENT
00043 } GMarkupError;
00044 
00045 #define G_MARKUP_ERROR g_markup_error_quark ()
00046 
00047 IMPORT_C GQuark g_markup_error_quark (void);
00048 
00049 typedef enum
00050 {
00051   /* Hmm, can't think of any at the moment */
00052   G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG = 1 << 0
00053   
00054 } GMarkupParseFlags;
00055 
00056 typedef struct _GMarkupParseContext GMarkupParseContext;
00057 typedef struct _GMarkupParser GMarkupParser;
00058 
00059 struct _GMarkupParser
00060 {
00061   /* Called for open tags <foo bar="baz"> */
00062   void (*start_element)  (GMarkupParseContext *context,
00063                           const gchar         *element_name,
00064                           const gchar        **attribute_names,
00065                           const gchar        **attribute_values,
00066                           gpointer             user_data,
00067                           GError             **error);
00068 
00069   /* Called for close tags </foo> */
00070   void (*end_element)    (GMarkupParseContext *context,
00071                           const gchar         *element_name,
00072                           gpointer             user_data,
00073                           GError             **error);
00074 
00075   /* Called for character data */
00076   /* text is not nul-terminated */
00077   void (*text)           (GMarkupParseContext *context,
00078                           const gchar         *text,
00079                           gsize                text_len,  
00080                           gpointer             user_data,
00081                           GError             **error);
00082 
00083   /* Called for strings that should be re-saved verbatim in this same
00084    * position, but are not otherwise interpretable.  At the moment
00085    * this includes comments and processing instructions.
00086    */
00087   /* text is not nul-terminated. */
00088   void (*passthrough)    (GMarkupParseContext *context,
00089                           const gchar         *passthrough_text,
00090                           gsize                text_len,  
00091                           gpointer             user_data,
00092                           GError             **error);
00093 
00094   /* Called on error, including one set by other
00095    * methods in the vtable. The GError should not be freed.
00096    */
00097   void (*error)          (GMarkupParseContext *context,
00098                           GError              *error,
00099                           gpointer             user_data);
00100 };
00101 
00102 IMPORT_C GMarkupParseContext *g_markup_parse_context_new   (const GMarkupParser *parser,
00103                                                    GMarkupParseFlags    flags,
00104                                                    gpointer             user_data,
00105                                                    GDestroyNotify       user_data_dnotify);
00106 IMPORT_C void                 g_markup_parse_context_free  (GMarkupParseContext *context);
00107 IMPORT_C gboolean             g_markup_parse_context_parse (GMarkupParseContext *context,
00108                                                    const gchar         *text,
00109                                                    gssize               text_len,  
00110                                                    GError             **error);
00111                                                    
00112 IMPORT_C gboolean             g_markup_parse_context_end_parse (GMarkupParseContext *context,
00113                                                        GError             **error);
00114 IMPORT_C G_CONST_RETURN gchar *g_markup_parse_context_get_element (GMarkupParseContext *context);
00115 
00116 /* For user-constructed error messages, has no precise semantics */
00117 IMPORT_C void                 g_markup_parse_context_get_position (GMarkupParseContext *context,
00118                                                           gint                *line_number,
00119                                                           gint                *char_number);
00120 
00121 /* useful when saving */
00122 IMPORT_C gchar* g_markup_escape_text (const gchar *text,
00123                              gssize       length);  
00124 
00125 IMPORT_C gchar *g_markup_printf_escaped (const char *format,
00126                                 ...) G_GNUC_PRINTF (1, 2);
00127 IMPORT_C gchar *g_markup_vprintf_escaped (const char *format,
00128                                  va_list     args);
00129 
00130 G_END_DECLS
00131 
00132 #endif /* __G_MARKUP_H__ */
00133