option.sgml

This GLib version 2.16.1. GLib is the low-level core library that forms the basis for projects such

<!-- ##### 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 the
popt 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 
nicely formatted 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 performance

Help Options:
  -?, --help               Show help options
  --help-all               Show all help options
  --help-gtk               Show GTK+ Options

Application 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 to
incorporate options from multiple sources. The intended use for this is
to let applications collect option groups from the libraries it uses,
add them to their #GOptionContext, and parse all options by a single call
to 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 takes
care of converting it to the right encoding; strings are returned in UTF-8,
filenames are returned in the GLib filename encoding. Note that this only
works if setlocale() has been called before g_option_context_parse().
</para>

<para>
Here is a complete example of setting up GOption to parse the example
commandline 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));
  if (!g_option_context_parse (context, &amp;argc, &amp;argv, &amp;error))
    {
      g_print ("option parsing failed: %s\n", error->message);
      exit (1);
    }

  /* ... */

}
</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 will
be 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_CALLBACK
options.
</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 options
are 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-visible
strings, 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>

</para>