2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
5
<!ENTITY version SYSTEM "version.xml">
7
<refentry id="glib-Commandline-option-parser">
9
<refentrytitle role="top_of_page" id="glib-Commandline-option-parser.top_of_page">Commandline option parser</refentrytitle>
10
<manvolnum>3</manvolnum>
11
<refmiscinfo>GLIB Library</refmiscinfo>
15
<refname>Commandline option parser</refname>
16
<refpurpose>parses commandline options</refpurpose>
19
<refsynopsisdiv id="glib-Commandline-option-parser.synopsis" role="synopsis">
20
<title role="synopsis.title">Synopsis</title>
24
#include <glib.h>
26
enum <link linkend="GOptionError">GOptionError</link>;
27
#define <link linkend="G-OPTION-ERROR--CAPS">G_OPTION_ERROR</link>
28
<link linkend="gboolean">gboolean</link> (<link linkend="GOptionArgFunc">*GOptionArgFunc</link>) (const <link linkend="gchar">gchar</link> *option_name,
29
const <link linkend="gchar">gchar</link> *value,
30
<link linkend="gpointer">gpointer</link> data,
31
<link linkend="GError">GError</link> **error);
32
<link linkend="GOptionContext">GOptionContext</link>;
33
<link linkend="GOptionContext">GOptionContext</link> * <link linkend="g-option-context-new">g_option_context_new</link> (const <link linkend="gchar">gchar</link> *parameter_string);
34
<link linkend="void">void</link> <link linkend="g-option-context-set-summary">g_option_context_set_summary</link> (<link linkend="GOptionContext">GOptionContext</link> *context,
35
const <link linkend="gchar">gchar</link> *summary);
36
const <link linkend="gchar">gchar</link> * <link linkend="g-option-context-get-summary">g_option_context_get_summary</link> (<link linkend="GOptionContext">GOptionContext</link> *context);
37
<link linkend="void">void</link> <link linkend="g-option-context-set-description">g_option_context_set_description</link> (<link linkend="GOptionContext">GOptionContext</link> *context,
38
const <link linkend="gchar">gchar</link> *description);
39
const <link linkend="gchar">gchar</link> * <link linkend="g-option-context-get-description">g_option_context_get_description</link> (<link linkend="GOptionContext">GOptionContext</link> *context);
40
const <link linkend="gchar">gchar</link> * (<link linkend="GTranslateFunc">*GTranslateFunc</link>) (const <link linkend="gchar">gchar</link> *str,
41
<link linkend="gpointer">gpointer</link> data);
42
<link linkend="void">void</link> <link linkend="g-option-context-set-translate-func">g_option_context_set_translate_func</link> (<link linkend="GOptionContext">GOptionContext</link> *context,
43
<link linkend="GTranslateFunc">GTranslateFunc</link> func,
44
<link linkend="gpointer">gpointer</link> data,
45
<link linkend="GDestroyNotify">GDestroyNotify</link> destroy_notify);
46
<link linkend="void">void</link> <link linkend="g-option-context-set-translation-domain">g_option_context_set_translation_domain</link>
47
(<link linkend="GOptionContext">GOptionContext</link> *context,
48
const <link linkend="gchar">gchar</link> *domain);
49
<link linkend="void">void</link> <link linkend="g-option-context-free">g_option_context_free</link> (<link linkend="GOptionContext">GOptionContext</link> *context);
50
<link linkend="gboolean">gboolean</link> <link linkend="g-option-context-parse">g_option_context_parse</link> (<link linkend="GOptionContext">GOptionContext</link> *context,
51
<link linkend="gint">gint</link> *argc,
52
<link linkend="gchar">gchar</link> ***argv,
53
<link linkend="GError">GError</link> **error);
54
<link linkend="void">void</link> <link linkend="g-option-context-set-help-enabled">g_option_context_set_help_enabled</link> (<link linkend="GOptionContext">GOptionContext</link> *context,
55
<link linkend="gboolean">gboolean</link> help_enabled);
56
<link linkend="gboolean">gboolean</link> <link linkend="g-option-context-get-help-enabled">g_option_context_get_help_enabled</link> (<link linkend="GOptionContext">GOptionContext</link> *context);
57
<link linkend="void">void</link> <link linkend="g-option-context-set-ignore-unknown-options">g_option_context_set_ignore_unknown_options</link>
58
(<link linkend="GOptionContext">GOptionContext</link> *context,
59
<link linkend="gboolean">gboolean</link> ignore_unknown);
60
<link linkend="gboolean">gboolean</link> <link linkend="g-option-context-get-ignore-unknown-options">g_option_context_get_ignore_unknown_options</link>
61
(<link linkend="GOptionContext">GOptionContext</link> *context);
62
<link linkend="gchar">gchar</link> * <link linkend="g-option-context-get-help">g_option_context_get_help</link> (<link linkend="GOptionContext">GOptionContext</link> *context,
63
<link linkend="gboolean">gboolean</link> main_help,
64
<link linkend="GOptionGroup">GOptionGroup</link> *group);
65
enum <link linkend="GOptionArg">GOptionArg</link>;
66
enum <link linkend="GOptionFlags">GOptionFlags</link>;
67
#define <link linkend="G-OPTION-REMAINING--CAPS">G_OPTION_REMAINING</link>
68
<link linkend="GOptionEntry">GOptionEntry</link>;
69
<link linkend="void">void</link> <link linkend="g-option-context-add-main-entries">g_option_context_add_main_entries</link> (<link linkend="GOptionContext">GOptionContext</link> *context,
70
const <link linkend="GOptionEntry">GOptionEntry</link> *entries,
71
const <link linkend="gchar">gchar</link> *translation_domain);
72
<link linkend="GOptionGroup">GOptionGroup</link>;
73
<link linkend="void">void</link> <link linkend="g-option-context-add-group">g_option_context_add_group</link> (<link linkend="GOptionContext">GOptionContext</link> *context,
74
<link linkend="GOptionGroup">GOptionGroup</link> *group);
75
<link linkend="void">void</link> <link linkend="g-option-context-set-main-group">g_option_context_set_main_group</link> (<link linkend="GOptionContext">GOptionContext</link> *context,
76
<link linkend="GOptionGroup">GOptionGroup</link> *group);
77
<link linkend="GOptionGroup">GOptionGroup</link> * <link linkend="g-option-context-get-main-group">g_option_context_get_main_group</link> (<link linkend="GOptionContext">GOptionContext</link> *context);
78
<link linkend="GOptionGroup">GOptionGroup</link> * <link linkend="g-option-group-new">g_option_group_new</link> (const <link linkend="gchar">gchar</link> *name,
79
const <link linkend="gchar">gchar</link> *description,
80
const <link linkend="gchar">gchar</link> *help_description,
81
<link linkend="gpointer">gpointer</link> user_data,
82
<link linkend="GDestroyNotify">GDestroyNotify</link> destroy);
83
<link linkend="void">void</link> <link linkend="g-option-group-free">g_option_group_free</link> (<link linkend="GOptionGroup">GOptionGroup</link> *group);
84
<link linkend="void">void</link> <link linkend="g-option-group-add-entries">g_option_group_add_entries</link> (<link linkend="GOptionGroup">GOptionGroup</link> *group,
85
const <link linkend="GOptionEntry">GOptionEntry</link> *entries);
86
<link linkend="gboolean">gboolean</link> (<link linkend="GOptionParseFunc">*GOptionParseFunc</link>) (<link linkend="GOptionContext">GOptionContext</link> *context,
87
<link linkend="GOptionGroup">GOptionGroup</link> *group,
88
<link linkend="gpointer">gpointer</link> data,
89
<link linkend="GError">GError</link> **error);
90
<link linkend="void">void</link> <link linkend="g-option-group-set-parse-hooks">g_option_group_set_parse_hooks</link> (<link linkend="GOptionGroup">GOptionGroup</link> *group,
91
<link linkend="GOptionParseFunc">GOptionParseFunc</link> pre_parse_func,
92
<link linkend="GOptionParseFunc">GOptionParseFunc</link> post_parse_func);
93
<link linkend="void">void</link> (<link linkend="GOptionErrorFunc">*GOptionErrorFunc</link>) (<link linkend="GOptionContext">GOptionContext</link> *context,
94
<link linkend="GOptionGroup">GOptionGroup</link> *group,
95
<link linkend="gpointer">gpointer</link> data,
96
<link linkend="GError">GError</link> **error);
97
<link linkend="void">void</link> <link linkend="g-option-group-set-error-hook">g_option_group_set_error_hook</link> (<link linkend="GOptionGroup">GOptionGroup</link> *group,
98
<link linkend="GOptionErrorFunc">GOptionErrorFunc</link> error_func);
99
<link linkend="void">void</link> <link linkend="g-option-group-set-translate-func">g_option_group_set_translate_func</link> (<link linkend="GOptionGroup">GOptionGroup</link> *group,
100
<link linkend="GTranslateFunc">GTranslateFunc</link> func,
101
<link linkend="gpointer">gpointer</link> data,
102
<link linkend="GDestroyNotify">GDestroyNotify</link> destroy_notify);
103
<link linkend="void">void</link> <link linkend="g-option-group-set-translation-domain">g_option_group_set_translation_domain</link>
104
(<link linkend="GOptionGroup">GOptionGroup</link> *group,
105
const <link linkend="gchar">gchar</link> *domain);
117
<refsect1 id="glib-Commandline-option-parser.description" role="desc">
118
<title role="desc.title">Description</title>
120
The GOption commandline parser is intended to be a simpler replacement for the
121
popt library. It supports short and long commandline options, as shown in the
125
<literal>testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2</literal>
128
The example demonstrates a number of features of the GOption commandline parser
129
<itemizedlist><listitem><para>
130
Options can be single letters, prefixed by a single dash. Multiple
131
short options can be grouped behind a single dash.
132
</para></listitem><listitem><para>
133
Long options are prefixed by two consecutive dashes.
134
</para></listitem><listitem><para>
135
Options can have an extra argument, which can be a number, a string or a
136
filename. For long options, the extra argument can be appended with an
137
equals sign after the option name.
138
</para></listitem><listitem><para>
139
Non-option arguments are returned to the application as rest arguments.
140
</para></listitem><listitem><para>
141
An argument consisting solely of two dashes turns off further parsing,
142
any remaining arguments (even those starting with a dash) are returned
143
to the application as rest arguments.
144
</para></listitem></itemizedlist>
147
Another important feature of GOption is that it can automatically generate
148
nicely formatted help output. Unless it is explicitly turned off with
149
<link linkend="g-option-context-set-help-enabled"><function>g_option_context_set_help_enabled()</function></link>, GOption will recognize the
150
<option>--help</option>, <option>-?</option>, <option>--help-all</option>
151
and <option>--help-</option><replaceable>groupname</replaceable> options
152
(where <replaceable>groupname</replaceable> is the name of a <link linkend="GOptionGroup"><type>GOptionGroup</type></link>)
153
and write a text similar to the one shown in the following example to stdout.
156
<informalexample><screen>
158
testtreemodel [OPTION...] - test tree model performance
161
-h, --help Show help options
162
--help-all Show all help options
163
--help-gtk Show GTK+ Options
166
-r, --repeats=N Average over N repetitions
167
-m, --max-size=M Test up to 2^M items
168
--display=DISPLAY X display to use
169
-v, --verbose Be verbose
170
-b, --beep Beep when done
171
--rand Randomize the data
172
</screen></informalexample>
175
GOption groups options in <link linkend="GOptionGroup"><type>GOptionGroup</type></link><!-- -->s, which makes it easy to
176
incorporate options from multiple sources. The intended use for this is
177
to let applications collect option groups from the libraries it uses,
178
add them to their <link linkend="GOptionContext"><type>GOptionContext</type></link>, and parse all options by a single call
179
to <link linkend="g-option-context-parse"><function>g_option_context_parse()</function></link>. See <link linkend="gtk-get-option-group"><function>gtk_get_option_group()</function></link> for an example.
182
If an option is declared to be of type string or filename, GOption takes
183
care of converting it to the right encoding; strings are returned in UTF-8,
184
filenames are returned in the GLib filename encoding. Note that this only
185
works if <link linkend="setlocale"><function>setlocale()</function></link> has been called before <link linkend="g-option-context-parse"><function>g_option_context_parse()</function></link>.
188
Here is a complete example of setting up GOption to parse the example
189
commandline above and produce the example help output.
192
<informalexample><programlisting>
193
static gint repeats = 2;
194
static gint max_size = 8;
195
static gboolean verbose = FALSE;
196
static gboolean beep = FALSE;
197
static gboolean rand = FALSE;
199
static GOptionEntry entries[] =
201
{ "repeats", 'r', 0, G_OPTION_ARG_INT, &repeats, "Average over N repetitions", "N" },
202
{ "max-size", 'm', 0, G_OPTION_ARG_INT, &max_size, "Test up to 2^M items", "M" },
203
{ "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL },
204
{ "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep when done", NULL },
205
{ "rand", 0, 0, G_OPTION_ARG_NONE, &rand, "Randomize the data", NULL },
210
main (int argc, char *argv[])
212
GError *error = NULL;
213
GOptionContext *context;
215
context = g_option_context_new ("- test tree model performance");
216
g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE);
217
g_option_context_add_group (context, gtk_get_option_group (TRUE));
218
if (!g_option_context_parse (context, &argc, &argv, &error))
220
g_print ("option parsing failed: %s\n", error->message);
227
</programlisting></informalexample></para>
232
<refsect1 id="glib-Commandline-option-parser.details" role="details">
233
<title role="details.title">Details</title>
234
<refsect2 id="GOptionError" role="enum">
235
<title>enum GOptionError</title>
236
<indexterm zone="GOptionError"><primary sortas="OptionError">GOptionError</primary></indexterm><programlisting>typedef enum
238
G_OPTION_ERROR_UNKNOWN_OPTION,
239
G_OPTION_ERROR_BAD_VALUE,
240
G_OPTION_ERROR_FAILED
244
Error codes returned by option parsing.</para>
246
</para><variablelist role="enum">
247
<varlistentry id="G-OPTION-ERROR-UNKNOWN-OPTION--CAPS" role="constant">
248
<term><literal>G_OPTION_ERROR_UNKNOWN_OPTION</literal></term>
249
<listitem><simpara> An option was not known to the parser.
250
This error will only be reported, if the parser hasn't been instructed
251
to ignore unknown options, see <link linkend="g-option-context-set-ignore-unknown-options"><function>g_option_context_set_ignore_unknown_options()</function></link>.
252
</simpara></listitem>
254
<varlistentry id="G-OPTION-ERROR-BAD-VALUE--CAPS" role="constant">
255
<term><literal>G_OPTION_ERROR_BAD_VALUE</literal></term>
256
<listitem><simpara> A value couldn't be parsed.
257
</simpara></listitem>
259
<varlistentry id="G-OPTION-ERROR-FAILED--CAPS" role="constant">
260
<term><literal>G_OPTION_ERROR_FAILED</literal></term>
261
<listitem><simpara> A <link linkend="GOptionArgFunc"><type>GOptionArgFunc</type></link> callback failed.
262
</simpara></listitem>
264
</variablelist></refsect2>
265
<refsect2 id="G-OPTION-ERROR--CAPS" role="macro">
266
<title>G_OPTION_ERROR</title>
267
<indexterm zone="G-OPTION-ERROR--CAPS"><primary sortas="OPTION_ERROR">G_OPTION_ERROR</primary></indexterm><programlisting>#define G_OPTION_ERROR (g_option_error_quark ())
270
Error domain for option parsing. Errors in this domain will
271
be from the <link linkend="GOptionError"><type>GOptionError</type></link> enumeration. See <link linkend="GError"><type>GError</type></link> for information on
272
error domains.</para>
275
<refsect2 id="GOptionArgFunc" role="function">
276
<title>GOptionArgFunc ()</title>
277
<indexterm zone="GOptionArgFunc"><primary sortas="OptionArgFunc">GOptionArgFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> (*GOptionArgFunc) (const <link linkend="gchar">gchar</link> *option_name,
278
const <link linkend="gchar">gchar</link> *value,
279
<link linkend="gpointer">gpointer</link> data,
280
<link linkend="GError">GError</link> **error);</programlisting>
282
The type of function to be passed as callback for <link linkend="G-OPTION-ARG-CALLBACK--CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link>
285
</para><variablelist role="params">
286
<varlistentry><term><parameter>option_name</parameter> :</term>
287
<listitem><simpara> The name of the option being parsed. This will be either a
288
single dash followed by a single letter (for a short name) or two dashes
289
followed by a long option name.
290
</simpara></listitem></varlistentry>
291
<varlistentry><term><parameter>value</parameter> :</term>
292
<listitem><simpara> The value to be parsed.
293
</simpara></listitem></varlistentry>
294
<varlistentry><term><parameter>data</parameter> :</term>
295
<listitem><simpara> User data added to the <link linkend="GOptionGroup"><type>GOptionGroup</type></link> containing the option when it
296
was created with <link linkend="g-option-group-new"><function>g_option_group_new()</function></link>
297
</simpara></listitem></varlistentry>
298
<varlistentry><term><parameter>error</parameter> :</term>
299
<listitem><simpara> A return location for errors. The error code <link linkend="G-OPTION-ERROR-FAILED--CAPS"><literal>G_OPTION_ERROR_FAILED</literal></link>
300
is intended to be used for errors in <link linkend="GOptionArgFunc"><type>GOptionArgFunc</type></link> callbacks.
301
</simpara></listitem></varlistentry>
302
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the option was successfully parsed, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if an error
303
occurred, in which case <parameter>error</parameter> should be set with <link linkend="g-set-error"><function>g_set_error()</function></link>
304
</simpara></listitem></varlistentry>
305
</variablelist></refsect2>
306
<refsect2 id="GOptionContext" role="struct">
307
<title>GOptionContext</title>
308
<indexterm zone="GOptionContext"><primary sortas="OptionContext">GOptionContext</primary></indexterm><programlisting>typedef struct _GOptionContext GOptionContext;</programlisting>
310
A <structname>GOptionContext</structname> struct defines which options
311
are accepted by the commandline option parser. The struct has only private
312
fields and should not be directly accessed.</para>
315
<refsect2 id="g-option-context-new" role="function" condition="since:2.6">
316
<title>g_option_context_new ()</title>
317
<indexterm zone="g-option-context-new" role="2.6"><primary sortas="option_context_new">g_option_context_new</primary></indexterm><programlisting><link linkend="GOptionContext">GOptionContext</link> * g_option_context_new (const <link linkend="gchar">gchar</link> *parameter_string);</programlisting>
319
Creates a new option context.
322
The <parameter>parameter_string</parameter> can serve multiple purposes. It can be used
323
to add descriptions for "rest" arguments, which are not parsed by
324
the <link linkend="GOptionContext"><type>GOptionContext</type></link>, typically something like "FILES" or
325
"FILE1 FILE2...". If you are using <link linkend="G-OPTION-REMAINING--CAPS"><type>G_OPTION_REMAINING</type></link> for
326
collecting "rest" arguments, GLib handles this automatically by
327
using the <parameter>arg_description</parameter> of the corresponding <link linkend="GOptionEntry"><type>GOptionEntry</type></link> in
331
Another usage is to give a short summary of the program
332
functionality, like " - frob the strings", which will be displayed
333
in the same line as the usage. For a longer description of the
334
program functionality that should be displayed as a paragraph
335
below the usage line, use <link linkend="g-option-context-set-summary"><function>g_option_context_set_summary()</function></link>.
338
Note that the <parameter>parameter_string</parameter> is translated using the
339
function set with <link linkend="g-option-context-set-translate-func"><function>g_option_context_set_translate_func()</function></link>, so
340
it should normally be passed untranslated.</para>
342
</para><variablelist role="params">
343
<varlistentry><term><parameter>parameter_string</parameter> :</term>
344
<listitem><simpara> a string which is displayed in
345
the first line of <option>--help</option> output, after the
347
<literal><replaceable>programname</replaceable> [OPTION...]</literal>
348
</simpara></listitem></varlistentry>
349
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly created <link linkend="GOptionContext"><type>GOptionContext</type></link>, which must be
350
freed with <link linkend="g-option-context-free"><function>g_option_context_free()</function></link> after use.
352
</simpara></listitem></varlistentry>
353
</variablelist><para role="since">Since 2.6</para></refsect2>
354
<refsect2 id="g-option-context-set-summary" role="function" condition="since:2.12">
355
<title>g_option_context_set_summary ()</title>
356
<indexterm zone="g-option-context-set-summary" role="2.12"><primary sortas="option_context_set_summary">g_option_context_set_summary</primary></indexterm><programlisting><link linkend="void">void</link> g_option_context_set_summary (<link linkend="GOptionContext">GOptionContext</link> *context,
357
const <link linkend="gchar">gchar</link> *summary);</programlisting>
359
Adds a string to be displayed in <option>--help</option> output
360
before the list of options. This is typically a summary of the
361
program functionality.
364
Note that the summary is translated (see
365
<link linkend="g-option-context-set-translate-func"><function>g_option_context_set_translate_func()</function></link> and
366
<link linkend="g-option-context-set-translation-domain"><function>g_option_context_set_translation_domain()</function></link>).</para>
368
</para><variablelist role="params">
369
<varlistentry><term><parameter>context</parameter> :</term>
370
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
371
</simpara></listitem></varlistentry>
372
<varlistentry><term><parameter>summary</parameter> :</term>
373
<listitem><simpara> a string to be shown in <option>--help</option> output
374
before the list of options, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
375
</simpara></listitem></varlistentry>
376
</variablelist><para role="since">Since 2.12</para></refsect2>
377
<refsect2 id="g-option-context-get-summary" role="function" condition="since:2.12">
378
<title>g_option_context_get_summary ()</title>
379
<indexterm zone="g-option-context-get-summary" role="2.12"><primary sortas="option_context_get_summary">g_option_context_get_summary</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> * g_option_context_get_summary (<link linkend="GOptionContext">GOptionContext</link> *context);</programlisting>
381
Returns the summary. See <link linkend="g-option-context-set-summary"><function>g_option_context_set_summary()</function></link>.</para>
383
</para><variablelist role="params">
384
<varlistentry><term><parameter>context</parameter> :</term>
385
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
386
</simpara></listitem></varlistentry>
387
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the summary
389
</simpara></listitem></varlistentry>
390
</variablelist><para role="since">Since 2.12</para></refsect2>
391
<refsect2 id="g-option-context-set-description" role="function" condition="since:2.12">
392
<title>g_option_context_set_description ()</title>
393
<indexterm zone="g-option-context-set-description" role="2.12"><primary sortas="option_context_set_description">g_option_context_set_description</primary></indexterm><programlisting><link linkend="void">void</link> g_option_context_set_description (<link linkend="GOptionContext">GOptionContext</link> *context,
394
const <link linkend="gchar">gchar</link> *description);</programlisting>
396
Adds a string to be displayed in <option>--help</option> output
397
after the list of options. This text often includes a bug reporting
401
Note that the summary is translated (see
402
<link linkend="g-option-context-set-translate-func"><function>g_option_context_set_translate_func()</function></link>).</para>
404
</para><variablelist role="params">
405
<varlistentry><term><parameter>context</parameter> :</term>
406
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
407
</simpara></listitem></varlistentry>
408
<varlistentry><term><parameter>description</parameter> :</term>
409
<listitem><simpara> a string to be shown in <option>--help</option> output
410
after the list of options, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
411
</simpara></listitem></varlistentry>
412
</variablelist><para role="since">Since 2.12</para></refsect2>
413
<refsect2 id="g-option-context-get-description" role="function" condition="since:2.12">
414
<title>g_option_context_get_description ()</title>
415
<indexterm zone="g-option-context-get-description" role="2.12"><primary sortas="option_context_get_description">g_option_context_get_description</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> * g_option_context_get_description (<link linkend="GOptionContext">GOptionContext</link> *context);</programlisting>
417
Returns the description. See <link linkend="g-option-context-set-description"><function>g_option_context_set_description()</function></link>.</para>
419
</para><variablelist role="params">
420
<varlistentry><term><parameter>context</parameter> :</term>
421
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
422
</simpara></listitem></varlistentry>
423
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the description
425
</simpara></listitem></varlistentry>
426
</variablelist><para role="since">Since 2.12</para></refsect2>
427
<refsect2 id="GTranslateFunc" role="function">
428
<title>GTranslateFunc ()</title>
429
<indexterm zone="GTranslateFunc"><primary sortas="TranslateFunc">GTranslateFunc</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> * (*GTranslateFunc) (const <link linkend="gchar">gchar</link> *str,
430
<link linkend="gpointer">gpointer</link> data);</programlisting>
432
The type of functions which are used to translate user-visible
433
strings, for <option>--help</option> output.</para>
435
</para><variablelist role="params">
436
<varlistentry><term><parameter>str</parameter> :</term>
437
<listitem><simpara> the untranslated string
438
</simpara></listitem></varlistentry>
439
<varlistentry><term><parameter>data</parameter> :</term>
440
<listitem><simpara> user data specified when installing the function, e.g.
441
in <link linkend="g-option-group-set-translate-func"><function>g_option_group_set_translate_func()</function></link>
442
</simpara></listitem></varlistentry>
443
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a translation of the string for the current locale.
444
The returned string is owned by GLib and must not be freed.
445
</simpara></listitem></varlistentry>
446
</variablelist></refsect2>
447
<refsect2 id="g-option-context-set-translate-func" role="function" condition="since:2.12">
448
<title>g_option_context_set_translate_func ()</title>
449
<indexterm zone="g-option-context-set-translate-func" role="2.12"><primary sortas="option_context_set_translate_func">g_option_context_set_translate_func</primary></indexterm><programlisting><link linkend="void">void</link> g_option_context_set_translate_func (<link linkend="GOptionContext">GOptionContext</link> *context,
450
<link linkend="GTranslateFunc">GTranslateFunc</link> func,
451
<link linkend="gpointer">gpointer</link> data,
452
<link linkend="GDestroyNotify">GDestroyNotify</link> destroy_notify);</programlisting>
454
Sets the function which is used to translate the contexts
455
user-visible strings, for <option>--help</option> output.
456
If <parameter>func</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link>, strings are not translated.
459
Note that option groups have their own translation functions,
460
this function only affects the <parameter>parameter_string</parameter> (see <link linkend="g-option-context-new"><function>g_option_context_new()</function></link>),
461
the summary (see <link linkend="g-option-context-set-summary"><function>g_option_context_set_summary()</function></link>) and the description
462
(see <link linkend="g-option-context-set-description"><function>g_option_context_set_description()</function></link>).
465
If you are using <link linkend="gettext"><function>gettext()</function></link>, you only need to set the translation
466
domain, see <link linkend="g-option-context-set-translation-domain"><function>g_option_context_set_translation_domain()</function></link>.</para>
468
</para><variablelist role="params">
469
<varlistentry><term><parameter>context</parameter> :</term>
470
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
471
</simpara></listitem></varlistentry>
472
<varlistentry><term><parameter>func</parameter> :</term>
473
<listitem><simpara> the <link linkend="GTranslateFunc"><type>GTranslateFunc</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
474
</simpara></listitem></varlistentry>
475
<varlistentry><term><parameter>data</parameter> :</term>
476
<listitem><simpara> user data to pass to <parameter>func</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
477
</simpara></listitem></varlistentry>
478
<varlistentry><term><parameter>destroy_notify</parameter> :</term>
479
<listitem><simpara> a function which gets called to free <parameter>data</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
480
</simpara></listitem></varlistentry>
481
</variablelist><para role="since">Since 2.12</para></refsect2>
482
<refsect2 id="g-option-context-set-translation-domain" role="function" condition="since:2.12">
483
<title>g_option_context_set_translation_domain ()</title>
484
<indexterm zone="g-option-context-set-translation-domain" role="2.12"><primary sortas="option_context_set_translation_domain">g_option_context_set_translation_domain</primary></indexterm><programlisting><link linkend="void">void</link> g_option_context_set_translation_domain
485
(<link linkend="GOptionContext">GOptionContext</link> *context,
486
const <link linkend="gchar">gchar</link> *domain);</programlisting>
488
A convenience function to use <link linkend="gettext"><function>gettext()</function></link> for translating
489
user-visible strings.</para>
491
</para><variablelist role="params">
492
<varlistentry><term><parameter>context</parameter> :</term>
493
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
494
</simpara></listitem></varlistentry>
495
<varlistentry><term><parameter>domain</parameter> :</term>
496
<listitem><simpara> the domain to use
497
</simpara></listitem></varlistentry>
498
</variablelist><para role="since">Since 2.12</para></refsect2>
499
<refsect2 id="g-option-context-free" role="function" condition="since:2.6">
500
<title>g_option_context_free ()</title>
501
<indexterm zone="g-option-context-free" role="2.6"><primary sortas="option_context_free">g_option_context_free</primary></indexterm><programlisting><link linkend="void">void</link> g_option_context_free (<link linkend="GOptionContext">GOptionContext</link> *context);</programlisting>
503
Frees context and all the groups which have been
507
Please note that parsed arguments need to be freed separately (see
508
<link linkend="GOptionEntry"><type>GOptionEntry</type></link>).</para>
510
</para><variablelist role="params">
511
<varlistentry><term><parameter>context</parameter> :</term>
512
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
513
</simpara></listitem></varlistentry>
514
</variablelist><para role="since">Since 2.6</para></refsect2>
515
<refsect2 id="g-option-context-parse" role="function" condition="since:2.6">
516
<title>g_option_context_parse ()</title>
517
<indexterm zone="g-option-context-parse" role="2.6"><primary sortas="option_context_parse">g_option_context_parse</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_option_context_parse (<link linkend="GOptionContext">GOptionContext</link> *context,
518
<link linkend="gint">gint</link> *argc,
519
<link linkend="gchar">gchar</link> ***argv,
520
<link linkend="GError">GError</link> **error);</programlisting>
522
Parses the command line arguments, recognizing options
523
which have been added to <parameter>context</parameter>. A side-effect of
524
calling this function is that <link linkend="g-set-prgname"><function>g_set_prgname()</function></link> will be
528
If the parsing is successful, any parsed arguments are
529
removed from the array and <parameter>argc</parameter> and <parameter>argv</parameter> are updated
530
accordingly. A '--' option is stripped from <parameter>argv</parameter>
531
unless there are unparsed options before and after it,
532
or some of the options after it start with '-'. In case
533
of an error, <parameter>argc</parameter> and <parameter>argv</parameter> are left unmodified.
536
If automatic <option>--help</option> support is enabled
537
(see <link linkend="g-option-context-set-help-enabled"><function>g_option_context_set_help_enabled()</function></link>), and the
538
<parameter>argv</parameter> array contains one of the recognized help options,
539
this function will produce help output to stdout and
540
call <literal>exit (0)</literal>.
543
Note that function depends on the
544
<link linkend="setlocale">current locale</link> for
545
automatic character set conversion of string and filename
548
</para><variablelist role="params">
549
<varlistentry><term><parameter>context</parameter> :</term>
550
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
551
</simpara></listitem></varlistentry>
552
<varlistentry><term><parameter>argc</parameter> :</term>
553
<listitem><simpara> a pointer to the number of command line arguments
554
</simpara></listitem></varlistentry>
555
<varlistentry><term><parameter>argv</parameter> :</term>
556
<listitem><simpara> a pointer to the array of command line arguments
557
</simpara></listitem></varlistentry>
558
<varlistentry><term><parameter>error</parameter> :</term>
559
<listitem><simpara> a return location for errors
560
</simpara></listitem></varlistentry>
561
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the parsing was successful,
562
<link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if an error occurred
564
</simpara></listitem></varlistentry>
565
</variablelist><para role="since">Since 2.6</para></refsect2>
566
<refsect2 id="g-option-context-set-help-enabled" role="function" condition="since:2.6">
567
<title>g_option_context_set_help_enabled ()</title>
568
<indexterm zone="g-option-context-set-help-enabled" role="2.6"><primary sortas="option_context_set_help_enabled">g_option_context_set_help_enabled</primary></indexterm><programlisting><link linkend="void">void</link> g_option_context_set_help_enabled (<link linkend="GOptionContext">GOptionContext</link> *context,
569
<link linkend="gboolean">gboolean</link> help_enabled);</programlisting>
571
Enables or disables automatic generation of <option>--help</option>
572
output. By default, <link linkend="g-option-context-parse"><function>g_option_context_parse()</function></link> recognizes
573
<option>--help</option>, <option>-h</option>,
574
<option>-?</option>, <option>--help-all</option>
575
and <option>--help-</option><replaceable>groupname</replaceable> and creates
576
suitable output to stdout.</para>
578
</para><variablelist role="params">
579
<varlistentry><term><parameter>context</parameter> :</term>
580
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
581
</simpara></listitem></varlistentry>
582
<varlistentry><term><parameter>help_enabled</parameter> :</term>
583
<listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> to enable <option>--help</option>, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> to disable it
584
</simpara></listitem></varlistentry>
585
</variablelist><para role="since">Since 2.6</para></refsect2>
586
<refsect2 id="g-option-context-get-help-enabled" role="function" condition="since:2.6">
587
<title>g_option_context_get_help_enabled ()</title>
588
<indexterm zone="g-option-context-get-help-enabled" role="2.6"><primary sortas="option_context_get_help_enabled">g_option_context_get_help_enabled</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_option_context_get_help_enabled (<link linkend="GOptionContext">GOptionContext</link> *context);</programlisting>
590
Returns whether automatic <option>--help</option> generation
591
is turned on for <parameter>context</parameter>. See <link linkend="g-option-context-set-help-enabled"><function>g_option_context_set_help_enabled()</function></link>.</para>
593
</para><variablelist role="params">
594
<varlistentry><term><parameter>context</parameter> :</term>
595
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
596
</simpara></listitem></varlistentry>
597
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if automatic help generation is turned on.
599
</simpara></listitem></varlistentry>
600
</variablelist><para role="since">Since 2.6</para></refsect2>
601
<refsect2 id="g-option-context-set-ignore-unknown-options" role="function" condition="since:2.6">
602
<title>g_option_context_set_ignore_unknown_options ()</title>
603
<indexterm zone="g-option-context-set-ignore-unknown-options" role="2.6"><primary sortas="option_context_set_ignore_unknown_options">g_option_context_set_ignore_unknown_options</primary></indexterm><programlisting><link linkend="void">void</link> g_option_context_set_ignore_unknown_options
604
(<link linkend="GOptionContext">GOptionContext</link> *context,
605
<link linkend="gboolean">gboolean</link> ignore_unknown);</programlisting>
607
Sets whether to ignore unknown options or not. If an argument is
608
ignored, it is left in the <parameter>argv</parameter> array after parsing. By default,
609
<link linkend="g-option-context-parse"><function>g_option_context_parse()</function></link> treats unknown options as error.
612
This setting does not affect non-option arguments (i.e. arguments
613
which don't start with a dash). But note that GOption cannot reliably
614
determine whether a non-option belongs to a preceding unknown option.</para>
616
</para><variablelist role="params">
617
<varlistentry><term><parameter>context</parameter> :</term>
618
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
619
</simpara></listitem></varlistentry>
620
<varlistentry><term><parameter>ignore_unknown</parameter> :</term>
621
<listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> to ignore unknown options, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> to produce
622
an error when unknown options are met
623
</simpara></listitem></varlistentry>
624
</variablelist><para role="since">Since 2.6</para></refsect2>
625
<refsect2 id="g-option-context-get-ignore-unknown-options" role="function" condition="since:2.6">
626
<title>g_option_context_get_ignore_unknown_options ()</title>
627
<indexterm zone="g-option-context-get-ignore-unknown-options" role="2.6"><primary sortas="option_context_get_ignore_unknown_options">g_option_context_get_ignore_unknown_options</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_option_context_get_ignore_unknown_options
628
(<link linkend="GOptionContext">GOptionContext</link> *context);</programlisting>
630
Returns whether unknown options are ignored or not. See
631
<link linkend="g-option-context-set-ignore-unknown-options"><function>g_option_context_set_ignore_unknown_options()</function></link>.</para>
633
</para><variablelist role="params">
634
<varlistentry><term><parameter>context</parameter> :</term>
635
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
636
</simpara></listitem></varlistentry>
637
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if unknown options are ignored.
639
</simpara></listitem></varlistentry>
640
</variablelist><para role="since">Since 2.6</para></refsect2>
641
<refsect2 id="g-option-context-get-help" role="function" condition="since:2.14">
642
<title>g_option_context_get_help ()</title>
643
<indexterm zone="g-option-context-get-help" role="2.14"><primary sortas="option_context_get_help">g_option_context_get_help</primary></indexterm><programlisting><link linkend="gchar">gchar</link> * g_option_context_get_help (<link linkend="GOptionContext">GOptionContext</link> *context,
644
<link linkend="gboolean">gboolean</link> main_help,
645
<link linkend="GOptionGroup">GOptionGroup</link> *group);</programlisting>
647
Returns a formatted, translated help text for the given context.
648
To obtain the text produced by <option>--help</option>, call
649
<literal>g_option_context_get_help (context, TRUE, NULL)</literal>.
650
To obtain the text produced by <option>--help-all</option>, call
651
<literal>g_option_context_get_help (context, FALSE, NULL)</literal>.
652
To obtain the help text for an option group, call
653
<literal>g_option_context_get_help (context, FALSE, group)</literal>.</para>
655
</para><variablelist role="params">
656
<varlistentry><term><parameter>context</parameter> :</term>
657
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
658
</simpara></listitem></varlistentry>
659
<varlistentry><term><parameter>main_help</parameter> :</term>
660
<listitem><simpara> if <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, only include the main group
661
</simpara></listitem></varlistentry>
662
<varlistentry><term><parameter>group</parameter> :</term>
663
<listitem><simpara> the <link linkend="GOptionGroup"><type>GOptionGroup</type></link> to create help for, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
664
</simpara></listitem></varlistentry>
665
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A newly allocated string containing the help text
667
</simpara></listitem></varlistentry>
668
</variablelist><para role="since">Since 2.14</para></refsect2>
669
<refsect2 id="GOptionArg" role="enum">
670
<title>enum GOptionArg</title>
671
<indexterm zone="GOptionArg"><primary sortas="OptionArg">GOptionArg</primary></indexterm><programlisting>typedef enum
676
G_OPTION_ARG_CALLBACK,
677
G_OPTION_ARG_FILENAME,
678
G_OPTION_ARG_STRING_ARRAY,
679
G_OPTION_ARG_FILENAME_ARRAY,
685
The <link linkend="GOptionArg"><type>GOptionArg</type></link> enum values determine which type of extra argument the
686
options expect to find. If an option expects an extra argument, it
687
can be specified in several ways; with a short option:
688
<option>-x arg</option>, with a long option: <option>--name arg</option>
689
or combined in a single argument: <option>--name=arg</option>.</para>
691
</para><variablelist role="enum">
692
<varlistentry id="G-OPTION-ARG-NONE--CAPS" role="constant">
693
<term><literal>G_OPTION_ARG_NONE</literal></term>
694
<listitem><simpara> No extra argument. This is useful for simple flags.
695
</simpara></listitem>
697
<varlistentry id="G-OPTION-ARG-STRING--CAPS" role="constant">
698
<term><literal>G_OPTION_ARG_STRING</literal></term>
699
<listitem><simpara> The option takes a string argument.
700
</simpara></listitem>
702
<varlistentry id="G-OPTION-ARG-INT--CAPS" role="constant">
703
<term><literal>G_OPTION_ARG_INT</literal></term>
704
<listitem><simpara> The option takes an integer argument.
705
</simpara></listitem>
707
<varlistentry id="G-OPTION-ARG-CALLBACK--CAPS" role="constant">
708
<term><literal>G_OPTION_ARG_CALLBACK</literal></term>
709
<listitem><simpara> The option provides a callback to parse the
711
</simpara></listitem>
713
<varlistentry id="G-OPTION-ARG-FILENAME--CAPS" role="constant">
714
<term><literal>G_OPTION_ARG_FILENAME</literal></term>
715
<listitem><simpara> The option takes a filename as argument.
716
</simpara></listitem>
718
<varlistentry id="G-OPTION-ARG-STRING-ARRAY--CAPS" role="constant">
719
<term><literal>G_OPTION_ARG_STRING_ARRAY</literal></term>
720
<listitem><simpara> The option takes a string argument, multiple
721
uses of the option are collected into an array of strings.
722
</simpara></listitem>
724
<varlistentry id="G-OPTION-ARG-FILENAME-ARRAY--CAPS" role="constant">
725
<term><literal>G_OPTION_ARG_FILENAME_ARRAY</literal></term>
726
<listitem><simpara> The option takes a filename as argument,
727
multiple uses of the option are collected into an array of strings.
728
</simpara></listitem>
730
<varlistentry id="G-OPTION-ARG-DOUBLE--CAPS" role="constant">
731
<term><literal>G_OPTION_ARG_DOUBLE</literal></term>
732
<listitem><simpara> The option takes a double argument. The argument
733
can be formatted either for the user's locale or for the "C" locale. Since 2.12
734
</simpara></listitem>
736
<varlistentry id="G-OPTION-ARG-INT64--CAPS" role="constant">
737
<term><literal>G_OPTION_ARG_INT64</literal></term>
738
<listitem><simpara> The option takes a 64-bit integer. Like <link linkend="G-OPTION-ARG-INT--CAPS"><literal>G_OPTION_ARG_INT</literal></link>
739
but for larger numbers. The number can be in decimal base, or in hexadecimal
740
(when prefixed with <literal>0x</literal>, for example, <literal>0xffffffff</literal>).
742
</simpara></listitem>
744
</variablelist></refsect2>
745
<refsect2 id="GOptionFlags" role="enum">
746
<title>enum GOptionFlags</title>
747
<indexterm zone="GOptionFlags"><primary sortas="OptionFlags">GOptionFlags</primary></indexterm><programlisting>typedef enum
749
G_OPTION_FLAG_HIDDEN = 1 << 0,
750
G_OPTION_FLAG_IN_MAIN = 1 << 1,
751
G_OPTION_FLAG_REVERSE = 1 << 2,
752
G_OPTION_FLAG_NO_ARG = 1 << 3,
753
G_OPTION_FLAG_FILENAME = 1 << 4,
754
G_OPTION_FLAG_OPTIONAL_ARG = 1 << 5,
755
G_OPTION_FLAG_NOALIAS = 1 << 6
759
Flags which modify individual options.</para>
761
</para><variablelist role="enum">
762
<varlistentry id="G-OPTION-FLAG-HIDDEN--CAPS" role="constant">
763
<term><literal>G_OPTION_FLAG_HIDDEN</literal></term>
764
<listitem><simpara> The option doesn't appear in <option>--help</option>
766
</simpara></listitem>
768
<varlistentry id="G-OPTION-FLAG-IN-MAIN--CAPS" role="constant">
769
<term><literal>G_OPTION_FLAG_IN_MAIN</literal></term>
770
<listitem><simpara> The option appears in the main section of the
771
<option>--help</option> output, even if it is defined in a group.
772
</simpara></listitem>
774
<varlistentry id="G-OPTION-FLAG-REVERSE--CAPS" role="constant">
775
<term><literal>G_OPTION_FLAG_REVERSE</literal></term>
776
<listitem><simpara> For options of the <link linkend="G-OPTION-ARG-NONE--CAPS"><literal>G_OPTION_ARG_NONE</literal></link> kind, this flag
777
indicates that the sense of the option is reversed.
778
</simpara></listitem>
780
<varlistentry id="G-OPTION-FLAG-NO-ARG--CAPS" role="constant">
781
<term><literal>G_OPTION_FLAG_NO_ARG</literal></term>
782
<listitem><simpara> For options of the <link linkend="G-OPTION-ARG-CALLBACK--CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link> kind,
783
this flag indicates that the callback does not take any argument
784
(like a <link linkend="G-OPTION-ARG-NONE--CAPS"><literal>G_OPTION_ARG_NONE</literal></link> option). Since 2.8
785
</simpara></listitem>
787
<varlistentry id="G-OPTION-FLAG-FILENAME--CAPS" role="constant">
788
<term><literal>G_OPTION_FLAG_FILENAME</literal></term>
789
<listitem><simpara> For options of the <link linkend="G-OPTION-ARG-CALLBACK--CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link>
790
kind, this flag indicates that the argument should be passed to the
791
callback in the GLib filename encoding rather than UTF-8. Since 2.8
792
</simpara></listitem>
794
<varlistentry id="G-OPTION-FLAG-OPTIONAL-ARG--CAPS" role="constant">
795
<term><literal>G_OPTION_FLAG_OPTIONAL_ARG</literal></term>
796
<listitem><simpara> For options of the <link linkend="G-OPTION-ARG-CALLBACK--CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link>
797
kind, this flag indicates that the argument supply is optional. If no argument
798
is given then data of <link linkend="GOptionParseFunc"><literal>GOptionParseFunc</literal></link> will be set to NULL. Since 2.8
799
</simpara></listitem>
801
<varlistentry id="G-OPTION-FLAG-NOALIAS--CAPS" role="constant">
802
<term><literal>G_OPTION_FLAG_NOALIAS</literal></term>
803
<listitem><simpara> This flag turns off the automatic conflict resolution
804
which prefixes long option names with <literal>groupname-</literal> if
805
there is a conflict. This option should only be used in situations where
806
aliasing is necessary to model some legacy commandline interface. It is
807
not safe to use this option, unless all option groups are under your
808
direct control. Since 2.8.
809
</simpara></listitem>
811
</variablelist></refsect2>
812
<refsect2 id="G-OPTION-REMAINING--CAPS" role="macro" condition="since:2.6">
813
<title>G_OPTION_REMAINING</title>
814
<indexterm zone="G-OPTION-REMAINING--CAPS" role="2.6"><primary sortas="OPTION_REMAINING">G_OPTION_REMAINING</primary></indexterm><programlisting>#define G_OPTION_REMAINING ""
817
If a long option in the main group has this name, it is not treated as a
818
regular option. Instead it collects all non-option arguments which would
819
otherwise be left in <literal>argv</literal>. The option must be of type
820
<link linkend="G-OPTION-ARG-CALLBACK--CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link>, <link linkend="G-OPTION-ARG-STRING-ARRAY--CAPS"><literal>G_OPTION_ARG_STRING_ARRAY</literal></link>
821
or <link linkend="G-OPTION-ARG-FILENAME-ARRAY--CAPS"><literal>G_OPTION_ARG_FILENAME_ARRAY</literal></link>.
824
Using <link linkend="G-OPTION-REMAINING--CAPS"><type>G_OPTION_REMAINING</type></link> instead of simply scanning <literal>argv</literal>
825
for leftover arguments has the advantage that GOption takes care of
826
necessary encoding conversions for strings or filenames.</para>
828
</para><para role="since">Since 2.6</para></refsect2>
829
<refsect2 id="GOptionEntry" role="struct">
830
<title>GOptionEntry</title>
831
<indexterm zone="GOptionEntry"><primary sortas="OptionEntry">GOptionEntry</primary></indexterm><programlisting>typedef struct {
832
const gchar *long_name;
839
const gchar *description;
840
const gchar *arg_description;
844
A <structname>GOptionEntry</structname> defines a single option.
845
To have an effect, they must be added to a <link linkend="GOptionGroup"><type>GOptionGroup</type></link> with
846
<link linkend="g-option-context-add-main-entries"><function>g_option_context_add_main_entries()</function></link> or <link linkend="g-option-group-add-entries"><function>g_option_group_add_entries()</function></link>.</para>
848
</para><variablelist role="struct">
850
<term>const <link linkend="gchar">gchar</link> *<structfield>long_name</structfield>;</term>
851
<listitem><simpara> The long name of an option can be used to specify it
852
in a commandline as --<replaceable>long_name</replaceable>. Every
853
option must have a long name. To resolve conflicts if multiple
854
option groups contain the same long name, it is also possible to
855
specify the option as
856
--<replaceable>groupname</replaceable>-<replaceable>long_name</replaceable>.
857
</simpara></listitem>
860
<term><link linkend="gchar">gchar</link> <structfield>short_name</structfield>;</term>
861
<listitem><simpara> If an option has a short name, it can be specified
862
-<replaceable>short_name</replaceable> in a commandline. <parameter>short_name</parameter> must be
863
a printable ASCII character different from '-', or zero if the option has no
865
</simpara></listitem>
868
<term><link linkend="gint">gint</link> <structfield>flags</structfield>;</term>
869
<listitem><simpara> Flags from <link linkend="GOptionFlags"><type>GOptionFlags</type></link>.
870
</simpara></listitem>
873
<term><link linkend="GOptionArg">GOptionArg</link> <structfield>arg</structfield>;</term>
874
<listitem><simpara> The type of the option, as a <link linkend="GOptionArg"><type>GOptionArg</type></link>.
875
</simpara></listitem>
878
<term><link linkend="gpointer">gpointer</link> <structfield>arg_data</structfield>;</term>
879
<listitem><simpara> If the <parameter>arg</parameter> type is <link linkend="G-OPTION-ARG-CALLBACK--CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link>, then <parameter>arg_data</parameter> must
880
point to a <link linkend="GOptionArgFunc"><type>GOptionArgFunc</type></link> callback function, which will be called to handle
881
the extra argument. Otherwise, <parameter>arg_data</parameter> is a pointer to a location to store
882
the value, the required type of the location depends on the <parameter>arg</parameter> type:
885
<term><link linkend="G-OPTION-ARG-NONE--CAPS"><literal>G_OPTION_ARG_NONE</literal></link></term>
886
<listitem><para><link linkend="gboolean"><literal>gboolean</literal></link></para></listitem>
889
<term><link linkend="G-OPTION-ARG-STRING--CAPS"><literal>G_OPTION_ARG_STRING</literal></link></term>
890
<listitem><para><link linkend="gchar"><literal>gchar</literal></link>*</para></listitem>
893
<term><link linkend="G-OPTION-ARG-INT--CAPS"><literal>G_OPTION_ARG_INT</literal></link></term>
894
<listitem><para><link linkend="gint"><literal>gint</literal></link></para></listitem>
897
<term><link linkend="G-OPTION-ARG-FILENAME--CAPS"><literal>G_OPTION_ARG_FILENAME</literal></link></term>
898
<listitem><para><link linkend="gchar"><literal>gchar</literal></link>*</para></listitem>
901
<term><link linkend="G-OPTION-ARG-STRING-ARRAY--CAPS"><literal>G_OPTION_ARG_STRING_ARRAY</literal></link></term>
902
<listitem><para><link linkend="gchar"><literal>gchar</literal></link>**</para></listitem>
905
<term><link linkend="G-OPTION-ARG-FILENAME-ARRAY--CAPS"><literal>G_OPTION_ARG_FILENAME_ARRAY</literal></link></term>
906
<listitem><para><link linkend="gchar"><literal>gchar</literal></link>**</para></listitem>
909
<term><link linkend="G-OPTION-ARG-DOUBLE--CAPS"><literal>G_OPTION_ARG_DOUBLE</literal></link></term>
910
<listitem><para><link linkend="gdouble"><literal>gdouble</literal></link></para></listitem>
913
If <parameter>arg</parameter> type is <link linkend="G-OPTION-ARG-STRING--CAPS"><literal>G_OPTION_ARG_STRING</literal></link> or <link linkend="G-OPTION-ARG-FILENAME--CAPS"><literal>G_OPTION_ARG_FILENAME</literal></link> the location
914
will contain a newly allocated string if the option was given. That string
915
needs to be freed by the callee using <link linkend="g-free"><function>g_free()</function></link>. Likewise if <parameter>arg</parameter> type is
916
<link linkend="G-OPTION-ARG-STRING-ARRAY--CAPS"><literal>G_OPTION_ARG_STRING_ARRAY</literal></link> or <link linkend="G-OPTION-ARG-FILENAME-ARRAY--CAPS"><literal>G_OPTION_ARG_FILENAME_ARRAY</literal></link>, the data should
917
be freed using <link linkend="g-strfreev"><function>g_strfreev()</function></link>.
918
</simpara></listitem>
921
<term>const <link linkend="gchar">gchar</link> *<structfield>description</structfield>;</term>
922
<listitem><simpara> the description for the option in <option>--help</option>
923
output. The <parameter>description</parameter> is translated using the <parameter>translate_func</parameter> of the
924
group, see <link linkend="g-option-group-set-translation-domain"><function>g_option_group_set_translation_domain()</function></link>.
925
</simpara></listitem>
928
<term>const <link linkend="gchar">gchar</link> *<structfield>arg_description</structfield>;</term>
929
<listitem><simpara> The placeholder to use for the extra argument parsed
930
by the option in <option>--help</option>
931
output. The <parameter>arg_description</parameter> is translated using the <parameter>translate_func</parameter> of the
932
group, see <link linkend="g-option-group-set-translation-domain"><function>g_option_group_set_translation_domain()</function></link>.
933
</simpara></listitem>
935
</variablelist></refsect2>
936
<refsect2 id="g-option-context-add-main-entries" role="function" condition="since:2.6">
937
<title>g_option_context_add_main_entries ()</title>
938
<indexterm zone="g-option-context-add-main-entries" role="2.6"><primary sortas="option_context_add_main_entries">g_option_context_add_main_entries</primary></indexterm><programlisting><link linkend="void">void</link> g_option_context_add_main_entries (<link linkend="GOptionContext">GOptionContext</link> *context,
939
const <link linkend="GOptionEntry">GOptionEntry</link> *entries,
940
const <link linkend="gchar">gchar</link> *translation_domain);</programlisting>
942
A convenience function which creates a main group if it doesn't
943
exist, adds the <parameter>entries</parameter> to it and sets the translation domain.</para>
945
</para><variablelist role="params">
946
<varlistentry><term><parameter>context</parameter> :</term>
947
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
948
</simpara></listitem></varlistentry>
949
<varlistentry><term><parameter>entries</parameter> :</term>
950
<listitem><simpara> a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of <link linkend="GOptionEntry"><type>GOptionEntry</type></link><!-- -->s
951
</simpara></listitem></varlistentry>
952
<varlistentry><term><parameter>translation_domain</parameter> :</term>
953
<listitem><simpara> a translation domain to use for translating
954
the <option>--help</option> output for the options in <parameter>entries</parameter>
955
with <link linkend="gettext"><function>gettext()</function></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
956
</simpara></listitem></varlistentry>
957
</variablelist><para role="since">Since 2.6</para></refsect2>
958
<refsect2 id="GOptionGroup" role="struct">
959
<title>GOptionGroup</title>
960
<indexterm zone="GOptionGroup"><primary sortas="OptionGroup">GOptionGroup</primary></indexterm><programlisting>typedef struct _GOptionGroup GOptionGroup;</programlisting>
962
A <structname>GOptionGroup</structname> struct defines the options in a single
963
group. The struct has only private fields and should not be directly accessed.
966
All options in a group share the same translation function. Libraries which
967
need to parse commandline options are expected to provide a function for
968
getting a <structname>GOptionGroup</structname> holding their options, which
969
the application can then add to its <link linkend="GOptionContext"><type>GOptionContext</type></link>.</para>
972
<refsect2 id="g-option-context-add-group" role="function" condition="since:2.6">
973
<title>g_option_context_add_group ()</title>
974
<indexterm zone="g-option-context-add-group" role="2.6"><primary sortas="option_context_add_group">g_option_context_add_group</primary></indexterm><programlisting><link linkend="void">void</link> g_option_context_add_group (<link linkend="GOptionContext">GOptionContext</link> *context,
975
<link linkend="GOptionGroup">GOptionGroup</link> *group);</programlisting>
977
Adds a <link linkend="GOptionGroup"><type>GOptionGroup</type></link> to the <parameter>context</parameter>, so that parsing with <parameter>context</parameter>
978
will recognize the options in the group. Note that the group will
979
be freed together with the context when <link linkend="g-option-context-free"><function>g_option_context_free()</function></link> is
980
called, so you must not free the group yourself after adding it
983
</para><variablelist role="params">
984
<varlistentry><term><parameter>context</parameter> :</term>
985
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
986
</simpara></listitem></varlistentry>
987
<varlistentry><term><parameter>group</parameter> :</term>
988
<listitem><simpara> the group to add
989
</simpara></listitem></varlistentry>
990
</variablelist><para role="since">Since 2.6</para></refsect2>
991
<refsect2 id="g-option-context-set-main-group" role="function" condition="since:2.6">
992
<title>g_option_context_set_main_group ()</title>
993
<indexterm zone="g-option-context-set-main-group" role="2.6"><primary sortas="option_context_set_main_group">g_option_context_set_main_group</primary></indexterm><programlisting><link linkend="void">void</link> g_option_context_set_main_group (<link linkend="GOptionContext">GOptionContext</link> *context,
994
<link linkend="GOptionGroup">GOptionGroup</link> *group);</programlisting>
996
Sets a <link linkend="GOptionGroup"><type>GOptionGroup</type></link> as main group of the <parameter>context</parameter>.
997
This has the same effect as calling <link linkend="g-option-context-add-group"><function>g_option_context_add_group()</function></link>,
998
the only difference is that the options in the main group are
999
treated differently when generating <option>--help</option> output.</para>
1001
</para><variablelist role="params">
1002
<varlistentry><term><parameter>context</parameter> :</term>
1003
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
1004
</simpara></listitem></varlistentry>
1005
<varlistentry><term><parameter>group</parameter> :</term>
1006
<listitem><simpara> the group to set as main group
1007
</simpara></listitem></varlistentry>
1008
</variablelist><para role="since">Since 2.6</para></refsect2>
1009
<refsect2 id="g-option-context-get-main-group" role="function" condition="since:2.6">
1010
<title>g_option_context_get_main_group ()</title>
1011
<indexterm zone="g-option-context-get-main-group" role="2.6"><primary sortas="option_context_get_main_group">g_option_context_get_main_group</primary></indexterm><programlisting><link linkend="GOptionGroup">GOptionGroup</link> * g_option_context_get_main_group (<link linkend="GOptionContext">GOptionContext</link> *context);</programlisting>
1013
Returns a pointer to the main group of <parameter>context</parameter>.</para>
1015
</para><variablelist role="params">
1016
<varlistentry><term><parameter>context</parameter> :</term>
1017
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
1018
</simpara></listitem></varlistentry>
1019
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the main group of <parameter>context</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if <parameter>context</parameter> doesn't
1020
have a main group. Note that group belongs to <parameter>context</parameter> and should
1021
not be modified or freed.
1023
</simpara></listitem></varlistentry>
1024
</variablelist><para role="since">Since 2.6</para></refsect2>
1025
<refsect2 id="g-option-group-new" role="function" condition="since:2.6">
1026
<title>g_option_group_new ()</title>
1027
<indexterm zone="g-option-group-new" role="2.6"><primary sortas="option_group_new">g_option_group_new</primary></indexterm><programlisting><link linkend="GOptionGroup">GOptionGroup</link> * g_option_group_new (const <link linkend="gchar">gchar</link> *name,
1028
const <link linkend="gchar">gchar</link> *description,
1029
const <link linkend="gchar">gchar</link> *help_description,
1030
<link linkend="gpointer">gpointer</link> user_data,
1031
<link linkend="GDestroyNotify">GDestroyNotify</link> destroy);</programlisting>
1033
Creates a new <link linkend="GOptionGroup"><type>GOptionGroup</type></link>.</para>
1035
</para><variablelist role="params">
1036
<varlistentry><term><parameter>name</parameter> :</term>
1037
<listitem><simpara> the name for the option group, this is used to provide
1038
help for the options in this group with <option>--help-</option><parameter>name</parameter>
1039
</simpara></listitem></varlistentry>
1040
<varlistentry><term><parameter>description</parameter> :</term>
1041
<listitem><simpara> a description for this group to be shown in
1042
<option>--help</option>. This string is translated using the translation
1043
domain or translation function of the group
1044
</simpara></listitem></varlistentry>
1045
<varlistentry><term><parameter>help_description</parameter> :</term>
1046
<listitem><simpara> a description for the <option>--help-</option><parameter>name</parameter> option.
1047
This string is translated using the translation domain or translation function
1049
</simpara></listitem></varlistentry>
1050
<varlistentry><term><parameter>user_data</parameter> :</term>
1051
<listitem><simpara> user data that will be passed to the pre- and post-parse hooks,
1052
the error hook and to callbacks of <link linkend="G-OPTION-ARG-CALLBACK--CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link> options, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1053
</simpara></listitem></varlistentry>
1054
<varlistentry><term><parameter>destroy</parameter> :</term>
1055
<listitem><simpara> a function that will be called to free <parameter>user_data</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1056
</simpara></listitem></varlistentry>
1057
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly created option group. It should be added
1058
to a <link linkend="GOptionContext"><type>GOptionContext</type></link> or freed with <link linkend="g-option-group-free"><function>g_option_group_free()</function></link>.
1060
</simpara></listitem></varlistentry>
1061
</variablelist><para role="since">Since 2.6</para></refsect2>
1062
<refsect2 id="g-option-group-free" role="function" condition="since:2.6">
1063
<title>g_option_group_free ()</title>
1064
<indexterm zone="g-option-group-free" role="2.6"><primary sortas="option_group_free">g_option_group_free</primary></indexterm><programlisting><link linkend="void">void</link> g_option_group_free (<link linkend="GOptionGroup">GOptionGroup</link> *group);</programlisting>
1066
Frees a <link linkend="GOptionGroup"><type>GOptionGroup</type></link>. Note that you must <emphasis>not</emphasis>
1067
free groups which have been added to a <link linkend="GOptionContext"><type>GOptionContext</type></link>.</para>
1069
</para><variablelist role="params">
1070
<varlistentry><term><parameter>group</parameter> :</term>
1071
<listitem><simpara> a <link linkend="GOptionGroup"><type>GOptionGroup</type></link>
1072
</simpara></listitem></varlistentry>
1073
</variablelist><para role="since">Since 2.6</para></refsect2>
1074
<refsect2 id="g-option-group-add-entries" role="function" condition="since:2.6">
1075
<title>g_option_group_add_entries ()</title>
1076
<indexterm zone="g-option-group-add-entries" role="2.6"><primary sortas="option_group_add_entries">g_option_group_add_entries</primary></indexterm><programlisting><link linkend="void">void</link> g_option_group_add_entries (<link linkend="GOptionGroup">GOptionGroup</link> *group,
1077
const <link linkend="GOptionEntry">GOptionEntry</link> *entries);</programlisting>
1079
Adds the options specified in <parameter>entries</parameter> to <parameter>group</parameter>.</para>
1081
</para><variablelist role="params">
1082
<varlistentry><term><parameter>group</parameter> :</term>
1083
<listitem><simpara> a <link linkend="GOptionGroup"><type>GOptionGroup</type></link>
1084
</simpara></listitem></varlistentry>
1085
<varlistentry><term><parameter>entries</parameter> :</term>
1086
<listitem><simpara> a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of <link linkend="GOptionEntry"><type>GOptionEntry</type></link><!-- -->s
1087
</simpara></listitem></varlistentry>
1088
</variablelist><para role="since">Since 2.6</para></refsect2>
1089
<refsect2 id="GOptionParseFunc" role="function">
1090
<title>GOptionParseFunc ()</title>
1091
<indexterm zone="GOptionParseFunc"><primary sortas="OptionParseFunc">GOptionParseFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> (*GOptionParseFunc) (<link linkend="GOptionContext">GOptionContext</link> *context,
1092
<link linkend="GOptionGroup">GOptionGroup</link> *group,
1093
<link linkend="gpointer">gpointer</link> data,
1094
<link linkend="GError">GError</link> **error);</programlisting>
1096
The type of function that can be called before and after parsing.</para>
1098
</para><variablelist role="params">
1099
<varlistentry><term><parameter>context</parameter> :</term>
1100
<listitem><simpara> The active <link linkend="GOptionContext"><type>GOptionContext</type></link>
1101
</simpara></listitem></varlistentry>
1102
<varlistentry><term><parameter>group</parameter> :</term>
1103
<listitem><simpara> The group to which the function belongs
1104
</simpara></listitem></varlistentry>
1105
<varlistentry><term><parameter>data</parameter> :</term>
1106
<listitem><simpara> User data added to the <link linkend="GOptionGroup"><type>GOptionGroup</type></link> containing the option when it
1107
was created with <link linkend="g-option-group-new"><function>g_option_group_new()</function></link>
1108
</simpara></listitem></varlistentry>
1109
<varlistentry><term><parameter>error</parameter> :</term>
1110
<listitem><simpara> A return location for error details
1111
</simpara></listitem></varlistentry>
1112
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the function completed successfully, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if an error
1113
occurred, in which case <parameter>error</parameter> should be set with <link linkend="g-set-error"><function>g_set_error()</function></link>
1114
</simpara></listitem></varlistentry>
1115
</variablelist></refsect2>
1116
<refsect2 id="g-option-group-set-parse-hooks" role="function" condition="since:2.6">
1117
<title>g_option_group_set_parse_hooks ()</title>
1118
<indexterm zone="g-option-group-set-parse-hooks" role="2.6"><primary sortas="option_group_set_parse_hooks">g_option_group_set_parse_hooks</primary></indexterm><programlisting><link linkend="void">void</link> g_option_group_set_parse_hooks (<link linkend="GOptionGroup">GOptionGroup</link> *group,
1119
<link linkend="GOptionParseFunc">GOptionParseFunc</link> pre_parse_func,
1120
<link linkend="GOptionParseFunc">GOptionParseFunc</link> post_parse_func);</programlisting>
1122
Associates two functions with <parameter>group</parameter> which will be called
1123
from <link linkend="g-option-context-parse"><function>g_option_context_parse()</function></link> before the first option is parsed
1124
and after the last option has been parsed, respectively.
1127
Note that the user data to be passed to <parameter>pre_parse_func</parameter> and
1128
<parameter>post_parse_func</parameter> can be specified when constructing the group
1129
with <link linkend="g-option-group-new"><function>g_option_group_new()</function></link>.</para>
1131
</para><variablelist role="params">
1132
<varlistentry><term><parameter>group</parameter> :</term>
1133
<listitem><simpara> a <link linkend="GOptionGroup"><type>GOptionGroup</type></link>
1134
</simpara></listitem></varlistentry>
1135
<varlistentry><term><parameter>pre_parse_func</parameter> :</term>
1136
<listitem><simpara> a function to call before parsing, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1137
</simpara></listitem></varlistentry>
1138
<varlistentry><term><parameter>post_parse_func</parameter> :</term>
1139
<listitem><simpara> a function to call after parsing, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1140
</simpara></listitem></varlistentry>
1141
</variablelist><para role="since">Since 2.6</para></refsect2>
1142
<refsect2 id="GOptionErrorFunc" role="function">
1143
<title>GOptionErrorFunc ()</title>
1144
<indexterm zone="GOptionErrorFunc"><primary sortas="OptionErrorFunc">GOptionErrorFunc</primary></indexterm><programlisting><link linkend="void">void</link> (*GOptionErrorFunc) (<link linkend="GOptionContext">GOptionContext</link> *context,
1145
<link linkend="GOptionGroup">GOptionGroup</link> *group,
1146
<link linkend="gpointer">gpointer</link> data,
1147
<link linkend="GError">GError</link> **error);</programlisting>
1149
The type of function to be used as callback when a parse error occurs.</para>
1151
</para><variablelist role="params">
1152
<varlistentry><term><parameter>context</parameter> :</term>
1153
<listitem><simpara> The active <link linkend="GOptionContext"><type>GOptionContext</type></link>
1154
</simpara></listitem></varlistentry>
1155
<varlistentry><term><parameter>group</parameter> :</term>
1156
<listitem><simpara> The group to which the function belongs
1157
</simpara></listitem></varlistentry>
1158
<varlistentry><term><parameter>data</parameter> :</term>
1159
<listitem><simpara> User data added to the <link linkend="GOptionGroup"><type>GOptionGroup</type></link> containing the option when it
1160
was created with <link linkend="g-option-group-new"><function>g_option_group_new()</function></link>
1161
</simpara></listitem></varlistentry>
1162
<varlistentry><term><parameter>error</parameter> :</term>
1163
<listitem><simpara> The <link linkend="GError"><type>GError</type></link> containing details about the parse error
1164
</simpara></listitem></varlistentry>
1165
</variablelist></refsect2>
1166
<refsect2 id="g-option-group-set-error-hook" role="function" condition="since:2.6">
1167
<title>g_option_group_set_error_hook ()</title>
1168
<indexterm zone="g-option-group-set-error-hook" role="2.6"><primary sortas="option_group_set_error_hook">g_option_group_set_error_hook</primary></indexterm><programlisting><link linkend="void">void</link> g_option_group_set_error_hook (<link linkend="GOptionGroup">GOptionGroup</link> *group,
1169
<link linkend="GOptionErrorFunc">GOptionErrorFunc</link> error_func);</programlisting>
1171
Associates a function with <parameter>group</parameter> which will be called
1172
from <link linkend="g-option-context-parse"><function>g_option_context_parse()</function></link> when an error occurs.
1175
Note that the user data to be passed to <parameter>error_func</parameter> can be
1176
specified when constructing the group with <link linkend="g-option-group-new"><function>g_option_group_new()</function></link>.</para>
1178
</para><variablelist role="params">
1179
<varlistentry><term><parameter>group</parameter> :</term>
1180
<listitem><simpara> a <link linkend="GOptionGroup"><type>GOptionGroup</type></link>
1181
</simpara></listitem></varlistentry>
1182
<varlistentry><term><parameter>error_func</parameter> :</term>
1183
<listitem><simpara> a function to call when an error occurs
1184
</simpara></listitem></varlistentry>
1185
</variablelist><para role="since">Since 2.6</para></refsect2>
1186
<refsect2 id="g-option-group-set-translate-func" role="function" condition="since:2.6">
1187
<title>g_option_group_set_translate_func ()</title>
1188
<indexterm zone="g-option-group-set-translate-func" role="2.6"><primary sortas="option_group_set_translate_func">g_option_group_set_translate_func</primary></indexterm><programlisting><link linkend="void">void</link> g_option_group_set_translate_func (<link linkend="GOptionGroup">GOptionGroup</link> *group,
1189
<link linkend="GTranslateFunc">GTranslateFunc</link> func,
1190
<link linkend="gpointer">gpointer</link> data,
1191
<link linkend="GDestroyNotify">GDestroyNotify</link> destroy_notify);</programlisting>
1193
Sets the function which is used to translate user-visible
1194
strings, for <option>--help</option> output. Different
1195
groups can use different <link linkend="GTranslateFunc"><type>GTranslateFunc</type></link><!-- -->s. If <parameter>func</parameter>
1196
is <link linkend="NULL--CAPS"><literal>NULL</literal></link>, strings are not translated.
1199
If you are using <link linkend="gettext"><function>gettext()</function></link>, you only need to set the translation
1200
domain, see <link linkend="g-option-group-set-translation-domain"><function>g_option_group_set_translation_domain()</function></link>.</para>
1202
</para><variablelist role="params">
1203
<varlistentry><term><parameter>group</parameter> :</term>
1204
<listitem><simpara> a <link linkend="GOptionGroup"><type>GOptionGroup</type></link>
1205
</simpara></listitem></varlistentry>
1206
<varlistentry><term><parameter>func</parameter> :</term>
1207
<listitem><simpara> the <link linkend="GTranslateFunc"><type>GTranslateFunc</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1208
</simpara></listitem></varlistentry>
1209
<varlistentry><term><parameter>data</parameter> :</term>
1210
<listitem><simpara> user data to pass to <parameter>func</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1211
</simpara></listitem></varlistentry>
1212
<varlistentry><term><parameter>destroy_notify</parameter> :</term>
1213
<listitem><simpara> a function which gets called to free <parameter>data</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1214
</simpara></listitem></varlistentry>
1215
</variablelist><para role="since">Since 2.6</para></refsect2>
1216
<refsect2 id="g-option-group-set-translation-domain" role="function" condition="since:2.6">
1217
<title>g_option_group_set_translation_domain ()</title>
1218
<indexterm zone="g-option-group-set-translation-domain" role="2.6"><primary sortas="option_group_set_translation_domain">g_option_group_set_translation_domain</primary></indexterm><programlisting><link linkend="void">void</link> g_option_group_set_translation_domain
1219
(<link linkend="GOptionGroup">GOptionGroup</link> *group,
1220
const <link linkend="gchar">gchar</link> *domain);</programlisting>
1222
A convenience function to use <link linkend="gettext"><function>gettext()</function></link> for translating
1223
user-visible strings.</para>
1225
</para><variablelist role="params">
1226
<varlistentry><term><parameter>group</parameter> :</term>
1227
<listitem><simpara> a <link linkend="GOptionGroup"><type>GOptionGroup</type></link>
1228
</simpara></listitem></varlistentry>
1229
<varlistentry><term><parameter>domain</parameter> :</term>
1230
<listitem><simpara> the domain to use
1231
</simpara></listitem></varlistentry>
1232
</variablelist><para role="since">Since 2.6</para></refsect2>
added
removed
docs/reference/glib/xml/option.xml
