source: appstream-generator/build/girepo/glib/SimpleXML.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

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