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