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  ...  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 }