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