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
33G_BEGIN_DECLS
34
35typedef 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
51GQuark g_markup_error_quark (void);
52
53typedef 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
60typedef struct _GMarkupParseContext GMarkupParseContext;
61typedef struct _GMarkupParser GMarkupParser;
62
63struct _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
106GMarkupParseContext *g_markup_parse_context_new   (const GMarkupParser *parser,
107                                                   GMarkupParseFlags    flags,
108                                                   gpointer             user_data,
109                                                   GDestroyNotify       user_data_dnotify);
110void                 g_markup_parse_context_free  (GMarkupParseContext *context);
111gboolean             g_markup_parse_context_parse (GMarkupParseContext *context,
112                                                   const gchar         *text,
113                                                   gssize               text_len,
114                                                   GError             **error);
115void                 g_markup_parse_context_push  (GMarkupParseContext *context,
116                                                   GMarkupParser       *parser,
117                                                   gpointer             user_data);
118gpointer             g_markup_parse_context_pop   (GMarkupParseContext *context);
119
120gboolean             g_markup_parse_context_end_parse (GMarkupParseContext *context,
121                                                       GError             **error);
122G_CONST_RETURN gchar *g_markup_parse_context_get_element (GMarkupParseContext *context);
123G_CONST_RETURN GSList *g_markup_parse_context_get_element_stack (GMarkupParseContext *context);
124
125/* For user-constructed error messages, has no precise semantics */
126void                 g_markup_parse_context_get_position (GMarkupParseContext *context,
127                                                          gint                *line_number,
128                                                          gint                *char_number);
129gpointer             g_markup_parse_context_get_user_data (GMarkupParseContext *context);
130
131/* useful when saving */
132gchar* g_markup_escape_text (const gchar *text,
133                             gssize       length);
134
135gchar *g_markup_printf_escaped (const char *format,
136				...) G_GNUC_PRINTF (1, 2);
137gchar *g_markup_vprintf_escaped (const char *format,
138				 va_list     args);
139
140typedef 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 */
153gboolean   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
161G_END_DECLS
162
163#endif /* __G_MARKUP_H__ */
164