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 public  import gtkc.glibtypes;
35 private import gtkd.Loader;
36 
37 
38 /**
39  * A `GOptionContext` struct defines which options
40  * are accepted by the commandline option parser. The struct has only private
41  * fields and should not be directly accessed.
42  */
43 public class OptionContext
44 {
45 	/** the main Gtk struct */
46 	protected GOptionContext* gOptionContext;
47 	protected bool ownedRef;
48 
49 	/** Get the main Gtk struct */
50 	public GOptionContext* getOptionContextStruct(bool transferOwnership = false)
51 	{
52 		if (transferOwnership)
53 			ownedRef = false;
54 		return gOptionContext;
55 	}
56 
57 	/** the main Gtk struct as a void* */
58 	protected void* getStruct()
59 	{
60 		return cast(void*)gOptionContext;
61 	}
62 
63 	/**
64 	 * Sets our main struct and passes it to the parent class.
65 	 */
66 	public this (GOptionContext* gOptionContext, bool ownedRef = false)
67 	{
68 		this.gOptionContext = gOptionContext;
69 		this.ownedRef = ownedRef;
70 	}
71 
72 	~this ()
73 	{
74 		if ( Linker.isLoaded(LIBRARY_GLIB) && ownedRef )
75 			g_option_context_free(gOptionContext);
76 	}
77 
78 
79 	/**
80 	 * Adds a #GOptionGroup to the @context, so that parsing with @context
81 	 * will recognize the options in the group. Note that this will take
82 	 * ownership of the @group and thus the @group should not be freed.
83 	 *
84 	 * Params:
85 	 *     group = the group to add
86 	 *
87 	 * Since: 2.6
88 	 */
89 	public void addGroup(OptionGroup group)
90 	{
91 		g_option_context_add_group(gOptionContext, (group is null) ? null : group.getOptionGroupStruct(true));
92 	}
93 
94 	/**
95 	 * A convenience function which creates a main group if it doesn't
96 	 * exist, adds the @entries to it and sets the translation domain.
97 	 *
98 	 * Params:
99 	 *     entries = a %NULL-terminated array of #GOptionEntrys
100 	 *     translationDomain = a translation domain to use for translating
101 	 *         the `--help` output for the options in @entries
102 	 *         with gettext(), or %NULL
103 	 *
104 	 * Since: 2.6
105 	 */
106 	public void addMainEntries(GOptionEntry* entries, string translationDomain)
107 	{
108 		g_option_context_add_main_entries(gOptionContext, entries, Str.toStringz(translationDomain));
109 	}
110 
111 	/**
112 	 * Frees context and all the groups which have been
113 	 * added to it.
114 	 *
115 	 * Please note that parsed arguments need to be freed separately (see
116 	 * #GOptionEntry).
117 	 *
118 	 * Since: 2.6
119 	 */
120 	public void free()
121 	{
122 		g_option_context_free(gOptionContext);
123 		ownedRef = false;
124 	}
125 
126 	/**
127 	 * Returns the description. See g_option_context_set_description().
128 	 *
129 	 * Returns: the description
130 	 *
131 	 * Since: 2.12
132 	 */
133 	public string getDescription()
134 	{
135 		return Str.toString(g_option_context_get_description(gOptionContext));
136 	}
137 
138 	/**
139 	 * Returns a formatted, translated help text for the given context.
140 	 * To obtain the text produced by `--help`, call
141 	 * `g_option_context_get_help (context, TRUE, NULL)`.
142 	 * To obtain the text produced by `--help-all`, call
143 	 * `g_option_context_get_help (context, FALSE, NULL)`.
144 	 * To obtain the help text for an option group, call
145 	 * `g_option_context_get_help (context, FALSE, group)`.
146 	 *
147 	 * Params:
148 	 *     mainHelp = if %TRUE, only include the main group
149 	 *     group = the #GOptionGroup to create help for, or %NULL
150 	 *
151 	 * Returns: A newly allocated string containing the help text
152 	 *
153 	 * Since: 2.14
154 	 */
155 	public string getHelp(bool mainHelp, OptionGroup group)
156 	{
157 		auto retStr = g_option_context_get_help(gOptionContext, mainHelp, (group is null) ? null : group.getOptionGroupStruct());
158 
159 		scope(exit) Str.freeString(retStr);
160 		return Str.toString(retStr);
161 	}
162 
163 	/**
164 	 * Returns whether automatic `--help` generation
165 	 * is turned on for @context. See g_option_context_set_help_enabled().
166 	 *
167 	 * Returns: %TRUE if automatic help generation is turned on.
168 	 *
169 	 * Since: 2.6
170 	 */
171 	public bool getHelpEnabled()
172 	{
173 		return g_option_context_get_help_enabled(gOptionContext) != 0;
174 	}
175 
176 	/**
177 	 * Returns whether unknown options are ignored or not. See
178 	 * g_option_context_set_ignore_unknown_options().
179 	 *
180 	 * Returns: %TRUE if unknown options are ignored.
181 	 *
182 	 * Since: 2.6
183 	 */
184 	public bool getIgnoreUnknownOptions()
185 	{
186 		return g_option_context_get_ignore_unknown_options(gOptionContext) != 0;
187 	}
188 
189 	/**
190 	 * Returns a pointer to the main group of @context.
191 	 *
192 	 * Returns: the main group of @context, or %NULL if
193 	 *     @context doesn't have a main group. Note that group belongs to
194 	 *     @context and should not be modified or freed.
195 	 *
196 	 * Since: 2.6
197 	 */
198 	public OptionGroup getMainGroup()
199 	{
200 		auto p = g_option_context_get_main_group(gOptionContext);
201 
202 		if(p is null)
203 		{
204 			return null;
205 		}
206 
207 		return new OptionGroup(cast(GOptionGroup*) p);
208 	}
209 
210 	/**
211 	 * Returns whether strict POSIX code is enabled.
212 	 *
213 	 * See g_option_context_set_strict_posix() for more information.
214 	 *
215 	 * Returns: %TRUE if strict POSIX is enabled, %FALSE otherwise.
216 	 *
217 	 * Since: 2.44
218 	 */
219 	public bool getStrictPosix()
220 	{
221 		return g_option_context_get_strict_posix(gOptionContext) != 0;
222 	}
223 
224 	/**
225 	 * Returns the summary. See g_option_context_set_summary().
226 	 *
227 	 * Returns: the summary
228 	 *
229 	 * Since: 2.12
230 	 */
231 	public string getSummary()
232 	{
233 		return Str.toString(g_option_context_get_summary(gOptionContext));
234 	}
235 
236 	/**
237 	 * Parses the command line arguments, recognizing options
238 	 * which have been added to @context. A side-effect of
239 	 * calling this function is that g_set_prgname() will be
240 	 * called.
241 	 *
242 	 * If the parsing is successful, any parsed arguments are
243 	 * removed from the array and @argc and @argv are updated
244 	 * accordingly. A '--' option is stripped from @argv
245 	 * unless there are unparsed options before and after it,
246 	 * or some of the options after it start with '-'. In case
247 	 * of an error, @argc and @argv are left unmodified.
248 	 *
249 	 * If automatic `--help` support is enabled
250 	 * (see g_option_context_set_help_enabled()), and the
251 	 * @argv array contains one of the recognized help options,
252 	 * this function will produce help output to stdout and
253 	 * call `exit (0)`.
254 	 *
255 	 * Note that function depends on the [current locale][setlocale] for
256 	 * automatic character set conversion of string and filename
257 	 * arguments.
258 	 *
259 	 * Params:
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 }