<!-- ##### SECTION Title ##### -->Commandline option parser<!-- ##### SECTION Short_Description ##### -->parses commandline options<!-- ##### SECTION Long_Description ##### --><para>The GOption commandline parser is intended to be a simpler replacement for thepopt library. It supports short and long commandline options, as shown in the following example:</para><para><literal>testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2</literal></para><para>The example demonstrates a number of features of the GOption commandline parser<itemizedlist><listitem><para>  Options can be single letters, prefixed by a single dash. Multiple  short options can be grouped behind a single dash.</para></listitem><listitem><para>  Long options are prefixed by two consecutive dashes.</para></listitem><listitem><para>  Options can have an extra argument, which can be a number, a string or a filename.  For long options, the extra argument can be appended with an equals sign after the  option name.</para></listitem><listitem><para>  Non-option arguments are returned to the application as rest arguments.</para></listitem><listitem><para>  An argument consisting solely of two dashes turns off further parsing, any remaining  arguments (even those starting with a dash) are returned to the application as rest   arguments.</para></listitem></itemizedlist></para><para>Another important feature of GOption is that it can automatically generate nicelyformatted help output. Unless it is explicitly turned off with g_option_context_set_help_enabled(), GOption will recognize the <option>--help</option>, <option>-?</option>, <option>--help-all</option>and <option>--help-</option><replaceable>groupname</replaceable> options (where <replaceable>groupname</replaceable> is the name of a #GOptionGroup) and write a text similar to the one shown in the following example to stdout.</para><informalexample><screen>Usage:  testtreemodel [OPTION...] - test tree model performanceHelp Options:  -?, --help               Show help options  --help-all               Show all help options  --help-gtk               Show GTK+ OptionsApplication Options:  -r, --repeats=N          Average over N repetitions  -m, --max-size=M         Test up to 2^M items  --display=DISPLAY        X display to use  -v, --verbose            Be verbose  -b, --beep               Beep when done     --rand                   Randomize the data</screen></informalexample><para>GOption groups options in #GOptionGroup<!-- -->s, which makes it easy toincorporate options from multiple sources. The intended use for this isto let applications collect option groups from the libraries it uses,add them to their #GOptionContext, and parse all options by a single callto g_option_context_parse(). See gtk_get_option_group() for an example.</para><para>If an option is declared to be of type string or filename, GOption takescare of converting it to the right encoding; strings are returned in UTF-8,filenames are returned in the GLib filename encoding.</para><para>Here is a complete example of setting up GOption to parse the examplecommandline above and produce the example help output.</para><informalexample><programlisting>static gint repeats = 2;static gint max_size = 8;static gboolean verbose = FALSE;static gboolean beep = FALSE;static gboolean rand = FALSE;static GOptionEntry entries[] = {  { "repeats", 'r', 0, G_OPTION_ARG_INT, &amp;repeats, "Average over N repetitions", "N" },  { "max-size", 'm', 0, G_OPTION_ARG_INT, &amp;max_size, "Test up to 2^M items", "M" },  { "verbose", 'v', 0, G_OPTION_ARG_NONE, &amp;verbose, "Be verbose", NULL },  { "beep", 'b', 0, G_OPTION_ARG_NONE, &amp;beep, "Beep when done", NULL },  { "rand", 0, 0, G_OPTION_ARG_NONE, &amp;rand, "Randomize the data", NULL },  { NULL }};int main (int argc, char *argv[]){  GError *error = NULL;  GOptionContext *context;  context = g_option_context_new ("- test tree model performance");  g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE);  g_option_context_add_group (context, gtk_get_option_group (TRUE));  g_option_context_parse (context, &amp;argc, &amp;argv, &amp;error);    /* ... */}</programlisting></informalexample><!-- ##### SECTION See_Also ##### --><para></para><!-- ##### SECTION Stability_Level ##### --><!-- ##### ENUM GOptionError ##### --><para>Error codes returned by option parsing.</para>@G_OPTION_ERROR_UNKNOWN_OPTION: An option was not known to the parser.  This error will only be reported, if the parser hasn't been instructed  to ignore unknown options, see g_option_context_set_ignore_unknown_options().@G_OPTION_ERROR_BAD_VALUE: A value couldn't be parsed.@G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed.<!-- ##### MACRO G_OPTION_ERROR ##### --><para>Error domain for option parsing. Errors in this domain willbe from the #GOptionError enumeration. See #GError for information on error domains.</para><!-- ##### USER_FUNCTION GOptionArgFunc ##### --><para>The type of function to be passed as callback for %G_OPTION_ARG_CALLBACKoptions.</para>@option_name: The name of the option being parsed. This will be either a   single dash followed by a single letter (for a short name) or two dashes  followed by a long option name.@value: The value to be parsed.@data: User data added to the #GOptionGroup containing the option when it  was created with g_option_group_new()@error: A return location for errors. The error code %G_OPTION_ERROR_FAILED  is intended to be used for errors in #GOptionArgFunc callbacks.@Returns: %TRUE if the option was successfully parsed, %FALSE if an error   occurred, in which case @error should be set with g_set_error()<!-- ##### STRUCT GOptionContext ##### --><para>A <structname>GOptionContext</structname> struct defines which optionsare accepted by the commandline option parser. The struct has only private fields and should not be directly accessed.</para><!-- ##### FUNCTION g_option_context_new ##### --><para></para>@parameter_string: @Returns: <!-- ##### FUNCTION g_option_context_set_summary ##### --><para></para>@context: @summary: <!-- ##### FUNCTION g_option_context_get_summary ##### --><para></para>@context: @Returns: <!-- ##### FUNCTION g_option_context_set_description ##### --><para></para>@context: @description: <!-- ##### FUNCTION g_option_context_get_description ##### --><para></para>@context: @Returns: <!-- ##### USER_FUNCTION GTranslateFunc ##### --><para>The type of functions which are used to translate user-visiblestrings, for <option>--help</option> output.</para>@str: the untranslated string@data: user data specified when installing the function, e.g.  in g_option_group_set_translate_func()@Returns: a translation of the string for the current locale.  The returned string is owned by GLib and must not be freed.<!-- ##### FUNCTION g_option_context_set_translate_func ##### --><para></para>@context: @func: @data: @destroy_notify: <!-- ##### FUNCTION g_option_context_set_translation_domain ##### --><para></para>@context: @domain: <!-- ##### FUNCTION g_option_context_free ##### --><para></para>@context: <!-- ##### FUNCTION g_option_context_parse ##### --><para></para>@context: @argc: @argv: @error: @Returns: <!-- ##### FUNCTION g_option_context_set_help_enabled ##### --><para></para>@context: @help_enabled: <!-- ##### FUNCTION g_option_context_get_help_enabled ##### --><para></para>@context: @Returns: <!-- ##### FUNCTION g_option_context_set_ignore_unknown_options ##### --><para>