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