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 gtkc.glib; 33 public import gtkc.glibtypes; 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, 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 * argc = a pointer to the number of command line arguments 260 * argv = a pointer to the array of command line arguments 261 * 262 * Returns: %TRUE if the parsing was successful, 263 * %FALSE if an error occurred 264 * 265 * Since: 2.6 266 * 267 * Throws: GException on failure. 268 */ 269 public bool parse(ref string[] argv) 270 { 271 int argc = cast(int)argv.length; 272 char** outargv = Str.toStringzArray(argv); 273 GError* err = null; 274 275 auto p = g_option_context_parse(gOptionContext, &argc, &outargv, &err) != 0; 276 277 if (err !is null) 278 { 279 throw new GException( new ErrorG(err) ); 280 } 281 282 argv = Str.toStringArray(outargv, argc); 283 284 return p; 285 } 286 287 /** 288 * Parses the command line arguments. 289 * 290 * This function is similar to g_option_context_parse() except that it 291 * respects the normal memory rules when dealing with a strv instead of 292 * assuming that the passed-in array is the argv of the main function. 293 * 294 * In particular, strings that are removed from the arguments list will 295 * be freed using g_free(). 296 * 297 * On Windows, the strings are expected to be in UTF-8. This is in 298 * contrast to g_option_context_parse() which expects them to be in the 299 * system codepage, which is how they are passed as @argv to main(). 300 * See g_win32_get_command_line() for a solution. 301 * 302 * This function is useful if you are trying to use #GOptionContext with 303 * #GApplication. 304 * 305 * Params: 306 * arguments = a pointer to the 307 * command line arguments (which must be in UTF-8 on Windows) 308 * 309 * Returns: %TRUE if the parsing was successful, 310 * %FALSE if an error occurred 311 * 312 * Since: 2.40 313 * 314 * Throws: GException on failure. 315 */ 316 public bool parseStrv(ref string[] arguments) 317 { 318 char** outarguments = Str.toStringzArray(arguments); 319 GError* err = null; 320 321 auto p = g_option_context_parse_strv(gOptionContext, &outarguments, &err) != 0; 322 323 if (err !is null) 324 { 325 throw new GException( new ErrorG(err) ); 326 } 327 328 arguments = Str.toStringArray(outarguments); 329 330 return p; 331 } 332 333 /** 334 * Adds a string to be displayed in `--help` output after the list 335 * of options. This text often includes a bug reporting address. 336 * 337 * Note that the summary is translated (see 338 * g_option_context_set_translate_func()). 339 * 340 * Params: 341 * description = a string to be shown in `--help` output 342 * after the list of options, or %NULL 343 * 344 * Since: 2.12 345 */ 346 public void setDescription(string description) 347 { 348 g_option_context_set_description(gOptionContext, Str.toStringz(description)); 349 } 350 351 /** 352 * Enables or disables automatic generation of `--help` output. 353 * By default, g_option_context_parse() recognizes `--help`, `-h`, 354 * `-?`, `--help-all` and `--help-groupname` and creates suitable 355 * output to stdout. 356 * 357 * Params: 358 * helpEnabled = %TRUE to enable `--help`, %FALSE to disable it 359 * 360 * Since: 2.6 361 */ 362 public void setHelpEnabled(bool helpEnabled) 363 { 364 g_option_context_set_help_enabled(gOptionContext, helpEnabled); 365 } 366 367 /** 368 * Sets whether to ignore unknown options or not. If an argument is 369 * ignored, it is left in the @argv array after parsing. By default, 370 * g_option_context_parse() treats unknown options as error. 371 * 372 * This setting does not affect non-option arguments (i.e. arguments 373 * which don't start with a dash). But note that GOption cannot reliably 374 * determine whether a non-option belongs to a preceding unknown option. 375 * 376 * Params: 377 * ignoreUnknown = %TRUE to ignore unknown options, %FALSE to produce 378 * an error when unknown options are met 379 * 380 * Since: 2.6 381 */ 382 public void setIgnoreUnknownOptions(bool ignoreUnknown) 383 { 384 g_option_context_set_ignore_unknown_options(gOptionContext, ignoreUnknown); 385 } 386 387 /** 388 * Sets a #GOptionGroup as main group of the @context. 389 * This has the same effect as calling g_option_context_add_group(), 390 * the only difference is that the options in the main group are 391 * treated differently when generating `--help` output. 392 * 393 * Params: 394 * group = the group to set as main group 395 * 396 * Since: 2.6 397 */ 398 public void setMainGroup(OptionGroup group) 399 { 400 g_option_context_set_main_group(gOptionContext, (group is null) ? null : group.getOptionGroupStruct(true)); 401 } 402 403 /** 404 * Sets strict POSIX mode. 405 * 406 * By default, this mode is disabled. 407 * 408 * In strict POSIX mode, the first non-argument parameter encountered 409 * (eg: filename) terminates argument processing. Remaining arguments 410 * are treated as non-options and are not attempted to be parsed. 411 * 412 * If strict POSIX mode is disabled then parsing is done in the GNU way 413 * where option arguments can be freely mixed with non-options. 414 * 415 * As an example, consider "ls foo -l". With GNU style parsing, this 416 * will list "foo" in long mode. In strict POSIX style, this will list 417 * the files named "foo" and "-l". 418 * 419 * It may be useful to force strict POSIX mode when creating "verb 420 * style" command line tools. For example, the "gsettings" command line 421 * tool supports the global option "--schemadir" as well as many 422 * subcommands ("get", "set", etc.) which each have their own set of 423 * arguments. Using strict POSIX mode will allow parsing the global 424 * options up to the verb name while leaving the remaining options to be 425 * parsed by the relevant subcommand (which can be determined by 426 * examining the verb name, which should be present in argv[1] after 427 * parsing). 428 * 429 * Params: 430 * strictPosix = the new value 431 * 432 * Since: 2.44 433 */ 434 public void setStrictPosix(bool strictPosix) 435 { 436 g_option_context_set_strict_posix(gOptionContext, strictPosix); 437 } 438 439 /** 440 * Adds a string to be displayed in `--help` output before the list 441 * of options. This is typically a summary of the program functionality. 442 * 443 * Note that the summary is translated (see 444 * g_option_context_set_translate_func() and 445 * g_option_context_set_translation_domain()). 446 * 447 * Params: 448 * summary = a string to be shown in `--help` output 449 * before the list of options, or %NULL 450 * 451 * Since: 2.12 452 */ 453 public void setSummary(string summary) 454 { 455 g_option_context_set_summary(gOptionContext, Str.toStringz(summary)); 456 } 457 458 /** 459 * Sets the function which is used to translate the contexts 460 * user-visible strings, for `--help` output. If @func is %NULL, 461 * strings are not translated. 462 * 463 * Note that option groups have their own translation functions, 464 * this function only affects the @parameter_string (see g_option_context_new()), 465 * the summary (see g_option_context_set_summary()) and the description 466 * (see g_option_context_set_description()). 467 * 468 * If you are using gettext(), you only need to set the translation 469 * domain, see g_option_context_set_translation_domain(). 470 * 471 * Params: 472 * func = the #GTranslateFunc, or %NULL 473 * data = user data to pass to @func, or %NULL 474 * destroyNotify = a function which gets called to free @data, or %NULL 475 * 476 * Since: 2.12 477 */ 478 public void setTranslateFunc(GTranslateFunc func, void* data, GDestroyNotify destroyNotify) 479 { 480 g_option_context_set_translate_func(gOptionContext, func, data, destroyNotify); 481 } 482 483 /** 484 * A convenience function to use gettext() for translating 485 * user-visible strings. 486 * 487 * Params: 488 * domain = the domain to use 489 * 490 * Since: 2.12 491 */ 492 public void setTranslationDomain(string domain) 493 { 494 g_option_context_set_translation_domain(gOptionContext, Str.toStringz(domain)); 495 } 496 497 /** 498 * Creates a new option context. 499 * 500 * The @parameter_string can serve multiple purposes. It can be used 501 * to add descriptions for "rest" arguments, which are not parsed by 502 * the #GOptionContext, typically something like "FILES" or 503 * "FILE1 FILE2...". If you are using #G_OPTION_REMAINING for 504 * collecting "rest" arguments, GLib handles this automatically by 505 * using the @arg_description of the corresponding #GOptionEntry in 506 * the usage summary. 507 * 508 * Another usage is to give a short summary of the program 509 * functionality, like " - frob the strings", which will be displayed 510 * in the same line as the usage. For a longer description of the 511 * program functionality that should be displayed as a paragraph 512 * below the usage line, use g_option_context_set_summary(). 513 * 514 * Note that the @parameter_string is translated using the 515 * function set with g_option_context_set_translate_func(), so 516 * it should normally be passed untranslated. 517 * 518 * Params: 519 * parameterString = a string which is displayed in 520 * the first line of `--help` output, after the usage summary 521 * `programname [OPTION...]` 522 * 523 * Returns: a newly created #GOptionContext, which must be 524 * freed with g_option_context_free() after use. 525 * 526 * Since: 2.6 527 * 528 * Throws: ConstructionException GTK+ fails to create the object. 529 */ 530 public this(string parameterString) 531 { 532 auto p = g_option_context_new(Str.toStringz(parameterString)); 533 534 if(p is null) 535 { 536 throw new ConstructionException("null returned by new"); 537 } 538 539 this(cast(GOptionContext*) p); 540 } 541 542 /** */ 543 public static GQuark optionErrorQuark() 544 { 545 return g_option_error_quark(); 546 } 547 }