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