1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD 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
13  * GNU 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 gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module glib.SimpleXML;
26 
27 private import glib.ConstructionException;
28 private import glib.ErrorG;
29 private import glib.GException;
30 private import glib.ListSG;
31 private import glib.Str;
32 private import gtkc.glib;
33 public  import gtkc.glibtypes;
34 
35 
36 /**
37  * A parse context is used to parse a stream of bytes that
38  * you expect to contain marked-up text.
39  * 
40  * See g_markup_parse_context_new(), #GMarkupParser, and so
41  * on for more details.
42  */
43 public class SimpleXML
44 {
45 	/** the main Gtk struct */
46 	protected GMarkupParseContext* gMarkupParseContext;
47 
48 	/** Get the main Gtk struct */
49 	public GMarkupParseContext* getSimpleXMLStruct()
50 	{
51 		return gMarkupParseContext;
52 	}
53 
54 	/** the main Gtk struct as a void* */
55 	protected void* getStruct()
56 	{
57 		return cast(void*)gMarkupParseContext;
58 	}
59 
60 	/**
61 	 * Sets our main struct and passes it to the parent class.
62 	 */
63 	public this (GMarkupParseContext* gMarkupParseContext)
64 	{
65 		this.gMarkupParseContext = gMarkupParseContext;
66 	}
67 
68 	/**
69 	 */
70 
71 	/**
72 	 * Creates a new parse context. A parse context is used to parse
73 	 * marked-up documents. You can feed any number of documents into
74 	 * a context, as long as no errors occur; once an error occurs,
75 	 * the parse context can't continue to parse text (you have to
76 	 * free it and create a new parse context).
77 	 *
78 	 * Params:
79 	 *     parser = a #GMarkupParser
80 	 *     flags = one or more #GMarkupParseFlags
81 	 *     userData = user data to pass to #GMarkupParser functions
82 	 *     userDataDnotify = user data destroy notifier called when
83 	 *         the parse context is freed
84 	 *
85 	 * Return: a new #GMarkupParseContext
86 	 *
87 	 * Throws: ConstructionException GTK+ fails to create the object.
88 	 */
89 	public this(GMarkupParser* parser, GMarkupParseFlags flags, void* userData, GDestroyNotify userDataDnotify)
90 	{
91 		auto p = g_markup_parse_context_new(parser, flags, userData, userDataDnotify);
92 		
93 		if(p is null)
94 		{
95 			throw new ConstructionException("null returned by new");
96 		}
97 		
98 		this(cast(GMarkupParseContext*) p);
99 	}
100 
101 	/**
102 	 * Signals to the #GMarkupParseContext that all data has been
103 	 * fed into the parse context with g_markup_parse_context_parse().
104 	 *
105 	 * This function reports an error if the document isn't complete,
106 	 * for example if elements are still open.
107 	 *
108 	 * Return: %TRUE on success, %FALSE if an error was set
109 	 *
110 	 * Throws: GException on failure.
111 	 */
112 	public bool endParse()
113 	{
114 		GError* err = null;
115 		
116 		auto p = g_markup_parse_context_end_parse(gMarkupParseContext, &err) != 0;
117 		
118 		if (err !is null)
119 		{
120 			throw new GException( new ErrorG(err) );
121 		}
122 		
123 		return p;
124 	}
125 
126 	/**
127 	 * Frees a #GMarkupParseContext.
128 	 *
129 	 * This function can't be called from inside one of the
130 	 * #GMarkupParser functions or while a subparser is pushed.
131 	 */
132 	public void free()
133 	{
134 		g_markup_parse_context_free(gMarkupParseContext);
135 	}
136 
137 	/**
138 	 * Retrieves the name of the currently open element.
139 	 *
140 	 * If called from the start_element or end_element handlers this will
141 	 * give the element_name as passed to those functions. For the parent
142 	 * elements, see g_markup_parse_context_get_element_stack().
143 	 *
144 	 * Return: the name of the currently open element, or %NULL
145 	 *
146 	 * Since: 2.2
147 	 */
148 	public string getElement()
149 	{
150 		return Str.toString(g_markup_parse_context_get_element(gMarkupParseContext));
151 	}
152 
153 	/**
154 	 * Retrieves the element stack from the internal state of the parser.
155 	 *
156 	 * The returned #GSList is a list of strings where the first item is
157 	 * the currently open tag (as would be returned by
158 	 * g_markup_parse_context_get_element()) and the next item is its
159 	 * immediate parent.
160 	 *
161 	 * This function is intended to be used in the start_element and
162 	 * end_element handlers where g_markup_parse_context_get_element()
163 	 * would merely return the name of the element that is being
164 	 * processed.
165 	 *
166 	 * Return: the element stack, which must not be modified
167 	 *
168 	 * Since: 2.16
169 	 */
170 	public ListSG getElementStack()
171 	{
172 		auto p = g_markup_parse_context_get_element_stack(gMarkupParseContext);
173 		
174 		if(p is null)
175 		{
176 			return null;
177 		}
178 		
179 		return new ListSG(cast(GSList*) p);
180 	}
181 
182 	/**
183 	 * Retrieves the current line number and the number of the character on
184 	 * that line. Intended for use in error messages; there are no strict
185 	 * semantics for what constitutes the "current" line number other than
186 	 * "the best number we could come up with for error messages."
187 	 *
188 	 * Params:
189 	 *     lineNumber = return location for a line number, or %NULL
190 	 *     charNumber = return location for a char-on-line number, or %NULL
191 	 */
192 	public void getPosition(int* lineNumber, int* charNumber)
193 	{
194 		g_markup_parse_context_get_position(gMarkupParseContext, lineNumber, charNumber);
195 	}
196 
197 	/**
198 	 * Returns the user_data associated with @context.
199 	 *
200 	 * This will either be the user_data that was provided to
201 	 * g_markup_parse_context_new() or to the most recent call
202 	 * of g_markup_parse_context_push().
203 	 *
204 	 * Return: the provided user_data. The returned data belongs to
205 	 *     the markup context and will be freed when
206 	 *     g_markup_parse_context_free() is called.
207 	 *
208 	 * Since: 2.18
209 	 */
210 	public void* getUserData()
211 	{
212 		return g_markup_parse_context_get_user_data(gMarkupParseContext);
213 	}
214 
215 	/**
216 	 * Feed some data to the #GMarkupParseContext.
217 	 *
218 	 * The data need not be valid UTF-8; an error will be signaled if
219 	 * it's invalid. The data need not be an entire document; you can
220 	 * feed a document into the parser incrementally, via multiple calls
221 	 * to this function. Typically, as you receive data from a network
222 	 * connection or file, you feed each received chunk of data into this
223 	 * function, aborting the process if an error occurs. Once an error
224 	 * is reported, no further data may be fed to the #GMarkupParseContext;
225 	 * all errors are fatal.
226 	 *
227 	 * Params:
228 	 *     text = chunk of text to parse
229 	 *     textLen = length of @text in bytes
230 	 *
231 	 * Return: %FALSE if an error occurred, %TRUE on success
232 	 *
233 	 * Throws: GException on failure.
234 	 */
235 	public bool parse(string text, ptrdiff_t textLen)
236 	{
237 		GError* err = null;
238 		
239 		auto p = g_markup_parse_context_parse(gMarkupParseContext, Str.toStringz(text), textLen, &err) != 0;
240 		
241 		if (err !is null)
242 		{
243 			throw new GException( new ErrorG(err) );
244 		}
245 		
246 		return p;
247 	}
248 
249 	/**
250 	 * Completes the process of a temporary sub-parser redirection.
251 	 *
252 	 * This function exists to collect the user_data allocated by a
253 	 * matching call to g_markup_parse_context_push(). It must be called
254 	 * in the end_element handler corresponding to the start_element
255 	 * handler during which g_markup_parse_context_push() was called.
256 	 * You must not call this function from the error callback -- the
257 	 * @user_data is provided directly to the callback in that case.
258 	 *
259 	 * This function is not intended to be directly called by users
260 	 * interested in invoking subparsers. Instead, it is intended to
261 	 * be used by the subparsers themselves to implement a higher-level
262 	 * interface.
263 	 *
264 	 * Return: the user data passed to g_markup_parse_context_push()
265 	 *
266 	 * Since: 2.18
267 	 */
268 	public void* pop()
269 	{
270 		return g_markup_parse_context_pop(gMarkupParseContext);
271 	}
272 
273 	/**
274 	 * Temporarily redirects markup data to a sub-parser.
275 	 *
276 	 * This function may only be called from the start_element handler of
277 	 * a #GMarkupParser. It must be matched with a corresponding call to
278 	 * g_markup_parse_context_pop() in the matching end_element handler
279 	 * (except in the case that the parser aborts due to an error).
280 	 *
281 	 * All tags, text and other data between the matching tags is
282 	 * redirected to the subparser given by @parser. @user_data is used
283 	 * as the user_data for that parser. @user_data is also passed to the
284 	 * error callback in the event that an error occurs. This includes
285 	 * errors that occur in subparsers of the subparser.
286 	 *
287 	 * The end tag matching the start tag for which this call was made is
288 	 * handled by the previous parser (which is given its own user_data)
289 	 * which is why g_markup_parse_context_pop() is provided to allow "one
290 	 * last access" to the @user_data provided to this function. In the
291 	 * case of error, the @user_data provided here is passed directly to
292 	 * the error callback of the subparser and g_markup_parse_context_pop()
293 	 * should not be called. In either case, if @user_data was allocated
294 	 * then it ought to be freed from both of these locations.
295 	 *
296 	 * This function is not intended to be directly called by users
297 	 * interested in invoking subparsers. Instead, it is intended to be
298 	 * used by the subparsers themselves to implement a higher-level
299 	 * interface.
300 	 *
301 	 * As an example, see the following implementation of a simple
302 	 * parser that counts the number of tags encountered.
303 	 *
304 	 * |[<!-- language="C" -->
305 	 * typedef struct
306 	 * {
307 	 * gint tag_count;
308 	 * } CounterData;
309 	 *
310 	 * static void
311 	 * counter_start_element (GMarkupParseContext  *context,
312 	 * const gchar          *element_name,
313 	 * const gchar         **attribute_names,
314 	 * const gchar         **attribute_values,
315 	 * gpointer              user_data,
316 	 * GError              **error)
317 	 * {
318 	 * CounterData *data = user_data;
319 	 *
320 	 * data->tag_count++;
321 	 * }
322 	 *
323 	 * static void
324 	 * counter_error (GMarkupParseContext *context,
325 	 * GError              *error,
326 	 * gpointer             user_data)
327 	 * {
328 	 * CounterData *data = user_data;
329 	 *
330 	 * g_slice_free (CounterData, data);
331 	 * }
332 	 *
333 	 * static GMarkupParser counter_subparser =
334 	 * {
335 	 * counter_start_element,
336 	 * NULL,
337 	 * NULL,
338 	 * NULL,
339 	 * counter_error
340 	 * };
341 	 * ]|
342 	 *
343 	 * In order to allow this parser to be easily used as a subparser, the
344 	 * following interface is provided:
345 	 *
346 	 * |[<!-- language="C" -->
347 	 * void
348 	 * start_counting (GMarkupParseContext *context)
349 	 * {
350 	 * CounterData *data = g_slice_new (CounterData);
351 	 *
352 	 * data->tag_count = 0;
353 	 * g_markup_parse_context_push (context, &counter_subparser, data);
354 	 * }
355 	 *
356 	 * gint
357 	 * end_counting (GMarkupParseContext *context)
358 	 * {
359 	 * CounterData *data = g_markup_parse_context_pop (context);
360 	 * int result;
361 	 *
362 	 * result = data->tag_count;
363 	 * g_slice_free (CounterData, data);
364 	 *
365 	 * return result;
366 	 * }
367 	 * ]|
368 	 *
369 	 * The subparser would then be used as follows:
370 	 *
371 	 * |[<!-- language="C" -->
372 	 * static void start_element (context, element_name, ...)
373 	 * {
374 	 * if (strcmp (element_name, "count-these") == 0)
375 	 * start_counting (context);
376 	 *
377 	 * // else, handle other tags...
378 	 * }
379 	 *
380 	 * static void end_element (context, element_name, ...)
381 	 * {
382 	 * if (strcmp (element_name, "count-these") == 0)
383 	 * g_print ("Counted %d tags\n", end_counting (context));
384 	 *
385 	 * // else, handle other tags...
386 	 * }
387 	 * ]|
388 	 *
389 	 * Params:
390 	 *     parser = a #GMarkupParser
391 	 *     userData = user data to pass to #GMarkupParser functions
392 	 *
393 	 * Since: 2.18
394 	 */
395 	public void push(GMarkupParser* parser, void* userData)
396 	{
397 		g_markup_parse_context_push(gMarkupParseContext, parser, userData);
398 	}
399 
400 	/**
401 	 * Increases the reference count of @context.
402 	 *
403 	 * Return: the same @context
404 	 *
405 	 * Since: 2.36
406 	 */
407 	public SimpleXML doref()
408 	{
409 		auto p = g_markup_parse_context_ref(gMarkupParseContext);
410 		
411 		if(p is null)
412 		{
413 			return null;
414 		}
415 		
416 		return new SimpleXML(cast(GMarkupParseContext*) p);
417 	}
418 
419 	/**
420 	 * Decreases the reference count of @context.  When its reference count
421 	 * drops to 0, it is freed.
422 	 *
423 	 * Since: 2.36
424 	 */
425 	public void unref()
426 	{
427 		g_markup_parse_context_unref(gMarkupParseContext);
428 	}
429 
430 	public static GQuark markupErrorQuark()
431 	{
432 		return g_markup_error_quark();
433 	}
434 
435 	/**
436 	 * Escapes text so that the markup parser will parse it verbatim.
437 	 * Less than, greater than, ampersand, etc. are replaced with the
438 	 * corresponding entities. This function would typically be used
439 	 * when writing out a file to be parsed with the markup parser.
440 	 *
441 	 * Note that this function doesn't protect whitespace and line endings
442 	 * from being processed according to the XML rules for normalization
443 	 * of line endings and attribute values.
444 	 *
445 	 * Note also that this function will produce character references in
446 	 * the range of &#x1; ... &#x1f; for all control sequences
447 	 * except for tabstop, newline and carriage return.  The character
448 	 * references in this range are not valid XML 1.0, but they are
449 	 * valid XML 1.1 and will be accepted by the GMarkup parser.
450 	 *
451 	 * Params:
452 	 *     text = some valid UTF-8 text
453 	 *     length = length of @text in bytes, or -1 if the text is nul-terminated
454 	 *
455 	 * Return: a newly allocated string with the escaped text
456 	 */
457 	public static string markupEscapeText(string text, ptrdiff_t length)
458 	{
459 		return Str.toString(g_markup_escape_text(Str.toStringz(text), length));
460 	}
461 
462 	/**
463 	 * Formats the data in @args according to @format, escaping
464 	 * all string and character arguments in the fashion
465 	 * of g_markup_escape_text(). See g_markup_printf_escaped().
466 	 *
467 	 * Params:
468 	 *     format = printf() style format string
469 	 *     args = variable argument list, similar to vprintf()
470 	 *
471 	 * Return: newly allocated result from formatting
472 	 *     operation. Free with g_free().
473 	 *
474 	 * Since: 2.4
475 	 */
476 	public static string markupVprintfEscaped(string format, void* args)
477 	{
478 		return Str.toString(g_markup_vprintf_escaped(Str.toStringz(format), args));
479 	}
480 }