Move GMarkup docs inline
[platform/upstream/glib.git] / 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 /**
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 void                 g_markup_parse_context_free  (GMarkupParseContext *context);
186 gboolean             g_markup_parse_context_parse (GMarkupParseContext *context,
187                                                    const gchar         *text,
188                                                    gssize               text_len,
189                                                    GError             **error);
190 void                 g_markup_parse_context_push  (GMarkupParseContext *context,
191                                                    const GMarkupParser *parser,
192                                                    gpointer             user_data);
193 gpointer             g_markup_parse_context_pop   (GMarkupParseContext *context);
194
195 gboolean             g_markup_parse_context_end_parse (GMarkupParseContext *context,
196                                                        GError             **error);
197 G_CONST_RETURN gchar *g_markup_parse_context_get_element (GMarkupParseContext *context);
198 G_CONST_RETURN GSList *g_markup_parse_context_get_element_stack (GMarkupParseContext *context);
199
200 /* For user-constructed error messages, has no precise semantics */
201 void                 g_markup_parse_context_get_position (GMarkupParseContext *context,
202                                                           gint                *line_number,
203                                                           gint                *char_number);
204 gpointer             g_markup_parse_context_get_user_data (GMarkupParseContext *context);
205
206 /* useful when saving */
207 gchar* g_markup_escape_text (const gchar *text,
208                              gssize       length);
209
210 gchar *g_markup_printf_escaped (const char *format,
211                                 ...) G_GNUC_PRINTF (1, 2);
212 gchar *g_markup_vprintf_escaped (const char *format,
213                                  va_list     args);
214
215 typedef enum
216 {
217   G_MARKUP_COLLECT_INVALID,
218   G_MARKUP_COLLECT_STRING,
219   G_MARKUP_COLLECT_STRDUP,
220   G_MARKUP_COLLECT_BOOLEAN,
221   G_MARKUP_COLLECT_TRISTATE,
222
223   G_MARKUP_COLLECT_OPTIONAL = (1 << 16)
224 } GMarkupCollectType;
225
226
227 /* useful from start_element */
228 gboolean   g_markup_collect_attributes (const gchar         *element_name,
229                                         const gchar        **attribute_names,
230                                         const gchar        **attribute_values,
231                                         GError             **error,
232                                         GMarkupCollectType   first_type,
233                                         const gchar         *first_attr,
234                                         ...);
235
236 G_END_DECLS
237
238 #endif /* __G_MARKUP_H__ */