source: appstream-generator/build/girepo/glib/OptionContext.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

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