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.OptionContext; 26 27 private import glib.ConstructionException; 28 private import glib.ErrorG; 29 private import glib.GException; 30 private import glib.OptionGroup; 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 `GOptionContext` struct defines which options 39 * are accepted by the commandline option parser. The struct has only private 40 * fields and should not be directly accessed. 41 */ 42 public class OptionContext 43 { 44 /** the main Gtk struct */ 45 protected GOptionContext* gOptionContext; 46 protected bool ownedRef; 47 48 /** Get the main Gtk struct */ 49 public GOptionContext* getOptionContextStruct(bool transferOwnership = false) 50 { 51 if (transferOwnership) 52 ownedRef = false; 53 return gOptionContext; 54 } 55 56 /** the main Gtk struct as a void* */ 57 protected void* getStruct() 58 { 59 return cast(void*)gOptionContext; 60 } 61 62 /** 63 * Sets our main struct and passes it to the parent class. 64 */ 65 public this (GOptionContext* gOptionContext, bool ownedRef = false) 66 { 67 this.gOptionContext = gOptionContext; 68 this.ownedRef = ownedRef; 69 } 70 71 ~this () 72 { 73 if ( Linker.isLoaded(LIBRARY_GLIB) && ownedRef ) 74 g_option_context_free(gOptionContext); 75 } 76 77 78 /** 79 * Adds a #GOptionGroup to the @context, so that parsing with @context 80 * will recognize the options in the group. Note that this will take 81 * ownership of the @group and thus the @group should not be freed. 82 * 83 * Params: 84 * group = the group to add 85 * 86 * Since: 2.6 87 */ 88 public void addGroup(OptionGroup group) 89 { 90 g_option_context_add_group(gOptionContext, (group is null) ? null : group.getOptionGroupStruct(true)); 91 } 92 93 /** 94 * A convenience function which creates a main group if it doesn't 95 * exist, adds the @entries to it and sets the translation domain. 96 * 97 * Params: 98 * entries = a %NULL-terminated array of #GOptionEntrys 99 * translationDomain = a translation domain to use for translating 100 * the `--help` output for the options in @entries 101 * with gettext(), or %NULL 102 * 103 * Since: 2.6 104 */ 105 public void addMainEntries(GOptionEntry[] entries, string translationDomain) 106 { 107 g_option_context_add_main_entries(gOptionContext, entries.ptr, Str.toStringz(translationDomain)); 108 } 109 110 /** 111 * Frees context and all the groups which have been 112 * added to it. 113 * 114 * Please note that parsed arguments need to be freed separately (see 115 * #GOptionEntry). 116 * 117 * Since: 2.6 118 */ 119 public void free() 120 { 121 g_option_context_free(gOptionContext); 122 ownedRef = false; 123 } 124 125 /** 126 * Returns the description. See g_option_context_set_description(). 127 * 128 * Returns: the description 129 * 130 * Since: 2.12 131 */ 132 public string getDescription() 133 { 134 return Str.toString(g_option_context_get_description(gOptionContext)); 135 } 136 137 /** 138 * Returns a formatted, translated help text for the given context. 139 * To obtain the text produced by `--help`, call 140 * `g_option_context_get_help (context, TRUE, NULL)`. 141 * To obtain the text produced by `--help-all`, call 142 * `g_option_context_get_help (context, FALSE, NULL)`. 143 * To obtain the help text for an option group, call 144 * `g_option_context_get_help (context, FALSE, group)`. 145 * 146 * Params: 147 * mainHelp = if %TRUE, only include the main group 148 * group = the #GOptionGroup to create help for, or %NULL 149 * 150 * Returns: A newly allocated string containing the help text 151 * 152 * Since: 2.14 153 */ 154 public string getHelp(bool mainHelp, OptionGroup group) 155 { 156 auto retStr = g_option_context_get_help(gOptionContext, mainHelp, (group is null) ? null : group.getOptionGroupStruct()); 157 158 scope(exit) Str.freeString(retStr); 159 return Str.toString(retStr); 160 } 161 162 /** 163 * Returns whether automatic `--help` generation 164 * is turned on for @context. See g_option_context_set_help_enabled(). 165 * 166 * Returns: %TRUE if automatic help generation is turned on. 167 * 168 * Since: 2.6 169 */ 170 public bool getHelpEnabled() 171 { 172 return g_option_context_get_help_enabled(gOptionContext) != 0; 173 } 174 175 /** 176 * Returns whether unknown options are ignored or not. See 177 * g_option_context_set_ignore_unknown_options(). 178 * 179 * Returns: %TRUE if unknown options are ignored. 180 * 181 * Since: 2.6 182 */ 183 public bool getIgnoreUnknownOptions() 184 { 185 return g_option_context_get_ignore_unknown_options(gOptionContext) != 0; 186 } 187 188 /** 189 * Returns a pointer to the main group of @context. 190 * 191 * Returns: the main group of @context, or %NULL if 192 * @context doesn't have a main group. Note that group belongs to 193 * @context and should not be modified or freed. 194 * 195 * Since: 2.6 196 */ 197 public OptionGroup getMainGroup() 198 { 199 auto __p = g_option_context_get_main_group(gOptionContext); 200 201 if(__p is null) 202 { 203 return null; 204 } 205 206 return new OptionGroup(cast(GOptionGroup*) __p); 207 } 208 209 /** 210 * Returns whether strict POSIX code is enabled. 211 * 212 * See g_option_context_set_strict_posix() for more information. 213 * 214 * Returns: %TRUE if strict POSIX is enabled, %FALSE otherwise. 215 * 216 * Since: 2.44 217 */ 218 public bool getStrictPosix() 219 { 220 return g_option_context_get_strict_posix(gOptionContext) != 0; 221 } 222 223 /** 224 * Returns the summary. See g_option_context_set_summary(). 225 * 226 * Returns: the summary 227 * 228 * Since: 2.12 229 */ 230 public string getSummary() 231 { 232 return Str.toString(g_option_context_get_summary(gOptionContext)); 233 } 234 235 /** 236 * Parses the command line arguments, recognizing options 237 * which have been added to @context. A side-effect of 238 * calling this function is that g_set_prgname() will be 239 * called. 240 * 241 * If the parsing is successful, any parsed arguments are 242 * removed from the array and @argc and @argv are updated 243 * accordingly. A '--' option is stripped from @argv 244 * unless there are unparsed options before and after it, 245 * or some of the options after it start with '-'. In case 246 * of an error, @argc and @argv are left unmodified. 247 * 248 * If automatic `--help` support is enabled 249 * (see g_option_context_set_help_enabled()), and the 250 * @argv array contains one of the recognized help options, 251 * this function will produce help output to stdout and 252 * call `exit (0)`. 253 * 254 * Note that function depends on the [current locale][setlocale] for 255 * automatic character set conversion of string and filename 256 * arguments. 257 * 258 * Params: 259 * argv = a pointer to the array of command line arguments 260 * 261 * Returns: %TRUE if the parsing was successful, 262 * %FALSE if an error occurred 263 * 264 * Since: 2.6 265 * 266 * Throws: GException on failure. 267 */ 268 public bool parse(ref string[] argv) 269 { 270 int argc = cast(int)argv.length; 271 char** outargv = Str.toStringzArray(argv); 272 GError* err = null; 273 274 auto __p = g_option_context_parse(gOptionContext, &argc, &outargv, &err) != 0; 275 276 if (err !is null) 277 { 278 throw new GException( new ErrorG(err) ); 279 } 280 281 argv = Str.toStringArray(outargv, argc); 282 283 return __p; 284 } 285 286 /** 287 * Parses the command line arguments. 288 * 289 * This function is similar to g_option_context_parse() except that it 290 * respects the normal memory rules when dealing with a strv instead of 291 * assuming that the passed-in array is the argv of the main function. 292 * 293 * In particular, strings that are removed from the arguments list will 294 * be freed using g_free(). 295 * 296 * On Windows, the strings are expected to be in UTF-8. This is in 297 * contrast to g_option_context_parse() which expects them to be in the 298 * system codepage, which is how they are passed as @argv to main(). 299 * See g_win32_get_command_line() for a solution. 300 * 301 * This function is useful if you are trying to use #GOptionContext with 302 * #GApplication. 303 * 304 * Params: 305 * arguments = a pointer 306 * to the command line arguments (which must be in UTF-8 on Windows). 307 * Starting with GLib 2.62, @arguments can be %NULL, which matches 308 * g_option_context_parse(). 309 * 310 * Returns: %TRUE if the parsing was successful, 311 * %FALSE if an error occurred 312 * 313 * Since: 2.40 314 * 315 * Throws: GException on failure. 316 */ 317 public bool parseStrv(ref string[] arguments) 318 { 319 char** outarguments = Str.toStringzArray(arguments); 320 GError* err = null; 321 322 auto __p = g_option_context_parse_strv(gOptionContext, &outarguments, &err) != 0; 323 324 if (err !is null) 325 { 326 throw new GException( new ErrorG(err) ); 327 } 328 329 arguments = Str.toStringArray(outarguments); 330 331 return __p; 332 } 333 334 /** 335 * Adds a string to be displayed in `--help` output after the list 336 * of options. This text often includes a bug reporting address. 337 * 338 * Note that the summary is translated (see 339 * g_option_context_set_translate_func()). 340 * 341 * Params: 342 * description = a string to be shown in `--help` output 343 * after the list of options, or %NULL 344 * 345 * Since: 2.12 346 */ 347 public void setDescription(string description) 348 { 349 g_option_context_set_description(gOptionContext, Str.toStringz(description)); 350 } 351 352 /** 353 * Enables or disables automatic generation of `--help` output. 354 * By default, g_option_context_parse() recognizes `--help`, `-h`, 355 * `-?`, `--help-all` and `--help-groupname` and creates suitable 356 * output to stdout. 357 * 358 * Params: 359 * helpEnabled = %TRUE to enable `--help`, %FALSE to disable it 360 * 361 * Since: 2.6 362 */ 363 public void setHelpEnabled(bool helpEnabled) 364 { 365 g_option_context_set_help_enabled(gOptionContext, helpEnabled); 366 } 367 368 /** 369 * Sets whether to ignore unknown options or not. If an argument is 370 * ignored, it is left in the @argv array after parsing. By default, 371 * g_option_context_parse() treats unknown options as error. 372 * 373 * This setting does not affect non-option arguments (i.e. arguments 374 * which don't start with a dash). But note that GOption cannot reliably 375 * determine whether a non-option belongs to a preceding unknown option. 376 * 377 * Params: 378 * ignoreUnknown = %TRUE to ignore unknown options, %FALSE to produce 379 * an error when unknown options are met 380 * 381 * Since: 2.6 382 */ 383 public void setIgnoreUnknownOptions(bool ignoreUnknown) 384 { 385 g_option_context_set_ignore_unknown_options(gOptionContext, ignoreUnknown); 386 } 387 388 /** 389 * Sets a #GOptionGroup as main group of the @context. 390 * This has the same effect as calling g_option_context_add_group(), 391 * the only difference is that the options in the main group are 392 * treated differently when generating `--help` output. 393 * 394 * Params: 395 * group = the group to set as main group 396 * 397 * Since: 2.6 398 */ 399 public void setMainGroup(OptionGroup group) 400 { 401 g_option_context_set_main_group(gOptionContext, (group is null) ? null : group.getOptionGroupStruct(true)); 402 } 403 404 /** 405 * Sets strict POSIX mode. 406 * 407 * By default, this mode is disabled. 408 * 409 * In strict POSIX mode, the first non-argument parameter encountered 410 * (eg: filename) terminates argument processing. Remaining arguments 411 * are treated as non-options and are not attempted to be parsed. 412 * 413 * If strict POSIX mode is disabled then parsing is done in the GNU way 414 * where option arguments can be freely mixed with non-options. 415 * 416 * As an example, consider "ls foo -l". With GNU style parsing, this 417 * will list "foo" in long mode. In strict POSIX style, this will list 418 * the files named "foo" and "-l". 419 * 420 * It may be useful to force strict POSIX mode when creating "verb 421 * style" command line tools. For example, the "gsettings" command line 422 * tool supports the global option "--schemadir" as well as many 423 * subcommands ("get", "set", etc.) which each have their own set of 424 * arguments. Using strict POSIX mode will allow parsing the global 425 * options up to the verb name while leaving the remaining options to be 426 * parsed by the relevant subcommand (which can be determined by 427 * examining the verb name, which should be present in argv[1] after 428 * parsing). 429 * 430 * Params: 431 * strictPosix = the new value 432 * 433 * Since: 2.44 434 */ 435 public void setStrictPosix(bool strictPosix) 436 { 437 g_option_context_set_strict_posix(gOptionContext, strictPosix); 438 } 439 440 /** 441 * Adds a string to be displayed in `--help` output before the list 442 * of options. This is typically a summary of the program functionality. 443 * 444 * Note that the summary is translated (see 445 * g_option_context_set_translate_func() and 446 * g_option_context_set_translation_domain()). 447 * 448 * Params: 449 * summary = a string to be shown in `--help` output 450 * before the list of options, or %NULL 451 * 452 * Since: 2.12 453 */ 454 public void setSummary(string summary) 455 { 456 g_option_context_set_summary(gOptionContext, Str.toStringz(summary)); 457 } 458 459 /** 460 * Sets the function which is used to translate the contexts 461 * user-visible strings, for `--help` output. If @func is %NULL, 462 * strings are not translated. 463 * 464 * Note that option groups have their own translation functions, 465 * this function only affects the @parameter_string (see g_option_context_new()), 466 * the summary (see g_option_context_set_summary()) and the description 467 * (see g_option_context_set_description()). 468 * 469 * If you are using gettext(), you only need to set the translation 470 * domain, see g_option_context_set_translation_domain(). 471 * 472 * Params: 473 * func = the #GTranslateFunc, or %NULL 474 * data = user data to pass to @func, or %NULL 475 * destroyNotify = a function which gets called to free @data, or %NULL 476 * 477 * Since: 2.12 478 */ 479 public void setTranslateFunc(GTranslateFunc func, void* data, GDestroyNotify destroyNotify) 480 { 481 g_option_context_set_translate_func(gOptionContext, func, data, destroyNotify); 482 } 483 484 /** 485 * A convenience function to use gettext() for translating 486 * user-visible strings. 487 * 488 * Params: 489 * domain = the domain to use 490 * 491 * Since: 2.12 492 */ 493 public void setTranslationDomain(string domain) 494 { 495 g_option_context_set_translation_domain(gOptionContext, Str.toStringz(domain)); 496 } 497 498 /** 499 * Creates a new option context. 500 * 501 * The @parameter_string can serve multiple purposes. It can be used 502 * to add descriptions for "rest" arguments, which are not parsed by 503 * the #GOptionContext, typically something like "FILES" or 504 * "FILE1 FILE2...". If you are using #G_OPTION_REMAINING for 505 * collecting "rest" arguments, GLib handles this automatically by 506 * using the @arg_description of the corresponding #GOptionEntry in 507 * the usage summary. 508 * 509 * Another usage is to give a short summary of the program 510 * functionality, like " - frob the strings", which will be displayed 511 * in the same line as the usage. For a longer description of the 512 * program functionality that should be displayed as a paragraph 513 * below the usage line, use g_option_context_set_summary(). 514 * 515 * Note that the @parameter_string is translated using the 516 * function set with g_option_context_set_translate_func(), so 517 * it should normally be passed untranslated. 518 * 519 * Params: 520 * parameterString = a string which is displayed in 521 * the first line of `--help` output, after the usage summary 522 * `programname [OPTION...]` 523 * 524 * Returns: a newly created #GOptionContext, which must be 525 * freed with g_option_context_free() after use. 526 * 527 * Since: 2.6 528 * 529 * Throws: ConstructionException GTK+ fails to create the object. 530 */ 531 public this(string parameterString) 532 { 533 auto __p = g_option_context_new(Str.toStringz(parameterString)); 534 535 if(__p is null) 536 { 537 throw new ConstructionException("null returned by new"); 538 } 539 540 this(cast(GOptionContext*) __p); 541 } 542 543 /** */ 544 public static GQuark optionErrorQuark() 545 { 546 return g_option_error_quark(); 547 } 548 }